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

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

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

​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

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