MagicPayments Integration Guides

Tajikistan QR Gate

Pay-inPay-outTJSQR

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.

OperationRailHow the integration looks
Pay-inBank QR code / card transferCreate an invoice, redirect the payer to the hosted page.
Pay-outCard or phone number at a Tajik bankServer-to-server call to the bank-account payout endpoint.
Whole-somoni amounts only

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.

Prerequisites

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

  1. Create the invoice Call the gate endpoint with your gate_id and the amount in TJS minor units.
  2. 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.
  3. 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.
  4. Receive the result Once the transfer is matched we call your callback_url and the invoice moves to paid. If the payer cancels, the invoice ends as payment_failed with the error code canceled_by_payer.
POST/api/invoice
Request body
{
  "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

POST/api/invoice/status
resp = signed_post("/api/invoice/status", {
    "merchant_invoice_id": "order-tj-2026-000123"
})
invoice = resp.json()
# invoice["status"] -> "paid" once the transfer is confirmed
Exact amount, one transfer

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.

POST/api/payment/payout/bank_account
FieldRequiredWhat 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.
Request body — card payout
{
  "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

POST/api/payment/status
resp = signed_post("/api/payment/status", {
    "merchant_payment_id": "payout-tj-2026-000045"
})
# resp.json()["status"] -> "success" | "processing" | "decline" | "error"
Payouts are not instant

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