FAQ

Common integration questions grouped by topic. See the corresponding API pages for complete fields and examples.

Integration & requests

How do we obtain portal access and test credentials?

Contact the integration team for portal access, application credentials and testing instructions. See environment and credentials.

What is the difference between H5 and H2H?

H5 uses create_order and returns pay_url for opening the payment page. H2H uses create_deeplink_order and returns payment details such as payee_account, default_open_url and wallet_options. Their response fields differ. See H5 creation and H2H creation.

What if wallet links are empty? Can we request QR-only display?

Wallet links in H5 meta may be empty; use pay_url. H2H wallet links are in wallet_options, with codes including paytm, phonepe and gpay. Use the options actually returned for the order. The request parameters do not support forcing QR-only display or a particular wallet.

Are returned Paytm and PhonePe links guaranteed to open? What if a link fails?

wallet_options lists the wallet payment options offered for the order; it does not guarantee that every device can open them or complete payment. Compatibility depends on the operating system, browser, wallet installation and version, among other factors. A VPA suffix alone does not establish compatibility. Use the returned links unchanged; do not replace the UPI ID or rewrite the link format. If a link fails, first check whether funds were debited. If not, try another option returned for the same order. If funds were debited, do not pay again; contact support with the order ID, device and wallet details. Opening a wallet is not proof of payment; confirm a verified signed success callback or query status=20.

Which field carries our order ID? Can we query without a platform order ID?

Send your order ID in tenant_order_no when creating an order. A status query requires at least one of tenant_order_no or platform_order_no; if both are supplied, they must identify the same order. See PayIn query and payout query.

Will submitting the same merchant order ID create a second payout?

Payout creation checks duplicate merchant order IDs. Matching key parameters return the original order, including a successful order, unless it has failed, been cancelled, expired or reversed. No second payout is created. Conflicting key parameters or an order in one of those failure, cancellation, expiration or reversal states return 100409. Use a unique merchant order ID for a new PayIn. If creation is uncertain, query the original order first. See payout creation.

Can the request body be Base64 or a JSON-encoded string?

Send a JSON object with Content-Type: application/json. Do not Base64-encode the entire request or encode the JSON object again as a quoted string. See requests and responses.

Does timestamp use seconds or milliseconds? What date format is used?

timestamp is the current Unix timestamp in seconds, not milliseconds. Business dates such as pay_time and created_at use YYYY-MM-DD HH:mm:ss, not ISO8601. See environment and credentials for the business timezone.

Must JSON fields be sent in a fixed order? Should the secret be Base64-decoded?

JSON field order does not affect verification, but parameter names must be sorted in ascending ASCII order when calculating the signature. Use app_secret exactly as supplied, without Base64 decoding. Retain 0 and exclude empty strings and null. See the signature rules.

Should pay_time and created_at be added to the request signature?

Do not add these fields to creation or status-query requests. Sign the non-empty parameters actually sent for the endpoint, excluding sign. If these dates are present in a callback, use their exact received values and exclude signature; do not reformat the dates.

Amounts & fees

Are decimal amounts supported?

Yes, for example "35.44". A decimal string is recommended. Use the same representation for signing and transmission; "200" and "200.00" produce different signature strings.

Can pay_sum differ from order_sum?

Yes. order_sum is the amount submitted at creation; pay_sum is the amount payable by the customer. For an order of 100.00, the payable amount might be 100.07 or 99.97. Follow the returned payment instructions without changing the payable amount. Payable does not mean funds have been received.

Is callback amount the actual amount paid by the customer?

PayIn callback amount is the original order amount. Obtain the payable amount from H5 payable_amount or H2H pay_sum. PayIn query paid_amount is the confirmed payment amount recorded by the platform; it is not independent proof of the amount debited from the player’s bank account. The callback has no dedicated field for the player’s bank debit. Use the final callback settlement_amount for the merchant’s net credit. See amounts and fees.

Can a payment succeed automatically when the amount differs from pay_sum?

Pay the exact pay_sum returned for the order. A different amount is not guaranteed to be confirmed automatically, and the size of the difference alone does not determine success or failure. Provide the UTR through Submit UTR for verification. Successful verification may allow automatic confirmation; not every case requires manual handling. If the payment remains unconfirmed, contact support with the order ID, UTR and payment receipt rather than marking it successful yourself.

Which amounts are returned and settled after manual reconciliation?

