POST/v2/account_information

SRD Validator API specification

This document describes the technical specification of the Secondary Reference Data (SRD) Account Validation API designed to help consumers determine whether an account is defined in the context of CoP as a so-called SRD Account or not. An SRD Account is an account for which the secondary reference identification field is mandatory because it represents a collection account of some sort. For those accounts the secondary reference identification field contains the data necessary to determine the actual beneficiary. The access token acquired and used for the Account Check API can also be used for the SRD validator.

To gain access to SurePay's add-ons, customers are required to notify service@surepay.co.uk first. This notification is essential to enable access to these additional features.

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

    RFC4122 UUID used as a interaction id

  • Name
    Content-Type
    Type
    application/json
    Tag(s)
    Mandatory
    Description

    Content type and encoding of the request

  • 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 nameValues
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)
    Mandatory
    Description

    Used to indicate sort code and account are used as the identifier.
    This must be SortCodeAccountNumber or SortCode

  • Name
    Identification
    Type
    string
    Tag(s)
    Mandatory
    Description

    The sort code & account number or sort code of the payee.
    SortCodeAccountNumber must be only numbers with 14 digits.
    SortCode must be only numbers with 6 digits.
    Pattern: ^[0-9]{14}$ or ^[0-9]{6}$

Response body

Successful response

Status code 200 is returned with fields and corresponding values as below

  • Name
    SRDAccount
    Type
    boolean
    Tag(s)
    Always returned
    Description
    • True - The account corresponds to an SRD Account. Automatically derived from OB directory (EISCDId attr).
    • False - The account does not correspond to an SRD Account from the OB directory.
  • Name
    SRDAccountType
    Type
    enum
    Tag(s)
    Description

    The possible values are HOCA, CreditCard, SavingsAccount, MortgageAccount, EWallet, UNKNOWN.
    This data is manually maintained by SurePay

  • Name
    SRDPattern
    Type
    string
    Tag(s)
    Description

    Regexp expression that gives a hint on the expected format. It can be empty or contain one or multiple patterns separated by pipe symbol.
    This data is manually maintained by SurePay.
    Max. length: 140

  • Name
    BankCode
    Type
    string
    Tag(s)
    Description

    The bank code of the account holding bank

  • Name
    BankName
    Type
    string
    Tag(s)
    Description

    The name of the account holding bank

  • Name
    ObOrganisationId
    Type
    string
    Tag(s)
    Description

    Organisation Id in the open banking directory

  • Name
    ObOrganisationName
    Type
    string
    Tag(s)
    Description

    Organisation name in the open banking directory

Request

POST
/v2/account_information
{
    "SchemeName": "SortCodeAccountNumber",
    "Identification": "99999200000063"
}

Response

{
    "SRDAccount": true,
    "SRDAccountType": "HOCA",
    "SRDPattern": "^[0-9]*$",
    "BankCode": "9992",
    "BankName": "Bank3",
    "ObOrganisationId": "ob org id",
    "ObOrganisationName": "Ob testing name"
}

Status and error codes

Errors respect standard HTTP status codes in the 4xx and 5xx range.

Error response

  • Name
    Code
    Type
    string
    Tag(s)
    Always returned
    Description

    High level textual error code, to help categorise the errors. The HTTPXXX related error code.
    Max. length: 40

  • Name
    Message
    Type
    string
    Tag(s)
    Always returned
    Description

    Brief error message.
    Max. length: 500

  • Name
    Errors
    Type
    Array
    Tag(s)
    Description
  • Name
    ErrorCode
    Type
    String
    Tag(s)
    Description

    Low level textual error code.
    Max. length: 128

  • Name
    Message
    Type
    String
    Tag(s)
    Description

    Message explains the technical error

  • Name
    Path
    Type
    String
    Tag(s)
    Description

    Returns the error field name

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
405 - Method not allowedThe client tried to access the resource with a method that is not supported.
415 - Unsupported Media TypeClient error response code indicates that the server refuses to accept the request because the payload format is in an unsupported format
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.

Error response

{
"Code": "400 Bad Request",
"Message": "BAD_REQUEST",
"Errors": [
    {
        "ErrorCode": "UK.SRD.Field.Invalid",
        "Message": "An invalid value is supplied in one of the fields.",
        "Path": "Identification"
    }
]
}
Previous