> For the complete documentation index, see [llms.txt](https://developer.ellypayapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ellypayapp.com/funds-payout/bank-account-transfers.md). # Bank Account Transfers {% hint style="info" %} We recommend checking out the [Getting Started](/funds-payout/getting-started.md) section to understand the basics of payouts first and the general workflow. This guide assumes that you have read that {% endhint %} ## Overview The currently supported payout bank channels are listed [here](/getting-started/supported-countries.md) (to be updated from time to time). Test bank accounts are also described in [this](/getting-started/sandbox-test-accounts.md#bank-supported-payout-banks) 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.
ParameterTypeRequiredDescription
merchant_referenceStringtrueThe unique reference for this request. It must be at least 8 characters long.
transaction_methodStringtrueThe transaction method to be used. This will be BANK for this request
currencyStringtrueThe 3-character ISO currency code for the request currency
amountNumbertrueThe amount to be transferred
provider_codeStringtrueThe provider code as obtained from the payment options list
account_numberStringtrueThe bank account of the recipient.
customer_nameStringtrueThe name of the customer
descriptionStringtrueThe description/narration for the transaction
extra_params.bank_codeStringtrueThe 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. ```json { "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. ```powershell 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" } }' ``` {% tabs %} {% tab title="202: Accepted - Request acknowledged for processing" %} ```json { "code": 202, "status": "accepted", "message": "Request Accepted", "data": { "internal_reference": "ELPREFA65BGTFR7NGUXM", "merchant_reference": "MCTREFT2WMNWZ23SBN6Y" } } ``` {% endtab %} {% tab title="400: Bad Request - Request is not formed as expected" %} ```json { "code": 400, "status": "error", "message": "bank_gu is not a valid provider code", "data": {} } ``` {% endtab %} {% endtabs %} ## Step 2: Handshake - Verify transaction {% hint style="info" %} The API will attempt to verify the transaction from your platform as described in [this](/funds-payout/getting-started.md#step-2-payout-verification-request) section. Ensure that the correct URL is configured on your merchant account and that you're handling the verification request appropriately. {% endhint %} ## 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](/utility-functions/handling-notifications-callbacks.md) to see how you should verify the signature(s) in the request headers and how to respond. {% tabs %} {% tab title="Successful Bank Payout" %} ```json { "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" } } ``` {% endtab %} {% tab title="Failed Bank Payout" %} ```json { "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" } } ``` {% endtab %} {% endtabs %}