Help Center
Operations
Glossary
| Term | Definition | Notes |
|---|---|---|
| Partner (PID) | Channel partner / reseller | Entity that has a partnership with Paydify and may onboard downstream merchants |
| Merchant (MID) | Merchant | Commercial entity that consumes Paydify payment services directly |
| x-api-key | Application Id | The unique ID that hosts a payment app or sub-merchant |
| x-api-secret | Secret key | |
| Payin | Collection | User pays the merchant in stablecoin |
| Payout | Disbursement | Merchant pays a user / supplier in stablecoin |
| Custodian | Custody | Inbound USDT is held in your Paydify balance and reused for batch USDT payouts or fiat settlement |
| CKP | Checkout Page | Paydify-hosted intermediary checkout page |
Payin
When should I use CKP, Deeplink or QRCode?
| Mode | Best for | User flow |
|---|---|---|
| CKP | WAP / App | Merchant redirects to the Paydify checkout, which orchestrates the wallet |
| Deeplink | WAP / App | Merchant renders its own checkout and jumps directly to a specific wallet |
| QRCode | Web (PC) | PC renders the QR code; the user scans with a mobile wallet |
All three modes share the same POST /payin/v1/createPayment endpoint — they differ only in whether you consume data.httplink, data.deeplink or data.qrCode in the response.
Which payment state values exist?
| state | Meaning | Terminal |
|---|---|---|
INIT | Order created, no on-chain activity yet | No |
PAYING | On-chain transfer detected, waiting for confirmations | No |
PAID | Payment confirmed, funds credited | Yes |
FAILED | Failed (on-chain failure / amount mismatch / user cancellation) | Yes |
TIMEOUT | Order expired before payment (lifetime reached) | Yes |
Why are both webhook and pull required?
- Webhook (primary) — Paydify pushes the state change with minimal delay.
- Pull (fallback) — covers temporary callback unavailability or network jitter via
POST /payin/v1/getPaymentStatus.
Relying on webhook only risks lost orders when delivery fails; polling only adds latency and wasted calls.
Deposit
Does the deposit address change?
No. The deposit address for each (App + chain) pair is permanent — it is generated once after KYC and never rotates. You can safely store it in your treasury system.
What happens to deposits without an allowlist match?
Funds enter FROZEN first; the merchant manually releases them to the balance or refunds them on the Portal. With an allowlist configured, matched deposits auto-credit to the balance.
Withdrawal
What happens if the balance is insufficient for a Crypto Withdraw?
The API returns INSUFFICIENT_BALANCE synchronously — no async flow is started and the balance is not deducted. You can top up and retry with the same mchWithdrawId.
How long is a Fiat Withdraw quote valid?
Default 60 seconds. After it expires you must call POST /payout/v1/fiat-withdraw/quote again.
Where do failed Fiat Withdraw funds go?
Back to your Paydify platform balance. If the failure was caused by wrong recipient details, a fail fee is deducted before the funds return.
Payout
Single vs batch payout — when to use which?
Single payout pays one recipient; batch payout lets you submit many payouts in the Portal or via API — ideal for payroll and promoter commissions. See Payout overview.
How do deposit allowlists and KYA screening affect payouts?
Deposits from non-allowlisted addresses are frozen; payout destinations are screened by KYA and high-risk addresses may be blocked. See Payout overview and the data dictionary.
Refund
Who can initiate a refund?
Currently only the merchant can initiate refunds via createRefund. There is no other channel.
What are the refund scenarios?
| Scenario | Fund path | Paydify refund flow |
|---|---|---|
| CEX refund (Binance / Bitget / OKX, etc.) | Original path in → original path out | Call createRefund; Paydify settles the refund on-chain. Multiple partial refunds are supported; ServiceFee is refunded proportionally to the refund amount. |
| DEX refund (MetaMask / Bitget Wallet / OKX Wallet, etc.) | User → merchant address (P2P) | The merchant first refunds off-chain (manual transfer or via Payout), then calls createRefund to update the order state. |
How is the refund amount calculated?
Validation rule: SUM(refunded) + this refund <= original order amount.
- Stablecoin orders — refund amount = the amount you request. Example: order = 100 USDT, paid = 100 USDT, refund request = 20 USDT → user receives 20 USDT.
- Fiat orders — refund amount =
merchant_refund_fiat / order_fiat_total * paid_stablecoin. Example: order = 100 USD, paid = 101 USDT at the order-time rate, refund request = 20 USD → user receives 20 USD / 100 USD × 101 USDT = 20.2 USDT.
Which fees are non-refundable?
- KYT / KYA on-chain screening fees already charged are non-refundable.
- On-chain gas paid by the user in DEX flows is non-refundable.
- Other ServiceFees are refunded proportionally to
refund_amount / order_amount.
Integration
What is apiPath in webhook signature verification?
It is the path of the endpoint that receives the callback — exactly matching the request path Paydify uses to deliver it, without the domain.
Example: if your callback URL is https://xxx.com/api/payment/notify, set apiPath to /api/payment/notify.
What should I reply on a successful callback?
HTTP 200 with body success (raw string, Content-Type: text/plain recommended). Paydify treats this as delivered; otherwise it retries up to 7 times at 1m / 5m / 30m / 2h / 6h / 12h / 24h intervals. See Webhook.
Can the same txnId callback fire more than once?
Yes — it may fire one or more times due to network jitter, temporary callback failures, or multiple on-chain events. Deduplicate by txnId + state on your side.
My server clock is off from Paydify — what happens?
Signed requests carry a timestamp; large skews are treated as expired and rejected. Keep your servers synced via NTP. The same applies to your callback endpoint.
Can sandbox and live credentials be mixed?
No. Sandbox and production x-api-key / x-api-secret are independent. Sandbox credentials only work against the sandbox domain; live credentials only work against production. See Service domain.