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

  • AuthorizationBearerMandatory

    Oauth 2.0 bearer token

  • X-fapi-interaction-IdstringMandatory

    RFC4122 UUID used as a interaction id

  • Content-Typeapplication/jsonMandatory

    Content type and encoding of the request

  • Acceptapplication/json

    application/json

Response Headers

  • X-fapi-interaction-IdstringMandatory

    RFC4122 UUID used as a interaction id

  • Content-Typeapplication/jsonMandatory

    Content type and encoding of the request

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

  • SchemeNameenumMandatory

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

  • IdentificationstringMandatory

    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

  • SRDAccountbooleanAlways returned
    • 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.
  • SRDAccountTypeenum

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

  • SRDPatternstring

    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

  • BankCodestring

    The bank code of the account holding bank

  • BankNamestring

    The name of the account holding bank

  • ObOrganisationIdstring

    Organisation Id in the open banking directory

  • ObOrganisationNamestring

    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

  • CodestringAlways returned

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

  • MessagestringAlways returned

    Brief error message. Max. length: 500

  • ErrorsArray
    • ErrorCodeString

      Low level textual error code. Max. length: 128

    • MessageString

      Message explains the technical error

    • PathString

      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