Documentation Index
Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt
Use this file to discover all available pages before exploring further.
Payment Intent (PI)
A Payment Intent represents a customer’s intention to make a payment. It serves as the primary container for payment-related information and maintains the overall payment state throughout the transaction lifecycle. It represents a complete collection intent, regardless of whether the collection ultimately succeeds or fails.Key characteristics
- Unique identifier: each PI has a unique ID with the prefix
PI(e.g.,PI1234567890123456789) - Order information: contains essential order details such as amount, currency, and merchant reference
- Expiration: automatically expires after 30 minutes if not completed
- Persistence: once created, it continues to exist and can be used for multiple payment attempts
- Idempotency: ensures each transaction is only charged once
- State tracking: maintains a complete record of state changes throughout the entire payment process
Payment Intent status reference
| Status | Description | Next actions | Phase | Webhook event |
|---|---|---|---|---|
REQUIRES_PAYMENT_METHOD | Initial state after creation or after failed payment attempt. Waiting for confirm request with payment method. | Confirm with payment method | Initial | acquiring.payment_intent.created |
REQUIRES_CUSTOMER_ACTION | Waiting for customer to complete authentication (3DS verification, QR code scan, etc.). Check next_action for specific instructions. | Awaiting the customer to complete the operation specified in the next_action field. | Customer Interaction | acquiring.payment_intent.requires_action |
REQUIRES_CAPTURE | Authorization successful, waiting for capture to complete payment. Funds are authorized but not yet settled. | Call capture API (not available yet) to complete full or partial amount payment | Authorization Complete | - |
PENDING | Processing payment with payment provider. No further action required. | Wait for result | Processing | - |
SUCCEEDED | Payment completed successfully. Transaction is finished. | No further action needed | Final state | acquiring.payment_intent.succeeded |
CANCELLED | Payment cancelled by merchant request. Payment is closed. | No further action needed | Final state | acquiring.cancel.succeeded |
FAILED | Payment failed due to error or system timeout (30 minutes). | No further action needed | Final state | acquiring.payment_intent.failed |
Payment Attempt (PA)
A Payment Attempt represents a specific attempt to process a payment within a Payment Intent. Each PA contains the payment method details and processing results for that specific attempt.Key characteristics
- Unique identifier: each PA has a unique ID with the prefix
PA(e.g.,PA1234567890123456789) - Temporary nature: represents a single specific payment attempt
- Retry capability: failed attempt can be retried by creating a new payment attempt for the same Payment Intent
- Detailed information: contains specific payment details such as payment method used, error information, etc.
Payment Attempt status reference
| Status | Description | Phase | Webhook event |
|---|---|---|---|
INITIATED | The payment attempt has been created based on the initial request. | Initial | acquiring.payment_attempt.created |
AUTHENTICATION_REDIRECTED | Waiting for customer to complete authentication (3DS verification, QR code scan, etc.). | Customer Interaction | - |
PENDING_AUTHORIZATION | Authorization request accepted, waiting for payment provider’s final result. | Processing | - |
AUTHORIZED | Authorization successful. Payment will be captured automatically or manually. | Authorization Complete | - |
CAPTURE_REQUESTED | Capture request submitted successfully. Payment is considered complete. | Capture | acquiring.payment_attempt.capture_requested |
SETTLED | UQPAY has received settlement from payment provider. | Settlement | - |
SUCCEEDED | UQPAY has settled funds to your wallet. | Final state | - |
CANCELLED | The payment attempt has been cancelled. Any authorized funds, if applicable, will be returned to the customer. | Final state | acquiring.payment_attempt.cancelled |
EXPIRED | The payment attempt was not completed within the allowed time window and has expired. | Final state | acquiring.payment_attempt.cancelled |
FAILED | Payment attempt failed. | Final state | acquiring.payment_attempt.failed |
Payment flow
The payment flow supports two modes to accommodate different merchant integration scenarios:- Direct payment — suitable for scenarios where payment method information is available at order creation time
- Delayed confirmation — ideal for scenarios where payment method selection happens after order creation, allowing for order modifications before payment confirmation