POST/v1/gateway

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

Name
Authorization
Type
Bearer
Tag(s)
Mandatory
Description
Oauth 2.0 bearer token
Name
X-fapi-interaction-Id
Type
string
Tag(s)
Mandatory
Description
An RFC4122 UUID used as a correlation id.
Name
Content-Type
Type
application/json
Tag(s)
Mandatory
Description
Content type and encoding of the request. charset=utf-8
Name
Accept
Type
application/json
Tag(s)
Description
application/json

Response Headers

Name
X-fapi-interaction-Id
Type
string
Tag(s)
Mandatory
Description
Name
Content-Type
Type
application/json
Tag(s)
Mandatory
Description

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

Name
SchemeName
Type
enum
Tag(s)
required
Description
Used to indicate sort code and account are used as the identifier.
- Always: SortCodeAccountNumber
Name
AccountType
Type
enum
Tag(s)
required
Description
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.
Name
Identification
Type
string
Tag(s)
required
Description
The sort code and account number of the payee.
- Format: Only numbers and always 14 digits allowed. ^[0-9]{14}$
Name
Name
Type
string
Tag(s)
required
Description
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
Name
SecondaryIdentification
Type
string
Tag(s)
Description
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.

Name
Matched
Type
boolean
Tag(s)
Always returned
Description
- 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.
Name
ReasonCode
Type
enum
Tag(s)
Description
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.
Name
name
Type
string
Tag(s)
Description
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

Name
Code
Type
string
Tag(s)
Always returned
Description
High level textual error code, to help categorise the errors. The HTTPXXX related error code.
- Format: Max. length: 40
Name
Id
Type
string
Tag(s)
Description
A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors. Max. length: 40
Name
Message
Type
string
Tag(s)
Always returned
Description
Brief Error message, e.g., “BAD_REQUEST”; Max. length: 500
Name
Errors
Type
Array
Tag(s)
Description
Name
ErrorCode
Type
String
Tag(s)
Description
Low level textual error code, e.g., INVALID_VALUE, MISSING_VALUE Or [Code] field propagated from the responder participant Max. length: 128
Name
Message
Type
String
Tag(s)
Description
The error code that represents the functional error. All the functional errors are described in the Functional Errors table.
Name
Path
Type
String
Tag(s)
Description
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"
            }
        ]
    }
]