Bank

The Bank Payout API allows a merchant to disburse funds to bank accounts of suppliers and customers directly. This API uses a single-step process where you provide the recipient's details directly in the payout request.

Note: Currency and network availability depends on your business account permissions. Contact support to enable additional currencies.

How it works

The payout flow is asynchronous. Here is the typical journey:

Initiation: Send a POST request with the recipient's bank details and amount.
Processing: OGateway validates the request and processes the disbursement.
Verification: OGateway sends a Webhook to your callbackURL confirming the success or failure.

Base URL

https://api.ogateway.io

Authentication

All requests must include your API key in the Authorization header:

Authorization: your_api_key

API Key Types

Test Keys: Start with test_ (e.g., test_sk_xxxxx) - Used for testing in sandbox mode.
Live Keys: Start with live_ (e.g., live_sk_xxxxx) - Used for real transactions.

Important: V1 Payouts is primarily accessed via Test Keys for development. Production traffic may be routed differently or require V2 depending on your integration setup.

Initiate Bank Payout

Disburse funds to a bank account. Endpoint: POST /disbursements/bank

Body Parameters

Parameter	Type	Required	Description
senderName	string	Yes	Name of the sender displayed on the transaction.
recipients	array	Yes	An array containing the recipient details. Note: V1 currently supports only one recipient per request.
reference	string	Yes	A unique string to identify this transaction in your system. Must be unique.
callbackURL	string	No	The URL for the final transaction status webhook. This overrides the default callback URL saved under your business.

Recipient Object (inside `recipients` array)

Parameter	Type	Required	Description
amount	number	Yes	The amount to transfer (e.g., 1000.00).
currency	string	Yes	The source currency code (See Currency codes for available currencies).
bank	string	Yes	The bank code. Ghana: Use Bank Codes (e.g. `ZEN`, `GTB`). Nigeria: Use Bank Codes (e.g. `090297`, `090131`). You can see a full list here
accountName	string	Yes	The name of the account holder.
accountNumber	string	Yes	The recipient's bank account number.
destination	string	No	The destination currency code if different from source currency (for cross-currency payouts).
channel	string	No	Transaction channel override. Default is `BANK`.

Example Request

curl --request POST \
  --url https://api.ogateway.io/disbursements/bank \
  --header 'Authorization: your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "senderName": "My Business Ltd",
    "recipients": [
      {
        "amount": 1000,
        "currency": "NGN",
        "bank": "000013",
        "accountName": "Jane Doe",
        "accountNumber": "9000000004091"
      }
    ],
    "reference": "bank_payout_002",
    "callbackURL": "https://your-website.com/webhook"
  }'

Example Response (200 OK)

The API returns an array containing the initiated transaction details.

[
  {
    "id": "trans_987654321",
    "amount": 1000,
    "fee": 10,
    "currency": "NGN",
    "status": "INITIATED",
    "channel": "BANK",
    "type": "CREDIT",
    "customer": {
      "email": "",
      "accountName": "Jane Doe",
      "accountNumber": "9000000004091"
    },
    "metadata": {
      "smsFee": 0,
      "sender_name": "My Business Ltd",
      "currency_source": "NGN",
      "currency_destination": null
    },
    "reason": "CREDIT_BANK",
    "network": "000013",
    "checkout_url": null,
    "reference_business": "bank_payout_002",
    "provider_message": "",
    "virtual_account": null
  }
]

Example Error Response (400 Bad Request)

{
  "statusCode": 400,
  "message": "Only one recipient at a time please!",
  "error": "Bad Request"
}

See Error Codes for Error Responses.

Handling the Callback

See full details in our Callbacks section

Payouts are processed asynchronously. Listen for a Webhook at your callbackURL to confirm the final status.

Success Payload Example

{
  "id": "trans_987654321",
  "amount": 1000,
  "fee": 10,
  "currency": "NGN",
  "status": "COMPLETED",
  "channel": "BANK",
  "type": "CREDIT",
  "customer": {
    "accountName": "Jane Doe",
    "accountNumber": "9000000004091"
  },
  "metadata": {
    "rate": 1,
    "rate_amount": 1000,
    "sender_name": "My Business Ltd",
    "currency_source": "NGN",
    "currency_destination": null
  },
  "reason": "CREDIT",
  "network": "000013",
  "checkout_url": null,
  "provider_message": "Success",
  "reference_business": "bank_payout_002",
  "created_at": "2023-10-27T10:05:00.000Z",
  "updated_at": "2023-10-27T10:05:30.000Z",
  "virtual_account": null,
  "error_message": null,
  "telco_response": null,
  "instructions": null
}

Failed Payload Example

{
  "id": "trans_987654321",
  "amount": 1000,
  "fee": 0,
  "currency": "NGN",
  "status": "FAILED",
  "channel": "BANK",
  "type": "CREDIT",
  "customer": {
    "accountName": "Jane Doe",
    "accountNumber": "9000000004091"
  },
  "metadata": null,
  "reason": "CREDIT_BANK",
  "network": "000013",
  "checkout_url": null,
  "provider_message": "Failed",
  "reference_business": "bank_payout_002",
  "created_at": "2023-10-27T10:05:00.000Z",
  "updated_at": "2023-10-27T10:06:00.000Z",
  "virtual_account": null,
  "error_message": "Transaction failed at the Provider",
  "telco_response": null,
  "instructions": null
}

Best Practices

Unique References: Always use a unique reference for each payout to avoid duplicates.
Wallet Balance: Ensure your OGateway wallet has sufficient funds for the payout amount plus applicable fees.
Sender Name: Provide a clear senderName as this often appears on the recipient's bank statement.
Idempotency: Do not retry failed requests immediately with the same reference; check the status first.
Bank Codes: Use the correct bank codes for each country. Refer to our Bank Codes Documentation.
Cross-Currency: Use the destination parameter if you intend to payout in a different currency than your source wallet (e.g., paying USD from an NGN wallet).