POST/vopgateway/v1/bulk

Bulk Request API Specification

This chapter contains information on the header, request, and response body required to make a successful bulk request with the EPC compliant API for Banks. You can read about the error status and codes here.

Document History

Expand to view the version history.

Version	Date	Description
1.0	15 Jan 2025	Original Digital Version. Aligned with PDF V1.0
1.1	14 Feb 2025	Updated format of lei number & Bicfi format as per the EPC
1.2	20 Feb 2025	Updated Language in request header from ISO639 to ISO639-1, Updated unstructuredRemittanceInformation from `String` to `Array of Strings`.
2.0	20 Mar 2025	Format changes, aligned with VoP single check API. Refer to the detailed changes here.
2.1	16 Apr 2025	Updated request structure to align the fields to their expected level and added the following new headers: X-End-User, X-Software-Supplier and X-Channel
2.2	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.3	16 Jun 2025	Updated description of EMPL from "employee" to "employer" under schemeNameCode.
2.4	21 Jul 2025	Accept Header updated to optional, default value added. Error Handling section added.

Go directly to

Expand to view the table of contents.

Request
- Request Headers
- Request Body
Response
- Response Headers
- Response Body
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/x-ndjson
AuthorizationStringMandatory
OAuth 2.0 bearer token.
AcceptStringOptional
The media type the client can process in the response. If not provided, this is 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/x-ndjson;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. The body of the request is a file in NDJSON format, applying the following data model for each record in the file. The client should stream the NDJSON file.

uetrStringMandatory
The Unique End-to-End Transaction Reference (UETR) is an RFC4122 UUID used as a record-level correlation ID to uniquely track and trace individual transactions throughout the process.
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/bulk

{"uetr":"13b8472f-d796-436a-ba76-0be4ec234206","party":{"name":"Henri Groenen"},"partyAccount":{"iban":"NL11RABO1234567890"},"unstructuredRemittanceInformation":["1234512345"],"partyAgent":{"financialInstitutionId":{"bicfi":"ABCDBEBBXXX"}},"requestingAgent":{"financialInstitutionId":{"bicfi":"ABCDBEBBXXX"}}}

Response

The response is the taskId of the bulk request.

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

taskIdStringMandatory
The unique ID of the bulk request, used to retrieve the status and ultimately the result file when completed.

Response

{
    "taskId": "12930484-129284501-ecernb"
}

Error Handling

Status and Error Codes

When an application error message occurs, an HTTP status code will be returned with an error message. The return format of the error messages are technical errors and functional errors.

Errors encountered when calling this endpoint pertain to the overall request rather than individual records within the uploaded file. A request-level error signifies that the file was not successfully uploaded and, consequently, no bulk checks were performed. Such errors typically arise from an invalid request format, such as an unreadable file (eg. zip file), an empty file, or a file exceeding the maximum allowed size.

It is possible to receive a 200 OK response from this endpoint, only to discover record-specific errors when retrieving results from the Download Results endpoint. These record-level errors, which pertain to individual rows within the NDJSON file, are detailed in the documentation for the Download Results endpoint.

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/or a character set other than UTF-8.
415 - Unsupported Media Type	The request contained a Content-Type header other than application/x-ndjson and/or a character set other than UTF-8.
429 - Too Many Requests	Too many requests towards the endpoint.
500 - Internal Server Error	Something went wrong on the Bulk API or service. In this case the body might contain extra details. This error can also be returned if the upstream service returns an error.

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

statusIntegerOptional
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.
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.
- Format: Max. 70 characters.
- Possible Values: Refer to the list here.
detailStringOptional
Detailed human readable text specific to this instance of the error.
- Format: Max. 500 characters.
instanceStringOptional
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

[
  {
    "status": 400,
    "type": "https://developer.surepay.nl/vop-bulk-for-banks/status-and-errorcodes",
    "code": "FORMAT_ERROR",
    "title": "INVALID_HEADER",
    "detail": "'X-Request-Id' header has a maximum of 128 characters",
    "instance": "/vopgateway/v1/bulk"
  }
]

Functional Errors

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.

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