# Add and Manage Beneficiary Accounts

Adding a beneficiary is a critical step in any payment workflow. With XYB’s Beneficiary APIs, developers can securely collect, verify, and manage recipient details, adapting to local compliance rules across countries and payment types.

Instead of hardcoding forms for every region, you can use our API to dynamically fetch required fields, validate inputs, and keep your front-end flexible.

***

### Workflow Overview

Here’s how you should implement beneficiary creation in your system:

| Step                                      | Description                                                                                                              | API                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| 1. Identify Customer                      | Assign or generate an `identityReference` for the logged-in customer. This will link all beneficiaries to that customer. | *Handled by your system*                                                   |
| 2. Fetch Dynamic Field Requirements       | Get the required fields (based on country, currency, payment method) for account creation.                               | `GET /api/v1/fields/{identityReference}/contact-account`                   |
| 3. Build the Beneficiary Form             | Dynamically render the form based on the above specs. Some fields may be mandatory, optional, or conditional.            | Front-end logic                                                            |
| 4. Submit Beneficiary                     | Send beneficiary data to create them.                                                                                    | `POST /api/v1/beneficiary/identity/{identityReference}`                    |
| 5. Handle Dynamic Coordinates (if needed) | For payment types like SWIFT/BSB, collect additional fields via dynamic schema.                                          | `POST /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates` |
| 6. (Optional) Verify with OTP             | Some beneficiary account types require OTP verification before activation.                                               | `GET` + `POST` verification endpoints                                      |
| 7. Ready for Payment                      | Once verified and stored, the beneficiary and their accounts can be used in any payment request.                         |                                                                            |

***

### Fetch Dynamic Field Specifications

Use this endpoint to get field requirements based on `identityReference`:

```
GET /api/v1/fields/{identityReference}/contact-account
```

#### Response

```json
{
  "groups": [
    {
      "label": "Bank Details",
      "fields": [
        {
          "name": "iban",
          "label": "IBAN",
          "required": true,
          "type": "string",
          "validation": { "regex": "..." }
        },
        {
          "name": "bic",
          "label": "BIC",
          "required": false,
          "type": "string"
        }
      ]
    }
  ]
}
```

#### What to Do

Render a form based on this JSON. Required fields should be validated and included in your `POST` request. Optional fields can be skipped.

***

### Create a Beneficiary

```
POST /api/v1/beneficiary/identity/{identityReference}
```

#### Sample Request Body

```json
{
  "first_name": "Alice",
  "last_name": "Smith",
  "organization_name": null,
  "contacts": [
    {
      "email": "alice@example.com",
      "mobile_prefix": "+44",
      "mobile_number": "7000000000"
    }
  ],
  "addresses": [
    {
      "address": "123 Main St",
      "city": "London",
      "country": "GB",
      "post_code": "W1A 1AA"
    }
  ],
  "coordinates": {
    "banking": {
      "iban": "GB82WEST12345698765432"
    },
    "currency_code": "EUR"
  }
}
```

#### Required Fields

* At least one name field: `first_name` or `organization_name`
* At least one account coordinate
* Optionally include contact and address for verification or policy requirements

***

### Optional: Add Dynamic Coordinates

If the country or currency requires additional information:

```
POST /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates
```

Use this if the earlier coordinate creation step requires extra dynamic fields like:

* BSB codes (Australia)
* SWIFT codes (international wires)
* IFSC codes (India)

The `CreateBeneficiaryCoordinateDynamicRequest` format will match what was returned in dynamic specs.

***

### OTP Verification (If Required)

Some destinations require user verification (e.g., SMS OTP):

**Send OTP**

```
GET /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification
```

**Submit OTP**

```
POST /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}
{
  "otp": "123456"
}
```

***

### Final Validation

Before using the beneficiary in a payment, validate their data against the target payment route:

```
POST /api/v1/fields/{identityReference}/payment/validate
```

This ensures:

* All required fields are populated
* No regulatory violations
* The beneficiary is ready to receive money

***

Bonus: Video – Integrating Beneficiary Flow into Send Money UI

> [Watch Video: Building a Beneficiary Form and Connecting to Payment Flow](https://chatgpt.com/g/g-p-67f79876be508191bbaafa9de483213f-ultimate-payments/c/67fcc1f8-16b8-8005-838a-ae5262dab908#)

This short tutorial walks you through:

* Creating a customer ID (`identityReference`)
* Dynamically building a form using `/contact-account` specs
* Submitting the beneficiary
* Using them in a real payment request

***

### Key Reminders

* Store the `beneficiary_id` and `beneficiary_account_id` after creation
* A single `identityReference` may have multiple beneficiaries
* Dynamic specs are region-, currency-, and policy-aware. Use them instead of hardcoding


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xyb.co/xyb-payments/payment-setup/add-and-manage-beneficiary-accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.