Skip to main content

Confirmation of Payee (Gateway)

UK-compliant confirmation of payee (CoP), delivered through a single, easy-to-integrate API.

Confirmation of Payee (CoP) is an account name-checking service designed to help reduce misdirected payments and provide greater assurance that payments are being sent, and collected from, the intended account holder for UK domestic payments.

This API is organised around REST. The API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Make all API requests over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API Metadata​

  • OpenAPI version: 3.0.4
  • API version: 1.0.1

External Documentation​

Servers​

URLDescriptionNote
https://test-apigw.apicunia.comSandboxUses a fixed set of dummy accounts with known outcomes.
Performance may be slower due to reduced scaling and cold‑start effects.
https://test-cop.apicunia.comTestConnects to the live CoP network but has a soft limit of 50 requests per day, per client.
Performance may be slower due to reduced scaling and cold‑start effects.
https://cop.apicunia.comProduction

Authentication​

Authentication for this API is via OAuth 2.0. Requesting client must provide a valid bearer/access token in the Authorization header for all API requests. The API uses the Client Credentials Grant flow.

Token Endpoint​

GET https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token

Request Example​

bash
curl --location --request GET 'https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={YOUR_CLIENT_ID}' \
--data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
--data-urlencode 'scope={YOUR_SCOPE_ID}/.default'

For additional information on this method of API authentication see OAuth 2.0.

Confirmation of Payee​

Confirm Payee
POST
/copgateway/v1.0/confirmation-payee/name-verification

Summary​

Confirmation of Payee detail endpoint.

Returns a Regulated UK CoP Response indicating whether the supplied Payee details are a match or otherwise.

As Requestor:
The endpoint validates and routes an incoming CoP request to the applicable responding PSP and relays the CoP response back to the calling application.

Request​

Request Headers​

NameTypeFormatRequiredDescription
x-fapi-interaction-idstringuuidYesAn RFC4122 UUID used as a correlation id by the Requesting PSP
X-Request-Timestampstringdate-timeYesTimestamp of the CoP Request in ISO 8601 UTC format (YYYY-MM-DDThh:mm:ss.sssZ)

Request Body​

Content Type: application/json
Schema: NameVerificationRequest

Schema: NameVerificationRequest
{
  "data": {
    "schemeName": "mandatory string (identifies the CoP scheme, always 'SortCodeAccountNumber')",
    "accountType": "mandatory string (Indicates either 'Personal' or 'Business' account type)",
    "identification": "mandatory string (6-digit Sort Code and 8-digit Account Number, ^[0-9]{14}$)",
    "name": "mandatory string (Name as input by the payment initiator, Max 140 Text)",
    "secondaryIdentification": "optional string (Secondary reference data input by the payment initiator, Max 140 Text)"
  }
}

Personal Account Type Examples (Sandbox data)​

Personal Account Type: NatWest
{
    "data": {
        "schemeName": "SortCodeAccountNumber",
        "accountType": "Personal",
        "identification": "60000190000001",
        "name": "John Smith"
    }
}

Business Account Type Examples (Sandbox data)​

Business Account Type: HSBC UK
{
    "data": {
        "schemeName": "SortCodeAccountNumber",
        "accountType": "Business",
        "identification": "40051580000001",
        "name": "Oak Accounting"
    }
}

Response​

Response Headers​

NameTypeFormatRequiredDescription
x-fapi-interaction-idstringuuidYesAn RFC4122 UUID used as a correlation id by the Requesting PSP
X-Response-Timestampstringdate-timeYesTimestamp of the CoP Response in ISO 8601 UTC format

Response Body​

Content type: application/json Schema: NameVerificationResponse

Schema: NameVerificationResponse
{
  "data": {
    "verificationReport": {
      "matched": "boolean (returns true for a full name match and false for all other outcomes)",
      "reasonCode": "string (see Reason Codes table below for details of applicable codes)",
      "name": "string (Returns the actual account name, only in the event of a close match)"
    }
  }
}

200 OK Response​

Regulated UK CoP Reason codes (HTTP Status Code 200) A code is returned when the verification did not result in a full match outcome.

CodeMeaningNote
ANNMAccount Name does not matchThis is a No Match outcome
AC01Unknown Account Number, Account does not exist in the CoP ResponderName Verification was not possible
MBAMThere may be a match on the Account Name (Close Match outcome)Account Name is passed back.
BANMThis is a match with a Business account, personal account was requested
PANMThis is a match with a Personal account, business account was requested
BAMMThis is close match with Business Account, personal account was requestedAccount Name is passed back.
PAMMThis is close match with Personal Account, business account was requestedAccount Name is passed back.
OPTO**Opted out of the CoP Scheme
ACNS**Account type Not supported by the CoP Responder
IVCR**Invalid Customer reference, relates to the Secondary Identification field in the request
CASS**Account has been switched using the Current Account Switch Service
SCNS**Sort code not supported by the CoP Responder
SECMISS**Secondary Reference Missing and is required before the name can be checked
FOURHUN**The CoP Responder replied with a 400 error and is unable to check the name
HTTPERR**The CoP Responder experienced an HTTP error and is unable to check the name
NOROUTE**Unable to find a participant bank to handle this request
**

This code is not returned by the test-apigw server endpoint when using the sandbox dummy accounts.
This is returned when using the test-cop and cop server endpoints.

NOTE: There are some legitimate reasons for a AC01 but the specific reason is not explicitly disclosed by the CoP responder. The account details supplied may well be valid at the CoP responding PSP/RVM but;

  • Not eligible for CoP (none accepting payment account)
  • Account is confidential/protected and reason cannot legally be disclosed
  • Issue with Name data at the PSP so cannot perform a CoP check

Response Examples (200 OK Status Code)​

