TsaraPay
Sign in Contact us
PAYIN & PAYOUT API · DocumentationAPI v3.1 · updated 24 Oct 2026

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.

◆Trusted by iGaming & forex operators worldwide
PAYIN · Environment LIVE
BASE URL  https://app.tsarapay.com
~2 min
Payouts
3
Methods
USDC
Settled
✓CARDVisa · Mastercard
✓UPIINR
✓CRYPTOUSDT · POLYGON
Getting started · I

Prerequisites

Complete these steps before your first API call.

01

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.

API access requires manual activation. After sign-up, email contact@tsarapay.com to go live. Our team will (1) issue your API-KEY and (2) register the IP address(es) your server will call the API from. Requests from unregistered IPs are rejected at the gateway level. also send us the list of the sites you operate — name, logo, activity (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.
02

Add your settlement wallet

Open your profile at app.tsarapay.com/client/profile and add your wallet address in the dedicated block.

  1. Go to app.tsarapay.com/client/profile and log in.
  2. Scroll to the Settlement wallet block.
  3. Paste your USDC wallet address (TRC-20 or ERC-20) into the input field.
  4. Click Save. All future payouts will be sent to this address.
03

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).

  1. Go to app.tsarapay.com/client/api.
  2. Find the Callback Payin URL field in the API block.
  3. Enter the full HTTPS URL of your webhook endpoint (e.g. https://yourdomain.com/webhooks/tsarapay).
  4. Click Save.
Note. Your callback endpoint must accept an HTTP 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.
Getting started · II

How to use the API

All endpoints are served from a single production base URL. Pass your API-KEY header on every request.

EnvironmentBase URL
Productionhttps://app.tsarapay.com
request.sh
curl -X GET "https://app.tsarapay.com/resource" \
  -H "API-KEY: YOUR_API_KEY"
Getting started

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.

IP headers are ignored. Only the address your server actually connects from is compared with the IP addresses 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.
header
API-KEY: 0d8d8e89a6cdcd
Keep it server-side. Never expose your API key in front-end or browser code — see Integration. Treat it like a password.
Create an invoice

Credit card POST

Create a card invoice. The request is an HTTP POST and your API key travels in the API-KEY header.

POSThttps://app.tsarapay.com/api/btn-create-invoice/get/

Body parameters

ParameterExampleDescription
emailrequiredalice@domain.comYour Customer's email address.
amountrequired15.04 or 42Invoice amount. Use . as the decimal separator.
deviserequiredUSDTransaction 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_urloptionalString | nullRedirect target after a failed or declined payment.
site_idoptional3f9c0a7e1d5b48c2a6e4b9d17c2f80aaThe site this payment is for. Required if your account has several approved sites. See Naming the site.
themeoptionaldark | lightTheme 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.
nameS2SJohn SmithUsed as the cardholder name.
address1S2S1000 Lombard StBilling address line 1.
address2S2SApt 4Billing address line 2.
cityS2SSan FranciscoBilling city.
countryS2SDEBilling country, 2-char code (ISO 3166-1 alpha-2).
stateoptionalNew YorkBilling state/region.
postcodeS2S90210Billing postal code.
date_of_birthS2S1990-12-31Cardholder date of birth.
card_numberS2S4242424242424242Card number.
card_expiry_dateS2S12/2030Card expiry (MM/YYYY).
card_ccvS2S000Card security code.
customer_ipS2S203.0.113.5The customer’s public IP address, IPv4 or IPv6. Mandatory in S2S mode. See the accepted formats.
phoneS2S020 7946 0018Customer phone. Mandatory in S2S mode.
pay_modeoptionalcardUse only with support's agreement.
payment_solution_typeoptionalCARD | UPI | CRYPTOUse only with support's agreement.
payment_solution_nameoptionalProvided by supportUse only with support's agreement.
S2S = server-to-server direct mode. Those fields are required only if you collect card data yourself; for the hosted redirect flow you can omit them.

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).

