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.

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 url in payment request

{
    "amount": 100,
    "currency": "USD",
    "externalTransactionId": "Merch-bf95219b-393d-4323-91bf-639be",
    "orderStatus": "Created",
    "externalParams": {
        "cardToken": "BankToken-bf95219b-393d-4323-91bf-639ac",
        "cardStorageToken": "PayStarToken-bf95219b-393d-4323-91bf-639ac",
        "cardNumber": "123456****1234",
        "cardHolder": "JOHN WEAK"
        }
    ]   
}

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

externald - 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: externald;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.

URL Configuration

Example of request with dinamic callback url

Example of callback url in payment request

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

Callbacks

URL Configuration#

Example of request with dinamic callback url#

Example of callback url in payment request#

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#

URL Configuration

Example of request with dinamic callback url

Example of callback url in payment request

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