POST/vopgateway/v1/single

API Specification

This chapter contains information on the header, request and response body required to make a successful request with the VOP Requester API for Banks. At the bottom of the page, information about the error scenarios are also described.

Document History

VersionDateDescription
1.0.015 Jan 2025Original Digital Version. Aligned with PDF V1.3
1.1.017 Jan 2025Added minor fixes. Updated 'nameMatched' to 'matchedName'
1.2.027 Jan 2025Changed the format of the 'bicfi' fields
1.3.010 Feb 2025Changed validation format to the request fields: 'accountId.type.iban' and 'lei'
1.3.119 Feb 2025Changed 'unstructuredRemittanceInformation' type from 'String' to 'Array of Strings'
1.4.021 Feb 2025Added new values and response logic to the field 'detailedMatchResult' and added examples
2.0.020 Mar 2025Aligned to YAML and included formatting changes. Refer to the detailed changes here.
2.1.016 Apr 2025Added the following new headers: X-End-User, X-Software-Supplier and X-Channel

Endpoints

EnvironmentEndpoint URL
SandboxAvailable on request
ProductionAvailable on request

Go directly to

Request

Request Headers

  • Name
    X-Request-Id
    Type
    String
    Tag(s)
    Mandatory
    Description

    A RFC4122 UUID used as a correlation id.

  • Name
    Content-Type
    Type
    String
    Tag(s)
    Mandatory
    Description

    Content type and encoding of the request.

    • Example: application/json
  • Name
    Authorization
    Type
    String
    Tag(s)
    Mandatory
    Description

    OAuth 2.0 bearer token.

  • Name
    Accept
    Type
    String
    Tag(s)
    Mandatory
    Description

    The media type the client can process in the response. This is always set to application/json.

    • Example: application/json
  • Name
    Accept-Language
    Type
    String
    Tag(s)
    Optional
    Description

    Can be provided by the Requesting PSP to be used as language in the matchedName response field (when data is available in the given language).

    • Format: ISO 639-1.
  • Name
    X-End-User
    Type
    string
    Tag(s)
    Optional
    Description

    This field is used to identify the endpoint user, customer, department or system.

    • In case the customer identifies more departments/end users within the same company which will use the API. Every department could be identified with a unique X-End-User.

    • In case the customer is reselling the API as a partner. Every new customer of the partner should be identified with a unique X-End-User.

    • Format: Max. 50 characters

    • Format: ^[a-zA-Z0-9\-]{3,50}

  • Name
    X-Software-Supplier
    Type
    string
    Tag(s)
    Optional
    Description

    It is used in case there is an external software supplier involved. This header must be provided if you are using a third party software supplier. In case the SurePay customer uses more than one software supplier then all of them can be provided in the header.

    • Format: Max. 70 characters
    • Example: X-Software-Supplier = "supplierA" / "supplierB" / "supplierC"
  • Name
    X-Channel
    Type
    string
    Tag(s)
    Optional
    Description

    In case the customer wants to distinguish traffic based on their channel. A channel can be set by the customer at any value and the value will show up in reporting.

    • Format: Max. 70 characters
    • Example: X-Channel = "web" / "mobile"

Example of Request Headers

Header nameExample
X-Request-Id123e4567-e89b-12d3-a456-42661417400
Content-Typeapplication/json;charset=utf-8
AuthorizationBearer <your bearer token>
Acceptapplication/json
Accept-LanguageEN
X-End-UserFinanceDepartment
X-Software-SupplierSupplierA
X-ChannelWeb

Request Body

