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

EnvironmentEndpoint URL
SandboxProvided via MSafe after being requested
ProductionProvided via MSafe after being requested

Go directly to

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 nameNotes
AuthorizationBearer <your bearer token>
x-fapi-interaction-idca1449f0-140d-4e93-a268-33b8067ecf23
Content-Typeapplication/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 CodeDescription
400 - Bad requestRequest has malformed missing or non-compliant JSON body or URL parameters.
401 - UnauthorisedAuthorization header missing or invalid token.
403 - ForbiddenToken has incorrect scope or a security policy was violated.
405 - Method not allowedThe client tried to access the resource with a method that is not supported.
406 - Not acceptedThe 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 requestsToo 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 errorSomething 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 unavailableThe service is down for maintenance.
504 - Internal server errorThere 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"
            }
        ]
    }
]
Previous
Next