Payout methods

Keeping your beneficiaries’ payout method details in sync means keeping their recipient records - the API objects that store each individual payout method - up to date.

​

Real-time updates

To maintain the most current recipient information, we strongly advise setting up webhooks and subscribing to RECIPIENT.* event types. This ensures your system is immediately notified of any changes or updates to recipient details, such as when a beneficiary adds, updates, or removes their information through a management session.

For detailed instructions on how to set up and manage webhooks, please refer to our webhooks guide.

​

Retrieving recipient data via API

While webhooks notify you of changes, the way to get the complete, updated recipient details is to call the API after you receive a relevant webhook event.

​

1. Get Recipient by ID

After receiving a webhook for a specific recipient, you should use the id from the webhook event to retrieve their full, updated details. This is the most direct way to get the latest information because all RECIPIENT.* webhook events include the id of the affected recipient.

GET /beneficiaries/organizations/recipients/{recipientId}

{
    "id": "06726a35-9f90-49b9-a5ef-0a1d97d28ff5",
    "externalUserId": "d6189905-7fd5-4e79-9496-8f62184649c6",
    "country": "US",
    "currency": "USD",
    "method": "BANK_ACCOUNT",
    "isDefault": false,
    "creditorAgent": {
        "clearingSystemMemberId": {
            "memberId": "021000021"
        }
    },
    "creditorAccount": {
        "id": {
            "value": "12345678",
            "type": "ACCOUNT_NUMBER"
        },
        "type": "CHECKING"
    },
    "creditor": {
        "type": "INDIVIDUAL",
        "name": "John Doe",
        "address": {
            "addressLine1": "620 8th Ave",
            "townName": "New York",
            "postCode": "10018",
            "countrySubdivision": "NY",
            "country": "US"
        },
        "documents": []
    }
}

​

2. List recipients by external user ID

You can retrieve all recipients associated with a specific one of your end-users using the ID you provided when creating the management session. This endpoint is helpful if you want to synchronize the state of all recipients for a given end-user or to simply list all recipients they have added.

GET /beneficiaries/organizations/recipients

Query parameters:

{
  "items": [
    {
        "id": "6f10711d-15b1-466f-ae5b-68ee81ac5f51",
        "externalUserId": "d6189905-7fd5-4e79-9496-8f62184649c6",
        ...
    },
    {
        "id": "06726a35-9f90-49b9-a5ef-0a1d97d28ff5",
        "externalUserId": "d6189905-7fd5-4e79-9496-8f62184649c6",
        ...
    },
  ]
}