API Reference

Recipients

A Recipient is a saved payout destination — a bank account registered under an opaque RCP_ code. Create recipients once, then send transfers to the code instead of repeating raw bank details.

Create a recipient

POST/v1/recipients

Resolves the account against NIBSS (sandbox resolver on test keys) and registers it under an RCP_ code. Idempotent on (bank_code, account_number) — a duplicate returns the existing recipient instead of erroring. The resolved account name is locked at creation; bank fields are immutable afterward.

Body parameters

namestringoptional

Friendly label, max 100 chars. Defaults to the resolved account name.

bank_codestringrequired

NIP bank code (3–6 digits).

account_numberstringrequired

10-digit NUBAN.

metadataobjectoptional

Arbitrary key/value pairs echoed back.

Response

201

recipient_codestring

Opaque RCP_ identifier. Use this in transfers.

namestring

Friendly label.

account_namestring

NIBSS-resolved account name.

account_numberstring

10-digit NUBAN.

bank_codestring

NIP bank code.

bank_namestring

Human-readable bank name.

activeboolean

False once soft-deleted.

metadataobject

Echoed metadata.

created_atstring

ISO-8601 timestamp.

updated_atstring

ISO-8601 timestamp.

Errors

INVALID_ACCOUNT400Account could not be resolved at the bank.

List recipients

GET/v1/recipients

Active-only by default. Pass active=false to include soft-deleted rows.

Query parameters

pageintegeroptional

Page number, 1-indexed.

per_pageintegeroptional

Results per page.

activebooleanoptional

Pass false to include soft-deleted recipients. Default true.

searchstringoptional

Fuzzy match across name and account name.

Response

200

dataarray<Recipient>

Array of recipient objects.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

Retrieve a recipient

GET/v1/recipients/:code

Returns the full recipient resource.

Path parameters

codestringrequired

The RCP_ recipient code.

Response

200

recipient_codestring

Opaque RCP_ identifier. Use this in transfers.

namestring

Friendly label.

account_namestring

NIBSS-resolved account name.

account_numberstring

10-digit NUBAN.

bank_codestring

NIP bank code.

bank_namestring

Human-readable bank name.

activeboolean

False once soft-deleted.

metadataobject

Echoed metadata.

created_atstring

ISO-8601 timestamp.

updated_atstring

ISO-8601 timestamp.

Update a recipient

PUT/v1/recipients/:code

Mutates name, metadata, or active. Bank account fields are immutable — to redirect to a different account, soft-delete and create a fresh recipient. Set active: true to reactivate a soft-deleted recipient.

Path parameters

codestringrequired

The RCP_ recipient code.

Body parameters

namestringoptional

New friendly label, max 100 chars.

metadataobjectoptional

Replacement metadata.

activebooleanoptional

Set false to deactivate, true to reactivate.

Response

200

recipient_codestring

Opaque RCP_ identifier.

namestring

Updated label.

activeboolean

Current active state.

Delete a recipient

DELETE/v1/recipients/:code

Sets active = false. Historical transfers still resolve via the code. Reactivate by PUTting active: true.

Path parameters

codestringrequired

The RCP_ recipient code.

Response

200

recipient_codestring

The deactivated recipient code.

activeboolean

Now false.