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

VersionDateDescription
1.015 Jan 2025Original Digital Version. Aligned with PDF V1.0
1.120 Feb 2025Updated Language in request header from ISO639 to ISO639-1
2.020 Mar 2025Format changes. Refer to detailed changes here.
2.116 Apr 2025Added the following new headers: X-End-User, X-Software-Supplier and X-Channel

Go directly to

List of Statuses

The status field can have one of the following values:

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

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/json
  • 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 always 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.
    • Value of the header will have no effect on the end result.
    • 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/json;charset=utf-8
AuthorizationBearer <your bearer token>
Acceptapplication/json
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.

  • Name
    taskId
    Type
    String
    Tag(s)
    Mandatory
    Description

    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

  • 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
    status
    Type
    Enum
    Tag(s)
    Mandatory
    Description

    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.
  • Name
    detail
    Type
    String
    Tag(s)
    Conditional
    Description

    The reason is provided if the status is FAILED or TIMED_OUT.

Response

{
  "status": "IN_PROGRESS"
}
Previous
Next