Beneficiary Verification API Migration (UAE)

This is a 1:1 endpoint mapping between the legacy and new Beneficiary Verification API. Only the differences are highlighted; anything not mentioned remains the same.

Migration checklist

• Update the base URL.
• Add the x-tenant: UAE header to the request.
• Update the endpoint path per the mapping table below.
• No request-body or response-shape changes: the payload and the response are unchanged.
• Ensure the client's subscription includes Beneficiary Verification (see Footnotes).

Global changes (apply to all endpoints)

1. Authentication

Authentication is identical to the legacy flow: the Token, Refresh, and JWKS endpoints, formats, and status changes are the same. In short:

• Token: GET /api/v1.0/authentication/Token → POST /auth/api-keys/sessions (200 → 201)
• Refresh: GET /api/v1.0/authentication/Refresh → POST /auth/api-keys/sessions/refresh
• JWKS: GET /api/v1.0/authentication/Jwks → GET /auth/.well-known/jwks.json (no auth, no tenant header)

Use the resulting Authorization: Bearer <token> on the verify call below, plus x-tenant: UAE.

2. Beneficiary Verification

2.1 Verify (Match)

Request body

{
  "iban": "AE070331234567890123456",
  "beneficiaryName": "ABC Trading LLC"
}

• iban: required. 23-character UAE IBAN (AE + check digits). Case-insensitive; normalized to upper case server-side.
• beneficiaryName: optional, max 150 characters. Omit or send blank if you only want an account-existence check.

Response body (unchanged from legacy)

{
  "data": {
    "requestId": "bv_01hqnx2w8f",
    "result": "MATCH",
    "bank": {
      "englishName": "Gulf International Bank",
      "arabicName": "بنك الخليج الدولي",
      "bankCode": "033"
    },
    "beneficiaryName": "ABC TRADING LLC",
    "inputBeneficiaryName": "ABC Trading LLC",
    "accountIdentifier": "AE070331234567890123456",
    "accountStatus": "Account Active and Available",
    "executionDate": "2026-07-31T10:15:00+00:00"
  }
}

• result: MATCH, NO_MATCH, or ERROR. null when the outcome is an error (errorDescription is populated instead). Values unchanged from legacy.
• errorDescription: present only on a non-pass; a human-readable message, not a raw provider code.
• accountIdentifier: the verified IBAN, echoed back. Field name unchanged from legacy.
• Null fields are omitted from the response in both APIs.

Quick reference: full endpoint map

Migrated endpoints (legacy → new)

Footnotes

1. Response envelope: the response is wrapped in a { "data": ... } envelope. Null fields are omitted in both the legacy and new APIs.
2. Error format: error responses follow the same structure across both APIs: { "error": "...", "errorDescription": "..." }. Business-level non-passes (for example a closed or mismatched account) still return 200 OK with result and errorDescription inside data; transport and validation failures use the usual 400 / 401 / 403 / 429 / 500 codes.
3. Entitlement: the endpoint is gated by the Beneficiary Verification subscription. If a client's plan doesn't include it, the call returns 403 Forbidden. Confirm the client is subscribed before cutover.
4. Result semantics: MATCH means name and account confirmed; NO_MATCH means the account resolved but the name did not match; ERROR means the account could not be verified (result is null, see errorDescription). These match the legacy semantics exactly.
5. Rate limiting: rate limits are enforced per endpoint and are unchanged from legacy.
6. Support: for migration questions or issues, contact support at support@tryspare.com.