After manual reconciliation, PayIn callback amount remains the original order amount, total_fee is the fee applied, and settlement_amount is the confirmed merchant net credit. Manual handling does not mean every order settles on the original amount or an amount reported by the player. Follow the reconciliation result and final callback settlement_amount; do not substitute pay_sum or your own amount - total_fee calculation. Contact support with the order ID if clarification is needed.

Does an underpayment receive full-order credit? Is an overpayment refunded automatically?

Do not treat an underpayment as full payment of the original order or assume an overpaid amount will be refunded automatically. Provide the order ID, UTR and payment receipt to verify the received funds and handling arrangements. An amount difference alone does not trigger an automatic top-up or refund to the player. Contact support to confirm whether the funds can be credited or returned and which amount applies.

With amount=1000.00 and total_fee=10.00, should the beneficiary receive 1000 or 990?

For a payout, the beneficiary principal is 1000.00, not 990.00; the merchant principal plus fee is normally 1010.00. A PayIn net settlement may instead be 990.00. total_fee is the order fee. The meaning of settlement_amount differs between PayIns and payouts; see amounts and fees.

What is frozen balance? How does it differ from available balance?

Frozen balance is committed funds that are temporarily unavailable. For example, payout creation freezes principal and fees; funds are settled after successful payment or released for failure and applicable release conditions. In the balance API, balance is available funds and freezeBalance is frozen funds. See balance query for the other fields.

Payment parameters

What does payment_type=1 mean? Is it fixed for every payout?

1 means bank transfer and 2 means UPI payout. Choose the value for the payout method: provide the beneficiary name and bank account for bank transfers, or payee_upi for UPI. See payout creation.

Is payer_name required?

For H2H creation, it is an optional string up to 128 characters. It is not a request parameter for H5 creation.

How should payee_account_name and payee_account_no be populated?

For payment_type=1, both fields are required and each allows up to 100 characters. Put the actual beneficiary name in payee_account_name and the actual bank account number in payee_account_no, preserving leading zeros. Do not swap the fields.

Is payee_bank_name required? Is a full bank-name list available?

payee_bank_name is an optional string up to 100 characters. When supplied, use the beneficiary bank’s standard name. This documentation does not provide a bank-name enumeration. Do not use a name unrelated to the beneficiary bank.

How do IFSC and bank account-number formats differ?

payee_bank_code is the bank branch IFSC. Its standard format is ^[A-Za-z]{4}0[A-Za-z0-9]{6}$, for example SBIN0001234. payee_account_no is the bank account number, not IFSC. Obtain the actual account and branch code from the beneficiary and confirm IFSC requirements for the enabled payment method.

How do we provide the beneficiary phone number and name?

payee_phone is an optional string up to 20 characters; supply the actual phone number. For bank transfers, payee_account_name allows up to 100 characters and should be the actual name associated with the receiving account. See payout creation.

Queries & order statuses

Does HTTP 200 or creation success=true mean payment succeeded?

No. The HTTP status describes request handling. Creation success=true and code=200 indicate a successful creation operation, not that the customer paid or the beneficiary received funds. Confirm the payment result from the order status in a query or callback; success is 20.

What does status=1 in a payout query mean?

1 means the payout order is created and pending processing, not a final successful or failed result. 2, 10, 11 and 30 also do not mean payment succeeded. See order statuses.

How do we distinguish pending, successful, failed and refunded statuses?

20 is success, 40 failure, 41 cancellation, 43 expiration and 44 refund/reversal. 0, 10 and 30 are pending, not successful; payouts also use 1, 2 and 11. See order statuses for PayIn expiration and later payment confirmation.

Can a transaction be treated as failed when query returns 203006?

203006 means no returnable order was found for this query; it is not a failed-payment status. Check the order IDs; when both are supplied, they must identify the same order. If creation was previously uncertain, use the original merchant order ID for verification and provide request_id to the integration team.

Can PayIn status=43 later become successful? Will there be a callback?

43 means the payment window expired. Later payment confirmation can update the status to 20; orders with notify_url configured receive a success notification, and queries reflect the update. Automatic expiration itself does not send a failed callback. Use the expiration time returned for the order. See order statuses.

When is status 43 definitively final? Can payment be cancelled with certainty?

There is currently no guaranteed universal cutoff or cancellation API that ensures an expired PayIn can never later succeed. Repeated query_order responses with 43 mean the order is still recorded as expired, not that non-receipt of funds is definitive. Before refunding, closing the transaction or making a replacement payment, contact support with the original order ID, payment time and any available UTR. Do not automatically refund or repeat payment solely because the status is 43.

