Recipient-Management: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
[email protected] (talk | contribs)
[email protected] (talk | contribs)
 
Line 67: Line 67:




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.
Supplying the same key on a retry will return the original successful response instead of creating a duplicate record. This is recommended for all creation requests to ensure safe retries in case of network errors.


== Reference ==
== Reference ==

Latest revision as of 07:35, 9 June 2026

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

  1. Create a recipient by sending a POST request to /v6/recipients. You can optionally include a payoutMethod object to attach a payout method in a single step. On success, the response contains the new recipientId and, if a payout method was provided, the new payoutMethodId.
  2. 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.
  3. Store the returned recipientId and payoutMethodId values 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 (search parameter, case-insensitive).
  • Paging via a cursor (cursor and limit parameters).
  • Change tracking to detect newly created, modified, or deleted recipients since a given date (afterModifiedDate parameter).
  • 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

Both operations return HTTP 204 No Content on success.

IMPORTANT
Deleted recipients and payout methods are soft-deleted. They can still be retrieved by using the showDeleted=true query parameter on the GET /v6/recipients endpoint.

Idempotency

The following endpoints support an optional Idempotency-Key header.

The value must be a GUID.

Recipients

Payout methods


Supplying the same key on a retry will return the original successful 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

Payout methods

Data types