ValueResult
203.0.113.5accepted public IPv4
1.1.1.1accepted addresses in 1.0.0.0/8 are real public space
2001:4860:4860::8888accepted public IPv6
8.8.8.8:80refused no port
8.8.8.8, 1.2.3.4refused one address only, not a list
008.008.008.008refused no zero-padded numbers
10.0.0.1refused private network
127.0.0.1refused loopback
::1refused loopback

Response

The service returns a JSON object. errorCode: 0 means success; any other code is an error.

Error codes

CodeMeaning
50001API-KEY required
50002email required
50003amount required
50004devise required
50005invalid email address
50006this API-KEY cannot be used from this IP address
50007invalid API-KEY
50008Wallet is being validated/activated; you'll get a confirmation email once done. Meanwhile you can edit it from your profile page.
50009invalid devise
50010No IP linked to your account. Add them in the profile → API block.
50011Amount is above the allowed maximum
50012Amount is below the allowed minimum
51012An S2S field is missing or invalid; errorMessage names it (for example Invalid customer_ip)
51019A return URL was not accepted. The message gives the field, not the reason — see Sites & return URLs
51020Too many refused requests in a short time. Try again later
51021site_id is not valid
51022site_id is required: several sites are registered for your account
error.json
{ "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.

success.json
{
  "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>"
}
Create an invoice

UPI POST

Create a UPI invoice. HTTP POST, API key in the API-KEY header.

POSThttps://app.tsarapay.com/api/btn-create-invoice/get/

Body parameters

ParameterExampleDescription
emailrequiredalice@domain.comYour Customer's email address.
amountrequired15.04 or 42Invoice amount. Use . as the decimal separator.
deviserequiredINRMust be INR. Convert on your side if you price in another currency.
nameoptionalJaya JamesYour Customer's name.
personal_idoptional45861024531Payer 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_urloptionalString | nullRedirect after a failed/declined payment.
site_idoptional3f9c0a7e1d5b48c2a6e4b9d17c2f80aaThe site this payment is for. Required if your account has several approved sites. See Naming the site.
themeoptionaldark | lightTheme 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_typeoptionalCARD | UPI | CRYPTOUse only with support's agreement.
payment_solution_nameoptionalProvided by supportUse only with support's agreement.

Response

Returns a JSON object. Same error codes as the card endpoint (50001–50012, 51012 and 51019–51022).

success.json
{
  "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>"
}
Create an invoice

Crypto POST

Create a crypto invoice. HTTP POST, API key in the API-KEY header.

POSThttps://app.tsarapay.com/api/btn-create-invoice/get/

Body parameters

ParameterExampleDescription
emailrequiredalice@domain.comYour Customer's email address.
amountrequired15.04 or 42Invoice amount. Use . as the decimal separator.
deviserequiredUSDMust be USD. Convert on your side if you price in another currency.
payableCurrenciesS2SUSDT_polygonPayable 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_urloptionalString | nullRedirect after a failed/declined payment.
site_idoptional3f9c0a7e1d5b48c2a6e4b9d17c2f80aaThe site this payment is for. Required if your account has several approved sites. See Naming the site.
themeoptionaldark | lightTheme 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_typeoptionalCARD | UPI | CRYPTOUse only with support's agreement.
payment_solution_nameoptionalProvided by supportUse only with support's agreement.

Response

Returns a JSON object. Same error codes as the card endpoint (50001–50012, 51012 and 51019–51022).

success.json
{
  "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>"
}
Create an invoice

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.

POSThttps://app.tsarapay.com/api/btn-create-invoice/get/
Same endpoint as card. Set 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

ParameterExampleDescription
emailrequiredbuyer@example.comCustomer email address.
amountrequired50 or 15.04Invoice amount. Use . as the decimal separator.
deviserequiredUSDMust be USD.
namerequiredJohn SmithCustomer full name.
countryrequiredUSCustomer country, 2-char ISO 3166-1 alpha-2 code.
cityrequiredSan FranciscoCustomer city.
address1required1000 Lombard StCustomer street address.
pay_modeoptionalgoogle_pay · apple_payForce 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_urloptionalString | nullRedirect after a failed or declined payment.
site_idoptional3f9c0a7e1d5b48c2a6e4b9d17c2f80aaThe site this payment is for. Required if your account has several approved sites. See Naming the site.
themeoptionaldark | lightTheme 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

success.json
{
  "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

create-mobile
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\"}"
  }'
Create an invoice

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 requestPayment page
"dark"Dark theme.
"light"Light theme.
omittedLight theme: light is the default.
any other value (for example "neon")The value is ignored and the page is light.
request.json
{
  "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.

The theme applies to the hosted payment page. Leave an address untouched when it sends your Customer somewhere that is not the TsaraPay payment page (for example a 3-D Secure address).
Read invoices

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.

GEThttps://app.tsarapay.com/api/invoice/status/

Query parameters

ParameterExampleDescription
idrequired185The invoice ID delivered through the callback.

Error codes

CodeMeaning
50001API-KEY required
50002id required
50006This API-KEY cannot be used from this IP address
50007invalid API-KEY
50010No IP linked to your account
50011This invoice belongs to another merchant
50013Invalid id
status.json
{
  "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"
  }
}
Auto-expiry. An invoice left in CREATED or OPENED for more than 14 days transitions automatically to invoice:expired.
Read invoices

Get invoice info GET

Retrieve the current status of one invoice. HTTP GET, API key in the API-KEY header.

GEThttps://app.tsarapay.com/api/client-invoice-info/get/

Query parameters

ParameterExampleDescription
idrequired185The 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.

info.json
{
  "errorCode": 0,
  "invoice": {
    "id": 1689,
    "devise": "USD",
    "amount": "4",
    "status": "invoice:created",
    "site_id": "3f9c0a7e1d5b48c2a6e4b9d17c2f80aa",
    "referrer_host": "pay.example.com"
  }
}
info.php
// 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 }
}
Read invoices

