Handling the beneficiary 'change_required' state

A beneficiary may transition to the change_required state when additional information or corrections are required before it can be used for transfers.

When a beneficiary enters this state:

• The beneficiary cannot be used to create transfers.
• A webhook is sent notifying you of the state change.
• Both the webhook payload and beneficiary query responses include a changes_required array identifying the fields that require updates.

The changes_required Field

The changes_required field is an array of beneficiary field names that require updates before the beneficiary can be verified again.

Example:

{
  "state": "change_required",
  "changes_required": [
    "account_type"
  ]
}

You should use the changes_required array to determine which fields of the beneficiary to update.

Receiving Notifications

When a beneficiary transitions to the change_required state, a webhook is sent containing the updated beneficiary, including the state and the changes_required array.

The same changes_required field is also returned when querying a beneficiary.

Example payload/response:

{
  "changes_required": [
    "account_type"
  ],
  "id": "22c1aad9-XXXX-288b8e346",
  "name": "John Smith",
  "bank_city": "Austin",
  "currency": "USD",
  "email": "[email protected]",
  "bank_name": "Chase Bank",
  "account_type": "checking",
  "organization_id": "1234123-XXXX-22befea",
  "phone": "",
  "country": "US",
  "name_on_bank_account": "John Smith",
  "bank_state_province_region": "Texas",
  "bank_country": "US",
  "routing_code": "111000614",
  "bank_postal_code": "78702",
  "account_number": "1234567890",
  "postal_code": "78702",
  "bank_address1": "123 S. Congress Ave",
  "city": "Austin",
  "state": "change_required",
  "user_id": "bb4fe475-XXXX-36159783",
  "bank_address2": "",
  "subscription_type": "beneficiary",
  "entity_id": "741cdcf6-4ae7-4cab-a288-61b832394a86",
  "type": "personal",
  "address1": "123 S. Congress Ave",
  "state_province_region": "TX"
}

Updating the Beneficiary

Update the fields listed in the changes_required array using the updateBeneficiary mutation.

After the required information has been submitted and successfully verified, the beneficiary returns to the verified state and can once again be used to create transfers.

For details on updating beneficiary fields, see the updateBeneficiary documentation.

Lifecycle

A beneficiary typically follows this lifecycle:

1. The beneficiary is in the verified state and can be used to create transfers.
2. If additional information or corrections are required, the beneficiary transitions to the change_required state.
3. While in the change_required state, the beneficiary cannot be used to create transfers.
4. Update the fields listed in the changes_required array using the updateBeneficiary mutation.
5. After the updated information has been reviewed and verified, the beneficiary returns to the verified state and can once again be used to create transfers.