Bank Account Transfers

The API enables you to transfer funds directly from your available balance to supported bank accounts. The documentation below explains further.

We recommend checking out the Getting Started section to understand the basics of payouts first and the general workflow. This guide assumes that you have read that

Overview

The currently supported payout bank channels are listed here (to be updated from time to time). Test bank accounts are also described in this section. It's very important that you track the available balance on your PAYOUT wallet before initiating these transactions.

Step 1: Obtain the required data for the payment request

The table below describes the request parameters that are used for the payout/disbursement request. Most/all will be collected from the paying customer.

Parameter	Type	Required	Description
merchant_reference	String	true	The unique reference for this request. It must be at least 8 characters long.
transaction_method	String	true	The transaction method to be used. This will be BANK for this request
currency	String	true	The 3-character ISO currency code for the request currency
amount	Number	true	The amount to be transferred
provider_code	String	true	The provider code as obtained from the payment options list
account_number	String	true	The bank account of the recipient.
customer_name	String	true	The name of the customer
description	String	true	The description/narration for the transaction
extra_params.bank_code	String	true	The bank code of the recipient bank as obtained from the payout bank list

After collecting the necessary bank transfer information from your customer, prepare your request payload as demonstrated below.

{
    "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
    "transaction_method": "BANK",
    "currency": "UGX",
    "amount": 10000,
    "provider_code": "bank_ug",
    "account_number": "9030015124058",
    "customer_name": "JOHN DOE",
    "description": "Test Payout",
    "extra_params": {
        "bank_code": "stanbic_bank_ug"
    }
}

POST https://gwapisdbx.ellypayapp.com/payout/send-funds

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared.

curl -X POST "https://gwapisdbx.ellypayapp.com/payout/send-funds" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -H "secret-key: your-secret-key" \
   -d '{
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "transaction_method": "BANK",
        "currency": "UGX",
        "amount": 10000,
        "provider_code": "bank_ug",
        "account_number": "9030015124058",
        "customer_name": "JOHN DOE",
        "description": "Test Payout",
        "extra_params": {
             "bank_code": "stanbic_bank_ug"
         }
    }'

202: Accepted - Request acknowledged for processing

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
    }
}

400: Bad Request - Request is not formed as expected

{
    "code": 400,
    "status": "error",
    "message": "bank_gu is not a valid provider code",
    "data": {}
}

Step 2: Handshake - Verify transaction

The API will attempt to verify the transaction from your platform as described in this section. Ensure that the correct URL is configured on your merchant account and that you're handling the verification request appropriately.

Step 3: Handle the final status webhook

Every merchant account is expected to have configured a callback/webhook URL for payouts. For all payouts that transition to the final state (COMPLETED or FAILED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

Successful Bank Payout

{
    "event": "transaction.completed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "transaction_type": "PAYOUT",
        "request_currency": "UGX",
        "transaction_amount": 10000,
        "transaction_currency": "UGX",
        "transaction_charge": 1000,
        "transaction_account": "9030015124058",
        "charge_customer": false,
        "total_debit": 11000,
        "provider_code": "bank_ug",
        "request_amount": 10000,
        "customer_name": "JOHN DOE",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

Failed Bank Payout

{
    "event": "transaction.failed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "transaction_type": "PAYOUT",
        "request_currency": "UGX",
        "transaction_amount": 10000,
        "transaction_currency": "UGX",
        "transaction_charge": 0,
        "transaction_account": "9030015124058",
        "charge_customer": false,
        "total_debit": 0,
        "provider_code": "bank_ug",
        "request_amount": 10000,
        "customer_name": "JOHN DOE",
        "transaction_status": "FAILED",
        "status_message": "Balance Insufficient for the transaction"
    }
}