POST/v1/gateway

COP UK Requester API Specification

This chapter contains information on the header, request body and response body required to make a successful request with the Confirmation of Payee API. At the bottom of the page, also information about the error scenario’s are described.

Click one of the buttons below to download the .YAML with the technical description and model of the API, the postman collection or a set of testcases which can be used on the sandbox environment.

Endpoints

Environment	Endpoint URL
Sandbox	Provided via MSafe after being requested
Production	Provided via MSafe after being requested

Request Headers

AuthorizationBearerMandatory
Oauth 2.0 bearer token
X-fapi-interaction-IdstringMandatory
An RFC4122 UUID used as a correlation id.
Content-Typeapplication/jsonMandatory
Content type and encoding of the request. charset=utf-8
Acceptapplication/json
application/json

Response Headers

X-fapi-interaction-IdstringMandatory
An RFC4122 UUID used as a correlation id.
Content-Typeapplication/jsonMandatory
Content type and encoding of the request. charset=utf-8

Example of request headers:

Header name	Notes
Authorization	Bearer <your bearer token>
x-fapi-interaction-id	ca1449f0-140d-4e93-a268-33b8067ecf23
Content-Type	application/json;charset=utf-8

Request body

SchemeNameenumrequired
Used to indicate sort code and account are used as the identifier.
- Always: SortCodeAccountNumber
AccountTypeenumrequired
Used to indicate sort code and account are used as the identifier. Possible enum values are:
- Personal - Used to indicate a personal bank account.
- Business - Used to indicate a business bank account.
Identificationstringrequired
The sort code and account number of the payee.
- Format: Only numbers and always 14 digits allowed. ^[0-9]{14}$
Namestringrequired
The name of the payee as input by the payer. For personal accounts this is: 'salutation,forename,surname' or '',,name'. For joint accounts and business accounts only the format is '',,name'
- Format: Max. length: 140
SecondaryIdentificationstring
The payment reference information as input by the payer required to identify some bank accounts.
- Format: Max. length: 140

Response body

The response has a different structure depending on the API call results.

Successful response (HTTP 200 - described below)
Error response (HTTPXXX - described in Errors) SurePay maps the response directly from the responding COP participant and it follows all guidelines specified in the Pay.UK CoP Technical Guide with one exception, which is reason code: SCNF.

MatchedbooleanAlways returned
- True - The CoP Responder has performed the matching and confirms it is a match.
- False - The CoP Responder has performed the matching and confirms it not a full match.
ReasonCodeenum
A This field should only be returned when Matched = False. The possible values are:
- ANNM - The CoP Responder has performed the matching and confirms it is not a match.
- MBAM - The CoP Responder has performed the matching and it is a close match.
- BANM - The CoP Requester indicated that the Payer intends to pay a personal account, but the actual account is a business account and the name matches.
- PANM - The CoP Requester indicated that the Payer intends to pay a business account, but the actual account is a personal account and the name matches.
- BAMM - The CoP Requester indicated that the Payer intends to pay a personal account, but the actual account is a business account and the name is a close match.
- PAMM - The CoP Requester indicated that the Payer intends to pay a business account, but the actual account is a personal account and the name is a close match.
- AC01 - Account does not exist in the CoP Responder’s books.
- IVCR - The CoP Responder was unable to locate the customer account based on the secondary reference data contained within the SecondaryIdentification field.
- ACNS - Account not supported for CoP by the CoP Responder. This code should also be used by a sponsor bank if the account relates to a collection account held by an ASPSP that is not reachable for CoP and they instruct payers to enter the SRD account level name for inbound payments as the sponsor will not be able to match based on the collection account name.
- OPTO - Payee has been opted out of the CoP service by the CoP Responder.
- CASS - The Payee’s account has been switched using the Current Account Switch Service (CASS).
- SCNS - The CoP Responder has incorrectly received a CoP request for a sort code that does not belong to them.
- SCNF (Not Pay.UK) - Sort Code Not Found is returned in case the Gateway cannot route the sort code to a corresponding participant.
namestring
The COP responder returns the account name in the event of a close match in an unstructured string. Only returned when ReasonCode equals MBAM, BAMM or PAMM.
- Format: Max. length: 140

Request

POST

v1/gateway

{
    "SchemeName": "SortCodeAccountNumber",
    "AccountType": "Personal",
    "Identification": "99999200000001",
    "Name": ",,David Martin"
}

Response

{
    {
        "Matched": true
    }
}

Status and error codes

Errors respect standard HTTP status codes in the 4xx and 5xx range. In some situations an error json object is included in the body, most notably when status code is 400 - Bad Request. The chosen structure is consistent with the error structure in the Pay.UK CoP specification.

Error response body

CodestringAlways returned
High level textual error code, to help categorise the errors. The HTTPXXX related error code.
- Format: Max. length: 40
Idstring
A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors. Max. length: 40
MessagestringAlways returned
Brief Error message, e.g., "BAD_REQUEST"; Max. length: 500
ErrorsArray
ErrorCodeString
Low level textual error code, e.g., INVALID_VALUE, MISSING_VALUE Or [Code] field propagated from the responder participant Max. length: 128
MessageString
The error code that represents the functional error. All the functional errors are described in the Functional Errors table.
PathString
The error code that represents the functional error. All the functional errors are described in the Functional Errors table.

Technical Errors

HTTP Status Code	Description
400 - Bad request	Request has malformed missing or non-compliant JSON body or URL parameters.
401 - Unauthorised	Authorization header missing or invalid token.
403 - Forbidden	Token has incorrect scope or a security policy was violated.
405 - Method not allowed	The client tried to access the resource with a method that is not supported.
406 - Not accepted	The request contained an accept header that requested a content-type other than application/JSON and a character set other than UTF-8.
429 - Too many requests	Too many requests towards endpoint. In this case the response contains a Retry-After header indicating how long the consumer must wait before retrying the operation.
500 - Internal server error	Something went wrong on the API gateway or service. In this case the body might contain extra details. This error can also be returned if the upstream service returns an error. All CoP participants error messages, will be reported from the Gateway API perspective as “500 Internal server error” errors with detailed information provided within the Errors array in the error message body.
503 - Service unavailable	The service is down for maintenance.
504 - Internal server error	There was no timely response from an upstream server that was needed to complete the request. This can happen if there was no response from the responding participant’s CoP endpoint.

Error response

    {
        "Code": "400 Bad Request",
        "Message": "BAD_REQUEST",
        "Errors": [
            {
                "ErrorCode": "INVALID_VALUE",
                "Message": "Invalid value in the request body.",
                "Path": "identification"
            }
        ]
    }