Skip to main content

API overview

The API reference provides the technical descriptions of the Payout API. The API provides multiple services e.g. complete payment processing to cards and accounts, perform a check on the status of a previously requested task/action, create a multi-task request to complete multiple functions. A list of available functions for the API is found in the POST /processing endpoint description (Request body -> payload.tasks).

A unique component of the API is that it allows a partner/customer to independently construct an API request processing flow based on their own requirements. All partners/customers can request the Enterprise product to complete a sequence of available functions. The API reference describes the recommend interaction flow between a partner/customer and the API, API methods and the available functions.

info

The recommended approach for API interaction is the asynchronous flow.

Asynchronous​

Asynchronous flow is the main flow to interact with API. A customer sends a request to process and receives a response with GlobalId for future status checks. After receiving a global identifier, the customer’s system waits for further notification requests (if the URL for notifications was included in the first request). When a notification is received, the customer’s system sends a status check request to obtain the changed information.

The following sequence of actions takes place for the asynchronous flow. The asynchronous interaction with API includes a callback from API to the customer’s system. The URI for the callback is defined in the request. Each request includes a different URI for the call back.

Registering request​

Registering request

Request processing and status retrieval​

Request processing and status retrieval

Synchronous​

Synchronous flow is not available for the Enterprise product, however a synchronous flow/interaction can be simulated if required.

warning

If the processing action is completed in less than 2 seconds, a response is provided synchronously. If a response takes longer than 2 seconds to complete, the interactions continue following the asynchronous flow. We do not recommend using this interaction option.

The following sequence of actions takes place for the synchronous flow.

Synchronous flow

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 (e.g., MD5) to this source string.
  3. Convert the resulting hash to a hexadecimal string.

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. We recommend using MD5 for a good balance of security and performance.

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"
  }
}

Request​

info

Detailed request body description can be found on POST /processing endpoint page.

The API supports programmable requests where each request is formed of a set of task trees. The below diagram is an example of the request structure.

The API request supports both simple and complex logic where a request can contain a single task, multiple tasks or multiple task trees.

Tasks can be linked by their results. A Request supports Success or Fail link types.

Tasks on the same execution level are executed in parallel. Execution of the request is finished when there are no more tasks to execute on the next execution level.

Each task in the diagram above is a function or template. Registry of functions defines the product. The list of available functions is found in the Response section.

A request is described as the following object:

{
    "header": {
        "request": {              
            "id": "string",
            "date": "date"
        },
        "service": {
            "sync": "boolean",
            "waitTime": "enum"
            "result": [
                {
                    "type": "enum",
                    "uri": "string",
                    "method": "enum"
                }
            ]
        }
    },
    "payload": {}
}

payload​

This is the most important part of request. This object contains the partner information, configuration for execution and the set of tasks.

Each payload is presented as:

"partner": {
    "identifier": "string",
    "parameters": {
        "anyParamName0": "string",
        "anyParamName1": "string"
    }
},
"settings": {
    "culture": "string",
    "encoding": "string",
    "contact": "string",
    "userIp": "string"
},
"tasks": []

task​

A task is an atom element within the Enterprise product. A task is a reference to the function and payload which include links to next level of execution and configuration of the execution process.

Each task can be represented by:

{
    "type": "string",
    "payload": {}, //task details should be here
    "success”: [], //list of task to execute if main task (in payload) succeeds
    "fail": [], //list of task to execute if main task (in payload) fails
    "always”: [], //list of task to execute after main task (in payload) not depending on result
    "expiration": {
        "date": "string"
    }
}

The tree of task helps to program the execution flow of requests. For example, a tree of tasks enables a card payment to be processed and a confirmation email is sent depending on the result of processing e.g. if the payment is successful a confirmation success email is sent, if the payment fails, a payment declined email is sent.

Response​

info

Detailed response body description can be found on POST /processing endpoint page.

A Response to processing or status requests is an object and includes all the requested fields and also includes the result or process status information relating to the request. Each of the tasks also includes result{} object with information on task status and data{} object (where applicable) with task-specific fields.

{
    "header": {
        "request": {
            "id": "string",
            "date": "date"
        },
        "response": {
            "globalId": "string",
            "id": "string",
            "date": "date"
        },
        "service": {
            "sync": "boolean",
            "waitingTime": "enum",
            "result": [
                {
                    "type": "enum",
                    "uri": "string",
                    "method": "enum"
                }
            ]
        }
    },
    "result": {
        "status": "enum",
        "code": "integer",
        "comment": "string",
        "interactive": {
            "type": "enum",
            "uri": "string",
            "method": "enum"
        }
    },
    "payload": {}
}

Status​

info

Detailed description of task statuses is available on Statuses page.

HTTP Status codes​

200 – OK​

This code is returned if the response is successful (and a specific response is required). A Response object is returned in the response.

400 – Bad request​

This code is returned if there is an issue in the request and an Error object is returned in the response. For example, this code will be returned if a request is sent without a header.request and empty payload.tasks which would be displayed as:

401 – Unauthorized​

That code is returned by system if the Signature or other partner information is incorrect.

404 – Not found​

This code is returned if the system cannot process the request now. If this code is received, a repeat request is submitted after a few seconds. If the code continues to be returned, this is escalated to the Support team. The system will return a response body with the text Sorry. Can't accept your request now..

Notifications​

A requestor can manage notifications in the request. By default, requestor can configure backward notification URL in each request. The requestor can configure more than one URL for notification in each request. In group with flexible parameters set in partner section, requestor can delegate a part of his logic to Paysend system.

The normal notification flow is described below:

  1. configure URL for notifications in request;
  2. get request on configured URL;
  3. request status from Enterprise API.

For example.

{
    "header": {
        …
        "service": {  
            …
            "result": [
                {
                    "type": "Web",
                    "uri": "https://www.company.com/paysend",
                    "method": "GET"
                }
            ]
        }
    },
    …
}

When the processing of a request is finished, all configured result item will get a request with parameter globalId that must be identical as parameter globalId in response.

In our example, when processing will be finished, we receive the request https://www.company.com/paysend?globalId=00000000-0000-0000-0000-000000000000.

If the configured method was POST for notifications, we receive the string globalId=00000000-0000-0000-0000-000000000000 in request body.

In our example, 00000000-0000-0000-0000-000000000000 is an example of globalId value. In real life, we will receive a real value of this key.

warning

Please check X-OPP-Signature header to verify that notification request was sent by API.