Withdraw

The withdrawal process for cash to bank.

POST /withdraw

Processes a withdrawal by verifying an on-chain redemption transaction and then initiating a bank transfer to the payout details previously sent along with the redeem request. It requires the generated transaction reference (pvRef) and the signed redeem transaction hash (txHash) from the blockchain.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <api_key>

Body

Name	Type	Description
pvRef	string	The transaction reference generated during redemption.
txHash	string	The signed transaction hash from the blockchain.

Example

Mint Allocation Check

{
  "pvRef": "PV-E8823747",
  "txHash": "0x2234a21626a407ae1a065dde7331a361114139c88077978811089f40f7323f90"
}

Response (200) Ok

{
  "status": 200,
  "message": "Withdrawal processed successfully",
  "data": {
    "pvRef": "PV-E8823747",
    "txHash": "0x2234a21626a407ae1a065dde7331a361114139c88077978811089f40f7323f90",
    "txStatus": "PENDING",
    "receiptStatus": 1,
    "transfer": {
      "status": "success",
      "data": {
        "id": "TR-AB12CD34",
        "reference": "TR-AB12CD34",
        "currency": "NGN",
        "amount": 100,
        "narration": "Withdrawal transfer for ENSC conversion",
        "debit_currency": "NGN",
        "account_bank": "058",
        "account_number": "0343761669",
        "beneficiary_name": "Resolved Account Name",
        "meta": [
          {
            "transactionType": "withdrawal",
            "originalReference": "PV-E8823747"
          }
        ]
      }
    },
    "amount": 100,
    "assetType": "ENSC",
    "payout": {
      "accountName": "Resolved Account Name",
      "bank": "058",
      "accountNumber": "0343761669"
    }
  }
}

Common Error Responses

Missing Fields:

{
  "status": 400,
  "error": "Invalid Request",
  "message": "Both pvRef and txHash are required"
}

Transaction Record Not Found:

{
  "status": 404,
  "error": "Transaction Not Found",
  "message": "No transaction record found for the provided pvRef and entity"
}

Invalid Asset Type (non‑ENSC):

{
  "status": 400,
  "error": "Invalid Asset",
  "message": "Only ENSC asset type is allowed for withdrawal"
}

Invalid Transaction Hash:

{
  "status": 400,
  "error": "Invalid Transaction Hash",
  "message": "Transaction not found on blockchain"
}

Transaction Failed On-chain:

{
  "status": 400,
  "error": "Transaction Failed",
  "message": "The blockchain transaction did not succeed"
}

Bank Transfer Failure:

{
  "status": 400,
  "error": "Bank Transfer Failed",
  "message": "Unable to initiate bank transfer"
}