Check Payment Status

You can check the current status of a payment at any time using the payment status endpoint. This is useful for verifying the state of a transaction, handling webhook delays, or building payment monitoring dashboards.

Check Payment Status Flow

Retrieve Payment Status

To check the status of a payment, send a GET request with the paymentId.

Request

$ curl -H 'Content-Type: application/json' \
>      -H 'API-KEY: YOUR_API_KEY' \
>      -H 'API-SECRET: YOUR_API_SECRET' \
>      -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
>      YOUR_API_URL/payments/:paymentId/status

Response

1 {
2   "paymentId": "550e8400-e29b-41d4-a716-446655440000",
3   "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
4   "paymentStatus": "COMPLETED",
5   "timestamp": "2024-01-15T14:30:00Z"
6 }

Payment Status Values

Status	Description	Next Action
`PENDING`	Payment is being processed	Wait and poll again
`AUTHORIZED`	Payment authorized, awaiting capture	Capture or void
`COMPLETED`	Payment successfully completed	Fulfill order
`FAILED`	Payment failed	Retry or inform customer
`CANCELLED`	Payment was cancelled	No action needed
`VOIDED`	Payment was voided before settlement	No action needed
`REFUNDED`	Payment was refunded	No action needed
`PARTIALLY_REFUNDED`	Partial refund processed	Track remaining amount

Polling Best Practices

When polling for payment status:

Polling Limits

Implement exponential backoff when polling. Start with 2-second intervals and increase gradually. Set a maximum retry count (e.g., 30 attempts) to avoid infinite loops.

Webhook Integration

While polling is available, we recommend using webhooks for real-time payment status updates:

Approach	Pros	Cons
Polling	Simple implementation	Delayed updates, API load
Webhooks	Real-time, efficient	Requires endpoint setup

For webhook configuration, see the Webhooks documentation.

Status Transitions

Typical payment status transitions:

Error Handling

If the payment ID is invalid or not found:

1 {
2   "error": "PAYMENT_NOT_FOUND",
3   "message": "No payment found with the specified ID",
4   "paymentId": "invalid-payment-id"
5 }

Example: Polling Implementation

1 async function waitForPaymentCompletion(paymentId, maxRetries = 30) {
2   for (let i = 0; i < maxRetries; i++) {
3     const response = await fetch(
4       `${API_URL}/payments/${paymentId}/status`,
5       {
6         headers: {
7           'Content-Type': 'application/json',
8           'API-KEY': API_KEY,
9           'API-SECRET': API_SECRET,
10           'MERCHANT-ID': MERCHANT_ID
11         }
12       }
13     );
14     
15     const data = await response.json();
16     
17     switch (data.paymentStatus) {
18       case 'COMPLETED':
19         return { success: true, status: data.paymentStatus };
20       case 'FAILED':
21       case 'CANCELLED':
22       case 'VOIDED':
23         return { success: false, status: data.paymentStatus };
24       case 'PENDING':
25       case 'AUTHORIZED':
26         // Wait before next poll (exponential backoff)
27         await new Promise(r => setTimeout(r, 2000 * Math.pow(1.5, i)));
28         break;
29     }
30   }
31   
32   return { success: false, status: 'TIMEOUT' };
33 }