Recipient-Management

From Barion Documentation
Revision as of 17:24, 28 May 2026 by [email protected] (talk | contribs) (Created page with "{{PageTitle|title=Recipient Management}} {| style="margin-left:2em;" align="right" | __TOC__ |} 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 r...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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 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

Payout methods

Data types