Match – Personal/Business
{
    "data": {
        "verificationReport": {
            "matched": true
        }
    }
}

Account Type Cross-Over Response Examples (200 OK Status Code)​

These are examples where positive name matching occurred against a different account type to what was requested.

Business Account Name Match, however Personal account type was specified
{
    "data": {
        "verificationReport": {
            "matched": false,
            "reasonCode": "BANM"
        }
    }
}

400 Status Code​

Bad/Malformed CoP Request. The request body is malformed. See Problem Details for additional information about API errors.

Bad Request Examples (400 Status Code)​

Format Error (Sort and Account)
{
  "type": "https://example.com/probs/FORMAT_ERROR",
  "code": "FORMAT_ERROR",
  "title": "Validation of CoP Request failed. See Detail",
  "status": 400,
  "detail": "Invalid Sort Code and Account format.",
  "instance": "/copgateway/v1.0/confirmation-payee/name-verification"
}

401 Status Code​

Invalid Request. The Requestor is not authorised to perform the request. See Problem Details for additional information about API errors.

Unauthorised Examples (401 Status Code)​

Invalid Client 1
{
  "type": "https://example.com/probs/CLIENT_INVALID",
  "code": "CLIENT_INVALID",
  "title": "Validating the client failed. See Detail",
  "status": 401,
  "detail": "Invalid Client, no permission to access resource.",
  "instance": "/copgateway/v1.0/confirmation-payee/name-verification"
}

500 Status Code​

Internal Server Error. This code is used whenever a technical problem occurred in the application code or application server that prevented the execution of the request. See Problem Details for additional information about API errors.

Internal Server Error Example (500 Status Code)​

Internal Server Error
{
  "type": "https://example.com/probs/SERVER_ERROR",
  "code": "SERVER_ERROR",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The API server experienced an unexpected error processing the request",
  "instance": "/copgateway/v1/payee-verifications"
}

502 Status Code​

Bad Gateway Error. This code is used whenever a technical problem occurred and the server acted as a gateway or proxy and received an invalid response from an upstream server. See Problem Details for additional information about API errors.

Bad Gateway Example (502 Status Code)​

Bad Gateway Error
{
  "type": "https://example.com/probs/SSL_ERROR",
  "code": "SSL_ERROR",
  "title": "SSL/TLS handshake failed",
  "status": 502,
  "detail": "SSL/TLS handshake failed.",
  "instance": "/copgateway/v1.0/confirmation-payee/name-verification"
}

504 Status Code​

Gateway Timeout Error. This code is used whenever the Apicunia server was working as a gateway to get a response and could not get a response within the alloted time. See Problem Details for additional information about API errors.

Gateway Timeout Example (504 Status Code)​

Gateway Timeout Error
{
  "type": "https://example.com/probs/TIMEOUT_ERROR",
  "code": "TIMEOUT_ERROR",
  "title": "Responder Timeout",
  "status": 504,
  "detail": "Responder did not respond within timespan (seconds): 7",
  "instance": "/copgateway/v1.0/confirmation-payee/name-verification"
}

Sandbox data (Dummy Accounts)​

The following Sort Code/Account Number and Account Name details may be used against the Apicunia CoP Sandbox for intitial automated integration testing.

These are dummy accounts and do not connect to the live CoP network. To test against actual accounts use the test-cop server endpoint with separate credentials upon request.

Each combination will trigger a known 200 Status OK CoP response with the specific result detailed.

TypeSort Code & AccountNameSandbox CoP Response
personal60000190000001John Smith"matched": true
SortCode/Account is valid and the personal Name matches exactly
personal20454590000002Bob Jones"matched": false, reasonCode": "MBAM"
SortCode/Account is valid and there may be a match on the Account Name
personal16522190000003Stephen George"matched": false, reasonCode": "ANNM"
SortCode/Account is valid but the Account Name does not match
personal30000290000005Sarah Thomas"matched": false, reasonCode": "AC01"
Either the Account does not exist or Name Verification was not possible
personal07011680000004Fienix Solutions"matched": false, reasonCode": "BANM"
Sort/Account is valid but this is an exact business Account Name match
personal07011680000004Feenix Solutions"matched": false, reasonCode": "BAMM"
Sort/Account is valid but there may be a match with a business Account Name
business40051580000001Oak Accounting"matched": true
SortCode/Account is valid and the business Name matches exactly
business77010180000002Bacon Estates"matched": false, reasonCode": "MBAM"
SortCode/Account is valid and there may be a match on the Account Name
business82200080000003Trade Bikes Ltd"matched": false, reasonCode": "ANNM"
SortCode/Account is valid but the Account Name does not match
business80226080000007Northbridge Consulting"matched": false, reasonCode": "AC01"
Either the Account does not exist or Name Verification was not possible
business11000190000005Susan White"matched": false, reasonCode": "PANM"
Sort/Account is valid but this is an exact personal Account Name match
business11000190000005Sue White"matched": false, reasonCode": "PAMM"
Sort/Account is valid but there may be a match with a personal Account Name

FAQs​

How does CoP Account Name matching work?​

Account Name matching is controlled entirely by the responding bank/PSP and CoP Requestors have no influence over the matching algorithm used. While CoP scheme rules define minimum expectations, banks could handle edge cases in different ways.

Banks/PSPs cannot return No Match when:

  • Forename and Surname are reversed
  • Surname matches and the provided Forename is a common nickname/variant (e.g. William/Bill, Elizabeth/Liz, Robert/Bob)
  • Forename contains a spelling error
  • Surname contains a spelling error

Banks/PSPs cannot return a Full Match unless:

  • Surname is an exact match
  • First character of the Forename is correct

Banks/PSPs may occasionally exceed these rules and return Full Match for slight deviations, but the behaviour can vary by institution.