CKP Checkout Integration

In CKP (Checkout Page) mode, the merchant redirects the buyer to Paydify's hosted checkout page, which orchestrates the wallet handoff and completes the payment. CKP is the lowest-effort, broadest-coverage option for Payin and is the recommended starting point.

Interaction

The merchant redirects the buyer to Paydify's hosted checkout page, where the buyer picks a wallet and completes the payment.

Prerequisites

Before integrating, make sure you have:

• Completed KYC and received your PartnerID, x-api-key and x-api-secret (Paydify emails the sandbox credential pack to the address registered during KYC);
• Reviewed the Service domain and Request / Response docs;
• Installed the server-side SDK (recommended — it encapsulates signing / verification). See Developer resources.

Integration steps

Sequence

Step 1 — Sign / verify

Every request to Paydify and every webhook delivered by Paydify carries a signature. Signing proves to both sides that "this call really came from us" and prevents tampering.

Recommended: use a Paydify server-side SDK (Java / Node.js / Python / PHP, etc.). The SDK encapsulates the signing routine; you only need to inject x-api-key and x-api-secret.

If you implement it yourself: see Signature. Key constraints:

• Every signed request carries 2 HTTP headers: x-api-key / x-api-timestamp;
• Server clocks (yours and Paydify's) must stay accurate (NTP recommended), otherwise requests are rejected as "expired";
• You must verify the signature on incoming webhooks too — reject anything that fails verification, otherwise spoofed callbacks can corrupt your order state.

Step 2 — Create a payment order on the server

Call POST /payin/v1/createPayment from your server to open a payment session and redirect to the Paydify checkout page. Pay attention to the following fields:

For additional fields (source / txnTitle / txnDesc / payerInfo / mchExtInfo), see API Reference · Create payment.

Request example:

{
  "mchTxnId": "MCH_TXN_20260610_002",
  "txnAmount": "0.01",
  "currency": "USDT",
  "checkoutMode": "MERCHANT",
  "payMethod1": "",
  "payMethod2": "",
  "notificationUrl": "https://your-domain.com/api/payment/notify",
  "successReturnUrl": "https://your-domain.com/pay/success",
  "failReturnUrl": "https://your-domain.com/pay/fail",
  "pendingReturnUrl": "https://your-domain.com/pay/pending",
  "txnTitle": "Test Payment Order",
  "source": "web",
  "txnDesc": "Payment for test product",
  "accountInfo": {
    "toAddress": "0x1111111111222222222233333333334444444444"
  },
  "payerInfo": {
    "uid": "USER_123456"
  },
  "mchExtInfo": "{\"orderId\":\"ORD_2025081201\",\"productId\":\"PROD_001\"}"
}

Response example:

// Successful response
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "txnId": "P1167515578018041857",
    "mchTxnId": "MCH_TXN_20260610_002",
    "state": "INIT",
    "errorMsg": "",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
    "deeplink": "bitkeep://pay?txnId=P20250827173005906",
    "httplink": "https://payrouter.paydify.com/en/pay/middle?txnId=P1167515578018041857&_needChain=base"
  },
  "success": true
}

// Failed response
{
  "code": "SYS_ERROR",
  "message": "System error",
  "messageDetail": "Error details",
  "data": null,
  "success": false
}

In CKP mode you mainly consume data.httplink.

Step 3 — Redirect the client to the Paydify checkout

Pass data.httplink from the createPayment response back to your front-end and redirect the user:

<a href="{{httplink}}" target="_self">Pay now</a>

The Paydify checkout auto-adapts to the device:

• Mobile — automatically tries to launch the user's wallet app;
• Desktop browsers — renders a QR code so the user can scan with a mobile wallet.

When the user returns to your site

When the checkout flow completes, Paydify redirects back to the URL you supplied in step 2:

Step 4 — Get the result (belt and braces)

After creating an order, integrate both the asynchronous webhook and the active query — that pair is the belt-and-braces guarantee:

• Webhook (primary) — Paydify pushes state changes with minimal delay;
• Active query (fallback) — covers network jitter or temporary outages on your callback endpoint.

4.1 Receive the webhook

Paydify sends a POST to your notificationUrl whenever the order state changes. The body is JSON; the headers carry the signature fields described in step 1. Full details on receiving, verifying, replying, and retrying live in Webhook.

The four facts you must internalize:

1. Verify the signature — reject (HTTP 400) + log alert on failure; do not continue with business logic;
2. Be idempotent — the same txnId may be delivered more than once (jitter, retries, multiple on-chain events). Deduplicate by txnId + state;
3. Reply correctly — return HTTP 200 with body "SUCCESS". Paydify only considers the delivery successful when it sees this response; any other response (including HTTP 200 with a non-SUCCESS body) triggers an automatic retry;
4. Auto-retry — failures are retried up to 7 times at 1m / 5m / 30m / 2h / 6h / 12h / 24h intervals; deliveries that still fail raise an alert. See Webhook.

