Tajikistan QR Gate
Accept bank QR pay-ins on a hosted page, and send payouts to a card or a phone number at a Tajik bank in Tajik Somoni (TJS).
When to use it
The Tajikistan QR Gate accepts QR pay-ins on a MagicPayments-hosted page — the payer scans
the QR code in their banking app (or transfers to the card number shown) and confirms the transfer on the
page — and sends payouts to a card or a phone number at a Tajik bank. Amounts are in
TJS (Tajik Somoni), which has two decimal places: 150000
minor units means 1,500.00 TJS.
| Operation | Rail | How the integration looks |
|---|---|---|
| Pay-in | Bank QR code / card transfer | Create an invoice, redirect the payer to the hosted page. |
| Pay-out | Card or phone number at a Tajik bank | Server-to-server call to the bank-account payout endpoint. |
This rail settles whole somoni, for pay-ins and payouts alike. The minor-unit amount must be a multiple
of 100 — 150000 (1,500.00 TJS) is fine, 150050 (1,500.50 TJS) is
rejected as an invalid amount before anything is sent to the rail.
Signing credentials from Getting started, a pay-in
gate_id for the Tajikistan QR gate, and a pay-out
cascade_id enabled for TJS payouts.
Pay-in — hosted QR page
-
Create the invoice
Call the gate endpoint with your
gate_idand the amount in TJS minor units. -
Redirect the payer
Send the browser to
invoice_url. Our page shows the QR code (with a download button and, where the bank offers one, a button that opens the bank app) and, on a second tab, the recipient card number to transfer to manually. The page is available in English, Russian, Tajik, Uzbek, Kazakh, Kyrgyz and Azerbaijani. - The payer confirms After transferring, the payer presses Confirm and enters the sender's name or the last 4 digits of the card they paid from. They can also cancel the payment from the page.
-
Receive the result
Once the transfer is matched we call your
callback_urland the invoice moves topaid. If the payer cancels, the invoice ends aspayment_failedwith the error codecanceled_by_payer.
/api/invoice{
"gate_id": "tj-qr-gate",
"invoice": {
"invoice_id": "order-tj-2026-000123",
"currency": "TJS",
"amount": 150000,
"description": "Premium plan",
"ttl_minutes": 30
},
"customer": {
"id": "cust-55021",
"full_name": "Olimjon Kupchkarov",
"phone_number": "+992901234567"
},
"workflow_hooks": {
"callback_url": "https://merchant.example.com/mp/callbacks",
"return_success_url": "https://merchant.example.com/orders/123/done",
"return_decline_url": "https://merchant.example.com/orders/123/retry"
}
}
Python
resp = signed_post("/api/invoice", {
"gate_id": "tj-qr-gate",
"invoice": {
"invoice_id": "order-tj-2026-000123",
"currency": "TJS",
"amount": 150_000, # 1,500.00 TJS — whole somoni only
"description": "Premium plan",
"ttl_minutes": 30,
},
"customer": {
"id": "cust-55021",
"full_name": "Olimjon Kupchkarov",
"phone_number": "+992901234567",
},
"workflow_hooks": {
"callback_url": "https://merchant.example.com/mp/callbacks",
"return_success_url": "https://merchant.example.com/orders/123/done",
"return_decline_url": "https://merchant.example.com/orders/123/retry",
},
})
redirect_url = resp.json()["invoice_url"]
Tracking the pay-in
/api/invoice/statusresp = signed_post("/api/invoice/status", {
"merchant_invoice_id": "order-tj-2026-000123"
})
invoice = resp.json()
# invoice["status"] -> "paid" once the transfer is confirmed
The hosted page tells the payer to transfer the exact amount shown in
one payment, and the payment details change with every invoice. A rounded amount, a
split transfer, or a transfer to an old invoice's details may not be matched to the order. Don't fulfil
the order before the invoice is paid.
Pay-out — to a card or a phone number
Tajik payouts use the bank-account payout endpoint for both cards and phone numbers.
The card payout endpoint (/api/payment/payout/card) is not available for
TJS, because every payout must name the recipient's bank.
/api/payment/payout/bank_account| Field | Required | What to send |
|---|---|---|
bank_account.account_number |
Yes |
Either the recipient's card number (Korti Milli, Visa or
Mastercard; 16–19 digits, e.g. 9417 5400 1234 1139)
or their Tajik phone number (+992901234567, or
the 9-digit national number 901234567). Spaces, dashes and brackets are ignored.
We tell the two apart by the number of digits, so send the full number. Anything else — a
foreign phone number, an account number or IBAN — makes the payout fail with the error code
invalid_request before it reaches the bank.
|
bank_account.bank_title |
Yes | The bank that issued the card or holds the phone-linked account, as a slug from the
supported-banks table. An unknown bank makes the payout fail with
invalid_request. |
bank_account.full_name |
No, but recommended | The recipient's name as the bank knows it. Recommended for Visa/Mastercard card payouts and for phone payouts; not needed for Korti Milli cards. Latin or Cyrillic. |
{
"cascade_id": "tj-payout",
"payment": {
"payment_id": "payout-tj-2026-000045",
"currency": "TJS",
"amount": 120000,
"description": "Seller settlement"
},
"bank_account": {
"bank_title": "alif_bank",
"account_number": "9417540012341139",
"full_name": "Olimjon Kupchkarov"
},
"customer": {
"id": "seller-9182",
"full_name": "Olimjon Kupchkarov"
},
"workflow_hooks": {
"callback_url": "https://merchant.example.com/mp/callbacks"
}
}
Python — phone payout
resp = signed_post("/api/payment/payout/bank_account", {
"cascade_id": "tj-payout",
"payment": {
"payment_id": "payout-tj-2026-000046",
"currency": "TJS",
"amount": 120_000, # 1,200.00 TJS — whole somoni only
"description": "Seller settlement",
},
"bank_account": {
"bank_title": "dushanbe_city_bank",
"account_number": "+992901234567", # a phone number, not a card
"full_name": "Olimjon Kupchkarov",
},
"customer": {"id": "seller-9182", "full_name": "Olimjon Kupchkarov"},
"workflow_hooks": {"callback_url": "https://merchant.example.com/mp/callbacks"},
})
payout_uid = resp.json()["payment_id"]
Supported banks
Pass one of these slugs as bank_title. If a bank you need is missing, ask your account manager.
| Bank | Русский | bank_title (send this) |
|---|---|---|
| Dushanbe City Bank | Душанбе Сити Банк | dushanbe_city_bank |
| Bank Eskhata | Банк Эсхата | bank_eskhata |
| Alif Bank | Алиф Банк | alif_bank |
| Vasl Bank | Васл Банк | vasl_bank |
| Amonatbonk | Амонатбонк | amonatbonk |
| Matin Bank | Матин Банк | matin_bank |
| Spitamen Bank | Спитамен Банк | spitamen_bank |
| Humo Bank | Хумо Банк | humo_bank |
Tracking the pay-out
/api/payment/statusresp = signed_post("/api/payment/status", {
"merchant_payment_id": "payout-tj-2026-000045"
})
# resp.json()["status"] -> "success" | "processing" | "decline" | "error"
A payout can stay in processing for a while before it completes. Rely on the callback
rather than tight polling. A payout to wrong or blocked details ends in decline.
Testing & go-live
- On stage, drive a pay-in to
paidand a payout tosuccessusing the test IDs. - Double-check TJS amounts: 2 decimal places, and only whole-somoni values (minor amount ends in
00) are accepted. - Send payouts to
/api/payment/payout/bank_accountwith abank_titlefrom the table — for cards as well as phone numbers. - Confirm your callback handler verifies the
X-MP-Signatureand tolerates retries.