Recipient-Management

From Barion Documentation
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 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