Payouts APIs
1. Fund your Fincra wallet
You can fund your wallet by making deposits into the virtual account generated for your business or by requesting a manual top-up. Learn more about [creating a virtual account] and funding your account to make the most of our virtual account collection method.
Note
For test transactions, you must fund your sandbox account. For more information on how to achieve this, please see the test section
2. Collect payment information
To initiate the transaction, you'll need to obtain and pass the relevant information about your payout like the beneficiary information, amount, sender information (in some cases) etc.
See all fields used in making a payout request.
| Field | Mandatory | Type | Description |
|---|---|---|---|
| business | Yes | String | The ID of the business making the payout. You can get this from your Account page on the merchant portal. |
| sourceCurrency | Yes | String | The currency which is used to fund the payout. |
| destinationCurrency | Yes | String | The currency in which the recipient will be receiving funds. For cross currency payouts, this value will vary from the |
| amount | Yes | String | The value that is to be transferred from the source currency wallet. |
| description | Yes | String | A simple description of payment e.g "From Daniella” |
| paymentDestination | Yes | String | This is the type of account you want to send your payments to, see [payment destinations](# Payment Destinations) for more details. |
| customerReference | Yes | String | The transaction's unique identifier on your system. Customer references prevent duplicate transactions. We advise that you add it to your payload |
| quoteReference | No | String | This is the reference generated when the source currency is compared against the destination currency. This is required for cross-currency payouts. You can generate a quote using the |
| sender | Conditional | Object | The details of the customer initiating the payout |
| sender.name | Conditional | String | The customer's full name. This name would show up in the transfer narration. |
| sender.email | Conditional | String | The customer's email. |
| beneficiary | Yes | Object | The recipient of the funds. Depending on the currency and beneficiary type, the properties of the beneficiaries are different. |
| beneficiary.firstName | Yes | String | The first name of the beneficiary. |
| beneficiary.lastName | Yes | String | The last name of the beneficiary. |
| beneficiary.accountHolderName | Yes | String | This field is required by all type of beneficiaries. |
| beneficiary.accountNumber | Yes | String | |
| beneficiary.country | Yes | String | The country in which the bank of the beneficiary is located. This field should be according to ISO 3166-1 alpha-2 codes standards e.g NG, GB |
| beneficiary.email | No | String | The beneficiary's email. |
| beneficiary.phone | No | String | |
| beneficiary.type | Yes | String | The type of beneficiary, see beneficiary types for more details |
| beneficiary.bankCode | Conditional | String | The beneficiary bank code. To get the bank code please see the list banks endpoint codes for more details. |
| beneficiary.mobileMoneyCode | |||
3. Initiate Payout
Using the fields collected, make a POST request to our Payout API. Depending on the type of beneficiary and the account's currency, you might need to give some extra information. See sample payloads for each currency
{
"business": "{{The business ID}}",
"sourceCurrency": "GBP",
"destinationCurrency": "GBP",
"amount": "1000",
"description": "i want to pay my vendor",
"paymentDestination": "bank_account",
"customerReference": "{{$randomUUID}}",
"beneficiary": {
"firstName": "Hassan",
"lastName": "Sarz",
"accountHolderName": "Hassan Sarz",
"country": "NG",
"phone": "0803443433",
"accountNumber": "GBXXCLJU04130780008933",
"type": "individual",
"email": "[email protected]",
"sortCode": "00000",
"bankSwiftCode": "UBSWCHZH80A"//required for Chaps payment scheme only
},
"paymentScheme": "{{paymentScheme}}",
"quoteReference": "d187b2fa-27cd-43e6-b622-66361e409c6d"
}
Updated 29 days ago