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": "https://bvnk.com/success",
  "customerId": "12345abc",
  "flow": "PAYROLL",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.2",
    "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:

Field	Description	Type	Mandatory	Example
`requesterIpAddressflow`	The IP address of the entity requesting the transaction.	string	Yes	172.16.254.2

`partyDetails`	An array of objects, each representing a party involved in the transaction. Detailed structure is provided below.	string	Yes	See `partyDetails` structure below
`flow`	Specifies the type of flow for the transaction. Only possible value = `PAYROLL`	string	Yes	`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.

Field	Description	Type	Mandatory	Example
`type`	Identifies the party type. Only possible value = `BENEFICIARY`.	string	Yes	`BENEFICIARY`
`name`	The full name of the beneficiary including middle names. For payouts to a business, this should be the name of the entity receiving the funds.	string	Yes	`John Marion Hardy Doe`
`entityType`	Classifies the beneficiary. Only possible values = `INDIVIDUAL`.	string	Yes	`INDIVIDUAL`
`dateOfBirth`	The beneficiary's date of birth. The format should be`YYYY-MM-DD`	string	Yes	`1983-09-23`