PayStar API Documentation
  1. Merchant EN
  • Merchant EN
    • Introduction
    • Glossary
    • Authorization key
    • Sandbox
    • Additional fields
    • Currencies
    • Bank names
    • Telecom operators
    • Callbacks
    • Error descriptions
    • Tech FAQ
    • Integratins
      • Stripe
      • Inwizo
      • 2Checkout
      • Adyen
      • AffiniPay
      • Alikassa
      • AlliancePay
      • Amazon Pay
      • AnyMoney
      • AstroPay
      • Aureavia
      • AurisMyChanger
      • Authorize.Net
      • Avatarix
    • Balance H2H
      GET
    • Deposit H2H - Card & P2P
      POST
    • Deposit H2H - Token
      POST
    • Deposit H2C - Card
      POST
    • Deposit status H2H - PayStar ID
      GET
    • Deposit status H2H - Merch ID
      GET
    • Payout H2H
      POST
    • Payout status H2H - PayStar ID
      GET
    • Payout status H2H - Merch ID
      GET
  1. Merchant EN

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#

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

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#

1.
Extract the values of externalId, status, amount and orderType from the request.
2.
Use your privateKey to construct the signature string in the following format: externalId;status;amount;orderType;privatekey

Step 2 - Calculating the Signature#

1.
Apply SHA-256 hashing to the string obtained in Step 1.
2.
Convert the hash result to a hexadecimal string.

Step 3 - Verifying the Signature#

1.
Extract the Signature header from the request.
2.
Repeat steps 1 and 2 to obtain the expected signature.
3.
Compare the received signature with the expected one. If they match, the request signature is valid.

Examples of validation#

JavaScript#

Python#

C Sharp#

Modified at 2025-05-13 13:23:02
Previous
Telecom operators
Next
Error descriptions
Built with