GET/vopgateway/v1/bulk/{taskId}

VOP Plus Results Request API Specification

This chapter provides detailed information on how to retrieve the Plus results of a bulk request. This document specifically covers the Plus offering of the API.

The Plus offering builds upon the Standard (EPC-compliant) version by including additional information related to the account and name check result. This includes fields such as the account holder type (e.g., Natural Person or Organisation) and expanded details for NMTC and NOAP responses, providing greater context and transparency in match results.

The results file can only be retrieved after the status of the bulk request has been updated to 'PROCESSED'. The response to this request is returned in NDJSON format, containing the finalized data for the completed bulk operation.

Document History

Expand to view the version history.

VersionDateDescription
1.021 Jul 2025Standard version split from V2.3 of the original Bulk Results API Specification. The original version can be viewed here. Error Handling section added. Name too short example updated. Removed Content-Type from headers. Accept Header updated to optional, default value added.

Go directly to

Expand to view the table of contents.

Request

Request Headers

  • X-Request-IdStringMandatory

    A RFC4122 UUID used as a correlation id.

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

    • Example: applicaton/x-ndjson
  • Accept-LanguageStringOptional

    Can be provided by the Requesting PSP to be used as language in the 'nameSuggestion' 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.
    • Value of the header will have no effect on the end result.
    • 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
AuthorizationBearer <your bearer token>
Acceptapplication/x-ndjson
Accept-LanguageEN
X-End-UserFinanceDepartment
X-Software-SupplierSupplierA
X-ChannelWeb

Request Body

This endpoint does not require a request body. The taskId is passed as a path parameter.

  • taskIdStringMandatory

    The Unique ID used for retrieving the result in a separate request. This is returned in the response when submitting the bulk request.

Request

GET
/vopgateway/v1/bulk/taskId
GET /vopgateway/v1/bulk/12930484-129284501-ecernb

Response

The response is an NDJSON file.

  • 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-DispositionStringMandatory

    Attachment where the filename is the taskId.

    • Example: "taskId.ndjson"

Example of Response headers

Header nameExample
X-Request-Id123e4567-e89b-12d3-a456-426614174000
Content-DispositiontaskId.ndjson

Response Body

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

  • 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: Natual 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.

    • fraudRiskIndicatorArray of ObjectsConditional

      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

{"uetr": "2f01983c-a558-445c-8728-dba547d2ff8b", "partyNameMatch": "MTCH", "additionalPartyInformation": {"advancedInfo": {"accountHolderType": "NP", "accountStatus": "ACTIVE"}}}

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. When interacting with this API, you may encounter two primary categories of errors: technical errors and record-level errors.

Technical Errors

Technical errors indicate issues with the API request itself, preventing successful processing. These errors are reflected in the HTTP status code of the response and typically fall within the 4xx or 5xx range. Examples include 401 Unauthorised (indicating missing or invalid authentication credentials) or 500 Internal Server Error (signifying a problem on the server's end). 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/or a character set other than UTF-8.
415 - Unsupported Media TypeThe request contained a Content-Type header other than application/x-ndjson and/or a character set other than UTF-8.
429 - Too Many RequestsToo many requests towards the endpoint.
500 - Internal Server ErrorSomething 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.

Record Level Errors

In contrast, record-level errors are not reflected in the HTTP status code of the initial API response. Instead, these errors are contained within the downloaded NDJSON result file. They indicate issues with the data within individual records (rows) of your file, typically related to invalid or malformed values. While these errors generally correspond to a 400 Bad Request at a logical level, their specific details and structure, following an NDJSON format, are thoroughly explained in the Functional Errors section of this document.

Error Response

The JSON formats detailed below are returned when an API-level error (also referred to as a request or technical error) occurs, indicating an issue with the request itself.

Conversely, an NDJSON example is provided for scenarios where errors are returned within the result file per record, signifying issues with individual data entries rather than the overall request.

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 nameExample
X-Request-Id123e4567-e89b-12d3-a456-426614174000
Content-Typeapplication/json;charset=utf-8

Error Response Body

  • uetrStringConditional

    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. This is only provided in record level errors.

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

API 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/ea933c4c-67f1-4883-8a93-75c3d90e0b36/status"
  }
]

Record Level Error response

{"uetr":"13b8472f-d796-436a-ba76-0be4ec234206","status":400,"type":"https://surepay.com/problem-type/invalid-input","code":"FORMAT_ERROR","title":"Invalid input data","detail":"Presence of two fields that are mutually exclusive","instance":"/request/body/field-name"}
{"uetr":"13b8472f-d796-436a-ba76-0be4ec234207","status":400,"type":"https://surepay.com/problem-type/invalid-input","code":"FORMAT_ERROR","title":"Invalid input data","detail":"Presence of two fields that are mutually exclusive","instance":"/request/body/field-name"}

Functional Errors

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'
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_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'
Previous
Next