Beneficiaries API

Manage saved beneficiaries for streamlined payout creation. Saving beneficiary information allows you to reuse it for recurring payments without re-entering details each time.

Endpoints Overview

Method	Endpoint	Description
GET	`/api/v1/beneficiaries`	List all beneficiaries
POST	`/api/v1/beneficiaries`	Create a new beneficiary
GET	`/api/v1/beneficiaries/:id`	Get beneficiary details
DELETE	`/api/v1/beneficiaries/:id`	Delete a beneficiary

List Beneficiaries

Retrieve a paginated list of saved beneficiaries.

Endpoint

GET /api/v1/beneficiaries

Authentication: Bearer token required

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page (max: 100)
`search`	string	-	Search by email or name
`sort_by`	string	`created_at`	Sort field
`sort_order`	string	`DESC`	Sort direction (`ASC` or `DESC`)

Response

Status Code: 200 OK

Response Headers:

X-Page: 1
X-Per-Page: 20
X-Total-Count: 45
X-Total-Pages: 3

Response Body:

[
  {
    "id": "ben_abc123xyz",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "phone": "+1234567890",
    "metadata": {
      "employee_id": "EMP001",
      "department": "Engineering"
    },
    "total_payouts": 5,
    "total_amount": 500.00,
    "last_payout_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

Pagination Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total number of beneficiaries
`X-Total-Pages`	Total number of pages

Example

curl -X GET "{{host}}/api/v1/beneficiaries?page=1&limit=20" \
  -H "Authorization: Bearer your_access_token"

<?php
function listBeneficiaries($accessToken, $page = 1, $limit = 20) {
    $url = "{{host}}/api/v1/beneficiaries?page=$page&limit=$limit";

    $options = [
        'http' => [
            'header' => "Authorization: Bearer $accessToken",
            'method' => 'GET'
        ]
    ];

    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);

    // Get pagination from response headers
    $headers = $http_response_header;
    $pagination = [];
    foreach ($headers as $header) {
        if (strpos($header, 'X-Total-Count:') === 0) {
            $pagination['total'] = (int) trim(substr($header, 14));
        }
        if (strpos($header, 'X-Total-Pages:') === 0) {
            $pagination['total_pages'] = (int) trim(substr($header, 14));
        }
    }

    return [
        'beneficiaries' => json_decode($result, true),
        'pagination' => $pagination
    ];
}

// Usage
$response = listBeneficiaries('your_access_token');

foreach ($response['beneficiaries'] as $beneficiary) {
    echo $beneficiary['first_name'] . ' ' . $beneficiary['last_name'] . "\n";
    echo "  Email: " . $beneficiary['email'] . "\n";
    echo "  Total Payouts: " . $beneficiary['total_payouts'] . "\n";
}
?>

Create Beneficiary

Save a new beneficiary for future payouts.

Endpoint

POST /api/v1/beneficiaries

Authentication: Bearer token required

Request Body

{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "country": "US",
  "phone": "+1234567890",
  "metadata": {
    "employee_id": "EMP001",
    "department": "Engineering"
  }
}

Field Descriptions

Field	Type	Required	Description
`email`	string	Yes	Beneficiary email address
`first_name`	string	Yes	Beneficiary first name
`last_name`	string	Yes	Beneficiary last name
`country`	string	No	Country code (ISO 3166-1 alpha-2)
`phone`	string	No	Phone number with country code
`metadata`	object	No	Custom metadata for your reference

Response

Status Code: 201 Created

{
  "id": "ben_abc123xyz",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "country": "US",
  "phone": "+1234567890",
  "metadata": {
    "employee_id": "EMP001",
    "department": "Engineering"
  },
  "total_payouts": 0,
  "total_amount": 0,
  "last_payout_at": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Error Responses

400 Bad Request - Validation Error

{
  "error": "ValidationException",
  "message": "email is required"
}

400 Bad Request - Invalid Email

{
  "error": "ValidationException",
  "message": "Invalid email format"
}

Example

curl -X POST "{{host}}/api/v1/beneficiaries" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "metadata": {
      "employee_id": "EMP001"
    }
  }'

<?php
function createBeneficiary($accessToken, $data) {
    $url = '{{host}}/api/v1/beneficiaries';

    $options = [
        'http' => [
            'header' => [
                "Content-Type: application/json",
                "Authorization: Bearer $accessToken"
            ],
            'method' => 'POST',
            'content' => json_encode($data)
        ]
    ];

    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);

    return json_decode($result, true);
}

// Usage
$beneficiary = createBeneficiary('your_access_token', [
    'email' => 'john.doe@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'country' => 'US',
    'metadata' => [
        'employee_id' => 'EMP001'
    ]
]);

echo "Created beneficiary: " . $beneficiary['id'] . "\n";
?>

Get Beneficiary

Retrieve details of a specific beneficiary.

Endpoint

GET /api/v1/beneficiaries/:id

Authentication: Bearer token required

Path Parameters

Parameter	Type	Description
`id`	string	Beneficiary public ID

Response

Status Code: 200 OK

{
  "id": "ben_abc123xyz",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "country": "US",
  "phone": "+1234567890",
  "metadata": {
    "employee_id": "EMP001",
    "department": "Engineering"
  },
  "total_payouts": 5,
  "total_amount": 500.00,
  "last_payout_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T00:00:00Z"
}

Error Responses

404 Not Found

{
  "error": "NotFound",
  "message": "Beneficiary not found"
}

Example

curl -X GET "{{host}}/api/v1/beneficiaries/ben_abc123xyz" \
  -H "Authorization: Bearer your_access_token"

Delete Beneficiary

Remove a saved beneficiary. This does not affect historical payout records.

Endpoint

DELETE /api/v1/beneficiaries/:id

Authentication: Bearer token required

Path Parameters

Parameter	Type	Description
`id`	string	Beneficiary public ID

Response

Status Code: 204 No Content

No response body on success.

Error Responses

404 Not Found

{
  "error": "NotFound",
  "message": "Beneficiary not found"
}

Example

curl -X DELETE "{{host}}/api/v1/beneficiaries/ben_abc123xyz" \
  -H "Authorization: Bearer your_access_token"

Best Practices

Store beneficiary IDs - Save the returned id to reference beneficiaries in future payouts
Handle duplicates - Check for existing beneficiaries before creating new ones
Use metadata - Store custom reference data (employee IDs, department codes) in the metadata field

Create Payout - Use beneficiary IDs when creating payouts

Beneficiaries API

On this page