showDeleted=true query parameter on the GET /v6/recipients endpoint.Recipient-Management
Recipient Management
The Recipient Management API allows wallets to store and manage the details of individuals or businesses to whom withdrawals can be sent. A recipient holds personal or company name information and can have one or more payout methods (e.g. bank account details) associated with them. Once a recipient is created, they can be referenced in withdrawal requests without having to re-supply their full details each time.
Prerequisites
Before using the Recipient Management API:
- You must register a Barion wallet at the Barion website or in the Sandbox environment. Learn more about the Sandbox environment here.
- Authentication is required for every request. Each endpoint accepts a wallet key. For details see Calling the Barion API.
Core concepts
Recipient
A recipient represents a person or company that can receive a withdrawal from your wallet. Each recipient has a recipientType of either individual or business, and the corresponding name fields (firstName / lastName or companyName) must be provided accordingly.
Every recipient is identified by a unique ID with the format rcp_<ordered-base64-ulid>.
Payout method
A payout method defines the channel through which money can be sent to a recipient. Currently the only supported method type is bank_transfer.
A recipient can have multiple payout methods. Each payout method is identified by a unique ID with the format pout_<ordered-base64-ulid>.
For the full structure of payout method objects see how they look in requests or responses.
Typical workflow
Creating a recipient with a payout method
- Create a recipient by sending a POST request to
/v6/recipients. You can optionally include apayoutMethodobject to attach a payout method in a single step. On success, the response contains the newrecipientIdand, if a payout method was provided, the newpayoutMethodId. - If the recipient was created without a payout method, or if you need to add more payout methods later, send a POST request to
/v6/recipients/{recipientid}/payout-methods. - Store the returned
recipientIdandpayoutMethodIdvalues in your system. These IDs are required for payout requests.
Listing and searching recipients
Use GET /v6/recipients to retrieve the recipients of your wallet. The endpoint supports:
- Search by display name (
searchparameter, case-insensitive). - Paging via a cursor (
cursorandlimitparameters). - Change tracking to detect newly created, modified, or deleted recipients since a given date (
afterModifiedDateparameter). - Showing deleted records by setting
showDeleted=true.
Updating a recipient
To correct or update the name details of an existing recipient, send a PATCH request to /v6/recipients/{recipientid}. A successful update returns HTTP 204 No Content.
Deleting a recipient or payout method
- To remove a specific payout method from a recipient, send a DELETE request to
/v6/recipients/{recipientid}/payout-methods/{payoutmethodid}. - To remove an entire recipient (and all of their associated payout methods), send a DELETE request to
/v6/recipients/{recipientid}.
Both operations return HTTP 204 No Content on success.
Idempotency
The POST /v6/recipients and POST /v6/recipients/{recipientid}/payout-methods endpoints support an optional Idempotency-Key header (GUID). Supplying the same key on a retry will return the original response instead of creating a duplicate record. This is recommended for all creation requests to ensure safe retries in case of network errors.
Reference
Recipients
- GET /v6/recipients — List or search recipients
- GET /v6/recipients/{recipientid} — Get a single recipient
- POST /v6/recipients — Create a new recipient
- PATCH /v6/recipients/{recipientid} — Update a recipient's name
- DELETE /v6/recipients/{recipientid} — Delete a recipient
Payout methods
- GET /v6/recipients/{recipientid}/payout-methods — List payout methods of a recipient
- POST /v6/recipients/{recipientid}/payout-methods — Add a payout method to a recipient
- DELETE /v6/recipients/{recipientid}/payout-methods/{payoutmethodid} — Delete a payout method
Data types
- PayoutMethod-Request — Bank transfer payout method object structure in a request
- PayoutMethod-Response — Bank transfer payout method object structure in a response