Get invoice history GET

List your invoices with filtering and pagination. HTTP GET, API key in the API-KEY header.

GEThttps://app.tsarapay.com/api/invoices/history/

Query parameters

ParameterExampleDescription
statusPAIDPAID · UNPAID · WAITING (awaiting approval) · EXPIRED (CREATED/OPENED > 14 days) · ALL.
from2023-06-01Start date filter.
to2023-06-19End date filter.
orderASCASC ascending or DESC descending, by date.
page2Page number. Max 50 records per page.

Error codes

CodeMeaning
50001API-KEY required
50006You cannot use this API from this IP address
50007invalid API-KEY
50010No IP linked to your account
50012Invalid order — must be ASC or DESC
history.json
{
  "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"
}
history.php
// 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

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.

Not to be confused with settlement. Settlement is what TsaraPay pays you: the USDT transfer to your wallet once PayIN invoices are paid. A PayOUT is what you pay your customer, out of your payout balance. They are separate balances and separate flows.

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

  1. You send the payout. The answer comes at once and carries a payment_id. success: true means the payout was accepted, not that the card has been credited. Treat payment_id as an opaque identifier.
  2. The payout is processed. Its status moves from payment:created to payment:pending, then to payment:success or payment:failed.
  3. 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_key with 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, marked idempotent_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.
PayOUT

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.

POSThttps://app.tsarapay.com/api/payout/payment/send

Body parameters

ParameterExampleDescription
firstnamerequiredAliceCardholder’s first name.
lastnamerequiredMartinCardholder’s last name.
card_numberrequired4111111111111111The card to credit, 16 digits. Spaces are ignored. A reading call never shows the full number: only the first four and last four digits.
expiryrequired12/2030Card expiry, MM/YYYY with a four-digit year. An expired card is refused.
amountrequired25.50Amount the card receives, in currency. Use . as the decimal separator. An amount with more than two decimals is rounded up to the next cent.
currencyoptionalEURISO 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_keyoptionalWD-10231Recommended. 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.
Card details are sensitive. Send this request from your server only, over HTTPS, and never log the card number.

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.

Every refusal has an 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.
An accepted payout may not leave at once. Acceptance means the payout is created, not that it has been sent. Until it is, it stays in payment:created. Do not send it again: follow it with Get a payout or the callback.

Error codes

