Core Concepts

Overview

Payment Intent (PI) and Payment Attempt (PA) are the fundamental building blocks of UQPAY's acquiring system. Understanding these concepts is essential for successful integration and payment processing.

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

PaymentIntent 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 - `SUCCEEDED`	`acquiring.payment_intent.succeeded`
`CANCELLED`	Payment cancelled by merchant request. Payment is closed.	No further action needed	Final state - `CANCELLED`	`acquiring.cancel.succeeded`
`FAILED`	Payment failed due to error or system timeout (30 minutes).	No further action needed	Final state - `FAILED`	`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.

PaymentAttempt 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 - `SUCCEEDED`	-
`CANCELLED`	The payment attempt has been cancelled. Any authorized funds, if applicable, will be returned to the customer.	Final state - `CANCELLED`	`acquiring.payment_attempt.cancelled`
`EXPIRED`	The payment attempt was not completed within the allowed time window and has expired.	Final state - `EXPIRED`	`acquiring.payment_attempt.cancelled`(it's not a typo)
`FAILED`	Payment attempt failed.	Final state - `FAILED`	`acquiring.payment_attempt.failed`

API Flow - Payment Sequence Diagram

Overview

This diagram illustrates the complete payment flow including both direct payment and delayed confirmation payment modes, with API calls, webhooks, and state transitions.

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

Sequence Diagram

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<br/>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<br/>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<br/>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<br/>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<br/>PI: CANCELLED
        UQPAY-->>Merchant: acquiring.cancel.succeeded
        UQPAY-->>Merchant: acquiring.payment_attempt.cancelled
    end