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.

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/x-ndjson
  • 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 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-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.

  • Name
    uetr
    Type
    String
    Tag(s)
    Mandatory
    Description

    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.

  • 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.
          • Usage Rule: Only one entry to be 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.

    • Usage Rule: Only one entry to be used.
    • Format: Max. 140 Characters.
  • 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/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

  • 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-426614174000
Content-Typeapplication/json;charset=utf-8

Response Body

  • Name
    taskId
    Type
    String
    Tag(s)
    Mandatory
    Description

    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'
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