Update Beneficiary Details

The API creates or modifies existing beneficiary records with the provided beneficiary ID.

You can only update a key’s owner record when you call with a beneficiary Key.

PUT /payments/beneficiaries/{id}

Body Parameters Request

Name	Type	Format / Values	Description	Required
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

PUT /payments/beneficiaries/my_id_22
{
   "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 "
   }
}

Response Examples

200 - Successful update

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

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
}