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

Version	Date	Description
1.0.0	15 Jan 2025	Original Digital Version. Aligned with PDF V1.3
1.1.0	17 Jan 2025	Added minor fixes. Updated 'nameMatched' to 'matchedName'
1.2.0	27 Jan 2025	Changed the format of the 'bicfi' fields
1.3.0	10 Feb 2025	Changed validation format to the request fields: 'accountId.type.iban' and 'lei'
1.3.1	19 Feb 2025	Changed 'unstructuredRemittanceInformation' type from 'String' to 'Array of Strings'
1.4.0	21 Feb 2025	Added new values and response logic to the field 'detailedMatchResult' and added examples
2.0.0	20 Mar 2025	Aligned to YAML and included formatting changes. Refer to the detailed changes here.
2.1.0	16 Apr 2025	Added the following new headers: X-End-User, X-Software-Supplier and X-Channel
2.2.0	15 May 2025	Added usage rules to unstructuredRemittanceInformation and organisation.others. Added format to unstructuredRemittanceInformation. Corrected the X-Request-Id example with valid RFC4122 value.
2.2.1	20 May 2025	Fixed malformed properties under `identification.organisationId`. Added missing `financialInstitutionId` object under the `requestingAgent` object.
2.2.2	16 Jun 2025	Updated description of EMPL from "employee" to "employer" under schemeNameCode. Updated description for `detailedMatchResult` field.

Endpoints

Environment	Endpoint URL
Sandbox	Available on request
Production	Available on request

Go directly to

Endpoints
Request
- Request Headers
- Request Body
Response
- Response Headers
- Response Body
Performance and Availability
Encoding and Special Characters
Security
Error Handling
List of Enumeration Values

Request

Request Headers

X-Request-IdStringMandatory
A RFC4122 UUID used as a correlation id.
Content-TypeStringMandatory
Content type and encoding of the request.
- Example: application/json
AcceptStringMandatory
The media type the client can process in the response. This is always set to application/json.
- Example: application/json
Accept-LanguageStringOptional
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.
X-End-UserStringOptional
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}
X-Software-SupplierStringOptional
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"
X-ChannelStringOptional
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 name	Example
X-Request-Id	123e4567-e89b-12d3-a456-426614174000
Content-Type	application/json;charset=utf-8
Authorization	Bearer <your bearer token>
Accept	application/json
Accept-Language	EN
X-End-User	FinanceDepartment
X-Software-Supplier	SupplierA
X-Channel	Web

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.

partyObjectMandatory
Provide information about the identification of the Payee.
nameStringConditional
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.

identificationObjectConditional
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.

organisationIdObjectOptional
Used to verify whether an organisation ID provided matches the organisation ID on the bank account.
leiStringConditional
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'

anyBICStringConditional
Business identification code of the organisation.

Usage Rule: Can only be used If lei or others are not used.

othersArray of ObjectsConditional
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.

Usage Rule: Only one entry to be used.

identificationStringMandatory
The identification code of the Payment Counterparty.

Format: Max. 256 characters.

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

Find the code list in here.

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

Format: Max. 35 characters.

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

Format: Max. 35 characters.
partyAccountObjectMandatory
Payment account details of the Payee.
ibanStringMandatory
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.
unstructuredRemittanceInformationArray of StringsOptional
Additional information about the account number sent by the Requester.
- Usage Rule: Only one entry to be used.
- Format: Max. 140 characters.
partyAgentObjectConditional
Identification of the Responding PSP.
- Usage Rule: Mandatory when Requesting PSP does not utilise the SurePay BIC Enrichment service.
financialInstitutionIdObjectMandatory
Financial Institution object.
bicfiStringMandatory
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'
requestingAgentObjectMandatory
Identification of the Requesting PSP.
financialInstitutionIdObjectMandatory
Financial Institution object.
bicfiStringMandatory
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

X-Request-IdStringMandatory
Value as sent in the corresponding request header.
Content-TypeStringMandatory
Content type and encoding of the request.
- Example: application/json

Example of Response Headers

Header name	Example
X-Request-Id	123e4567-e89b-12d3-a456-426614174000
Content-Type	application/json;charset=utf-8

Response Body

partyNameMatchEnumConditional
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.
partyIdMatchEnumConditional
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.
matchedNameStringConditional
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.
additionalPartyInformationObjectConditional
This is additional information on top of the VoP Scheme. Its availability is dependent on the responding PSP and whether the SurePay Plus subscription and Add-ons (like FRI) are enabled.
advancedInfoObjectConditional
This is advanced information on top of the VoP Scheme if subscribed to SurePay Plus. Its availability is dependent on the responding PSP.
accountHolderTypeEnumConditional
Describes the type of the account holder.

Possible Values:

NP: Natural Person.

ORG: Organisation.

UNKNOWN: Not provided by the Responding PSP.

accountStatusEnumConditional
The status of the account.

Possible Values:

ACTIVE: a valid account and supported for checks.

INACTIVE: a valid account marked by the Responding PSP as inactive.

UNKNOWN: for an account that its status has been not known/provided by the Responding PSP.

detailedMatchResultEnumConditional
Additional information in case the matching result was not a match.

Possible Values:

