GET/vopgateway/v1/bulk/{taskId}/status

Bulk Status Request API Specification

This endpoint allows you to check the current status of a bulk request using the taskId provided during the request submission. By querying this endpoint, you can determine when the result file is ready to be fetched or if any errors occurred during processing. The response will include the current status of the bulk request.

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	20 Feb 2025	Updated Language in request header from ISO639 to ISO639-1
2.0	20 Mar 2025	Format changes. Refer to detailed changes here.
2.1	16 Apr 2025	Added the following new headers: X-End-User, X-Software-Supplier and X-Channel
2.2	21 Jul 2025	Removed Content-Type from headers. 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 Statuses

The status field can have one of the following values:

Status	Description
NOT_STARTED	The file is in the queue, waiting to be processed.
IN_PROGRESS	The file is actively being processed, and individual records are being checked.
PROCESSED	The file has been successfully processed and is ready to be fetched.
FAILED	The file processing failed due to one of the following reasons: invalid format, corruption, or exceeding the maximum size/record limit.
TIMED_OUT	The file was not processed within the service-level agreement (SLA) timeframe. This could be due to timeouts from the responding PSPs.

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/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.
- 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 name	Example
X-Request-Id	123e4567-e89b-12d3-a456-426614174000
Authorization	Bearer <your bearer token>
Accept	application/json
Accept-Language	EN
X-End-User	FinanceDepartment
X-Software-Supplier	SupplierA
X-Channel	Web

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 status and result in a separate request. This is returned in the response when submitting the bulk request.

Request

GET

/vopgateway/v1/bulk/{taskId}/status

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

Response

Response Headers

X-Request-IdStringMandatory
Value as sent in the corresponding request header.

Example of Response Headers

Header name	Example
X-Request-Id	123e4567-e89b-12d3-a456-426614174000

Response Body

statusEnumMandatory
The status of the bulk request. In the case of a FAILED or TIMED_OUT response, the bulk request has to be resent.\

Values:
- NOT_STARTED: The file is in the queue, waiting to be processed.
- IN_PROGRESS: The file is actively being processed, and individual records are being checked.
- PROCESSED: The file has been successfully processed and is ready to be fetched.
- FAILED: The file processing failed due to one of the following reasons: invalid format, corruption, or exceeding the maximum size/record limit.
- TIMED_OUT: The file was not processed within the service-level agreement (SLA) timeframe. This could be due to timeouts from the Responding PSPs.
detailStringConditional
The reason is provided if the status is FAILED or TIMED_OUT.

Response

{
  "status": "IN_PROGRESS"
}

Error Handling

Status and Error Codes

When an application error message occurs, an HTTP status code will be returned with an error message. 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.
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

[
  {
    "status": 400,
    "type": "https://developer.surepay.nl/vop-bulk-for-banks/status-and-errorcodes",
    "code": "FORMAT_ERROR",
    "title": "INVALID_FIELD",
    "detail": "Field 'taskId' must be a UUID",
    "instance": "/vopgateway/v1/bulk/abc/status"
  }
]

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_FIELD	The provided taskId in the request does not comply with the expected structure.