The payment page URL is dynamically generated and may vary based on the selected currency, payment method, and region. Always use the exact URL returned in the API response.
Redirect your customer to this URL to complete the payment.
Payment is being processed, awaiting customer action
❌
-
completed
Payment was successful, funds transferred
✅
payment.completed
failed
Payment failed due to error or rejection
✅
payment.failed
cancelled
Payment was cancelled by merchant or system
✅
payment.cancelled
expired
Payment expired before completion
✅
payment.failed
refunded
Payment was fully refunded
✅
payment.refunded
partial_refund
Payment was partially refunded
✅
payment.refunded
Terminal statuses (completed, failed, cancelled, expired, refunded, partial_refund) are final states - the payment cannot transition to non-terminal status.
The payment has been created and is waiting to be processed. For withdrawals, this means the payout is queued and awaiting approval or processing by the payment provider.Next possible statuses:processing, cancelled, expired
processing
The payment is actively being processed. For deposits, this means the customer has been given payment instructions (bank details, payment page URL) and we are waiting for them to complete the transfer.Next possible statuses:completed, failed, cancelled, expired
completed
The payment was successful. For deposits, the funds have been received and credited to your merchant balance. For withdrawals, the funds have been sent to the beneficiary.This is a terminal status. You will receive a payment.completed webhook.
failed
The payment could not be completed. This can happen due to various reasons: bank rejection, invalid account details, insufficient funds (for withdrawals), or technical issues.This is a terminal status. You will receive a payment.failed webhook with an error_code and error_message.
cancelled
The payment was cancelled before completion. This can be initiated by the merchant via API, by an admin, or automatically by the system.This is a terminal status. You will receive a payment.cancelled webhook.
expired
The payment was not completed within the allowed time window. Deposits typically expire after 1-60 minutes (configurable per merchant).This is a terminal status. You will receive a payment.failed webhook with error_code: TTL_EXPIRED.
refunded
The payment was fully refunded after completion. The refunded amount has been deducted from your merchant balance.This is a terminal status. You will receive a payment.refunded webhook.
partial_refund
The payment was partially refunded. Part of the original amount has been returned to the customer.This is a terminal status. You will receive a payment.refunded webhook with the refunded amount.
Always use webhooks to track payment status changes. Polling the API is not recommended as it adds latency and may hit rate limits.
Copy
// Example: Handling status in your webhook handlerswitch (payment.status) { case 'completed': // Update order to paid, deliver goods/services await markOrderAsPaid(payment.merchant_reference); break; case 'failed': case 'expired': // Notify customer, allow retry await notifyPaymentFailed(payment.merchant_reference, payment.error_message); break; case 'cancelled': // Clean up pending order await cancelOrder(payment.merchant_reference); break; case 'refunded': case 'partial_refund': // Process refund in your system await processRefund(payment.merchant_reference, payment.refunded_amount); break;}
Payments are automatically linked to customers in your account. You can optionally pass an existing customer ID to link a payment to a specific customer.
When customer_id is provided, the system validates that the customer exists and belongs to your merchant account. The customer object is still required for display purposes.
Use unique merchant_reference values for idempotency. If you submit a payment with a reference that was already used, the API will return the existing payment instead of creating a duplicate.
