Confirmation of Payee — API Guide 2 min read

Request headers

Query parameters

Request body

Content-Type: application/json

The Hub sends a plain JSON body — not a JWS. The body identifies a single account by IBAN, and carries nothing else. The name the TPP submitted is not sent to you: look the account up by IBAN and return the holders you have, and the Hub does the comparing.

data.account

Example

{
  "data": {
    "account": {
      "schemeName": "IBAN",
      "identification": "AE070331234567890123456"
    }
  }
}

Response

Content-Type: application/json

Return 200 in all lookup scenarios — whether the account is found or not. The Hub interprets the data array contents to determine the match result returned to the TPP.

200 — Account found

Return a data array containing one entry per account holder. id, name and accountStatus are the only required members of an entry.

accountStatus uses the same code set as status on the account resource returned by GET /accounts/{accountId}: Active, Inactive, Dormant, Unclaimed, Deceased, Suspended or Closed. A joint account MUST return the same value on every entry. The Hub returns it to the TPP as AccountStatus.

Personal account

name.fullName is mandatory and is the value the Hub matches on today. Every other name field is optional — supply givenName, middleName, familyName and alsoKnownAs where your systems hold them separately, so that improvements to the matching algorithm can use them without a further change to this contract. These are the names CustomerPersonClaims uses on GET /customer. A response carrying only fullName and accountStatus is fully conformant.

{
  "data": [
    {
      "id": "cust-001",
      "name": {
        "fullName": "Ahmed Al Mansouri",
        "givenName": "Ahmed",
        "familyName": "Al Mansouri"
      },
      "accountStatus": "Active"
    }
  ],
  "meta": {
    "totalPages": 1,
    "totalRecords": 1
  }
}

Personal account — minimum conformant response

{
  "data": [
    {
      "id": "cust-001",
      "name": {
        "fullName": "Ahmed Al Mansouri"
      },
      "accountStatus": "Active"
    }
  ],
  "meta": {
    "totalPages": 1,
    "totalRecords": 1
  }
}

Joint account

Return one entry per holder. The Hub evaluates every entry in data, so the order is not significant — do not attempt to place the most likely match first.

{
  "data": [
    {
      "id": "cust-001",
      "name": {
        "fullName": "Ahmed Al Mansouri",
        "givenName": "Ahmed",
        "familyName": "Al Mansouri"
      },
      "accountStatus": "Active"
    },
    {
      "id": "cust-002",
      "name": {
        "fullName": "Fatima Al Mansouri",
        "givenName": "Fatima",
        "familyName": "Al Mansouri"
      },
      "accountStatus": "Active"
    }
  ],
  "meta": {
    "totalPages": 1,
    "totalRecords": 2
  }
}

Business account

Populate name.businessName with the registered business name on the account. alsoKnownAs is optional.

{
  "data": [
    {
      "id": "cust-003",
      "name": {
        "businessName": "Al Mansouri Trading LLC",
        "alsoKnownAs": ["Al Mansouri Trading"]
      },
      "accountStatus": "Active"
    }
  ],
  "meta": {
    "totalPages": 1,
    "totalRecords": 1
  }
}

200 — Account not found, opted out

Return 200 with an empty data array where no account was found matching the IBAN, the account is under a bar, or the customer has opted out of CoP. Do not use 204, 404, 201 or 202 — the Hub expects 200 and treats an empty array as a no-result response.

The three cases are deliberately indistinguishable to the TPP, so that a CoP query cannot be used to probe for the existence of an account.

{
  "data": [],
  "meta": {
    "totalPages": 0,
    "totalRecords": 0
  }
}

Error responses

All error bodies must include errorCode and errorMessage.

403 — Forbidden

504 — Gateway Timeout

You MAY return 504 when you cannot complete processing within your internal time limit. The API Hub treats it as a timeout. The body for this status is not standardised and no schema is defined for it. A 504 is a 5xx response, so it counts as a failed request under the Ozone Connect Availability Policy.