Webhook payload example:

{
  "txnId": "P5081643613805693697",
  "mchTxnId": "dcb97435-6713-4129-b428-2340c61c5605",
  "state": "PAID",
  "txnAmount": "0.01",
  "currency": "USDT",
  "paidAmount": "0.01",
  "paidCurrency": "USDT",
  "paidNetwork": "BNB",
  "paidTime": 1780971481993,
  "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "fromAddress": "0x5555555555666666666677777777778888888888",
  "toAddress": "0x1111111111222222222233333333334444444444",
  "fee": "0",
  "errorMsg": "",
  "mchExtInfo": "{\"orderId\":\"ORD_2025081201\",\"productId\":\"PROD_001\"}"
}

Merchant reply example:

• HTTP status: 200
• Content-Type: text/plain
• Body (raw string, case-insensitive):

success

The following replies are also accepted as success (no further retries):

• success / SUCCESS / Success
• Leading / trailing whitespace or newline: success , success\n

The following replies are treated as failure and trigger a retry:

• JSON objects: {"status":"success"} / {"code":0} / {"result":"success"}
• HTML error pages or an empty body
• Any literal other than success (including fail)

4.2 Active query

See Query payment status.

Endpoint: POST /payin/v1/getPaymentStatus

Request (txnId or mchTxnId, one of two):

Request example:

{
  "txnId": "P5081643613805693697"
}

Response example:

{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "txnId": "P5081643613805693697",
    "mchTxnId": "dcb97435-6713-4129-b428-2340c61c5605",
    "state": "PAID",
    "txnAmount": "0.01",
    "currency": "USDT",
    "paidAmount": "0.01",
    "paidCurrency": "USDT",
    "paidNetwork": "BNB",
    "paidTime": 1780971481993,
    "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "fromAddress": "0x5555555555666666666677777777778888888888",
    "toAddress": "0x1111111111222222222233333333334444444444",
    "fee": "0",
    "errorMsg": "",
    "mchExtInfo": "{\"orderId\":\"ORD_2025081201\"}"
  },
  "success": true
}

state values:

Recommended usage:

• After receiving a webhook, verify the signature + deduplicate → call getPaymentStatus for a second confirmation rather than trusting the payload blindly;
• If a webhook is overdue (use a timeout ≥ order lifetime), poll getPaymentStatus as a fallback.

Step 5 — Issue a refund (optional)

Once an order reaches PAID, you can refund all or part of it. Refunds are asynchronous: Paydify pushes the terminal result via a separate webhook.

Create a refund

Endpoint: POST /payin/v1/createRefund — see Create refund and Query refund status.

Request parameters:

Request example:

{
  "mchTxnId": "REFUND_2026061001",
  "paymentTxnId": "P5081643613805693697",
  "refundAmount": "0.01",
  "mchExtInfo": "{\"reason\":\"customer_cancel\"}"
}

Response example:

{
  "code": "SYS_SUCCESS",
  "data": {
    "refundTxnId": "R5081643613805694001",
    "mchTxnId": "REFUND_2026061001",
    "paymentTxnId": "P5081643613805693697",
    "state": "PENDING",
    "refundAmount": "0.01",
    "currency": "USDT"
  },
  "success": true
}

For refund scenarios (CEX / DEX differences) and fee rules, see FAQ — Refund.

Step 6 — Settlement files (optional)

Settlement files power daily reconciliation, finance booking and cross-system matching. The API call (request params, response fields, Summary / Detail download links) is described in Get settlement files.

• settlementDate uses format YYYY-MM-DD in the UTC time zone; only today-1 and earlier can be queried;
• summaryFileUrl / detailFileUrl are S3 pre-signed links valid for 60 minutes; call this API again for fresh links after expiry;
• Recommended pull window: after UTC 01:00, fetch the T-1 file. Avoids contention with merchant traffic peaks.

Summary file format

Summary outputs one aggregated row per settlementCurrency. CSV, UTF-8, comma-separated, with a header row.

Detail file format

Each Detail row corresponds to one PAYMENT or REFUND. CSV, UTF-8, comma-separated, with a header row.

Go-live checklist

[ ] Sandbox run-through complete: createPayment → checkout → webhook → getPaymentStatus
[ ] Failing webhook signature returns HTTP 400
[ ] Duplicate webhook delivery for the same txnId is deduplicated
[ ] Webhook reply is HTTP 200 with raw body `success`
[ ] successReturnUrl / failReturnUrl / pendingReturnUrl all configured
[ ] BD confirmed: production domain, outbound IP allowlist, HTTPS certificate
[ ] Switched to production x-api-key / x-api-secret; sandbox credentials retired