POST/oauth/client_credential/accesstoken

Webhook API Specification

This page describes the specification that the customer needs to implement to receive Webhook calls.
SurePay VOP Bulk API Webhook Service is designed for Payment Service Providers (PSP) that send bulk VOP requests, either within the SurePay ecosystem or to external VOP responders, while complying with the EPC VOP Rulebook requirements.
A consumer of the VOP Bulk API should be able to register to the webhook service and receive status notifications after the bulk VOP request has been processed. However the internal logic of the service is not part of this specification.

This specification outlines the API structure, data models, and response handling to ensure a seamless and standardized integration. By following this guide, PSPs can confidently implement a robust VoP solution that meets industry standards.

Document History

Expand to view the version history.

VersionDateDescription
1.015 Jan 2026Original Digital Version. Aligned with PDF V1.1

Go directly to

Expand to view the table of contents.

What items do we need to establish the connection?

  • The exact endpoints for both production and test environments.
  • The certificates required to connect to the provided endpoints (SurePay's certificates are signed by DigiCert).
  • Client credentials, if needed, to access an Access Token API.
  • The token endpoint to be used with the above client credentials to retrieve the access token. This should be implemented according to the RFC6749 standard, you can find the specification here.
  • A text file containing equivalent "curl" requests.

Request

Request Headers

  • AuthorizationStringMandatory

    OAuth 2.0 bearer token. An authentication endpoint must be provided where a token can be fetched and refreshed.
    The endpoint you specify during onboarding will receive POST requests containing JSON formatted data from SurePay.

Example of Request headers

Header nameExample
AuthorizationBearer <a bearer token>

Request Body

  • taskIdStringMandatory

    Unique ID used for retrieving the result in a separate request.

  • statusEnumMandatory

    The status of the bulk request after completion.

    • Possible values:
      • PROCESSED
      • FAILED

Request

POST
{customer_provided_url}
    { 
      "taskId": "12930484-129284501-ecernb",
      "status": "PROCESSED"
    }

Response

The response on the API call results:
• Successful response (HTTP 200)
• Error response (HTTPXXX)

In case of an unsuccessful response, a meaningful HTTP code and error message is expected.

Retries

If your service has problems handling notifications at any time, SurePay will attempt to re-send failed notifications up to 4 times (5 attempts).

SurePay will retry in the following cases:
• Connection failed: SurePay cannot open an HTTP connection to the provided webhook URL or access token URL.
• Timeout: your service takes longer than five seconds to send back a response.
• Error codes: your service responds with any HTTP status code (4xx or 5xx).

Notifications will be retried up to 5 times. These retries will be spread out over the next 24 hours, with varying delays between requests.

Previous
Next