NAME_TOO_SHORT: the user only inputs a first name instead of a first name and surname.

BANK_NOT_FOUND: the Responding PSP is not yet part of the VOP Scheme.

OPTED_OUT: the account holder has opted out.

ID_NOT_SUPPORTED: the provided partyIdentification type is not supported by the Responding PSP.

NOT_FOUND: the account number was not found in the Responding PSP's records.

townNameStringConditional
The residence town/city of the account holder.
fraudRiskIndicatorObjectConditional
The fraud risk indicator object as a Add-on on top of the VoP Scheme.
switchingInformationObjectConditional
The switch check info object as a Add-on on top of the VoP Scheme. Only returned when the account has switched to another bank.

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 Code	Description
200 - OK	The request has succeeded.
400 - Bad request	Request has malformed, missing or non-compliant JSON body or URL parameters.
401 - Unauthorised	Authorization header missing or invalid token.
403 - Forbidden	Token has incorrect scope or a security policy was violated.
405 - Method not Allowed	The Requester tried to access the resource with a method that is not supported.
406 - Not Accepted	The 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 Requests	Too 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 error	Something 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 Timeout	There 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

X-Request-IdStringMandatory
Value as sent in the corresponding request header.
Content-TypeStringMandatory
Content type and encoding of the request.
- Example: application/json

Example of Error Response Headers

Header name	Example
X-Request-Id	123e4567-e89b-12d3-a456-426614174000
Content-Type	application/json;charset=utf-8

Error Response Body

typeStringMandatory
A URI reference [RFC3986] that identifies the problem type.
- Format: Max. 70 characters.
codeStringMandatory
Message code to explain the nature of the underlying error.
- Possible Values: Refer to the list here.
titleStringOptional
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.
statusStringOptional
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.
detailStringOptional
Detailed human readable text specific to this instance of the error.
- Format: Max. 500 characters.
instanceString
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 Code	Description
FORMAT_ERROR	Incorrect data format has been provided, not compliant with the expected specifications (e.g., invalid JSON format, missing or incorrectly formatted fields).
CLIENT_INVALID	The client is not recognised or is invalid (an attempt to access resources by an unauthorized client).
CLIENT_INCONSISTENT	The client information provided in the certificate and/or in the request message body is not consistent with related directory information
INTERNAL_SERVER_ERROR	An 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 Code	HTTP Code	Title	Detailer Error
FORMAT_ERROR	400	INVALID_HEADER	The provided value for the header ‘___’ differs from the expected format. Possible values : X-Request-Id, Accepted-Language, Content-Type and Authorization
FORMAT_ERROR	400	MANDATORY_HEADER_NOT_PROVIDED	A mandatory header ‘___’ has not been provided, therefore the request cannot be sent. Possible values : 'X-Request-Id', 'Content-Type' and 'Authorization'
FORMAT_ERROR	400	INVALID_REQUEST	The provided JSON format in the request does not comply with the expected structure.
FORMAT_ERROR	400	MANDATORY_FIELD_NOT_PROVIDED	The request is missing the mandatory field ‘____’. Possible values : 'name' or 'identification', 'bicfi' (requesting, agent), 'iban'
FORMAT_ERROR	400	INVALID_FIELD	The provided value for the field ‘____’ differs from the expected format. Possible values : 'name', 'identification','lei', 'schemeNameCode', 'schemeNameProprietary', 'anyBIC', 'bicfi' (requesting, agent), 'issuer'
FORMAT_ERROR	400	NAME_TOO_LONG	The value provided in the field ‘name’ is longer than the maximum number of characters: 140.
FORMAT_ERROR	400	MUTUALLY_EXCLUSIVE_FIELDS_USED	Two fields mutually exclusive were added in the request. Possible values : 'name' and 'identification'; 'lei', 'anyBIC' and 'others'; 'schemeNameCode' and 'schemeNameProperty'
CLIENT_INVALID	401	The API Client has a valid certificate but is not contained in the addressed scheme directory	The Requesting’s PSP is not adherent to the Scheme.

List of Enumeration Values

schemeNameCode

The following table contain a list of enumeration values:

Enumeration value	Description	Format	Example
BANK	Bank 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'
CBID	Central 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'
CHID	Clearing 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'
CINC	Certificate 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'
COID	Country 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'
CUST	Customer 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'
DUNS	Data Universal Numbering System request. A unique identification number provided by Dun & Bradstreet to identify an organization.	Format: `[0-9]{9}`	Example: '123456789'
EMPL	Employer Identification Number request. Number assigned by a registration authority to an employer.	Format: `(EMP)[0-9]{6,8}`	Example: 'EMP123456'
GS1G	GS1 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'
SREN	The unique French business identification number assigned by INSEE, the French National Institute for Statistics and Economic Studies.	Format: `[0-9]{9}`	Example: '123456789'
SRET	Number 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'
TXID	Tax Identification Number request.	Format: `(TX)[0-9]{8,12}`	Example: 'TX123456789'
BDID	Business Domain Identifier request. An identifier representing the business domain in which the organization operates.	Format: `(BUSDOM)[0-9]{5,10}`	Example: 'BUSDOM12345'
BOID	Business Other Identification request. Other identification for the organization.	Format: Not specified	Example: Not Applicable