Payments built for casinos and forex.
One API for card, UPI and crypto deposits. Create an invoice, redirect your Customer to the hosted payment page, settle in USDC, and reconcile with signed webhook callbacks. To pay a customer, send a PayOUT to their card.
Prerequisites
Complete these steps before your first API call.
Create your account
Register your merchant account at app.tsarapay.com/signup, or request access via tsarapay.com/#contact. The form takes under 5 minutes — have your company name, website URL, and operating vertical (casino, forex, etc.) on hand.
igaming, fx,
ecommerce, web3 or others) and the web addresses each one is served from. We register
and approve them for you, and you prove each address with a DNS record — see
Sites & return URLs.Add your settlement wallet
Open your profile at app.tsarapay.com/client/profile and add your wallet address in the dedicated block.
- Go to app.tsarapay.com/client/profile and log in.
- Scroll to the Settlement wallet block.
- Paste your USDC wallet address (TRC-20 or ERC-20) into the input field.
- Click Save. All future payouts will be sent to this address.
Set your callback URL
In the API block (app.tsarapay.com/client/api), enter your Callback Payin URL. TsaraPay calls this URL to notify you of each invoice's status — once right after creation (invoice:created) and again after payment (invoice:paid).
- Go to app.tsarapay.com/client/api.
- Find the Callback Payin URL field in the API block.
- Enter the full HTTPS URL of your webhook endpoint (e.g.
https://yourdomain.com/webhooks/tsarapay). - Click Save.
POST and always reply quickly with 200 OK. TsaraPay will call it once on invoice creation (invoice:created) and again on payment (invoice:paid). For WooCommerce, use the dedicated plugin available from your profile page.How to use the API
All endpoints are served from a single production base URL. Pass your API-KEY header on every request.
| Environment | Base URL |
|---|---|
| Production | https://app.tsarapay.com |
curl -X GET "https://app.tsarapay.com/resource" \
-H "API-KEY: YOUR_API_KEY"
Authentication
Authenticate every request with the API key TsaraPay issued to you, passed as an HTTP header named API-KEY. Calls are additionally restricted to the IP address(es) registered on your account.
Client-IP,
X-Forwarded-For and similar headers are no longer taken into account, so register your servers’
real outgoing addresses (profile → API block) to avoid errorCode 50006.API-KEY: 0d8d8e89a6cdcd
Credit card POST
Create a card invoice. The request is an HTTP POST and your API key travels in the API-KEY header.
https://app.tsarapay.com/api/btn-create-invoice/get/Body parameters
| Parameter | Example | Description |
|---|---|---|
| emailrequired | alice@domain.com | Your Customer's email address. |
| amountrequired | 15.04 or 42 | Invoice amount. Use . as the decimal separator. |
| deviserequired | USD | Transaction currency (ISO 4217). Supported: USD, EUR, GBP, INR, ZAR. |
| success_urloptional | …/service/pay/success/ | Redirect target after a successful payment. https, on a verified host of your site — see Sites & return URLs. We never call this URL ourselves. |
| cancel_urloptional | …/service/pay/cancel/ | Redirect target after a cancelled payment. |
| pending_urloptional | …/service/pay/pending/ | Redirect target when the payment is still pending. |
| failure_urloptional | String | null | Redirect target after a failed or declined payment. |
| site_idoptional | 3f9c0a7e1d5b48c2a6e4b9d17c2f80aa | The site this payment is for. Required if your account has several approved sites. See Naming the site. |
| themeoptional | dark | light | Theme of the hosted payment page your Customer is sent to. light if omitted; any other value is ignored. See Light or dark payment page. |
| callbackJsonoptional | {"txId":"qktr12eqzg"} | Merchant data (JSON). Echoed back to you on the callback URL. |
| nameS2S | John Smith | Used as the cardholder name. |
| address1S2S | 1000 Lombard St | Billing address line 1. |
| address2S2S | Apt 4 | Billing address line 2. |
| cityS2S | San Francisco | Billing city. |
| countryS2S | DE | Billing country, 2-char code (ISO 3166-1 alpha-2). |
| stateoptional | New York | Billing state/region. |
| postcodeS2S | 90210 | Billing postal code. |
| date_of_birthS2S | 1990-12-31 | Cardholder date of birth. |
| card_numberS2S | 4242424242424242 | Card number. |
| card_expiry_dateS2S | 12/2030 | Card expiry (MM/YYYY). |
| card_ccvS2S | 000 | Card security code. |
| customer_ipS2S | 203.0.113.5 | The customer’s public IP address, IPv4 or IPv6. Mandatory in S2S mode. See the accepted formats. |
| phoneS2S | 020 7946 0018 | Customer phone. Mandatory in S2S mode. |
| pay_modeoptional | card | Use only with support's agreement. |
| payment_solution_typeoptional | CARD | UPI | CRYPTO | Use only with support's agreement. |
| payment_solution_nameoptional | Provided by support | Use only with support's agreement. |
Format of customer_ip
One single public address, on its own: IPv4 or IPv6, with no port, no list and no surrounding text. Anything
else is refused with errorCode 51012 (Invalid customer_ip).
| Value | Result |
|---|---|
203.0.113.5 | accepted public IPv4 |
1.1.1.1 | accepted addresses in 1.0.0.0/8 are real public space |
2001:4860:4860::8888 | accepted public IPv6 |
8.8.8.8:80 | refused no port |
8.8.8.8, 1.2.3.4 | refused one address only, not a list |
008.008.008.008 | refused no zero-padded numbers |
10.0.0.1 | refused private network |
127.0.0.1 | refused loopback |
::1 | refused loopback |
Response
The service returns a JSON object. errorCode: 0 means success; any other code is an error.
Error codes
| Code | Meaning |
|---|---|
50001 | API-KEY required |
50002 | email required |
50003 | amount required |
50004 | devise required |
50005 | invalid email address |
50006 | this API-KEY cannot be used from this IP address |
50007 | invalid API-KEY |
50008 | Wallet is being validated/activated; you'll get a confirmation email once done. Meanwhile you can edit it from your profile page. |
50009 | invalid devise |
50010 | No IP linked to your account. Add them in the profile → API block. |
50011 | Amount is above the allowed maximum |
50012 | Amount is below the allowed minimum |
51012 | An S2S field is missing or invalid; errorMessage names it (for example Invalid customer_ip) |
51019 | A return URL was not accepted. The message gives the field, not the reason — see Sites & return URLs |
51020 | Too many refused requests in a short time. Try again later |
51021 | site_id is not valid |
51022 | site_id is required: several sites are registered for your account |
{ "errorCode": 50003, "errorMessage": "amount required" }
Success example
On success you receive a redirectUrl (use it for automatic redirection, and to complete 3-D Secure in S2S direct) and an html anchor snippet you can drop into your page. In S2S direct mode you also receive status and ID. To choose a light or dark payment page, see Light or dark payment page.
{
"errorCode": 0,
"redirectUrl": "https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...",
"html": "<a href='https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...'></a>"
}
UPI POST
Create a UPI invoice. HTTP POST, API key in the API-KEY header.
https://app.tsarapay.com/api/btn-create-invoice/get/Body parameters
| Parameter | Example | Description |
|---|---|---|
| emailrequired | alice@domain.com | Your Customer's email address. |
| amountrequired | 15.04 or 42 | Invoice amount. Use . as the decimal separator. |
| deviserequired | INR | Must be INR. Convert on your side if you price in another currency. |
| nameoptional | Jaya James | Your Customer's name. |
| personal_idoptional | 45861024531 | Payer identity ID (11 digits). |
| success_urloptional | …/service/pay/success/ | Redirect after a successful payment. https, on a verified host of your site. |
| cancel_urloptional | …/service/pay/cancel/ | Redirect after a cancelled payment. |
| pending_urloptional | …/service/pay/pending/ | Redirect while the payment is pending. |
| failure_urloptional | String | null | Redirect after a failed/declined payment. |
| site_idoptional | 3f9c0a7e1d5b48c2a6e4b9d17c2f80aa | The site this payment is for. Required if your account has several approved sites. See Naming the site. |
| themeoptional | dark | light | Theme of the hosted payment page your Customer is sent to. light if omitted; any other value is ignored. See Light or dark payment page. |
| callbackJsonoptional | {"txId":"qktr12eqzg"} | Merchant data (JSON), echoed on the callback. |
| payment_solution_typeoptional | CARD | UPI | CRYPTO | Use only with support's agreement. |
| payment_solution_nameoptional | Provided by support | Use only with support's agreement. |
Response
Returns a JSON object. Same error codes as the card endpoint (50001–50012, 51012 and 51019–51022).
{
"errorCode": 0,
"redirectUrl": "https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...",
"html": "<a href='https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...'></a>"
}
Crypto POST
Create a crypto invoice. HTTP POST, API key in the API-KEY header.
https://app.tsarapay.com/api/btn-create-invoice/get/Body parameters
| Parameter | Example | Description |
|---|---|---|
| emailrequired | alice@domain.com | Your Customer's email address. |
| amountrequired | 15.04 or 42 | Invoice amount. Use . as the decimal separator. |
| deviserequired | USD | Must be USD. Convert on your side if you price in another currency. |
| payableCurrenciesS2S | USDT_polygon | Payable currency value (e.g. USDT_polygon). Mandatory in S2S mode. |
| success_urloptional | …/service/pay/success/ | Redirect after a successful payment. https, on a verified host of your site. |
| cancel_urloptional | …/service/pay/cancel/ | Redirect after a cancelled payment. |
| failure_urloptional | String | null | Redirect after a failed/declined payment. |
| site_idoptional | 3f9c0a7e1d5b48c2a6e4b9d17c2f80aa | The site this payment is for. Required if your account has several approved sites. See Naming the site. |
| themeoptional | dark | light | Theme of the hosted payment page your Customer is sent to. light if omitted; any other value is ignored. See Light or dark payment page. |
| callbackJsonoptional | {"txId":"qktr12eqzg"} | Merchant data (JSON), echoed on the callback. |
| payment_solution_typeoptional | CARD | UPI | CRYPTO | Use only with support's agreement. |
| payment_solution_nameoptional | Provided by support | Use only with support's agreement. |
Response
Returns a JSON object. Same error codes as the card endpoint (50001–50012, 51012 and 51019–51022).
{
"errorCode": 0,
"redirectUrl": "https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...",
"html": "<a href='https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...'></a>"
}
Google Pay & Apple Pay POST
Google Pay and Apple Pay are credit card payments processed through a mobile wallet — they tokenise the underlying card on the customer's device. There is no new integration to build: you use the exact same card invoice endpoint, and simply set pay_mode to google_pay or apple_pay. If you omit pay_mode, the customer can choose their preferred wallet on the hosted payment page.
The only difference from a standard card call is that the billing fields name, country, city, and address1 become required, as the mobile wallet flow needs them to pre-fill the checkout form.
https://app.tsarapay.com/api/btn-create-invoice/get/pay_mode: "google_pay" or pay_mode: "apple_pay" on your existing card invoice call — that's all. No additional SDK or library is required on your side.Body parameters
| Parameter | Example | Description |
|---|---|---|
| emailrequired | buyer@example.com | Customer email address. |
| amountrequired | 50 or 15.04 | Invoice amount. Use . as the decimal separator. |
| deviserequired | USD | Must be USD. |
| namerequired | John Smith | Customer full name. |
| countryrequired | US | Customer country, 2-char ISO 3166-1 alpha-2 code. |
| cityrequired | San Francisco | Customer city. |
| address1required | 1000 Lombard St | Customer street address. |
| pay_modeoptional | google_pay · apple_pay | Force a specific wallet. Omit to let the customer choose on the payment page. |
| success_urloptional | …/pay/success/ | Redirect after a successful payment. https, on a verified host of your site. |
| cancel_urloptional | …/pay/cancel/ | Redirect after a cancelled payment. |
| failure_urloptional | String | null | Redirect after a failed or declined payment. |
| site_idoptional | 3f9c0a7e1d5b48c2a6e4b9d17c2f80aa | The site this payment is for. Required if your account has several approved sites. See Naming the site. |
| themeoptional | dark | light | Theme of the hosted payment page your Customer is sent to. light if omitted; any other value is ignored. See Light or dark payment page. |
| callbackJsonoptional | {"txId":"qktr12eqzg"} | Merchant data (JSON), echoed back on the callback URL. |
Response
Returns a JSON object. Same error codes as the card endpoint (50001–50012, 51012 and 51019–51022).
Success example
{
"errorCode": 0,
"redirectUrl": "https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...",
"html": "<a href='https://app.tsarapay.com/widget/invoice/create/?token=cyR0YnNOe...'></a>"
}
Request examples
curl -X POST "https://app.tsarapay.com/api/btn-create-invoice/get/" \
-H "API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "buyer@example.com",
"amount": 50,
"devise": "USD",
"name": "John Smith",
"country": "US",
"city": "San Francisco",
"address1": "1000 Lombard St",
"pay_mode": "google_pay",
"success_url": "https://yoursite.com/pay/success",
"cancel_url": "https://yoursite.com/pay/cancel",
"callbackJson": "{\"userId\":\"u_8821\"}"
}'
Light or dark payment page
The hosted payment page comes in a light and a dark theme. You choose it in the request that creates the invoice, with the optional
theme field (credit card, UPI, crypto, Google Pay & Apple Pay). The redirectUrl you get back then opens the
payment page in that theme: you have nothing to add to it.
theme in your request | Payment page |
|---|---|
"dark" | Dark theme. |
"light" | Light theme. |
| omitted | Light theme: light is the default. |
any other value (for example "neon") | The value is ignored and the page is light. |
{
"email": "alice@domain.com",
"amount": 15.04,
"devise": "USD",
"theme": "dark"
}
The theme you choose is kept for the rest of the payment (success and failure pages).
You can still decide link by link: a &theme=dark or &theme=light added to the redirectUrl (use
&, the address already contains a ?) takes precedence over the theme of the request; an invalid value
there is ignored.
Get an invoice status GET
Fetch the most recent notification we sent to your callback URL for one invoice — the same fields as the webhook body. HTTP GET, API key in the API-KEY header.
https://app.tsarapay.com/api/invoice/status/Query parameters
| Parameter | Example | Description |
|---|---|---|
| idrequired | 185 | The invoice ID delivered through the callback. |
Error codes
| Code | Meaning |
|---|---|
50001 | API-KEY required |
50002 | id required |
50006 | This API-KEY cannot be used from this IP address |
50007 | invalid API-KEY |
50010 | No IP linked to your account |
50011 | This invoice belongs to another merchant |
50013 | Invalid id |
{
"errorCode": 0,
"merchant_id": "1",
"invoice_id": 1689,
"data": {
"status": "invoice:paid",
"id": 1689,
"devise": "USD",
"amount": 5,
"description": "Payment of the invoice has been made successfully",
"callbackJson": null,
"fiat_amount": 409.71,
"fiat_currency": "INR",
"totalAmount": 4,
"totalCurrency": "USDC",
"site_id": "3f9c0a7e1d5b48c2a6e4b9d17c2f80aa",
"referrer_host": "pay.example.com",
"datetime": "2026-10-23 19:09:48"
}
}
CREATED or OPENED for more than 14 days transitions automatically to invoice:expired.Get invoice info GET
Retrieve the current status of one invoice. HTTP GET, API key in the API-KEY header.
https://app.tsarapay.com/api/client-invoice-info/get/Query parameters
| Parameter | Example | Description |
|---|---|---|
| idrequired | 185 | The invoice ID delivered through the callback. |
Error codes match Get an invoice status, except that an invoice belonging to another merchant is answered with 50012.
{
"errorCode": 0,
"invoice": {
"id": 1689,
"devise": "USD",
"amount": "4",
"status": "invoice:created",
"site_id": "3f9c0a7e1d5b48c2a6e4b9d17c2f80aa",
"referrer_host": "pay.example.com"
}
}
// Install php-curl-class: composer require php-curl-class/php-curl-class
require __DIR__ . '/vendor/autoload.php';
use Curl\Curl;
$API_KEY = ''; // Your API-KEY (issued by TsaraPay)
$url = 'https://app.tsarapay.com/api/client-invoice-info/get/';
$data = [ 'id' => 185 ];
$curl = new Curl();
$curl->setHeader('Content-Type', 'application/json');
$curl->setHeader('API-KEY', $API_KEY);
$curl->post($url, $data);
if ($curl->error) {
echo 'Error: ' . $curl->errorMessage;
} else if ($curl->response->errorCode == 0) {
var_dump($curl->response); // invoice info payload
} else {
var_dump($curl->response); // { errorCode, errorMessage }
}
Get invoice history GET
List your invoices with filtering and pagination. HTTP GET, API key in the API-KEY header.
https://app.tsarapay.com/api/invoices/history/Query parameters
| Parameter | Example | Description |
|---|---|---|
| status | PAID | PAID · UNPAID · WAITING (awaiting approval) · EXPIRED (CREATED/OPENED > 14 days) · ALL. |
| from | 2023-06-01 | Start date filter. |
| to | 2023-06-19 | End date filter. |
| order | ASC | ASC ascending or DESC descending, by date. |
| page | 2 | Page number. Max 50 records per page. |
Error codes
| Code | Meaning |
|---|---|
50001 | API-KEY required |
50006 | You cannot use this API from this IP address |
50007 | invalid API-KEY |
50010 | No IP linked to your account |
50012 | Invalid order — must be ASC or DESC |
{
"errorCode": 0,
"status": "PAID",
"from": "2023-06-01",
"to": "2023-06-19",
"page": 2,
"order": "DESC",
"list": [
{
"id": "1932",
"email": "buyer@gmail.com",
"status": "PAID",
"amount": "1.00",
"symbol": "USD",
"create_date": "2023-06-15 10:39:34",
"status_date": "2023-06-15 10:40:38",
"tx_hash": "0xda4fd344e6310738db73dabdb42a213a38f14d2379b13c27fe86f8452002d4c5",
"exchange_currency_symbol": "USDC",
"paid_amount": "1.00",
"merchant_amount": "0.900",
"fee_amount": "0.100",
"ip": "102.117.124.254",
"country": "United Arab Emirates",
"success_url": null,
"pending_url": null,
"cancel_url": null
}
],
"total": "51"
}
// composer require php-curl-class/php-curl-class
require __DIR__ . '/vendor/autoload.php';
use Curl\Curl;
$API_KEY = ''; // Your API-KEY
$url = 'https://app.tsarapay.com/api/invoices/history/';
$data = [
'status' => 'PAID',
'from' => '2023-06-01',
'to' => '2023-06-19',
'order' => 'ASC',
'page' => 2,
];
$curl = new Curl();
$curl->setHeader('Content-Type', 'application/json');
$curl->setHeader('API-KEY', $API_KEY);
$curl->post($url, $data);
if ($curl->error) {
echo 'Error: ' . $curl->errorMessage;
} else {
var_dump($curl->response);
}
PayOUT — pay a customer’s card
PayOUT sends money from your payout balance to a customer’s bank card: a withdrawal, a winnings payment, a refund you decide to make. It uses the same API key, the same base URL and the same IP allow-list as PayIN.
Before your first PayOUT
- PayOUT has to be enabled for your account. It is switched on per account by TsaraPay. Until it is, a send is refused. Ask your account manager.
- Your server’s IP address must be on your allow-list — the same list as for PayIN, set in the profile → API block. A call from any other address is refused.
- Your payout balance must be funded. It is topped up with your account manager, not through the API. Read it at any time with Get the available balance.
- Set your payout callback URL in the dashboard (field Callback Payout Url, API page). It is a different field from the PayIN callback URL. See Payout callbacks.
How a payout goes
- You send the payout. The answer comes at once and carries a
payment_id.success: truemeans the payout was accepted, not that the card has been credited. Treatpayment_idas an opaque identifier. - The payout is processed. Its status moves from
payment:createdtopayment:pending, then topayment:successorpayment:failed. - Each change is sent to your payout callback URL. You can also read the state yourself with Get a payout or Get the payout history.
What to know before you build
- The amount you send is the amount the card receives. Our fees are charged on top of it and taken from your payout balance, so your balance must cover the amount plus fees. The fee schedule is in your contract.
- A card can receive only a limited number of payouts in a given period. Beyond that, the payout is refused (
62056). The limit is not published. - Send an
idempotency_keywith every payout. It is a key of your own, one per payout (your withdrawal id works well). If a call times out and you send it again with the same key and the same parameters, you get the payout that was already created, markedidempotent_replay, and nothing is paid twice. Without a key, every request creates a payout: a request sent twice is paid twice. - A payout that stays pending for too long is marked failed by the platform, and you are notified like for any other failure.
Send a payout POST
Create a payout to a card. HTTP POST, your API key in the API-KEY header. The body is JSON
(Content-Type: application/json) or ordinary form fields.
https://app.tsarapay.com/api/payout/payment/sendBody parameters
| Parameter | Example | Description |
|---|---|---|
| firstnamerequired | Alice | Cardholder’s first name. |
| lastnamerequired | Martin | Cardholder’s last name. |
| card_numberrequired | 4111111111111111 | The card to credit, 16 digits. Spaces are ignored. A reading call never shows the full number: only the first four and last four digits. |
| expiryrequired | 12/2030 | Card expiry, MM/YYYY with a four-digit year. An expired card is refused. |
| amountrequired | 25.50 | Amount the card receives, in currency. Use . as the decimal separator. An amount with more than two decimals is rounded up to the next cent. |
| currencyoptional | EUR | ISO 4217 code, EUR if omitted. If your account cannot pay out in the currency you send, the answer is 620301 and lists the currencies available to you. |
| merchant_dataoptional | {"withdrawal_id":"WD-10231"} | Your own reference, text or JSON. Returned unchanged in the callback and in every reading call. |
| idempotency_keyoptional | WD-10231 | Recommended. A key of your own, 1 to 64 characters among letters, digits and . _ : -, different for each payout. Send the same key again with the same parameters and the answer is the payout already created, with idempotent_replay: true: no second payout. With other parameters the answer is 62061. A request refused before the payout is created does not use up its key. A key identifies one payout for ever, whatever became of it: if that payout failed, a new attempt needs a new key. merchant_data is not compared: it can change between two attempts. |
Response
The service returns a JSON object. A payout is accepted when success is true and errorCode is
0; the answer then carries its payment_id. Any other answer is a refusal: nothing was created, and nothing was
taken from your balance.
errorCode and an errorMessage. A few also keep the older field
error with the same text, for integrations that already read it; read errorCode instead. Treat any answer without
success: true as a refusal.payment:created. Do not send it again: follow it with Get a payout or the callback.Error codes
| Code | Meaning |
|---|---|
-1 | Your account is blocked. Please contact support. |
62008 | Your wallet is still being validated and activated. You will get a confirmation email once it is done. |
62029 | invalid API-KEY |
62030 | Provider Payout not enabled. |
620301 | Currency not Authorized. The message lists the currencies available to you. |
62031 | No provider selected. |
62032 | No IP is linked to your account. Please contact your account manager for details. |
62033 | You can not use this API from this IP address |
62034 | Required firstname |
62035 | Required lastname |
62036 | Required card_number |
62037 | Required expiry |
62038 | Required payment_amount |
62039 | Required currency |
62040 | Invalid card number |
62041 | Invalid Expiry |
62042 | Min amount is … (the message gives the smallest amount you can send, in your currency) |
62043 | Max amount is … (the message gives the largest amount you can send, in your currency) |
62045 | You have no enough balance |
62046 | You have no enough balance : Payment fees must be taken into account |
62056 | You can no longer use this card today. |
62057 | We cannot yet process your request at this time |
62060 | Invalid idempotency_key |
62061 | idempotency_key already used with different parameters |
62062 | A request with this idempotency_key is still being processed |
{
"firstname": "Alice",
"lastname": "Martin",
"card_number": "4111111111111111",
"expiry": "12/2030",
"amount": 25.5,
"currency": "EUR",
"merchant_data": "{\"withdrawal_id\":\"WD-10231\"}",
"idempotency_key": "WD-10231"
}
Success example
{
"errorCode": 0,
"success": true,
"payment_id": 2141,
"paymentMessage": "Payment is being processed. Any status update will be notified via the configured callback."
}
Sent again with the same key
The same request sent again, with the same idempotency_key, returns the payout created the first time. Nothing is created and nothing is taken from your balance. status is the payout’s state now, not at the first attempt: if it says payment:failed, that payout is over and a new attempt needs a new key.
{
"errorCode": 0,
"success": true,
"payment_id": 2141,
"status": "payment:created",
"idempotent_replay": true,
"paymentMessage": "Payment is being processed. Any status update will be notified via the configured callback."
}
{
"errorCode": 62046,
"errorMessage": "You have no enough balance : Payment fees must be taken into account "
}
// composer require php-curl-class/php-curl-class
require __DIR__ . '/vendor/autoload.php';
use Curl\Curl;
$API_KEY = ''; // Your API-KEY
$url = 'https://app.tsarapay.com/api/payout/payment/send';
$data = [
'firstname' => 'Alice',
'lastname' => 'Martin',
'card_number' => '4111111111111111',
'expiry' => '12/2030',
'amount' => 25.50,
'currency' => 'EUR',
'merchant_data' => json_encode(['withdrawal_id' => 'WD-10231']),
// One key per payout. If the call times out, send the request again WITH THE SAME KEY: you get the same payout, never a second one.
'idempotency_key' => 'WD-10231',
];
$curl = new Curl();
$curl->setHeader('Content-Type', 'application/json');
$curl->setHeader('API-KEY', $API_KEY);
$curl->post($url, json_encode($data));
if ($curl->error) {
// Network error or timeout: send the same request again with the same idempotency_key.
echo 'Error: ' . $curl->errorMessage;
} elseif (isset($curl->response->success) && $curl->response->success === true) {
echo 'Accepted, payment_id = ' . $curl->response->payment_id;
} else {
echo 'Refused: ' . ($curl->response->errorMessage ?? $curl->response->error ?? 'unknown');
}
Get a payout GET
Read one payout by its payment_id. HTTP GET, API key in the API-KEY header. You can only read your own payouts.
https://app.tsarapay.com/api/payout/payment/get-detailQuery parameters
| Parameter | Example | Description |
|---|---|---|
| idrequired | 2141 | The payment_id returned when you sent the payout. |
Error codes
| Code | Meaning |
|---|---|
-1 | Your account is blocked. Please contact support. |
62049 | API-KEY required |
62050 | id required |
62051 | invalid API-KEY |
62052 | invalid id |
62053 | id not belonging to the merchant |
62054 | No IP is linked to your account. Please contact your account manager for details. |
62055 | You can not use this API from this IP address |
Fields
| Field | Description |
|---|---|
status | payment:created · payment:pending · payment:success · payment:failed · payment:refunded. See the status table. |
amount | The amount you asked for, as text with its currency: 25.5 EUR. |
amount_reached | The amount credited to the card, as text with its currency. Blank until the payout succeeds. |
card_number__expiry | The masked card and its expiry: 4111XXXXXXXX1111 12/2030. |
merchant_data | What you sent in merchant_data, unchanged. |
status_date | When the status last changed. |
{
"errorCode": 0,
"merchant_id": "1",
"id": "2141",
"data": {
"id": "2141",
"create_date": "2026-10-23 09:12:41",
"card_holder": "Alice Martin",
"card_number__expiry": "4111XXXXXXXX1111 12/2030",
"amount": "25.5 EUR",
"amount_reached": "25.5 EUR",
"status": "payment:success",
"status_date": "2026-10-23 09:13:05",
"merchant_data": "{\"withdrawal_id\":\"WD-10231\"}"
}
}
Get the payout history GET
List your payouts with filtering and pagination. HTTP GET, API key in the API-KEY header. Each item has the same fields as
Get a payout.
https://app.tsarapay.com/api/payout/payment/get-historyQuery parameters
| Parameter | Example | Description |
|---|---|---|
| statusoptional | SUCCESS | SUCCESS · PENDING · FAILED · ALL (default). |
| fromoptional | 2026-10-01 | Start date filter. |
| tooptional | 2026-10-23 | End date filter. |
| orderrequired | DESC | ASC or DESC, by date. Required: without it the answer is 62048. |
| pageoptional | 2 | Page number, 1 if omitted. 50 records per page. |
Error codes
| Code | Meaning |
|---|---|
-1 | Your account is blocked. Please contact support. |
62044 | API-KEY required |
62045 | invalid API-KEY |
62046 | No IP is linked to your account. Please contact your account manager for details. |
62047 | You can not use this API from this IP address |
62048 | Invalid order. order must be ASC or DESC |
{
"errorCode": 0,
"status": "ALL",
"from": "2026-10-01",
"to": "2026-10-23",
"page": 1,
"order": "DESC",
"list": [
{
"id": "2141",
"create_date": "2026-10-23 09:12:41",
"card_holder": "Alice Martin",
"card_number__expiry": "4111XXXXXXXX1111 12/2030",
"amount": "25.5 EUR",
"amount_reached": "25.5 EUR",
"status": "payment:success",
"status_date": "2026-10-23 09:13:05",
"merchant_data": "{\"withdrawal_id\":\"WD-10231\"}"
}
],
"total": 1
}
Get the available balance POST
Read the balance a new payout can use. HTTP POST, API key in the API-KEY header, JSON body.
https://app.tsarapay.com/api/payout/payment/get-available-balanceBody parameters
| Parameter | Example | Description |
|---|---|---|
| currencyoptional | EUR | ISO 4217 code, EUR if omitted. |
Error codes
| Code | Meaning |
|---|---|
-1 | Your account is blocked. Please contact support. |
62049 | API-KEY required |
62051 | invalid API-KEY |
62054 | No IP is linked to your account. Please contact your account manager for details. |
62055 | You can not use this API from this IP address |
{
"errorCode": 0,
"merchant_id": "1",
"balance": "1 250.00",
"currency": "EUR"
}
25.50 you need a balance of
at least 25.50 plus the fees of that payout.Payout callbacks
When the status of a payout changes, TsaraPay notifies the Callback Payout Url you set in your dashboard (API page). It is an HTTP
POST, and it is not the PayIN callback described in Webhook notifications: the fields and the signature
are different.
- Header
X-Signature— HMAC-SHA256 signature, to confirm the notification really came from TsaraPay. - Body — JSON (
Content-Type: application/json). Some accounts receive the same fields as form fields (application/x-www-form-urlencoded) instead: read theContent-Type, as the example below does.
Body fields
| Field | Type | Description |
|---|---|---|
| id | integer | The payment_id of the payout. |
| status | string | The new status. See the table below. |
| amount | decimal | The amount of the payout. |
| currency | string | The currency of the payout, for example EUR. |
| description | string | Human-readable status description. |
| merchant_data | string | What you sent in merchant_data, unchanged. |
| failed_reason | string | Short reason, for a failed payout. Empty otherwise. |
Status values
| status value | Description |
|---|---|
| payment:created | The payout was accepted and is waiting to be sent. |
| payment:pending | The payout was sent and is being processed. |
| payment:success | The card was credited. |
| payment:failed | The payout failed; failed_reason says why. Nothing was credited to the card. |
| payment:refunded | The payout was returned. |
{
"id": 2141,
"currency": "EUR",
"amount": 25.5,
"status": "payment:success",
"description": "The payment is successfull",
"merchant_data": "{\"withdrawal_id\":\"WD-10231\"}",
"failed_reason": ""
}
How the signature is built
X-Signature is the HMAC-SHA256, keyed with your API key, of the JSON text of exactly four values, in this order and with no
spaces: id (integer), amount (number), currency and status. Write the amount the way PHP’s
json_encode writes a float: 25.0, 25.5. For the callback above, the signed text is
{"id":2141,"amount":25.5,"currency":"EUR","status":"payment:success"}. The other fields are not signed.
// ---- Read the body: JSON, or form fields on accounts configured that way
$raw = file_get_contents('php://input');
$body = (stripos($_SERVER['CONTENT_TYPE'] ?? '', 'application/json') !== false)
? json_decode($raw, true)
: $_POST;
// ---- The signature header
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
// ---- Recompute the HMAC-SHA256 with YOUR API key
$expected = hash_hmac('sha256',
json_encode([
'id' => (int) $body['id'],
'amount' => (float) $body['amount'],
'currency' => $body['currency'],
'status' => $body['status'],
]),
$YOUR_API_KEY // the API-KEY TsaraPay issued to you
);
// ---- Compare
$trusted = hash_equals($expected, $signature);
if ($trusted) {
// OK: record the status for this id (idempotent), then answer HTTP 200.
http_response_code(200);
} else {
// KO: reject the notification.
http_response_code(400);
}
Delivery
Answer with HTTP 200 once you have stored the event. A payout callback is sent once and is not retried: if your endpoint
was down or answered anything else, the notification is not sent again by itself. Never rely on the callback alone — read the payout with
Get a payout whenever you need its state, and reconcile with
the history. Your support contact can send a notification again on request.
One payout produces several notifications over its life, so the same id reaches you more than once with a different
status. Be idempotent on id + status: if you have already recorded that event, answer 200 and
do nothing else.
Integration
// composer require php-curl-class/php-curl-class
require __DIR__ . '/vendor/autoload.php';
use Curl\Curl;
$API_KEY = ''; // Your API-KEY (issued by TsaraPay)
// Invoice creation endpoint (IP-restricted call)
$url = 'https://app.tsarapay.com/api/btn-create-invoice/get/';
$data = [
'email' => 'buyer' . date('His') . '@example.com',
'amount' => 1,
'devise' => 'USD',
// 'site_id' => 'YOUR_SITE_ID', // required when your account has several approved sites
];
$curl = new Curl();
$curl->setHeader('Content-Type', 'application/json');
$curl->setHeader('API-KEY', $API_KEY);
$curl->post($url, $data);
if ($curl->error) {
echo 'Error: ' . $curl->errorMessage . "\n";
} else if ($curl->response->errorCode == 0) {
echo 'redirectUrl: ' . $curl->response->redirectUrl . "\n";
echo 'html: ' . $curl->response->html . "\n";
} else {
echo $curl->response->errorMessage . "\n";
}
Webhook notifications (callbacks)
Once you set a callback URL in your dashboard, TsaraPay notifies it on every payment operation — success or failure. Each notification is an HTTP POST with a JSON body and a signature header.
- Header
X-Signature— HMAC signature you use to confirm the notification really came from TsaraPay (see the PHP verification below). - Header
Content-Type: application/json - Body — POST variables in JSON.
Status values
| status value | Label | Description |
|---|---|---|
| invoice:created | CREATED | Invoice successfully created. |
| invoice:opened | OPENED | Invoice created and the Customer was redirected to the payment page. |
| invoice:paid | PAID | After settlement, the equivalent USDT (POLYGON) amount is transferred to your ERC-20 wallet and the status becomes paid. |
| invoice:failed | FAILED | An error occurred. |
| invoice:awaiting_approval | WAITING SETTLEMENT | Customer payment succeeded — you may already credit their balance. |
| invoice:chargeback | CHARGEBACK | Chargeback raised. |
| invoice:refund | REFUND | Payment refunded. |
Other body fields
| Field | Type | Description |
|---|---|---|
| devise | string | Currency symbol (currently USD). |
| amount | decimal | Amount in USD. |
| id | integer | Sale / invoice ID. |
| description | string | Human-readable status description. |
| callbackJson | string | The merchant data you sent in callbackJson. |
| site_id | string | The site the invoice belongs to. Only for an invoice that belongs to a site. See Sites & return URLs. |
| referrer_host | string | The host the customer came from, as reported by their browser. Informational; not covered by X-Signature. Only when known. |
{
"status": "invoice:paid",
"devise": "USD",
"amount": "1500.00",
"id": "15515",
"description": "Invoice paid",
"callbackJson": "{\"txId\":\"qktr12eqzg\",\"status\":\"sfrt\"}",
"site_id": "3f9c0a7e1d5b48c2a6e4b9d17c2f80aa",
"referrer_host": "pay.example.com"
}
{
"status": "invoice:failed",
"description": "An error occurred",
"id": "15515",
"callbackJson": "{\"txId\":\"qktr12eqzg\",\"status\":\"sfrt\"}"
}
// ---- Read POST parameters
$id = intval($_POST['id']);
$status = $_POST['status'];
$devise = $_POST['devise'];
$amount = floatval($_POST['amount']);
$description = $_POST['description'];
$callbackJson = $_POST['callbackJson'];
// ---- Read the signature header
$signatureKey = 'X-Signature';
$headers = [];
if (function_exists('apache_request_headers')) {
$headers = apache_request_headers();
} else {
foreach ($_SERVER as $key => $value) {
if (substr($key, 0, 5) == "HTTP_") {
$key = str_replace(" ", "-",
ucwords(strtolower(str_replace('_', ' ', substr($key, 5)))));
$headers[$key] = $value;
}
}
}
$signature = $headers[$signatureKey];
// ---- Recompute the HMAC-SHA256 hash with YOUR API key
$hashData = hash_hmac('sha256',
json_encode([
'id' => $id,
'amount' => $amount,
'devise' => $devise,
'status' => $status,
]),
$YOUR_API_KEY // the API-KEY TsaraPay issued to you
);
// ---- Compare
if (hash_equals($hashData, $signature)) {
// OK — trusted. Insert / update your records.
} else {
// KO — reject the notification.
}
Retries, and why your endpoint must be idempotent
What your endpoint answers decides what happens next. Any 2xx is final: we consider the
notification delivered and that event is never sent again. Anything else — a 4xx, a
5xx, a timeout, a connection error — is retried.
The first attempt is made immediately, as part of the operation. If it does not get a
2xx, a background job takes over and retries it up to 4 more times, so a notification is
attempted at most 5 times in all before it is abandoned.
| Your answer | What we do next |
|---|---|
| 2xx | Delivered. That event is never re-sent. |
| 4xx / 5xx | Retried, up to 4 more times, then abandoned. The last status code your endpoint returned is kept, so support can tell you exactly what it answered. |
| timeout / unreachable | Same: retried. |
One invoice legitimately produces several notifications, because its status changes over its life:
invoice:created, then invoice:paid, and possibly invoice:refund or
invoice:chargeback much later. A new status opens a new round of retries for that invoice even if the
previous notification had been delivered. The same id will therefore reach you more than once, with a
different status.
id + status. If you have already recorded
that event, answer 2xx and do nothing else — do not credit the customer twice. A retry carries
exactly the same body as the attempt that failed, so nothing in the request tells you it is a retry: only what you
already stored does.Answer 2xx as soon as you have stored the event, not once you have finished
processing it. A slow endpoint becomes a timeout on our side, and a timeout is a retry — so the same event
arrives again while your first run is still working on it.
Retries cover the notifications that matter to your accounting: invoice:created,
invoice:paid and invoice:failed. Informational ones, such as the notice that an unpaid
invoice has expired, are sent once and not retried — do not build your reconciliation on them. If you
need the state of an invoice at any time, read it with
Get an invoice status rather than waiting for a notification.
Sites & return URLs
Every payment page shows the customer who is collecting the money. That identity comes from a
site registered with TsaraPay for your account — never from a parameter of your request. This
section explains how a site is registered, how to prove you own its domain, how to name it on an invoice with
site_id, and what the return URLs (success_url, failure_url,
cancel_url, pending_url) have to look like.
success_url, failure_url, cancel_url or pending_url —
not a GET, not a HEAD, ever. They are opened only by the customer’s own browser.
On many platforms a return URL is not a neutral page but a trigger: calling a success URL credits the
customer. So we verify your domain instead, with a DNS record, and never the return URLs themselves.1. Your sites
A site is one storefront, brand or service that takes payments through your account. For each one we keep:
- a display name and, optionally, a slogan;
- a logo, which we host ourselves — a logo is never loaded from your server;
- its activity:
igaming,fx,ecommerce,web3orothers; - its hosts — the web addresses it is served from — each one proved by a DNS record (section 4);
- whether it is also used from a mobile app or a WebView (section 8).
Send the list of sites you operate, with those details, to
contact@tsarapay.com. We create the site for you; it is then
reviewed and approved by TsaraPay. You cannot create or approve a site yourself, and a site is identified by its
site_id — a 32-character identifier we send you, which is not derived from your domain.
site_id are refused with 51021 (section 6). Send us changes
early, not on the day you need them.One account can have several sites, and one site can be served by several of your accounts. A verified host belongs to a single site: the same host cannot be verified for two different sites.
2. What your customer sees
On the payment page the customer sees the approved name, logo and slogan of the site the invoice belongs to, and the verified domain it is served from. Nothing else on that block can be set by a request: not a name, not a logo, not a link.
3. Hosts and path prefixes
Each host of a site is the exact host name, not the registered domain: registering
example.com does not cover www.example.com or pay.example.com.
Tell us every host your return URLs actually use.
A host may optionally be narrowed to a path prefix, if only part of a site is usable as a return
target. The comparison is on whole path segments. A return URL must also use https:
| Registered host | Return URL | Result |
|---|---|---|
pay.example.com | https://pay.example.com/anything | accepted no prefix set, the whole host is usable |
pay.example.com | https://PAY.example.com/ok | accepted host names are not case sensitive |
pay.example.com | https://pay.example.com:8443/ok | accepted the port is not part of the host |
pay.example.com + /pay | https://pay.example.com/pay/ok | accepted |
pay.example.com + /pay | https://pay.example.com/paystore | refused whole segments only, /pay is not a prefix of /paystore |
pay.example.com + /pay | https://pay.example.com/other/pay | refused the prefix must be at the start of the path |
example.com | https://www.example.com/ok | refused different host, register it too |
pay.example.com | http://pay.example.com/ok | refused not https |
What cannot be registered as a host of a site: a raw IP address (https://203.0.113.9/pay),
localhost, and any host name that resolves to a private or internal address. Return URLs are for a
customer’s browser, so they have to be public names.
Shared platforms cannot be registered either. A sub-domain of a service where anyone can get a
sub-domain does not designate a business — for example *.vercel.app,
*.github.io, *.netlify.app or *.linktr.ee, and URL shorteners such as
bit.ly. Register a domain your business owns.
4. Prove the domain is yours
A host starts as pending and becomes verified once you have proved it, once,
with a DNS record. We make no HTTP request to your site at all: the proof is a DNS lookup.
pay.example.com stands for your own host.
example.com is the domain reserved by RFC 2606 for documentation — it belongs to nobody
and exists so that examples cannot accidentally point at a real site. Read pay.example.com as
“the host your return URLs actually use”, and substitute it everywhere below.The DNS TXT record
Add one TXT record. Its name is the fixed label _tsarapay-verify placed
in front of the host you are proving:
| Field | Value | What it is |
|---|---|---|
| Type | TXT | — |
| Name | _tsarapay-verify.pay.example.com | the fixed label _tsarapay-verify, then the host you are proving. See the table below for what to type in your DNS panel. |
| Value | <the token we gave you> | the token on its own. Some panels want it in double quotes, most add them for you. |
| TTL | whatever your panel suggests | no requirement. A short TTL just means a correction propagates sooner. |
In a zone file, that same record is written on one line, with a trailing dot after the name:
_tsarapay-verify.pay.example.com. IN TXT "<the token we gave you>"
Two things about that line that trip people up:
- The leading underscore is deliberate. A label starting with
_cannot be a real host name, so the record can never collide with a machine you own. It is the same convention as_dmarc,_acme-challengeor_domainkey. - The trailing dot is zone-file notation, meaning “this name is absolute, do not append the zone to it”. You only type it if you are editing a zone file by hand. In a hosting control panel you do not type it — and usually you do not type the domain either, because the panel appends the zone for you.
So what you actually type in the Name (or Host) field depends on which zone you are editing:
| Host to prove | Zone you edit | Name field | Full record name |
|---|---|---|---|
example.com | example.com | _tsarapay-verify | _tsarapay-verify.example.com |
pay.example.com | example.com | _tsarapay-verify.pay | _tsarapay-verify.pay.example.com |
pay.example.com | pay.example.com delegated | _tsarapay-verify | _tsarapay-verify.pay.example.com |
dig +short TXT _tsarapay-verify.pay.example.com
# or, without dig:
nslookup -type=TXT _tsarapay-verify.pay.example.com
It must print the token, and nothing else surprising. If it prints nothing, the record has not propagated yet or the name is wrong — compare it against the table above.
Leave the record in place after verification. A host can be re-checked, and one whose record has gone
stops being accepted as a return target. Only verified hosts are accepted.
5. Return URLs
A return URL must use https and must be on a verified host of the site the invoice belongs
to (section 3). Some destinations are not accepted at all, whatever the site.
The https and verified-host check is switched on account by account, and we tell you in
advance before it applies to yours. Once it is on, a return URL that is not accepted refuses the whole
request, and the response does not say why:
{
"errorCode": 51019,
"errorMessage": "Return URL not accepted (success_url)."
}
The field name in brackets is the first return URL that was not accepted. If you think a refusal is wrong, send us the request and we will tell you what we see.
If your account sends several refused requests in a short time, the next requests that would be refused are
answered with 51020 instead of 51019, for a while. A correct request is not affected:
{
"errorCode": 51020,
"errorMessage": "Too many refused requests. Please try again later."
}
6. Naming the site: site_id
Add site_id to the body of an invoice creation to say which of your sites the payment is for. It
is accepted by all four creation endpoints.
| Your account has | What site_id does |
|---|---|
| one approved site | Optional. If you leave it out, the invoice belongs to that site. |
| several approved sites | Required. Without it the request is refused with 51022. |
| no approved site | Leave it out. A site_id that is sent is refused with 51021. |
A site_id that is not valid — unknown, not yours, or a site awaiting approval — is
always answered the same way, on purpose:
{
"errorCode": 51021,
"errorMessage": "Invalid site_id."
}
{
"errorCode": 51022,
"errorMessage": "site_id is required: several sites are registered for your account."
}
The site of an invoice is fixed when the invoice is created and cannot be changed afterwards.
The widget
If you collect payments with the TsaraPay widget and your account has several approved sites, the code shown in
your dashboard contains one block per site. Each block carries a data-site attribute with the
site_id of that site. Put the block of the site the payment is for on that site’s pages, and keep
the scripts included once. Without it, a widget payment from an account with several sites is refused with
site_id is required: several sites are registered for your account. When a site is added or approved,
copy the code again. With no site or a single approved site, the code is the same as before.
7. site_id and referrer_host in what we send you
For an invoice that belongs to a site, two informational fields are added to the webhook notifications and to the answers of Get an invoice status and Get invoice info:
| Field | What it is |
|---|---|
| site_id | The site_id of the site the invoice belongs to. |
| referrer_host | The host the customer’s browser reported it came from when it first opened the payment page, for example pay.example.com. Host only: never a path, never a query string. Absent when the browser reported nothing readable. |
referrer_host is reported by the customer’s browser;
it is not a guarantee, and it is not covered by the X-Signature header. Do not use either field to
decide whether to credit a customer: use the status and the signature, as before. An invoice that
does not belong to a site carries neither field.8. Mobile apps and WebViews
If a site is also used from a mobile app, or from a WebView inside one, tell us when it is registered, and tell us again if you add an app later. We record it on the site.
9. Your declared activity
Each site carries the activity it was registered for: igaming, fx,
ecommerce, web3 or others. Processing traffic for a third party, or for
sites other than the ones registered on your account, is not permitted. Adult content, adult streaming and adult
IPTV are not accepted activities on this platform, whatever the declared type.
10. What we keep
When a customer opens the payment page we note the website they came from: the host only, never the
path or the query string, nothing belonging to the customer. We keep it with the invoice, and it is what
referrer_host reports. Nothing for you to do, and nothing else changes in the API. It is listed
because it is data we keep about your account and you are entitled to know it.
When framing protection is switched on for your account, the payment page can be displayed inside another page only if that page is on one of your verified hosts. We tell you in advance, before it applies to your account.
Failed reasons
Credit card — Visa & Mastercard
| Failed reason | Description |
|---|---|
| 3D authentication failed / expired | The Customer did not complete the extra security step (e.g. one-time password) — often due to wrong details, a timeout, or a technical issue. |
| Unknown error · Generic decline · No acquirers to choose | Generic messages. Our error mapping keeps improving; contact us and we'll investigate specific cases. |
| Cannot authorize | Declined by the Customer's bank — possibly insufficient funds, fraud rules, or another cardholder issue. Investigate case by case. |
| Suspected fraud | Could indicate several underlying issues; investigate each transaction individually. |
| User is banned | Permanent ban triggered after repeated attempts with different cards (flagged as fraud). Do not route this user to us again. |
| User is suspended | 24-hour suspension after repeated failed or expired transactions. |
| Transaction expired without payment | The Customer had trouble reaching the payment page — often ad blockers or connectivity problems. |
| Transaction not permitted to cardholder | Usually the issuing bank does not permit this transaction. |
| Validation failed | Authentication-related error; investigate each transaction individually. |
| Card is restricted or blocked | Investigate to determine why the card is blocked. |
| Card is blacklisted on acquirer side | The card was blacklisted by the acquirer's anti-fraud system. |
| Email validation failed | The email is invalid or undeliverable. Ensure it's accurate for a successful transaction. |
| User cancelled the transaction | The Customer cancelled and abandoned the payment. |
| Do not honour | Can mean several underlying issues; investigate individually. |
| Transaction expired · Timeout | The processing window closed, usually because the Customer abandoned the flow. |
| Exceeds card limits | From the issuing bank — the Customer exceeded their card limits. Advise them to contact their bank. |
| Error from issuing bank | Bank-side issue; individual investigation required. |
Checkout — grouped rejection categories
- Contact bank. Declined by the issuer ("do not honour", restricted card, not permitted, issuer inoperative, lost/stolen, suspected fraud). The Customer should contact their bank to authorize.
- General rejection. Invalid transaction, routing/system error, not permitted at terminal, general failure, timeout. The Customer can retry later or contact support.
- 3DS-related. 3-D Secure failed, challenge failed/timed out, card not 3DS-enrolled. Retry or use a 3DS-capable card.
- Payment not funded. Insufficient funds or no linked account. The Customer must top up or use another method.
- Bad scoring (fraud check). Blocked by the fraud engine as high risk. The Customer should complete KYC or contact support.
- Invalid CVV. Wrong CVV/CVC. The Customer should re-enter the correct value.
- Card blocked or expired. Expired/blocked card or invalid details. Check details or use another card.
- Edge / system errors. Unexpected system error or communication failure. Retry later or contact the bank.
Release notes
Short on purpose: everything here is documented in full in the section it belongs to. If you are integrating for the first time, read the sections and skip this table.
| Version | What changed, and where it is documented |
|---|---|
| v3.1 | Light or dark payment page. New optional theme field (dark or light) on the four invoice creations: the redirectUrl you get back opens the payment page in that theme. Light if omitted or invalid. A &theme= added to the link still takes precedence. → Light or dark payment page |
| v3.0 | Sites. The sites you operate are registered and approved by TsaraPay, each with a site_id; the payment page shows the approved name, logo and slogan of the site. A host is proved with a DNS TXT record only. → Sites & return URLs |
| v3.0 | site_id is accepted on the four invoice creations: optional with one approved site, required with several. New errors 51021 and 51022. → Naming the site |
| v3.0 | PayOUT. Paying a customer’s card is documented: sending a payout, reading one or the history, reading the available balance, the signed payout callback, and the idempotency_key that makes a payout safe to send again after a timeout. → PayOUT |
| v3.0 | Widget. With several approved sites the widget code in your dashboard has one block per site (data-site), and a widget payment without a site is refused. → Naming the site |
| v3.0 | site_id and referrer_host are added to the webhook notifications and to the answers of Get an invoice status and Get invoice info, for an invoice that belongs to a site. → Webhook callbacks |
| v3.0 | A return URL that is not accepted is refused with 51019 and a message that gives the field only; repeated refusals are answered with 51020. The https and verified-host check is switched on account by account, with notice. → Return URLs |
| v3.0 | Documentation corrected: the example answers of Get an invoice status and Get invoice info had been swapped, and the accepted formats of customer_ip are now listed. → Get an invoice status |
| v2.4 | Webhook retries and idempotency written down: a 2xx is final, anything else is retried up to 4 more times, and one invoice produces several notifications over its life. → Retries and idempotency |
| v2.3 | We never call your return URLs. The checker that used to fetch them has been removed: on many platforms a return URL is a trigger, not a page. → Sites & return URLs |
| v2.1 | Client-IP, X-Forwarded-For and similar headers are ignored: only the address your server actually connects from is used, and it must be registered on your account, otherwise errorCode 50006. → Authentication |
| v2.1 | customer_ip is validated: a malformed value is refused with errorCode 51012 instead of being accepted silently. One public IPv4 or IPv6 address only — no port, no list. Addresses in 1.0.0.0/8 and 2.0.0.0/8 are accepted — they are real public space and used to be refused by mistake. → Format of customer_ip |
API-first, never alone
Stuck on an integration, or need your API key and IP whitelisted? A dedicated engineer will get you live. Manage your keys, wallet and callbacks anytime at app.tsarapay.com.
Ready to get paid, properly?
Request integration access and we'll set up your keys and IP whitelist.