Payees

Beneficiaries

Storing a payee once removes the largest and most error-prone part of the payment payload, and lets you confirm the account exists before you ever move money.

Store

POST /beneficiaries takes the party, the account and the agent. For an organisation use type: "ORGA"; for a person, type: "INDV", where identification accepts nationalId, passportNumber or dateAndPlaceOfBirth.

{
  "reference": "MERIDIAN-TEXTILES",
  "type": "ORGA",
  "name": "Meridian Textiles Pvt Ltd",
  "address": {
    "streetName": "Trade Centre", "buildingNumber": "402",
    "postCode": "400051", "townName": "Mumbai",
    "countrySubDivision": "Maharashtra", "country": "IN"
  },
  "identification": { "taxId": "AAACM1234F", "lei": "3358005XXXXXXXXXXXXX" },
  "contact": { "email": "ap@meridiantextiles.in", "phone": "+912266778899" },
  "account": { "scheme": "IN_ACCOUNT", "id": "50100234567890", "currency": "INR" },
  "agent": {
    "clearingSystem": "INIFSC", "clearingSystemMemberId": "HDFC0000123",
    "bic": "HDFCINBBXXX", "name": "HDFC Bank", "country": "IN"
  },
  "defaultPurpose": "GDDS",
  "metadata": { "supplierCode": "SUP-4471", "costCentre": "CC-EMEA-07" }
}

The response returns corridors — the pairs this payee can be used on, derived from the account and agent — and masks the account number on every subsequent read.

Validate — Confirmation of Payee

POST /beneficiaries/{id}/validate checks that the account exists and that the name matches, before money moves. On corridors that support it, this is the single largest lever on your AC03 rejection rate.

`result`	What it means	What to do
`MATCH`	Account is active and the name matches.	Proceed.
`CLOSE_MATCH`	`accountHolderName` is returned so a human can decide. Typically a legal-name variant.	Queue for review; do not auto-proceed on high value.
`NO_MATCH`	The account exists, the name does not match.	Stop. Confirm details out of band.
`ACCOUNT_NOT_FOUND`	No such account at that agent.	Stop. The payment would fail `AC03`.
`ACCOUNT_CLOSED`	The account exists but is closed.	Stop. The payment would fail `AC04`.
`UNAVAILABLE`	This corridor does not support validation.	Proceed, and rely on your own controls.

Results carry expiresAt, typically thirty days. Re-validate before it lapses, and always after a beneficiary’s account or agent changes.

Reuse

With beneficiaryId on the payment, name, address, identification, account and agent are all resolved server-side. What remains is identity, amount and the corridor-specific fields.

json

{
  "endToEndId": "INV-2026-4471",
  "provider": "AUTO",
  "instructedAmount": { "currency": "USD", "value": "24500.00" },
  "debtorAccount": { "scheme": "US_ACCOUNT", "id": "8901234567" },
  "beneficiaryId": "ben_01J8M4TQ7X2K9",
  "purpose": "P0103",
  "remittanceInformation": { "unstructured": ["Invoice INV-2026-4471"] },
  "metadata": { "costCentre": "CC-EMEA-07" }
}

Update and deactivate

PATCH /beneficiaries/{id} updates in place. Changing the account or the agent resets validation to UNVALIDATED — re-run Confirmation of Payee before the next payment.
DELETE /beneficiaries/{id} deactivates rather than deletes. History is preserved: payments already made keep pointing at the payee they were made to.
GET /beneficiaries?q= searches by reference, name and account fragment, with cursor pagination.