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 always contains a single account identified by IBAN and a name to match against.

data.account

PersonName

BusinessName

Example — personal name

{
  "data": {
    "account": {
      "schemeName": "IBAN",
      "identification": "AE070331234567890123456",
      "name": {
        "fullName": "Ahmed Al Mansouri",
        "firstName": "Ahmed",
        "lastName": "Al Mansouri"
      }
    }
  }
}

Example — business name

{
  "data": {
    "account": {
      "schemeName": "IBAN",
      "identification": "AE070331234567890123456",
      "name": {
        "businessName": "Al Mansouri Trading LLC"
      }
    }
  }
}

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 and name are the only required members of an entry.

Personal account

name.fullName is mandatory and is the value the Hub matches on today. Every other field is optional — supply firstName, middleName, lastName, fullNameAr 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. A response carrying only fullName is fully conformant.

{
  "data": [
    {
      "id": "cust-001",
      "name": {
        "fullName": "Ahmed Al Mansouri",
        "firstName": "Ahmed",
        "lastName": "Al Mansouri",
        "fullNameAr": "أحمد المنصوري"
      }
    }
  ],
  "meta": {
    "totalPages": 1,
    "totalRecords": 1
  }
}

Personal account — minimum conformant response

{
  "data": [
    {
      "id": "cust-001",
      "name": {
        "fullName": "Ahmed Al Mansouri"
      }
    }
  ],
  "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",
        "firstName": "Ahmed",
        "lastName": "Al Mansouri"
      }
    },
    {
      "id": "cust-002",
      "name": {
        "fullName": "Fatima Al Mansouri",
        "firstName": "Fatima",
        "lastName": "Al Mansouri"
      }
    }
  ],
  "meta": {
    "totalPages": 1,
    "totalRecords": 2
  }
}

Business account

Populate name.businessName with the registered business name on the account. businessNameAr and alsoKnownAs are optional.

{
  "data": [
    {
      "id": "cust-003",
      "name": {
        "businessName": "Al Mansouri Trading LLC",
        "alsoKnownAs": ["Al Mansouri Trading"]
      }
    }
  ],
  "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