Direct API Integration

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:

Direct payment
Delayed confirmation

Include payment_method in the creation request. The payment processes immediately.

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

Create a PI without a payment method first:

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:

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

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.
`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

{
  "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,
    "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:

{
  "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:

QR code display

For e-wallet payments (AlipayCN, WeChatPay, etc.), next_action may contain a QR code:

{
  "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 — payment completed
acquiring.payment_attempt.failed — 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 — capture submitted. Receiving this event also indicates the payment has succeeded.

Retrieve API (polling)

Query the payment status directly:

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

E-wallet payments

The same API supports e-wallet payment methods. Replace the payment_method object with the appropriate wallet type:

AlipayCN QR code example

{
  "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.

AlipayCN payment code example (in-person)

{
  "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.

Pre-authorization and manual capture

Before using pre-authorization, confirm that your account and payment channel support it. Use the direct API with card or card_present; Hosted Payment Page and Payment Links do not support pre-authorization.

Set authorization_type to pre_authorization when you create or confirm the PaymentIntent. Set payment_method.card.auto_capture or payment_method.card_present.auto_capture to false. If you also provide the authorization type inside the payment method, both values must match. A pre-authorized PaymentIntent cannot be changed to ordinary authorization at confirmation.
After authorization, inspect intent_status, authorization_expires_at, and available_to_capture. Capture while the PaymentIntent is REQUIRES_CAPTURE and before the returned expiry. Do not assume a fixed authorization period.
Capture the PaymentIntent once. Omit final_capture or set it to true; false is rejected. Omit amount_to_capture to capture the available amount, or supply a positive amount up to that balance. Partial final capture requires channel support. Zero, empty, and null amounts are rejected. The system handles any remaining authorization release; do not send a second capture or a zero-amount capture to release it.
Keep the returned capture_id and merchant_capture_order_id. Retrieve the PaymentIntent to inspect capture_records. Capture acceptance and the PaymentIntent aggregate amount do not establish channel completion. Each record has a channel_capture_status: 0 pending, 1 processing, 2 completed, or 3 failed.

For ordinary authorization with manual capture, the capture amount must equal the full authorized amount. Pre-authorization is the flow that permits a smaller final amount when supported.

Capture references and retries

Use an account-unique merchant_capture_order_id of at most 64 characters. If omitted, it defaults to the PaymentIntent’s merchant_order_id. Keep the same X-Idempotency-Key when retrying an identical request after a transport failure. A recorded capture reference submitted again outside the cached response is rejected, not executed as another capture. Query the existing PaymentIntent to determine the result before taking further action. A failed capture does not permit another capture against the same authorization.

Cancellation and refunds

Before any capture, you can cancel an unexpired pre-authorization when the channel supports cancellation. After capture, use the refund flow for captured funds. A positive available_to_void value alone does not establish cancellation eligibility. PaymentIntent captured_amount is the aggregate capture amount; PaymentAttempt has no capture-amount field. Use capture_records[].capture_amount and the associated processing status for individual captures.

Getting Started

Accept Payments

Manage Payments

Testing

Reference

Step 1: Create a Payment Intent

Step 2: Handle the response

Successful response example

Step 3: Handle customer actions

3DS redirect

QR code display

Step 4: Get payment results

Webhooks (recommended)

Retrieve API (polling)

E-wallet payments

Pre-authorization and manual capture

Capture references and retries

Cancellation and refunds

​Step 1: Create a Payment Intent

​Step 2: Handle the response

​Successful response example

​Step 3: Handle customer actions

​3DS redirect

​QR code display

​Step 4: Get payment results

​Webhooks (recommended)

​Retrieve API (polling)

​E-wallet payments

​Pre-authorization and manual capture

​Capture references and retries

​Cancellation and refunds

Step 1: Create a Payment Intent

Step 2: Handle the response

Successful response example

Step 3: Handle customer actions

3DS redirect

QR code display

Step 4: Get payment results

Webhooks (recommended)

Retrieve API (polling)

E-wallet payments

Pre-authorization and manual capture

Capture references and retries

Cancellation and refunds