> ## 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.
# Direct API Integration
> Accept card payments by creating payment intents and handling payment attempts directly via the UQPAY API.
This guide walks you through a complete card-not-present (online) payment flow using the direct API integration. You create a Payment Intent, handle authentication if required, and receive the payment result.
## Step 1: Create a Payment Intent
There are two approaches depending on when the payment method is available:
Include `payment_method` in the creation request. The payment processes immediately.
```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create \
-H "Content-Type: application/json" \
-H "x-auth-token: Bearer {your_access_token}" \
-H "x-client-id: {your_client_id}" \
-H "x-idempotency-key: $(uuidgen)" \
-d '{
"amount": "8.98",
"currency": "SGD",
"payment_method": {
"type": "card",
"card": {
"card_name": "UQPAY",
"card_number": "5346930100108117",
"expiry_month": "12",
"expiry_year": "2026",
"cvc": "811",
"network": "mastercard",
"billing": {
"first_name": "UQPAY",
"last_name": "ACQ",
"email": "acq@uqpay.com",
"phone_number": "0524-91353515",
"address": {
"country_code": "SG",
"state": "Singapore",
"city": "Singapore",
"street": "444 Orchard Rd, Midpoint Orchard, Singapore",
"postcode": "924011"
}
},
"auto_capture": true,
"authorization_type": "authorization",
"three_ds_action": "skip_3ds"
}
},
"merchant_order_id": "order-001",
"description": "Test payment",
"metadata": {},
"return_url": "https://example.com/callback"
}'
```
**API reference:** [Create Payment Intent](/global-acquiring/v1.6/api-reference/create-payment-intent)
Create a PI without a payment method first:
```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create \
-H "Content-Type: application/json" \
-H "x-auth-token: Bearer {your_access_token}" \
-H "x-client-id: {your_client_id}" \
-H "x-idempotency-key: $(uuidgen)" \
-d '{
"amount": "8.98",
"currency": "SGD",
"merchant_order_id": "order-002",
"description": "Test payment",
"metadata": {},
"return_url": "https://example.com/callback"
}'
```
The PI is created with `intent_status: "REQUIRES_PAYMENT_METHOD"`. You can optionally update the PI (amount, currency, etc.) before confirming.
Then confirm with a payment method:
```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v2/payment_intents/{payment_intent_id}/confirm \
-H "Content-Type: application/json" \
-H "x-auth-token: Bearer {your_access_token}" \
-H "x-client-id: {your_client_id}" \
-H "x-idempotency-key: $(uuidgen)" \
-d '{
"payment_method": {
"type": "card",
"card": {
"card_name": "UQPAY",
"card_number": "5346930100108117",
"expiry_month": "12",
"expiry_year": "2026",
"cvc": "811",
"network": "mastercard",
"billing": {
"first_name": "UQPAY",
"last_name": "ACQ",
"email": "acq@uqpay.com",
"phone_number": "0524-91353515",
"address": {
"country_code": "SG",
"state": "Singapore",
"city": "Singapore",
"street": "444 Orchard Rd, Midpoint Orchard, Singapore",
"postcode": "924011"
}
},
"auto_capture": true,
"authorization_type": "authorization",
"three_ds_action": "skip_3ds"
}
}
}'
```
**API reference:** [Confirm Payment Intent](/global-acquiring/v1.6/api-reference/confirm-payment-intent)
## Step 2: Handle the response
Check the `intent_status` field in the response to determine what to do next:
| `intent_status` | Action |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCCEEDED` | Payment complete. Update your order status. |
| `REQUIRES_CUSTOMER_ACTION` | The customer needs to complete an additional step (e.g., 3DS verification). See [Handle customer actions](#step-3-handle-customer-actions). |
| `REQUIRES_PAYMENT_METHOD` | The payment attempt failed. Prompt the customer to try another payment method or card. |
| `PENDING` | Payment is processing. Wait for the webhook notification. |
### Successful response example
```json theme={null}
{
"amount": 8.98,
"currency": "SGD",
"intent_status": "SUCCEEDED",
"payment_intent_id": "PI1933438751883661312",
"latest_payment_attempt": {
"attempt_id": "PA1933438751988518912",
"attempt_status": "CAPTURE_REQUESTED",
"amount": 8.98,
"captured_amount": 8.98,
"complete_time": "2025-06-13T16:18:14+08:00"
},
"merchant_order_id": "order-001"
}
```
## Step 3: Handle customer actions
When `intent_status` is `REQUIRES_CUSTOMER_ACTION`, the `next_action` field tells you what the customer needs to do.
### 3DS redirect
If the card requires 3D Secure authentication, `next_action` contains a redirect URL:
```json theme={null}
{
"next_action": {
"redirect_to_url": {
"return_url": "",
"url": "https://checkout-sandbox.uqpaytech.com/secure/..."
},
"type": "redirect_to_url"
}
}
```
Redirect the customer to the URL. After they complete 3DS, they are redirected to your `return_url`. For detailed 3DS integration guidance, see:
* [3DS Integration Guide - Option 1](/global-acquiring/v1.6/guide/3ds-integration-guide-option-1)
* [3DS Integration Guide - Option 2](/global-acquiring/v1.6/guide/3ds-integration-guide-option-2)
### QR code display
For e-wallet payments (AlipayCN, WeChatPay, etc.), `next_action` may contain a QR code:
```json theme={null}
{
"next_action": {
"display_qr_code": {
"qr_code": "https://global.alipay.com/281002040092rZoN1k6ln7O91r9fwjb2tUo2",
"qr_code_url": "https://global.alipay.com/merchant/order/showQrImage.htm?code=...",
"expires_at": "2025-06-19T14:38:59.563+08:00"
}
}
}
```
Display the QR code to the customer and wait for them to scan and confirm payment in their wallet app.
## Step 4: Get payment results
Use one or both of these methods to confirm the final payment status:
### Webhooks (recommended)
Configure your server to receive asynchronous notifications from UQPAY. This is the most reliable method.
Key webhook events:
* [`acquiring.payment_intent.succeeded`](/global-acquiring/v1.6/webhooks/paymentintent-result) — payment completed
* [`acquiring.payment_attempt.failed`](/global-acquiring/v1.6/webhooks/paymentattempt-result) — payment attempt failed. Note: `acquiring.payment_intent.failed` is only triggered when the PI times out and auto-closes (30-minute expiry), not on individual attempt failures.
* [`acquiring.payment_attempt.capture_requested`](/global-acquiring/v1.6/webhooks/paymentattempt-result) — capture submitted. Receiving this event also indicates the payment has succeeded.
### Retrieve API (polling)
Query the payment status directly:
```bash theme={null}
curl https://api-sandbox.uqpaytech.com/api/v2/payment_intents/{payment_intent_id} \
-H "x-auth-token: Bearer {your_access_token}" \
-H "x-client-id: {your_client_id}"
```
**API reference:** [Retrieve Payment Intent](/global-acquiring/v1.6/api-reference/retrieve-payment-intent)
## E-wallet payments
The same API supports e-wallet payment methods. Replace the `payment_method` object with the appropriate wallet type:
```json theme={null}
{
"amount": "7.77",
"currency": "SGD",
"payment_method": {
"type": "alipaycn",
"alipaycn": {
"flow": "qrcode",
"is_present": false
}
},
"merchant_order_id": "order-alipay-001",
"description": "Alipay test",
"metadata": {},
"return_url": "https://example.com/callback"
}
```
The response will contain `next_action.display_qr_code` for the customer to scan.
```json theme={null}
{
"amount": "1.11",
"currency": "SGD",
"payment_method": {
"type": "alipaycn",
"alipaycn": {
"flow": "qrcode",
"os_type": "ios",
"is_present": true,
"payment_code": "284057804613761079"
}
},
"merchant_order_id": "order-alipay-002",
"description": "Alipay payment code test",
"metadata": {},
"return_url": "https://example.com/callback"
}
```
Payment code transactions complete immediately when the code is valid.
For a full list of supported payment methods and their parameters, see [Payment methods](/global-acquiring/v1.6/guide/payment-methods).