POSTvopgateway/v1/single

API Specification

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

Document History

VersionDateDescription
1.015 Jan 2025Original Digital Version. Aligned with PDF V1.3
1.117 Jan 2025Added minor fixes. Updated 'nameMatched' to 'matchedName'

Endpoints

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

Go directly to

Headers

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

    A RFC4122 UUID used as a correlation id.

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

    Content type and encoding of the request.

  • Name
    Authorization
    Type
    Bearer
    Tag(s)
    Mandatory
    Description

    Oauth 2.0 bearer token.

  • Name
    Accept-Language
    Type
    String
    Tag(s)
    Optional
    Description

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

    • Format: ISO 639.

Example of Request headers

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

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
      String
      Tag(s)
      Conditional
      Description

      Organisation’s legal identification.

      • Required 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)
        Description

        Used to verify whether an organisation ID matches a 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: If ‘lei’ is used, ‘other’ and ‘anyBIC’ fields cannot be used. 
          • Format: ^[0-9]{4}00[A-Z0-9]{12}[[A-Z]0-9]{2}?$
          • Example: '549300DTUYXVMJXZNY7'
        • Name
          anyBIC
          Type
          String
          Tag(s)
          Conditional
          Description

          Business identification code of the organisation.

          • Usage Rule: If ‘anyBIC’ is used, ‘lei’ or ‘others’ fields cannot be used.
        • Name
          others
          Type
          Object
          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
            schemeNamePropietary
            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)
            Description

            Entity that assigns the identification.

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

    Additional information about the account number sent by the Requester.

  • Name
    partyAccount
    Type
    Object
    Tag(s)
    Mandatory
    Description

    Used to verify whether a person ID matches a bank account.

    • 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}
  • Name
    partyAgent
    Type
    Object
    Tag(s)
    Mandatory
    Description

    Identification of the Responding PSP.

    • 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]{4}[A-Z]{2}[1-9][A-Z]{2}[1-9][A-Z]{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 Responding PSP (Swift BIC). BIC of the Agent.

        • Format: [A-Z]{4}[A-Z]{2}[1-9][A-Z]{2}[1-9][A-Z]{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)

Headers

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

    The Requesting PSP’s reference number of the VOP Request. Value sent in the request, mapped directly to the response (not generated again).

Example of Request headers

Header nameExample
X-Request-Id123e4567-e89b-12d3-a456-42661417400

Body

  • Name
    partyNameMatch
    Type
    Enum
    Tag(s)
    Conditional
    Description

    Describes the result of the IBAN-Name Check.

    • MTCH (Match)
    • CMTC (Close Match)
    • NMTC (No Match)
    • NOAP (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)
    • NMTC (No Match)
    • NOAP (Not Applicable) Only applicable if ‘identification’ object has been added in the request.
  • Name
    matchedName
    Type
    String
    Tag(s)
    Conditional
    Description

    Contains 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)
    Add-on feature
    Description

Response

POST
vopgateway/v1/single
{
    "partyNameMatch": "MTCH"
}

Security

The API is designed for usage by a trusted backend or middleware service. Each single 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 a server-server connection is permitted. If a connection is compromised, SurePay can disconnect it.

The interface is based on various premises, these premises are:

  • The SurePay API client is a trusted partner.
  • On 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).
  • We support SSL session reuse.

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.

Response

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

    The string ‘application/json’ is used.

Body

  • Name
    type
    Type
    String
    Tag(s)
    Mandatory
    Description

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

  • Name
    code
    Type
    String
    Tag(s)
    Mandatory
    Description

    Message code to explain the nature of the underlying error.

  • Name
    title
    Type
    String
    Tag(s)
    Description

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

  • Name
    status
    Type
    String
    Tag(s)
    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)
    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.

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
TIMESTAMP_INVALIDThe timestamp provided in the request is invalid (incorrect format, value in the future, or if it exceeds the allowed validity period by the system).

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', 'unstructuredRemittanceInformation'
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_ERROR400DUPLICATED_FIELDThe request contains two fields duplicated.
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.
Certificate items401Certificate is invalid, revokedThe API Client’s certificate is not a valid PSD2 QWAC.
CLIENT_INCONSISTENT401-Certificate’s NAN and request BIC do not match
Internal Server Error500-An exception occurs during code execution and the request cannot be further processed

