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

{
  "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

{
  "first_name": "Alice",
  "last_name": "Smith",
  "organization_name": null,
  "contacts": [
    {
      "email": "[email protected]",
      "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

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