Create A Beneficiary

Before you can initiate a fx conversion and payout to a beneficiary, you need the beneficiary id during fx creation. The beneficiary id can be gotten after a beneficiary is created using the create a beneficiary endpoint.

{
"beneficiaryEntityType": "individual",
"accountNumber": "9090961234",
"beneficiaryCountryCode": "NG",
"country": "Nigeria",
"beneficiaryFirstName": "Winning",
"beneficiaryLast": "Winning",
"nationalId": "00123",
"currency": "NGN",
"clientReference": "Test-Bene100"
}

Once the beneficiary is created, you will get a beneficiary id that can be used during payout creation.

{
  "success": true,
  "account": {
    "id": 284,
    "accountNumber": "9090961234",
    "bankName": "PUNJAB NATIONAL BANK",
    "beneficiaryAddress": "",
    "beneficiaryCity": "",
    "beneficiaryFirstName": "Winning",
    "beneficiaryLast": "Winning",
    "beneficiaryCountryCode": "NG",
    "beneficiaryEntityType": "individual",
    "country": "Nigeria",
    "reference": "RP-09062022-003",
    "beneficiaryFirstName": "",
    "beneficiaryLastName": "",
    "nationalId": "00123",
    "currency": "NGN",
    "clientReference": "Test-Bene100",
    "status": "approved"
  }
}

Validate account details (optional and is only needed for NG beneficiaries for local payouts)

Before creating a beneficiary you want to validate the account details gotten are correct and confirm to the user that the account belongs to the person they intend to send to.

You can achieve this by passing the account number and code of the bank they intend to send funds.

//request

{
    "bankCountry": "NG",
    "bankCode": "000003",
    "accountNumber": "4713920010"
}

This request will return the name of the beneficiary linked to the account. The name of the account can be displayed to the user for confirmation purposes.

//response
{
    "bankCountry": "NG",
    "bankCode": "000003",
    "accountNumber": "4713920010",
    "accountName": "TOFINE LOGISTICS SERVICES LIMITED"
}

For NGN, you can find the list of bank codes for the banks here.