Error response

[
    {
        "type": "https://surepay.com/problem-type/duplicated-field",
        "code": "FORMAT_ERROR",
        "title": "DUPLICATED_FIELD",
        "status": 400,
        "detail": "The request contains two fields duplicated.",
        "instance": "/request/body/field-name"
    }
]

List of Enumeration values

schemeNameCode

The following table contain a list of enumeration values:

Enumeration valueDescriptionFormatExample
BANKRequestBankPartyIdentification. Bank party identification is requested. This is a unique and unambiguous assignment made by a specific bank or similar financial institution to identify a relationship as defined between the bank and its client.Format: [CountryCode][BankCode][BranchCode]Example: 'US123BANK001'
CBIDRequestCentralBankIdentificationNumber. Central bank identification number is requested. This is a unique identification number assigned by a central bank to identify an organisation.Format: (CB)(0-9)[9-12 digits]Example: 'CB123456789'
CHIDRequestClearingIdentificationNumber. Clearing identification number is requested. This is a unique identification number assigned by a clearing house to identify an organisationFormat: (A-Z)(2-4 letters)(0-9)(4-6 digits)Example: 'CHCLRG1234'
CINCRequestCertificateOfIncorporationNumber. Certificate of incorporation number is requested. This is a unique identification number assigned by a designated authority to a certificate of incorporation and used to identify an organisation.Format: (INC)(0-9)(7-10 digits)Example: 'INC1234567'
COIDRequestCountryIdentificationCode. Country identification code is requested. This is a country authority given organisation identification (e.g., corporate registration number).Format: (A-Z)(2 digits)(0-9)(8-10 digits)Example: 'US123456789'
CUSTRequestCustomerNumber. Customer number is requested. This is a number assigned by an issuer to identify a customer or a number assigned by a party to identify a creditor or debtor relationship.Format: (CUST)(0-9)(6-8 digits)Example: 'CUST789456'
DUNSRequestDataUniversalNumberingSystem. Data universal number is requested. This is a unique identification number provided by Dun & Bradstreet to identify an organisation.Format: (0-9)(9 digits)Example: '123456789'
EMPLRequestEmployeeIdentificationNumber. Employee Identification Number is requested.Format: (EMP)(0-9)[6-8 digits]Example: 'EMP123456'
GS1GRequestGS1GLNIdentifier. GS1GLN (Global location number) identifier is requested. This is a non-significant reference number used to identify legal entities, functional entities, or physical entities according to GS1 numbering scheme rules. The number is used to retrieve detailed information that is linked to it.Format: (0-9)(13-14 digits)Example: 'GLN1234567890123'
SRENRequestSIREN. SIREN number is requested. This is a 9 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation in France.Format: (0-9)(9 digits)Example: '123456789'
SRETRequestSIRET. SIRET number is requested. This is a 14 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation unit in France. It consists of the SIREN number, followed by a five digit classification number, to identify the local geographical unit of that entity.Format: (0-9)(14 digits)Example: '12345678912345'
TXIDRequestTaxIdentificationNumber. Tax Identification Number is requested.Format: (TX)(0-9)(8-12 digits)Example: 'TX123456789'
BDIDRequestBusinessDomainIdentifier. Identifier of the business domain in which the organisation is active is requested.Format: (BUSDOM)(0-9)(5-10 digits)Example: 'BUSDOM12345'
BOIDRequestBusinessOtherIdentification. Other identification of the organisation is requested.--
Previous
Next