Callbacks

INFO

This section describes the capabilities of the PayStar platform's callback system — including how to configure callbacks, which fields can be received, and how to verify the callback signature.

URL Configuration

In PayStar platform, implemented a callback function - there is two ways to set it up:

For static url Account manager can add it in endpoint configuratuin - you need to provide your static url.

For dinamic url, you can send it in payment.
PayStar.uk_Callbacks_Setting.png

Example of request with dinamic callback url

curl --request POST \
 --url https://secure.PayStar.uk/api/v1/integration/deposit-order\ 
 --header 'Authorization: Bearer YOUR TOKEN' \ 
 --header 'Content-Type: application/json' \
 --header 'accept: text/plain' \
 --data '{
  "amount": 100,
  "currency": "USD",
  "externalTransactionId": "MerchantPaymentId-12345",
  "callbackUrl": "http://merch.com/MerchantPaymentId-12345"
}'

Example of callback body with payment history

{
  "externalId": "PayStar-bf95219b-393d-4323-91bf-639be",
  "status": "Created",
  "amount": "100",
  "orderType": "Deposit",
  "externalParams": {
    "cardToken": "BankToken-bf95219b-393d-4323-91bf-639ac",
    "cardStorageToken": "PayStarToken-bf95219b-393d-4323-91bf-639ac",
    "cardHolder": "123456****1234",
    "cardNumber": "JOHN WEAK"
  },
  "orderHistory": [
    {
      "Time": "2026-02-17T12:29:05.421337",
      "Action": null,
      "NewCode": "1.1.2.00"
    },
    {
      "Time": "2026-02-17T12:29:05.448393",
      "Action": null,
      "NewCode": "2.1.1.00"
    }
  ]
}

Callback type configuration

In PayStar platform, implemented a five types of callbac - you need to provide us what type of callbacks you'd like to recive:

Payment in Create status

Payment in Prigress status

Payment in Success status

Payment in Failed status

Payment Amount was changed (availeble in some payment flow)

Callback request

Callback will be a POST HTTP request to the address you have configured, depending on the status the order transitions to.

The request will include a "Signature" header by which you can verify the validity of the request. However, we still recommend making a request to check the status.

:::

CallBack params

externalId - order id in our system (string)
amount - order amount (number)
currency: order currency
status - order status (string)
orderType - type of the order (string) It can accept values Deposit or Withdrawal
cardToken - card token issued by a bank
cardStorageToken - card token issued by a PayStar.uk
cardNumber - card mask 6x4
cardHolder - card holder name

Signature validation

The request will include a Signature header, which you can use to verify that the request is valid. However, we still recommend making a status check request.

Step 1 - Retrieving Data for the Signature

Extract the values of externalId, status, amount and orderType from the request.

Use your privateKey to construct the signature string in the following format: externalId;status;amount;orderType;privatekey

Step 2 - Calculating the Signature

Apply SHA-256 hashing to the string obtained in Step 1.

Convert the hash result to a hexadecimal string.

Step 3 - Verifying the Signature

Extract the Signature header from the request.

Repeat steps 1 and 2 to obtain the expected signature.

Compare the received signature with the expected one. If they match, the request signature is valid.

Examples of validation

JavaScript

Python

C Sharp

Callback retries (undelivered notifications)

If your endpoint does not acknowledge a callback with HTTP 200, PayStar retries delivery on a Fibonacci × 7 minutes backoff schedule.
Retries stop as soon as your endpoint returns 2xx or when the schedule reaches the final retry at ~27 hours (see table below).

Intervals between attempts (minutes):
7, 14, 21, 35, 56, 91, 147, 238, 385, 623

Full schedule (from the first send)

Attempt #	Delay before attempt	Cumulative time since first attempt
1	0 min	0 min
2	7 min	7 min
3	14 min	21 min
4	21 min	42 min
5	35 min	1 h 17 min
6	56 min	2 h 13 min
7	91 min	3 h 44 min
8	147 min	6 h 11 min
9	238 min	10 h 9 min
10	385 min	16 h 34 min
11	623 min	26 h 57 min (final retry)

Note: Returning HTTP 2xx immediately stops further retries for that event.

Best practices

Acknowledge fast: return 2xx quickly; perform heavy processing asynchronously on your side.

Idempotency: de-duplicate by stable identifiers (e.g., externalTransactionId + status) to safely handle duplicates.

Verify status: you can always confirm the final state via the Status API.

Security: validate the callback signature (header Signature) and only accept HTTPS endpoints.

URL Configuration#

Example of request with dinamic callback url#

Example of callback body with payment history#

Callback type configuration#

Callback request#

CallBack params#

Signature validation#

Step 1 - Retrieving Data for the Signature#

Step 2 - Calculating the Signature#

Step 3 - Verifying the Signature#

Examples of validation#

JavaScript#

Python#

C Sharp#

Callback retries (undelivered notifications)#

Full schedule (from the first send)#

Best practices#

URL Configuration

Example of request with dinamic callback url

Example of callback body with payment history

Callback type configuration

Callback request

CallBack params

Signature validation

Step 1 - Retrieving Data for the Signature

Step 2 - Calculating the Signature

Step 3 - Verifying the Signature

Examples of validation

JavaScript

Python

C Sharp

Callback retries (undelivered notifications)

Full schedule (from the first send)

Best practices