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.0

External Documentation​

Servers​

URLDescription
https://test-apigw.apicunia.comTest/Sandbox
https://apigw.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.
OPTOOpted out of the CoP Scheme
ACNSAccount type Not supported by the CoP Responder
IVCRInvalid Customer reference, relates to the Secondary Identification field in the request
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.
CASSAccount has been switched using the Current Account Switch Service
SCNSSort code not supported by the CoP Responder

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

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 Examples (500 Status Code)​

Internal Server Error
{
  "type": "https://example.com/probs/SERVER_ERROR",
  "code": "SERVER_ERROR",
  "title": "Encountered an unexpected error/condition",
  "status": 500,
  "detail": "Encountered an unexpected error/condition.",
  "instance": "/copgateway/v1.0/confirmation-payee/name-verification"
}

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 Examples (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"
}