CodeMeaning
-1Your account is blocked. Please contact support.
62008Your wallet is still being validated and activated. You will get a confirmation email once it is done.
62029invalid API-KEY
62030Provider Payout not enabled.
620301Currency not Authorized. The message lists the currencies available to you.
62031No provider selected.
62032No IP is linked to your account. Please contact your account manager for details.
62033You can not use this API from this IP address
62034Required firstname
62035Required lastname
62036Required card_number
62037Required expiry
62038Required payment_amount
62039Required currency
62040Invalid card number
62041Invalid Expiry
62042Min amount is … (the message gives the smallest amount you can send, in your currency)
62043Max amount is … (the message gives the largest amount you can send, in your currency)
62045You have no enough balance
62046You have no enough balance : Payment fees must be taken into account
62056You can no longer use this card today.
62057We cannot yet process your request at this time
62060Invalid idempotency_key
62061idempotency_key already used with different parameters
62062A request with this idempotency_key is still being processed
payout-send-request.json
{
  "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

payout-send-response.json
{
  "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.

payout-send-replay.json
{
  "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."
}
error.json
{
  "errorCode": 62046,
  "errorMessage": "You have no enough balance : Payment fees must be taken into account "
}
payout-send.php
// 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');
}
PayOUT

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.

GEThttps://app.tsarapay.com/api/payout/payment/get-detail

Query parameters

ParameterExampleDescription
idrequired2141The payment_id returned when you sent the payout.

Error codes

CodeMeaning
-1Your account is blocked. Please contact support.
62049API-KEY required
62050id required
62051invalid API-KEY
62052invalid id
62053id not belonging to the merchant
62054No IP is linked to your account. Please contact your account manager for details.
62055You can not use this API from this IP address

Fields

FieldDescription
statuspayment:created · payment:pending · payment:success · payment:failed · payment:refunded. See the status table.
amountThe amount you asked for, as text with its currency: 25.5 EUR.
amount_reachedThe amount credited to the card, as text with its currency. Blank until the payout succeeds.
card_number__expiryThe masked card and its expiry: 4111XXXXXXXX1111 12/2030.
merchant_dataWhat you sent in merchant_data, unchanged.
status_dateWhen the status last changed.
payout-detail-response.json
{
  "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\"}"
  }
}
PayOUT

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.

GEThttps://app.tsarapay.com/api/payout/payment/get-history

Query parameters

ParameterExampleDescription
statusoptionalSUCCESSSUCCESS · PENDING · FAILED · ALL (default).
fromoptional2026-10-01Start date filter.
tooptional2026-10-23End date filter.
orderrequiredDESCASC or DESC, by date. Required: without it the answer is 62048.
pageoptional2Page number, 1 if omitted. 50 records per page.

Error codes

CodeMeaning
-1Your account is blocked. Please contact support.
62044API-KEY required
62045invalid API-KEY
62046No IP is linked to your account. Please contact your account manager for details.
62047You can not use this API from this IP address
62048Invalid order. order must be ASC or DESC
payout-history-response.json
{
  "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
}
PayOUT

Get the available balance POST

Read the balance a new payout can use. HTTP POST, API key in the API-KEY header, JSON body.

POSThttps://app.tsarapay.com/api/payout/payment/get-available-balance

Body parameters

ParameterExampleDescription
currencyoptionalEURISO 4217 code, EUR if omitted.

Error codes

CodeMeaning
-1Your account is blocked. Please contact support.
62049API-KEY required
62051invalid API-KEY
62054No IP is linked to your account. Please contact your account manager for details.
62055You can not use this API from this IP address
payout-balance-response.json
{
  "errorCode": 0,
  "merchant_id": "1",
  "balance": "1 250.00",
  "currency": "EUR"
}
Fees are taken from this balance on top of the payout amount: to send 25.50 you need a balance of at least 25.50 plus the fees of that payout.
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 the Content-Type, as the example below does.

Body fields

FieldTypeDescription
idintegerThe payment_id of the payout.
statusstringThe new status. See the table below.
amountdecimalThe amount of the payout.
currencystringThe currency of the payout, for example EUR.
descriptionstringHuman-readable status description.
merchant_datastringWhat you sent in merchant_data, unchanged.
failed_reasonstringShort reason, for a failed payout. Empty otherwise.