Two combinations are supported as VOP requests (A) Name + IBAN and (B) Identifier Code + IBAN. In case of Natural Person, only combination (A) is possible.

  • Name
    party
    Type
    Object
    Tag(s)
    Mandatory
    Description

    Provide information about the identification of the Payee.

    • Name
      name
      Type
      String
      Tag(s)
      Conditional
      Description

      The name of the Payment Counterparty.

      • Mandatory for Natural Person.
      • Optional for organisations.
      • Usage Rule: If name is included, the identification object cannot be used in the same request.
      • Format: Max. 140 characters.
    • Name
      identification
      Type
      Object
      Tag(s)
      Conditional
      Description

      Organisation’s legal identification.

      • Mandatory if name is not provided.
      • Usage Rule: If identification is included, the name field cannot be used in the same request.
      • Name
        organisationId
        Type
        Object
        Tag(s)
        Optional
        Description

        Used to verify whether an organisation ID provided matches the organisation ID on the bank account.

        • Name
          lei
          Type
          String
          Tag(s)
          Conditional
          Description

          Legal entity identification as an alternate identification for a party. LEI is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".

          • Usage Rule: Can only be used if other and anyBIC fields are not used. 
          • Format: ^[A-Z0-9]{18}[0-9]{2}$
          • Example: '549300DTUYXVMJXZNY7'
        • Name
          anyBIC
          Type
          String
          Tag(s)
          Conditional
          Description

          Business identification code of the organisation.

          • Usage Rule: Can only be used If lei or others are not used.
        • Name
          others
          Type
          Array of Objects
          Tag(s)
          Conditional
          Description

          Object defined to add another type of legal identification besides 'Legal Entity Identifier'.

          • Usage Rule: Can only be used if lei and anyBIC are not used.
          • Name
            identification
            Type
            String
            Tag(s)
            Mandatory
            Description

            The identification code of the Payment Counterparty.

            • Format: Max. 256 characters.
          • Name
            schemeNameCode
            Type
            Enum
            Tag(s)
            Conditional
            Description

            The type of the identification code of the Payment Counterparty. Either schemeNameCode or schemeNameProprietary is used.

            • Find the code list in here.
          • Name
            schemeNameProprietary
            Type
            String
            Tag(s)
            Conditional
            Description

            Name of the identification scheme, in a free text form. Either schemeNameCode or schemeNameProprietary is used.

            • Format: Max. 35 characters.
          • Name
            issuer
            Type
            String
            Tag(s)
            Optional
            Description

            Entity that assigns the identification. You can find more information here. You can find the latest list of issuers here.

            • Format: Max. 35 characters.
  • Name
    partyAccount
    Type
    Object
    Tag(s)
    Mandatory
    Description

    Payment account details of the Payee.

    • Name
      iban
      Type
      String
      Tag(s)
      Mandatory
      Description

      The Payment Account Number of the Payment Counterparty. The IBAN needs to be valid, otherwise it results in a validation error.

      • Format: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$
      • Format: Max. 34 Characters.
  • Name
    unstructuredRemittanceInformation
    Type
    Array of Strings
    Tag(s)
    Optional
    Description

    Additional information about the account number sent by the Requester.

  • Name
    partyAgent
    Type
    Object
    Tag(s)
    Conditional
    Description

    Identification of the Responding PSP.

    • Usage Rule: Mandatory when Requesting PSP does not utilise the SurePay BIC Enrichment service.
    • Name
      financialInstitutionId
      Type
      Object
      Tag(s)
      Mandatory
      Description

      Financial Institution object.

      • Name
        bicfi
        Type
        String
        Tag(s)
        Mandatory
        Description

        Identification of the Responding PSP (Swift BIC). BIC of the Agent.

        • Format: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
        • Example:
          • 8 characters: 'DEUTDEFF’
          • 11 characters: ‘DEUTDEFF500’
  • Name
    requestingAgent
    Type
    Object
    Tag(s)
    Mandatory
    Description

    Identification of the Requesting PSP.

    • Name
      financialInstitutionId
      Type
      Object
      Tag(s)
      Mandatory
      Description

      Financial Institution object.

      • Name
        bicfi
        Type
        String
        Tag(s)
        Mandatory
        Description

        Identification of the Requesting PSP (Swift BIC). BIC of the Agent.

        • Format: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
        • Example:
          • 8 characters: ‘DEUTDEFF’
          • 11 characters: ‘DEUTDEFF500’

Request

POST
vopgateway/v1/single
    {
        "party": {
            "name": "David Alex Miller"
        },
        "partyAccount": {
            "iban": "NL72SRPY0000000001"
        },
        "unstructuredRemittanceInformation": ["1234512345"],
        "partyAgent": {
            "financialInstitutionId": {
                "bicfi": "ABCDBEBBXXX"
            }
        },
        "requestingAgent": {
            "financialInstitutionId": {
                "bicfi": "SRPYNL2U"
            }
        }
    }

Response

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

  • Successful response (HTTP 200 - described below)
  • Error response (HTTPXXX - described in Errors)

Response Headers

  • Name
    X-Request-Id
    Type
    String
    Tag(s)
    Mandatory
    Description

    Value as sent in the corresponding request header.

  • Name
    Content-Type
    Type
    String
    Tag(s)
    Mandatory
    Description

    Content type and encoding of the request.

    • Example: application/json

Example of Response Headers

Header nameExample
X-Request-Id123e4567-e89b-12d3-a456-42661417400
Content-Typeapplication/json;charset=utf-8

