Supplying additional beneficiary data

When creating a payout, along with the standard request parameters mentioned here, you should include detailed information about the beneficiary under the complianceDetails object. Below is an example JSON payload illustrating how to embed beneficiary data within your payout API request:

  "merchantId": "f0206b3a-3fda-47c6-ac21-367a482f3498",
  "amount": 990,
  "currency": "USD",
  "reference": "REF1234",
  "type": "OUT",
  "expiryMinutes": 2880,
  "returnUrl": "",
  "customerId": "12345abc",
  "flow": "PAYROLL",
  "complianceDetails": {
    "requesterIpAddress": "",
    "partyDetails": [
        "type": "BENEFICIARY",
        "name": "John Marion Hardy Doe",
        "entityType": "INDIVIDUAL",
        "dateOfBirth": "1983-09-23"

Detailed Field Explanation

The table below outlines and explains the attributes within the complianceDetails object specifically related to the beneficiary data, including examples for a better understanding:

requesterIpAddressflowThe IP address of the entity requesting the transaction.stringYes172.16.254.2
partyDetailsAn array of objects, each representing a party involved in the transaction. Detailed structure is provided below.stringYesSee partyDetails structure below
flowSpecifies the type of flow for the transaction.
Only possible value = PAYROLL
  • PartyDetails Field Structure
    The partyDetails field specifies the details of the parties involved in the transaction. This field is an array where each element is an object containing information about an individual party, such as a beneficiary. This allows for including multiple parties in a single request if necessary.
typeIdentifies the party type.
Only possible value = BENEFICIARY.
nameThe full name of the beneficiary including middle names. For payouts to a business, this should be the name of the entity receiving the funds.stringYesJohn Marion Hardy Doe
entityTypeClassifies the beneficiary.
Only possible values = INDIVIDUAL.
dateOfBirthThe beneficiary's date of birth.
The format should beYYYY-MM-DD