> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts
> Understand Payment Intent and Payment Attempt, the core building blocks of UQPAY's acquiring system.
## 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
```mermaid theme={null}
sequenceDiagram
participant Consumer as Consumer
participant Merchant as Merchant System
participant UQPAY as UQPAY System
Note over Consumer,UQPAY: Direct Payment Mode
Consumer->>Merchant: Place order with payment method info
Merchant->>UQPAY: Create a PaymentIntent (with payment_method)
UQPAY-->>Merchant: acquiring.payment_intent.created
UQPAY-->>Merchant: acquiring.payment_attempt.created
alt Payment Success
UQPAY->>UQPAY: Process payment
Note right of UQPAY: PA: CAPTURE_REQUESTED
PI: SUCCEEDED
UQPAY-->>Merchant: acquiring.payment_intent.succeeded
UQPAY-->>Merchant: acquiring.payment_attempt.capture_requested
Merchant->>Consumer: Payment successful
else Payment Failed
UQPAY->>UQPAY: Process payment
Note right of UQPAY: PA: FAILED
PI: REQUIRES_PAYMENT_METHOD
UQPAY-->>Merchant: acquiring.payment_attempt.failed
Merchant->>Consumer: Payment failed
end
Note over Consumer,UQPAY: Delayed Confirmation Payment Mode
Consumer->>Merchant: Place order only (no payment method info)
Merchant->>UQPAY: Create a PaymentIntent (without payment_method)
Note right of UQPAY: PI: REQUIRES_PAYMENT_METHOD
UQPAY-->>Merchant: acquiring.payment_intent.created
Note over Merchant,UQPAY: Optional: Update order information
Merchant->>UQPAY: Update a PaymentIntent (amount, currency, etc.)
UQPAY->>Merchant: PaymentIntent updated
Consumer->>Merchant: Select payment method & enter details
Merchant->>UQPAY: Confirm a PaymentIntent
Note right of UQPAY: PA: INITIATED
UQPAY-->>Merchant: acquiring.payment_attempt.created
alt Payment Success
UQPAY->>UQPAY: Process payment
Note right of UQPAY: PA: CAPTURE_REQUESTED
PI: SUCCEEDED
UQPAY-->>Merchant: acquiring.payment_intent.succeeded
UQPAY-->>Merchant: acquiring.payment_attempt.capture_requested
Merchant->>Consumer: Payment successful
else Payment Failed
UQPAY->>UQPAY: Process payment
Note right of UQPAY: PA: FAILED
PI: REQUIRES_PAYMENT_METHOD
UQPAY-->>Merchant: acquiring.payment_attempt.failed
Merchant->>Consumer: Payment failed
end
Note over Consumer,UQPAY: Cancellation Scenarios
alt System Auto-Close (30min timeout)
UQPAY->>UQPAY: Auto-close expired PI
Note right of UQPAY: PI: FAILED
UQPAY-->>Merchant: acquiring.payment_intent.failed
else Merchant Initiated Cancel
Merchant->>UQPAY: Cancel a PaymentIntent
UQPAY->>UQPAY: Cancel payment
Note right of UQPAY: PA: CANCELLED
PI: CANCELLED
UQPAY-->>Merchant: acquiring.cancel.succeeded
UQPAY-->>Merchant: acquiring.payment_attempt.cancelled
end
```