Response Body

  • Name
    partyNameMatch
    Type
    Enum
    Tag(s)
    Conditional
    Description

    Describes the result of the IBAN-Name Check.

    • MTCH (Match): The name matches exactly with a record in the system – a confirmed match.
    • CMTC (Close Match): The name closely matches a record but may have slight differences, like spelling variations – a partial or approximate match.
    • NMTC (No Match): The name doesn’t match any records in the system – no match found.
    • NOAP (Not Applicable): Verification check not possible, validation check is not applicable.

    Only applicable when name field has been added in the request.

  • Name
    partyIdMatch
    Type
    Enum
    Tag(s)
    Conditional
    Description

    Describes the result of the IBAN-ID Check.

    • MTCH (Match): The ID matches a record in the system - a confirmed match.
    • NMTC (No Match): The ID does not match any records - no match found.
    • NOAP (Not Applicable): The ID code is not supported or known by the Responding PSP - Verification check not possible, validation check is not applicable.

    Only applicable if identification object has been added in the request.

  • Name
    matchedName
    Type
    String
    Tag(s)
    Conditional
    Description

    Returns the corrected name of the account holder. Always returned in case of a Close Match (CMTC). It’s also returned in case of a No Match (NMTC) and the account type is ‘ORG', if supported by the Responding PSP.

  • Name
    additionalPartyInformation
    Type
    Object
    Tag(s)
    Conditional
    Description

Response

    {
        "partyNameMatch": "MTCH"
    }

Performance and Availability

The VoP Gateway API will comply with the highest availability standards, operating 24/7 and allowing consumers to submit name-matching requests without downtime. All SLAs related to availability, support, and resolution times are defined in a separate Service Level Agreement (SLA) document, agreed upon with the PSP to which the service is provided.

Encoding and Special Characters

API requests and responses must use UTF-8 character encoding, which is the default encoding for JSON (RFC 7158 - Section 8.1).

Security

The API is designed for use by a trusted backend or middleware service. Each individual connection between SurePay and the bank is secured by:

  • HTTPS only
  • IP whitelisting
  • OAuth 2.0

Non-secure devices, like mobile apps, are not permitted to connect directly, nor can the API be directly integrated into web pages. Only server-to-server connections are permitted. If a connection is compromised, SurePay can disconnect it.

The interface is based on several key premises:

  • The SurePay API client is a trusted partner.
  • On the SurePay client side, security measures are implemented, such as handling DoS attacks.
  • Additional data fields will not break the connection on the client side (backward compatibility support).
  • SSL session reuse is supported.

Error Handling

Status and Error Codes

When an application error message occurs, an HTTP status code will be returned plus an error message. The return format of the error messages are technical errors and functional errors. The table below reflects the used HTTP status codes in case of a technical error.

HTTP Status CodeDescription
200 - OKThe request has succeeded.
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 Requester 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 the 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 VOP 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.
504 - Gateway TimeoutThere 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 payee’s VOP endpoint.

Error Response

Error Response Headers

  • Name
    X-Request-Id
    Type
    String
    Tag(s)
    Mandatory
    Description

    Value as sent in the corresponding request header.

  • Name
    Content-Type
    Type
    String
    Tag(s)
    Mandatory
    Description

    Content type and encoding of the request.

    • Example: application/json

Example of Error Response Headers

Header nameExample
X-Request-Id123e4567-e89b-12d3-a456-42661417400
Content-Typeapplication/json;charset=utf-8

Error Response Body

  • Name
    type
    Type
    String
    Tag(s)
    Mandatory
    Description

    A URI reference [RFC3986] that identifies the problem type.

    • Format: Max. 70 Characters.
  • Name
    code
    Type
    String
    Tag(s)
    Mandatory
    Description

    Message code to explain the nature of the underlying error.

    • Possible Values: Refer to the list here.
  • Name
    title
    Type
    String
    Tag(s)
    Optional
    Description

    Short human readable description of error type. Could be in local language. To be provided by the Responding PSP.

    • Format: Max. 70 Characters.
    • Possible Values: Refer to the list here.
  • Name
    status
    Type
    String
    Tag(s)
    Optional
    Description

    HTTP response code generated by the Server. If contained, this is more relevant as the actual http response code in the actual response, because it is introduced by the Application Server.

  • Name
    detail
    Type
    String
    Tag(s)
    Optional
    Description

    Detailed human readable text specific to this instance of the error.

    • Format: Max. 500 characters.
  • Name
    instance
    Type
    String
    Tag(s)
    Description

    This attribute is containing a JSON pointer (as defined in RFC6901) or XPath expression to indicate the path to an issue generating the error in the related request.

    • Format: Max. 256 characters.

Error response

    [
        {
            "type": "https://surepay.com/problem-type/invalid_field",
            "code": "FORMAT_ERROR",
            "title": "INVALID_FIELD",
            "status": 400,
            "detail": "The provided value for the field ‘____’ differs from the expected format.",
            "instance": "/request/body/field-name"
        }
    ]

Functional Errors

Error Message Codes

