Disburse funds directly from your Xtopay Disbursement Account to any recipient bank account via the GhIPSS network.

Direct Send-To-Bank

The Direct Send-To-Bank API allows merchants to programmatically disburse funds directly from their Xtopay Disbursement Account to any customer or supplier bank account across all available banks on the GhIPSS network. This is ideal for automated vendor payments, customer refunds to bank accounts, payroll disbursements, and settlement transfers.

Supported Banks & Channels

Xtopay supports direct transfers to the following bank channels using their specific bank codes:

Bank Channel	BankCode	Country
STANDARD CHARTERED BANK	`300302`	Ghana
ABSA BANK GHANA LIMITED	`300303`	Ghana
GCB BANK LIMITED	`300304`	Ghana
NATIONAL INVESTMENT BANK	`300305`	Ghana
ARB APEX BANK LIMITED	`300306`	Ghana
AGRICULTURAL DEVELOPMENT BANK	`300307`	Ghana
UNIVERSAL MERCHANT BANK	`300309`	Ghana
REPUBLIC BANK LIMITED	`300310`	Ghana
ZENITH BANK GHANA LTD	`300311`	Ghana
ECOBANK GHANA LTD	`300312`	Ghana
CAL BANK LIMITED	`300313`	Ghana
FIRST ATLANTIC BANK	`300316`	Ghana
PRUDENTIAL BANK LTD	`300317`	Ghana
STANBIC BANK	`300318`	Ghana
FIRST BANK OF NIGERIA	`300319`	Ghana
BANK OF AFRICA	`300320`	Ghana
GUARANTY TRUST BANK	`300322`	Ghana
FIDELITY BANK LIMITED	`300323`	Ghana
SAHEL - SAHARA BANK (BSIC)	`300324`	Ghana
UNITED BANK OF AFRICA	`300325`	Ghana
ACCESS BANK LTD	`300329`	Ghana
CONSOLIDATED BANK GHANA	`300331`	Ghana
FIRST NATIONAL BANK	`300334`	Ghana
GHL BANK	`300362`	Ghana

Disbursement Account Funding

To disburse payments via the Direct Send-To-Bank API, your business must maintain an active balance in your Disbursement Account.

You can fund your Disbursement Account via one of two methods:

Online Funding: Fund it using bank transfer or card payment from your merchant dashboard.
Balance Transfer: Instantly transfer settled collections from your Xtopay Collection Account to your Disbursement Account.

For detailed custom limits or support, please contact your Xtopay Relationship Manager.

Business IP Whitelisting

[!WARNING] Whitelisting Required Direct Send-To-Bank endpoints are live and require strict IP whitelisting. Requests from non-whitelisted IP addresses will return a 403 Forbidden error or timeout.

Please submit your production server public IP addresses to your Xtopay Retail Systems Engineer for whitelisting. We permit a maximum of four (4) IP addresses per service key.

Understanding the Service Flow

The Direct Send-To-Bank process is asynchronous. When you initiate a bank transfer, Xtopay processes and dispatches the request to the GhIPSS network. The final settlement status is usually resolved within a few minutes.

Service Steps

Step	Description
1	Your server makes a Send-To-Bank request to `POST /v1/merchants/{disbursementAccountNumber}/send/bank/gh/{bankCode}`.
2	Xtopay validates the credentials and disbursement balance, debits the account, and returns a pending status `0001` (Accepted).
3	Xtopay dispatches the funds to the recipient bank through the GhIPSS network.
4	Once confirmed by the clearing house/bank, Xtopay dispatches an HTTP POST callback to your `PrimaryCallbackUrl` containing the final state.
5	If no callback is received within five (5) minutes of initiation, query the Transaction Status Check API to verify the final status.

Direct Send-To-Bank Request Flow

sequenceDiagram
    autonumber
    actor Recipient as Recipient Bank Account
    participant AppServer as Merchant Server
    participant Xtopay as Xtopay API
    participant GhIPSS as GhIPSS / Bank Gateway

    AppServer->>Xtopay: POST /v1/merchants/{disbursementAccountNumber}/send/bank/gh/{bankCode} (Auth: Bearer secret_key)
    Xtopay-->>AppServer: Return accepted response (ResponseCode 0001)
    Xtopay->>GhIPSS: Dispatch bank transfer request
    GhIPSS-->>Recipient: Funds credited to bank account
    GhIPSS-->>Xtopay: Bank settlement confirmation
    Xtopay->>AppServer: Send Webhook Callback (POST to PrimaryCallbackUrl)
    Note over AppServer, Xtopay: Fallback: Check status via GET /v1/merchants/.../transactions/status if callback fails

API Reference

To initiate a bank transfer, send an HTTP POST request. You must replace {disbursementAccountNumber} with your Xtopay Disbursement Account Number and {bankCode} with the recipient's bank code.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/merchants/{disbursementAccountNumber}/send/bank/gh/{bankCode}`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`

Path Parameters

Parameter	Type	Required	Description
`disbursementAccountNumber`	`String`	Yes	Your Xtopay Disbursement Account Number (e.g. `11691`).
`bankCode`	`String`	Yes	The 6-digit destination bank code (e.g. `300311` for Zenith Bank).

Request Parameters