Status values

status valueDescription
payment:createdThe payout was accepted and is waiting to be sent.
payment:pendingThe payout was sent and is being processed.
payment:successThe card was credited.
payment:failedThe payout failed; failed_reason says why. Nothing was credited to the card.
payment:refundedThe payout was returned.
payout-callback-success.json
{
  "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.

verify-payout-signature.php
// ---- 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.

Whitelist the source IP. Callbacks originate from TsaraPay’s dedicated notification IP. Confirm the current address with your account manager before whitelisting it.
Integrate · III

Integration

Server-to-server only. Do not call the API directly from AJAX or any browser request — those are rejected, and calls from unknown or unregistered IPs are blocked. If you need to trigger a request from the browser, call a script on your server, which then calls TsaraPay.
create-invoice.php
// 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";
}
Integrate · IV

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 valueLabelDescription
invoice:createdCREATEDInvoice successfully created.
invoice:openedOPENEDInvoice created and the Customer was redirected to the payment page.
invoice:paidPAIDAfter settlement, the equivalent USDT (POLYGON) amount is transferred to your ERC-20 wallet and the status becomes paid.
invoice:failedFAILEDAn error occurred.
invoice:awaiting_approvalWAITING SETTLEMENTCustomer payment succeeded — you may already credit their balance.
invoice:chargebackCHARGEBACKChargeback raised.
invoice:refundREFUNDPayment refunded.

Other body fields

FieldTypeDescription
devisestringCurrency symbol (currently USD).
amountdecimalAmount in USD.
idintegerSale / invoice ID.
descriptionstringHuman-readable status description.
callbackJsonstringThe merchant data you sent in callbackJson.
site_idstringThe site the invoice belongs to. Only for an invoice that belongs to a site. See Sites & return URLs.
referrer_hoststringThe host the customer came from, as reported by their browser. Informational; not covered by X-Signature. Only when known.
notification.paid.json
{
  "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"
}
notification.failed.json
{
  "status": "invoice:failed",
  "description": "An error occurred",
  "id": "15515",
  "callbackJson": "{\"txId\":\"qktr12eqzg\",\"status\":\"sfrt\"}"
}
Whitelist the source IP. Callbacks originate from TsaraPay's dedicated notification IP. Confirm the current address with your account manager before whitelisting it.
verify-signature.php
// ---- 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 answerWhat we do next
2xxDelivered. That event is never re-sent.
4xx / 5xxRetried, 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 / unreachableSame: 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.

Be idempotent on 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.

Integrate & reference

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.

We never call these URLs. TsaraPay issues no request of any kind to your 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, web3 or others;
  • 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.

A change sends the site back to approval. Changing a site’s name, slogan, logo or hosts is done by us, and the site goes back to approval each time. While a site is awaiting approval, requests that name it with 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 hostReturn URLResult
pay.example.comhttps://pay.example.com/anythingaccepted no prefix set, the whole host is usable
pay.example.comhttps://PAY.example.com/okaccepted host names are not case sensitive
pay.example.comhttps://pay.example.com:8443/okaccepted the port is not part of the host
pay.example.com + /payhttps://pay.example.com/pay/okaccepted
pay.example.com + /payhttps://pay.example.com/paystorerefused whole segments only, /pay is not a prefix of /paystore
pay.example.com + /payhttps://pay.example.com/other/payrefused the prefix must be at the start of the path
example.comhttps://www.example.com/okrefused different host, register it too
pay.example.comhttp://pay.example.com/okrefused 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.

Throughout this section, 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:

FieldValueWhat it is
TypeTXT—
Name_tsarapay-verify.pay.example.comthe 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.
TTLwhatever your panel suggestsno 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:

zone-file form
_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-challenge or _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 proveZone you editName fieldFull record name
example.comexample.com_tsarapay-verify_tsarapay-verify.example.com
pay.example.comexample.com_tsarapay-verify.pay_tsarapay-verify.pay.example.com
pay.example.compay.example.com delegated_tsarapay-verify_tsarapay-verify.pay.example.com
Check it yourself before telling us it is ready. The record is public, so you can read back exactly what we will read:
verify your own record
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:

refused · return URL not accepted
{
  "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:

refused · too many refused requests
{
  "errorCode": 51020,
  "errorMessage": "Too many refused requests. Please try again later."
}
Get your hosts verified before the check is switched on for your account. A host that has not been proved accepts no return URL, so an account whose sites are not ready would see its requests refused. That is why we switch it on one account at a time.

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 hasWhat site_id does
one approved siteOptional. If you leave it out, the invoice belongs to that site.
several approved sitesRequired. Without it the request is refused with 51022.
no approved siteLeave 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:

refused · invalid site_id
{
  "errorCode": 51021,
  "errorMessage": "Invalid site_id."
}
refused · site_id required
{
  "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:

FieldWhat it is
site_idThe site_id of the site the invoice belongs to.
referrer_hostThe 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.
Informational only. 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.

Why any of this exists. Our acquiring MIDs are registered for a specific activity. Traffic that does not match it puts the MID — and therefore every merchant sharing it — at risk with the card schemes. Registering your sites keeps your own traffic clean, and separable from everyone else’s.

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.

Reference · V

Failed reasons

Credit card — Visa & Mastercard

Failed reasonDescription
3D authentication failed / expiredThe 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 chooseGeneric messages. Our error mapping keeps improving; contact us and we'll investigate specific cases.
Cannot authorizeDeclined by the Customer's bank — possibly insufficient funds, fraud rules, or another cardholder issue. Investigate case by case.
Suspected fraudCould indicate several underlying issues; investigate each transaction individually.
User is bannedPermanent ban triggered after repeated attempts with different cards (flagged as fraud). Do not route this user to us again.
User is suspended24-hour suspension after repeated failed or expired transactions.
Transaction expired without paymentThe Customer had trouble reaching the payment page — often ad blockers or connectivity problems.
Transaction not permitted to cardholderUsually the issuing bank does not permit this transaction.
Validation failedAuthentication-related error; investigate each transaction individually.
Card is restricted or blockedInvestigate to determine why the card is blocked.
Card is blacklisted on acquirer sideThe card was blacklisted by the acquirer's anti-fraud system.
Email validation failedThe email is invalid or undeliverable. Ensure it's accurate for a successful transaction.
User cancelled the transactionThe Customer cancelled and abandoned the payment.
Do not honourCan mean several underlying issues; investigate individually.
Transaction expired · TimeoutThe processing window closed, usually because the Customer abandoned the flow.
Exceeds card limitsFrom the issuing bank — the Customer exceeded their card limits. Advise them to contact their bank.
Error from issuing bankBank-side issue; individual investigation required.

Checkout — grouped rejection categories

  1. 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.
  2. General rejection. Invalid transaction, routing/system error, not permitted at terminal, general failure, timeout. The Customer can retry later or contact support.
  3. 3DS-related. 3-D Secure failed, challenge failed/timed out, card not 3DS-enrolled. Retry or use a 3DS-capable card.
  4. Payment not funded. Insufficient funds or no linked account. The Customer must top up or use another method.
  5. Bad scoring (fraud check). Blocked by the fraud engine as high risk. The Customer should complete KYC or contact support.
  6. Invalid CVV. Wrong CVV/CVC. The Customer should re-enter the correct value.
  7. Card blocked or expired. Expired/blocked card or invalid details. Check details or use another card.
  8. Edge / system errors. Unexpected system error or communication failure. Retry later or contact the bank.
MCC-related rejections. When a bank blocks based on the Merchant Category Code, it usually surfaces as "declined by the card issuer" or "not permitted at terminal" — mapping to the Contact bank or General rejection categories above.
Release · API v3.1

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.

VersionWhat changed, and where it is documented
v3.1Light 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.0Sites. 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.0site_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.0PayOUT. 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.0Widget. 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.0site_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.0A 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.0Documentation 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.4Webhook 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.3We 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.1Client-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.1customer_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
Support

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.