HTTP Status CodeDescription
FORMAT_ERRORIncorrect data format has been provided, not compliant with the expected specifications (e.g., invalid JSON format, missing or incorrectly formatted fields).
CLIENT_INVALIDThe client is not recognised or is invalid (an attempt to access resources by an unauthorized client).
CLIENT_INCONSISTENTThe client information provided in the certificate and/or in the request message body is not consistent with related directory information
INTERNAL_SERVER_ERRORAn exception occurred during code execution and the request cannot be further processed.

Error table

The following table contain a list of error code values:

Error Message CodeHTTP CodeTitleDetailer Error
FORMAT_ERROR400INVALID_HEADERThe provided value for the header ‘___’ differs from the expected format. Possible values : X-Request-Id, Accepted-Language, Content-Type and Authorization
FORMAT_ERROR400MANDATORY_HEADER_NOT_PROVIDEDA mandatory header ‘___’ has not been provided, therefore the request cannot be sent. Possible values : 'X-Request-Id', 'Content-Type' and 'Authorization'
FORMAT_ERROR400INVALID_REQUESTThe provided JSON format in the request does not comply with the expected structure.
FORMAT_ERROR400MANDATORY_FIELD_NOT_PROVIDEDThe request is missing the mandatory field ‘____’. Possible values : 'name' or 'identification', 'bicfi' (requesting, agent), 'iban'
FORMAT_ERROR400INVALID_FIELDThe provided value for the field ‘____’ differs from the expected format. Possible values : 'name', 'identification','lei', 'schemeNameCode', 'schemeNameProprietary', 'anyBIC', 'bicfi' (requesting, agent), 'issuer'
FORMAT_ERROR400NAME_TOO_LONGThe value provided in the field ‘name’ is longer than the maximum number of characters: 140.
FORMAT_ERROR400MUTUALLY_EXCLUSIVE_FIELDS_USEDTwo fields mutually exclusive were added in the request. Possible values : 'name' and 'identification'; 'lei', 'anyBIC' and 'others'; 'schemeNameCode' and 'schemeNameProperty'
CLIENT_INVALID401The API Client has a valid certificate but is not contained in the addressed scheme directoryThe Requesting’s PSP is not adherent to the Scheme.

List of Enumeration Values

schemeNameCode

The following table contain a list of enumeration values:

Enumeration valueDescriptionFormatExample
BANKBank Party Identification request. A unique and unambiguous assignment made by a specific bank or financial institution to identify a relationship between the bank and its client.Format: [CountryCode][BankCode][BranchCode]Example: 'US123BANK001'
CBIDCentral Bank Identification Number request. A unique identification number assigned by a central bank to identify an organization.Format: (CB)[0-9]{9,12}Example: 'CB123456789'
CHIDClearing Identification Number request. A unique identification number assigned by a clearing house to identify an organization.Format: [A-Z]{2,4}[0-9]{4,6}Example: 'CHCLRG1234'
CINCCertificate of Incorporation Number request. A unique identification number assigned by a designated authority to a certificate of incorporation, used to identify an organization.Format: (INC)[0-9]{7,10}Example: 'INC1234567'
COIDCountry Identification Code request. An identification code assigned by the country authority to identify an organization (e.g., corporate registration number).Format: [A-Z]{2}[0-9]{8,10}Example: 'US123456789'
CUSTCustomer Number request. A number assigned by an issuer to identify a customer or by a party to identify a creditor or debtor relationship.Format: (CUST)[0-9]{6,8}Example: 'CUST789456'
DUNSData Universal Numbering System request. A unique identification number provided by Dun & Bradstreet to identify an organization.Format: [0-9]{9}Example: '123456789'
EMPLEmployee Identification Number request.Format: (EMP)[0-9]{6,8}Example: 'EMP123456'
GS1GGS1 GLN (Global Location Number) Identifier request. A non-significant reference number used to identify legal, functional, or physical entities according to GS1 numbering scheme rules.Format: [0-9]{13,14}Example: 'GLN1234567890123'
SRENThe unique French business identification number assigned by INSEE, the French National Institute for Statistics and Economic Studies.Format: [0-9]{9}Example: '123456789'
SRETNumber providing information about the business location in France. The registration number contains an extra 5 digits (added to the end of the SIREN number to form the full SIRET number).Format: [0-9]{14}Example: '12345678900001'
TXIDTax Identification Number request.Format: (TX)[0-9]{8,12}Example: 'TX123456789'
BDIDBusiness Domain Identifier request. An identifier representing the business domain in which the organization operates.Format: (BUSDOM)[0-9]{5,10}Example: 'BUSDOM12345'
BOIDBusiness Other Identification request. Other identification for the organization.Format: Not specifiedExample: Not Applicable
Previous
Next