Parameter	Type	Required	Description
`Amount`	`Float`	Yes	The amount to send. Must be a float with exactly 2 decimal places (e.g. `0.80`).
`PrimaryCallbackUrl`	`String`	Yes	The callback URL to receive the transaction final status payload once completed.
`Description`	`String`	Yes	Narration description of the bank transfer transaction.
`BankAccountNumber`	`String`	Yes	Recipient's bank account number.
`BankAccountName`	`String`	No	Full legal name associated with the destination bank account.
`RecipientPhoneNumber`	`String`	No	Recipient's mobile phone number in international E.164 format (e.g. `233249111411`).
`BankName`	`String`	No	Name of the recipient bank.
`BankBranch`	`String`	No	Destination bank branch name.
`BankBranchCode`	`String`	No	Branch code of the destination bank.
`ClientReference`	`String`	Yes	A unique alphanumeric transaction reference generated by your system. Maximum length is 36 characters.

Code Examples

curl https://api.xtopay.co/v1/merchants/11691/send/bank/gh/300311 \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 0.8,
    "BankName": "",
    "BankBranch": "",
    "BankBranchCode": "",
    "BankAccountNumber": "4XXXXXXXXX",
    "BankAccountName": "",
    "ClientReference": "sendToBank101",
    "PrimaryCallbackUrl": "https://webhook.site/b503d1a9-e726-f315254a6ede",
    "Description": "Test Deposit",
    "RecipientPhoneNumber": ""
  }'

Sample Response

200 OK

{
  "ResponseCode": "0001",
  "Data": {
      "AmountDebited": 0.0,
      "TransactionId": "367121386447",
      "Description": "Your request has been accepted. We will notify you when the transaction is completed.",
      "ClientReference": "sendToBank101",
      "ExternalTransactionId": "",
      "Amount": 0.8,
      "Charges": 0.0,
      "Meta": null,
      "RecipientName": null
  }
}

Send-To-Bank Callback

Xtopay dispatches callback webhook alerts to your registered PrimaryCallbackUrl once the payout is finalized on the bank clearing network.

Sample Callback (Successful)

{
  "ResponseCode": "0000",
  "Data": {
      "AmountDebited": 0.8,
      "TransactionId": "367121386447",
      "ExternalTransactionId": "367121386447",
      "Description": "The Instant Bank Request has been processed successfully",
      "ClientReference": "sendToBank101",
      "Amount": 0.8,
      "Charges": 0.010,
      "Meta": null,
      "RecipientName": "Joe Doe"
  }
}

Sample Callback (Failed)

{
  "ResponseCode": "4075",
  "Data": {
    "AmountDebited": 10.1,
    "TransactionId": "9933e637066a406dba1a8b255b928b44",
    "ClientReference": "sendToBank102",
    "Description": "Insufficient prepaid balance.",
    "ExternalTransactionId": null,
    "Amount": 10,
    "Charges": 0.1,
    "Meta": null,
    "RecipientName": null
  }
}

Transaction Status Check

Checks the status of a bank transfer transaction. It is mandatory to implement this check to verify the final transaction state if no webhook callback is received within 5 minutes of initiation.

To poll the status, send an HTTP GET request appending the client reference as a query parameter.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/merchants/{disbursementAccountNumber}/transactions/status`
Request Type	`GET`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`

Path Parameters

Parameter	Type	Required	Description
`disbursementAccountNumber`	`String`	Yes	Your Xtopay Disbursement Account Number (e.g. `11691`).

Query Parameters

Parameter	Type	Required	Description
`clientReference`	`String`	Yes (Recommended)	The client reference of the transaction (`sendToBank101`).
`xtopayTransactionId`	`String`	No	The transaction ID returned by Xtopay in the initial response.
`networkTransactionId`	`String`	No	The transaction reference returned by the upstream bank provider.

Code Examples

curl "https://api.xtopay.co/v1/merchants/11691/transactions/status?clientReference=sendToBank101" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response (Succeeded)

200 OK

{
  "ResponseCode": "success",
  "Data": {
    "TransactionId": "367121386447",
    "networkTransactionId": "367121386447",
    "Amount": 0.8,
    "fees": 0.010,
    "ClientReference": "sendToBank101",
    "Channel": "gip-gh",
    "CustomerNumber": "233546335113",
    "Description": "TestSendToBankDeposit",
    "transactionStatus": "success",
    "CreatedAt": "2022-08-23 11:31:06"
  }
}

Sample Response (Failed)

200 OK

{
  "ResponseCode": "success",
  "Data": {
    "TransactionId": "9933e637066a406dba1a8b255b928b44",
    "networkTransactionId": null,
    "Amount": 10.0,
    "fees": 0.1,
    "ClientReference": "sendToBank102",
    "Channel": "gip-gh",
    "customerNumber": "233200585542",
    "Description": "TestSendToBankDeposit",
    "transactionStatus": "failed",
    "CreatedAt": "2024-08-01 08:30:53"
  }
}

Response Codes & Actions

Response Code	Description	Required Action
`0000`	The bank transfer transaction has been processed successfully.	None. Update the transaction as successful in your local database.
`0001`	Request has been accepted. A callback will be sent on final state.	Mark the payout as pending. Wait for the webhook callback.
`2001`	Transaction failed (e.g. name check failed, invalid bank account details, or GhIPSS processing error).	Inspect your request parameters and account details, then try again.
`3050`	Mobile number is not registered for Mobile Payment.	Ensure to pass the appropriate payment channel if using mobile details.
`4000`	Validation errors. Request payload contains incorrect parameters.	Inspect the request schema, verify all parameters, and retry.
`4075`	Insufficient prepaid balance in Disbursement Account.	Top up your Disbursement Account balance from the Xtopay dashboard or via balance transfer.
`5000`	Something went wrong while processing this request.	Inspect your request or contact Xtopay support / Retail Systems Engineer.

Direct Send-To-Bank

On this page