Can a failed PayIn result be updated after later payment confirmation?

Later PayIn payment confirmation can update a previous failure or expiration result. Confirm the current status through a query for the original order and payment-result callbacks. See order statuses.

Is 44 Reversed / Refund successful? Is it a dispute status?

44 means refund/reversal, not success and not a dedicated dispute status. The current status reference has no separate dispute status. See order statuses.

Callbacks & UTR

Should our H2H page require a UTR for Manual Transfer?

Yes. For Manual Transfer, where the player copies the UPI ID, we recommend requiring the UTR after payment. Ask the player to use the current order’s payment details and pay the exact pay_sum before expiry, then submit the UTR from your server through Submit UTR. Use the H2H response trade_no as platform_order_no. Confirm payment only from a verified signed success callback or query status=20.

Will an exact Manual Transfer amount match automatically without a UTR?

Payment may still be confirmed, but the amount alone is not guaranteed to associate a manual transfer with the correct order when an order reference or UTR is unavailable. A matching amount or screenshot alone is not proof that the order succeeded. Collect and submit the UTR where possible. If no UTR is available or the payment remains unconfirmed, contact support with the order ID and payment receipt.

Does submitting a UTR guarantee automatic credit?

No. submitted_utr submits a payment reference for verification; it is not an instruction to mark an order successful. Successful verification may confirm payment and trigger a success callback, but submission or HTTP 200 alone is not proof of credit. Confirm a verified signed success callback or query the original order for status=20. If verification fails or the result remains unclear, contact support instead of paying again.

Are webhooks supported? How do notify_url and return_url differ?

Yes. Supply your own notify_url during creation to receive server-side payment results. No order callback is sent when it is omitted. H5 return_url is for the browser return flow and does not replace a webhook. H2H and payout creation documentation do not include a return_url parameter.

Are order callbacks sent using GET or POST?

Order-result callbacks use POST with a JSON body. Handle browser requests separately from server-side callbacks. If you observe GET, provide the order ID, request URL and receiver logs for investigation by the integration team.

Where are the successful callback body and cURL examples?

PayIn callbacks and payout callbacks include fields, signed JSON bodies and cURL examples.

Is returning HTTP 200 alone enough to acknowledge a callback?

Return HTTP 200 with the plain-text body success or ok. HTTP 200 alone, or a body such as {"status":200}, is insufficient to acknowledge receipt. See the acknowledgment examples for PayIn and payout callbacks.

Is an order successful when status=20 but notify_status=3?

The payment result is successful. status is the order status; notify_status is the notification status. 3 means notification failed, for example because the receiver was unreachable or the acknowledgment was not accepted. Check the creation notify_url and receiver response, and provide the order ID for assistance.

Why can the same order receive more than one successful callback?

A success notification may be repeated for the same order. Repeated 20 notifications with the same order ID refer to the same payment, not a new transaction. Return the documented acknowledgment after successful receipt.

Is UTR returned in PayIn and payout callbacks and queries?

Successful callbacks include utr when the payment reference is available; it may be omitted otherwise. Payout query includes utr, which can be empty. Current PayIn query_order does not include it; use UTR query to query by reference.

Errors & support

What should we check for 100422 Request parameter error?

Check required fields, data types and formats for the endpoint. For payouts, also check beneficiary fields for payment_type, ensure the name and account number are not swapped, and confirm the body is a JSON object. Provide a redacted request, response and request_id for assistance; do not send real secrets.

What does 202003 Invalid application key mean?

Confirm that tenant_id and app_key belong to the same merchant application and use the correct supplied credentials. Do not use app_secret as app_key. See error codes.

Which error code is returned for insufficient payout funds?

When available balance plus credit cannot cover payout principal and fees, the response uses 203005. The code also covers other creation failures; inspect message for the description. See balance query.

Can creation be marked failed after a timeout, connection error or HTTP 500?

These results alone do not establish whether the order was created or payment completed. Query using the original tenant_order_no. If still uncertain, provide the request time, original order ID and request_id to the integration team. See request errors.

Why is message sometimes Chinese and sometimes English?

message is descriptive text and may be Chinese or English. Use code for the API result and order status for the payment result, rather than depending on a fixed message string.

Which field contains the failure reason? Do queries or callbacks include details?

For creation failure, inspect top-level code and message. Current query_order responses and ordinary result callbacks do not have a unified detailed failure-reason field. Provide the merchant order ID, platform order ID or request_id to the integration team for details.