Skip to main content

Authentication & Idempotency

Authentication​

Authentication​

The Paysend Enterprise API uses API keys and digital signatures for authentication and request validation.

API Keys You will receive two sets of API keys:

  • A key for inbound requests (your requests to our API)
  • A key for outbound requests (our notifications to your systems)

Request Signing​

All API requests must include a digital signature in the X-OPP-Signature header. To generate this signature:

  1. Construct the source string: {RequestBody}{InboundAPIKey}
  2. Apply the agreed-upon hash algorithm to this source string.
  3. Convert the resulting hash to a hexadecimal string.

Signing for Status Checks�​

For�status check operations (e.g., when querying a request�s status using the�globalId) you must instead compute the hash over the�{globalId}{InboundAPIKey}�string. This ensures the�X-OPP-Signature�header is correctly generated for status queries as well as regular API calls, and is required for the Paysend Enterprise API to validate the authenticity of both types of operations.

Supported Hash Algorithms​

Paysend Enterprise API supports the following hash algorithms for generating signatures:

  • SHA-256
  • SHA-512 Choose the algorithm that best fits your security requirements.

Idempotency​

Idempotency is a crucial feature in financial APIs that ensures the same operation is not accidentally performed multiple times. This is particularly important for payment transactions to prevent duplicate charges or transfers. The Paysend Enterprise API implements idempotency using a combination of two key elements:

  • Idempotency Key: A unique identifier for each API request.
  • Request Timestamp: The time at which the request was initiated by the client.

When making a request to the API:

  1. Generate a unique idempotency key for each new request.
  2. Include the idempotency key in the header.request.id field of your request.
  3. Include the current timestamp in the header.request.date field.

Example request header:

"header": {
  "request": {
      "id": "unique-idempotency-key-123",
      "date": "2024-08-15T14:30:00Z"
  }
}