Core Concepts

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 succeeded and is awaiting capture.	Call the capture API; see capture amount rules.	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`
`PARTIALLY_CAPTURED`	A partially captured authorization has an outstanding balance.	Do not submit another capture; query capture results.	Processing	-
`EXPIRED`	The pre-authorization expired and was released.	Do not submit capture.	Final state	-

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

Getting Started

Accept Payments

Manage Payments

Testing

Reference

Payment Intent (PI)

Key characteristics

Payment Intent status reference

Payment Attempt (PA)

Key characteristics

Payment Attempt status reference

Payment flow

​Payment Intent (PI)

​Key characteristics

​Payment Intent status reference

​Payment Attempt (PA)

​Key characteristics

​Payment Attempt status reference

​Payment flow

Payment Intent (PI)

Key characteristics

Payment Intent status reference

Payment Attempt (PA)

Key characteristics

Payment Attempt status reference

Payment flow