Payment Status

Monitor payment status through API calls or webhooks. The payment gateway tracks payments from creation through blockchain confirmations to final settlement.

Payment Status Lifecycle

stateDiagram-v2
    [*] --> OPEN: Payment Created
    OPEN --> FOUND: Transaction Detected
    FOUND --> RECEIVED: Confirmed on Blockchain
    FOUND --> UNDERPAID: Insufficient Amount
    RECEIVED --> CONFIRMED: Webhook Sent Successfully
    UNDERPAID --> RECEIVED: Additional Payment
    OPEN --> CANCELLED: Merchant Cancelled
    OPEN --> ERROR: Processing Error
    CONFIRMED --> REFUND: Refund Processed

Status Values

Status	Description	Next Actions
`OPEN`	Payment created, awaiting payment	Monitor for transaction
`FOUND`	Transaction detected on blockchain, awaiting confirmations	Wait for blockchain confirmations
`UNDERPAID`	Received less than the requested amount	Request additional payment or accept
`RECEIVED`	Full payment received and confirmed on blockchain	Await webhook confirmation
`CONFIRMED`	Payment confirmed, merchant webhook executed	Deliver goods/services
`CANCELLED`	Payment cancelled by merchant	No action needed
`ERROR`	Error during payment processing	Investigate and retry
`REFUND`	Payment has been refunded	Process refund in your system

Get Payment Status

Single Payment

GET /api/payment/{paymentId}
Authorization: Bearer YOUR_TOKEN

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CONFIRMED",
    "reference": "ORDER-123",
    "referenceLabel": "Order #123",
    "currencyCode": "USD",
    "amount": {
      "value": 100.00,
      "amount": 10000,
      "formatted": "$100.00"
    },
    "receivedAmount": {
      "value": 100.00,
      "amount": 10000,
      "formatted": "$100.00"
    },
    "confirmedAt": "2026-01-15T10:30:00Z",
    "foundAt": "2026-01-15T10:15:00Z",
    "date": "2026-01-15T10:00:00Z"
  }
}

Status Updates via Webhooks

Configure webhooks to receive automatic status notifications:

Event	Triggered When
`payment.received`	Funds received and confirmed on blockchain
`payment.completed`	Payment fully confirmed (webhook executed)
`payment.underpaid`	Received amount is less than requested
`payment.refund`	Refund completed

See Webhook Setup for configuration details.

Polling for Status

If webhooks are not configured, you can poll for status changes:

async function pollPaymentStatus(paymentId, apiKey) {
  const interval = 5000; // 5 seconds
  const timeout = 3600000; // 1 hour
  const startTime = Date.now();

  const poll = async () => {
    const response = await fetch(`https://api.yourdomain.com/api/payment/${paymentId}`, {
      headers: { Authorization: `Bearer ${apiKey}` }
    });

    const data = await response.json();
    const status = data.data.status;

    if (['CONFIRMED', 'CANCELLED', 'ERROR', 'REFUND'].includes(status)) {
      return data.data; // Terminal state
    }

    if (Date.now() - startTime > timeout) {
      throw new Error('Polling timeout');
    }

    await new Promise((resolve) => setTimeout(resolve, interval));
    return poll();
  };

  return poll();
}

Handling Edge Cases

Underpayment

When a payment is underpaid, the UNDERPAID status is set. If allowUnderpay is enabled for the payment application, the payment may still be accepted.

Refunds

Refund requests are created separately via the refund request endpoint. Once processed, the payment status changes to REFUND.

Best Practices

Use webhooks instead of polling for real-time updates
Always verify payment status via API before fulfilling orders
Handle all status values in your integration
Log status changes for audit and debugging
Implement idempotent handlers for webhook events