How It Works

Payment flow, lifecycle states, and webhook events for Paratro Checkout

How It Works

Paratro Checkout processes stablecoin payments through a simple, deterministic flow — from order creation to settlement.

Payment Flow

Step-by-Step Flow

1. Create a payment order

   Your server calls the Paratro API to create a payment order with the amount, currency, and metadata (e.g., internal order ID, customer email). The API returns a unique payment URL and order ID.

2. Customer opens payment page

   Redirect the customer to the Paratro-hosted payment page, or render the Embed Widget on your site. The customer sees the amount, supported chains, and a wallet address or QR code to send funds to.

3. Customer sends payment

   The customer sends USDC or USDT from their wallet (MetaMask, Coinbase Wallet, Trust Wallet, or any compatible wallet) to the displayed address on their chosen chain.

4. Blockchain confirmation

   Paratro monitors the blockchain for the incoming transaction. Once detected, the payment moves to confirming status. After sufficient block confirmations, it moves to confirmed.

5. KYT / AML screening

   Every payment is automatically screened against sanctions lists and risk scoring models. Flagged transactions are held for review.

6. Auto-sweep to merchant wallet

   Confirmed funds are automatically swept from the collection address to your designated merchant wallet. The payment moves to settled.

7. Webhook notification

   Paratro sends a webhook to your configured endpoint for each status change, allowing your system to update order status, send receipts, or fulfill the order.

Payment Lifecycle

Every payment order progresses through a defined set of states:

State	Description
created	Payment order created. Waiting for customer to send funds.
pending	Transaction detected on-chain but not yet confirmed.
confirming	Transaction is accumulating block confirmations.
confirmed	Sufficient confirmations received. KYT screening passed.
settled	Funds swept to merchant wallet. Terminal success state.
expired	Customer did not send funds within the payment window (default: 30 minutes).
failed	Transaction failed on-chain, or KYT screening flagged the payment.

The number of required block confirmations varies by chain. Ethereum requires 12 confirmations, Base and Polygon require 20, and Solana requires 32 slot confirmations.

Webhook Events

Configure a webhook endpoint in your Dashboard to receive real-time notifications. All webhooks are signed with HMAC-SHA256 for verification.

Event	Description	Triggered When
payment.created	Payment order was created	POST /checkout/orders is called
payment.pending	On-chain transaction detected	Customer’s transfer appears in mempool or on-chain
payment.confirming	Block confirmations in progress	First block confirmation received
payment.confirmed	Payment fully confirmed	Required block confirmations reached and KYT passed
payment.settled	Funds swept to merchant wallet	Auto-sweep transaction confirmed
payment.expired	Payment window expired	Customer did not pay within the time limit
payment.failed	Payment failed	On-chain failure or KYT screening flagged

Webhook Payload

{
  "event": "payment.settled",
  "timestamp": "2026-04-12T10:30:00Z",
  "data": {
    "order_id": "ord_01HXZ...",
    "amount": "100.00",
    "currency": "USDC",
    "chain": "base",
    "status": "settled",
    "tx_hash": "0xabc123...",
    "merchant_reference": "INV-2026-0412",
    "settled_at": "2026-04-12T10:30:00Z"
  }
}

Verifying Webhook Signatures

Paratro signs every webhook with HMAC-SHA256 using your webhook secret. The signature is included in the X-Paratro-Signature header with a v1= prefix.

import crypto from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Always verify webhook signatures before processing events. Reject any request with an invalid or missing signature.