Create A Beneficiary

The API is utilized to create a beneficiary within the account. Once registered, the beneficiary ID can be used to send payment instructions.

POST /payments/beneficiaries

Body Parameters Request

Name	Type	Format / Values	Description	Required
entity_type	string	BUSINESS, INDIVIDUAL	The beneficiary's type.
id	string		The beneficiary ID serves as the unique identifier for this beneficiary contact on the platform.
country	string	/^[A-Z]{2,2}$/	Bank country code (2-letter ISO 3166-2 country code).	Yes
currency	string	/^[A-Z]{3,3}$/	Account currency (3-letter ISO 4217 currency code).	Yes
tags	object
user_tags	object
entity	object			Yes
bank_details	object			Yes

Body Parameters Response

Name	Type	Description
active	boolean	Is this beneficiary active
name	string	A custom display name
bank_details	object	Bank account attributes
country	string	The 2 letter ISO country code this beneficiaries account is located in
currency	string	The 3 letter ISO currency code this beneficiaries bank account is setup to receive
entity	object	Beneficiary owning entity attributes
id	string	Unique id of beneficiary
type	string	Entity type (contact)
user_tags	object	A set of K/V pairs the beneficiary has been tagged with

Request Example

POST /payments/beneficiaries
{
   "entity_type": "INDIVIDUAL",
   "country": "US",
   "currency": "USD",
   "user_tags": {
      "department": "R&D",
      "cost_center": "US"
   },
   "entity": {
      "individual_first_name": "Smith",
      "individual_last_name": "Johny",
      "date_of_birth": "1970-01-01",
      "address_line_1": "944 Fairfield Street",
      "address_city": "Los Angeles",
      "address_country": "US",
      "address_country_subdivision": "CA",
      "address_postal_code": "90210"
   },
   "bank_details": {
      "account_name": "John Smith",
      "account_number": "1234567",
      "bank_code": "123456789",
      "bank_name": "Bank of America ",
      "bank_identifier_code": "BOFAUS22XXX"
   }
}

Response Examples

201 - Created

{
   "type": "contact",
   "id": "GHXY5QuJRxSIrfkfcaBzUg",
   "currency": "USD",
   "country": "US",
   "bank_details": {
      "account_country": "US",
      "account_name": "John Smith",
      "account_number": "1234567",
      "bank_code": "123456789",
      "bank_identifier_code": "BOFAUS22XXX",
      "bank_name": "Bank of America "
   },
   "entity": {
      "address_city": "Los Angeles",
      "address_country": "US",
      "address_country_subdivision": "CA",
      "address_line_1": "944 Fairfield Street",
      "address_postal_code": "90210",
      "date_of_birth": "1970-01-01",
      "individual_first_name": "Smith",
      "individual_last_name": "Johny"
   },
   "user_tags": {
      "department": "R&D",
      "cost_center": "US"
   },
   "active": false
}

400 - Bad Request

{
  "error": "bad_request",
  "description": "Validation errors: {\"type\":\"INDIVIDUAL\",\"id\":\"5SYjAkHqXHW0Z2cqBRW4JAAA\",\"cou... at root failed with \"Missing property org_id\"",
  "error_code": 400
}