Save a beneficiary

Save a recipient. The response carries the name-check result and the screening state, so a mismatch is visible immediately rather than at the first payout.

Authorization

OAuth2PasswordBearer

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

label*Label

What you call this recipient. Shown in your lists; ours to display and never to match on.

Length1 <= length <= 140

Example"Rwanda Metal Works — settlement"

full_name*Full Name

The name on the account. This is the one that gets checked: we ask the rail who owns the account and compare, and the answer comes back in validation_status and account_name_returned.

Length1 <= length <= 200

Example"Rwanda Metal Works Ltd"

type*BeneficiaryType

What kind of account this is.

Example"bank"

Value in

"mobile_money"
"bank"
"card"

account_identifier*Account Identifier

The account itself — a wallet number, a bank account number, a card token. Saving the same account twice is a 409: pay the beneficiary you have rather than making a second one, which would carry its own separate screening state.

Length1 <= length <= 128

Example"00040100123456789"

currency*Currency

What this recipient is paid in.

Length3 <= length <= 3

Example"RWF"

country_code*Country Code

ISO 3166-1 alpha-2. Decides the corridor.

Length2 <= length <= 2

Example"RW"

destination?||

Where the money goes. Omit it when you send beneficiary_id — a saved beneficiary carries its own.

The shape depends on method. These are the shapes our rails read; the field itself is not yet validated against them, so a mistyped key is accepted here and fails at the rail. If you want the account checked before anything is committed, save a beneficiary and pay that instead — it is name-checked and screened.

bank_name?|

The bank, as it is written on the account.

Example"Banque de Kigali"

Response Body

`application/json`

curl -X POST "https://example.com/api/b/v1/beneficiaries" \  -H "Content-Type: application/json" \  -d '{    "label": "Rwanda Metal Works — settlement",    "full_name": "Rwanda Metal Works Ltd",    "type": "bank",    "account_identifier": "00040100123456789",    "currency": "RWF",    "country_code": "RW"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "label": "string",  "full_name": "string",  "type": "string",  "currency": "string",  "country_code": "string",  "account_identifier": "string",  "bank_name": "string",  "validation_status": "unchecked",  "account_name_returned": "string",  "screening_status": "unscreened",  "screening_notes": "string",  "screened_at": "2019-08-24T14:15:22Z",  "reviewed_at": "2019-08-24T14:15:22Z",  "payable": true,  "archived_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}

Authorization

Cookie Parameters

Request Body

Response Body

201application/json

400application/json

409application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`