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

VersionDateDescription
1.015 Jan 2025Original Digital Version. Aligned with PDF V1.0
1.114 Feb 2025Updated format of lei number & Bicfi format as per the EPC
1.220 Feb 2025Updated Language in request header from ISO639 to ISO639-1, Updated unstructuredRemittanceInformation from String to Array of Strings.
2.020 Mar 2025Format changes, aligned with VoP single check API. Refer to the detailed changes here.
2.116 Apr 2025Updated 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.215 May 2025Added usage rules to unstructuredRemittanceInformation and organisation.others. Added format to unstructuredRemittanceInformation. Corrected the X-Request-Id example with valid RFC4122 value.
2.316 Jun 2025Updated description of EMPL from "employee" to "employer" under schemeNameCode.

Go directly to

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.

  • AcceptStringMandatory

    The media type the client can process in the response. 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 nameExample
X-Request-Id123e4567-e89b-12d3-a456-426614174000
Content-Typeapplication/x-ndjson;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. 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 nameExample
X-Request-Id123e4567-e89b-12d3-a456-426614174000
Content-Typeapplication/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"
}

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'
EMPLEmployer Identification Number request. Number assigned by a registration authority to an employer.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