跳转到主要内容
POST
/
v2
/
payment_intents
/
create
Create a PaymentIntent
curl --request POST \
  --url https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <api-key>' \
  --header 'x-client-id: <x-client-id>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "amount": "10.12",
  "currency": "SGD",
  "merchant_order_id": "<string>",
  "description": "<string>",
  "return_url": "<string>",
  "payment_method": {
    "card": {
      "card_name": "<string>",
      "card_number": "<string>",
      "expiry_month": "<string>",
      "expiry_year": "<string>",
      "cvc": "<string>",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "address": {
          "country_code": "SG",
          "city": "Singapore",
          "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
          "postcode": "924011",
          "state": ""
        },
        "phone_number": "12025550123"
      },
      "auto_capture": false,
      "three_ds": {
        "return_url": "<string>",
        "acs_response": "<string>",
        "device_data_collection_res": "<string>",
        "ds_transaction_id": "<string>"
      }
    }
  },
  "ip_address": "212.121.222.123",
  "customer_id": "cus_asyknf3wlfxhs1s6plamk80i8v",
  "payment_orders": {
    "type": "physical_goods",
    "products": [
      {
        "name": "<string>",
        "price": "<string>",
        "quantity": 123,
        "image_url": "<string>"
      }
    ]
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}
'
{
  "payment_intent_id": "b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6",
  "amount": "10.12",
  "currency": "SGD",
  "description": "<string>",
  "available_payment_method_types": [
    "<string>"
  ],
  "captured_amount": "10.12",
  "customer": {
    "id": "cus_hkduz3gvz1feg25e87fjcahsxq",
    "external_customer_id": "CUS_1715740800123",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1 123456789",
    "address": {
      "country_code": "SG",
      "city": "Singapore",
      "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
      "postcode": "924011",
      "state": ""
    },
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "create_time": "2025-03-21T17:17:32+08:00",
    "update_time": "2025-03-21T17:17:32+08:00"
  },
  "customer_id": "cus_asyknf3wlfxhs1s6plamk80i8v",
  "cancel_time": "2024-03-01T00:00:00+08:00",
  "cancellation_reason": "Order cancelled",
  "client_secret": "eyJhbGciOiJI***********ujNdZ1DF9CqWEfF1jphxI",
  "merchant_order_id": "1bf70d90-9ed0-48ce-9370-9bd7ef6ab9ee",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "next_action": {
    "redirect_to_url": {
      "url": "https://example.checkout-page.com",
      "return_url": "https://example.payment-result-page.com"
    },
    "redirect_iframe": {
      "iframe": "<string>"
    },
    "display_qr_code": {
      "qr_code_url": "https://sg-acquiring-bucket-sandbox.s3.ap-southeast-1.amazonaws.com/payment/20250829/qrcode_PA1961262701099356160?X-Amz-Algorithm=AWS4-HMAC-SHA256\\u0026X-Amz-Credential=ASIAY******f987429",
      "expires_at": "2023-11-07T05:31:56Z"
    },
    "display_bank_details": {
      "bank_name": "<string>",
      "account_number": "GB71950018692652646598",
      "routing_number": "012345678"
    }
  },
  "return_url": "https://127.0.0.1:8080/api/v1/callback",
  "create_time": "2024-03-01T00:00:00+08:00",
  "complete_time": "2024-03-01T00:00:00+08:00",
  "update_time": "2024-03-01T00:00:00+08:00",
  "latest_payment_attempt": {
    "attempt_id": "24fc62b4-90d1-42e3-96ab-dd54ccc648b3",
    "amount": "9.98",
    "currency": "SGD",
    "captured_amount": "0.00",
    "refunded_amount": "0.00",
    "create_time": "2025-03-21T17:17:32+08:00",
    "update_time": "2025-03-21T17:17:32+08:00",
    "complete_time": "2024-03-01T00:00:00+08:00",
    "cancellation_reason": "Order cancelled",
    "auth_code": "A12B3C",
    "arn": "74537604221222132710572",
    "rrn": "123456789012",
    "advice_code": "01",
    "authentication_data": {
      "avs_result": "Y",
      "three_ds": {
        "three_ds_version": "2.2.0",
        "eci": "05",
        "cavv": "AAABCZIhcQAAAABZlyFxAAAAAAA=",
        "three_ds_authentication_status": "Y",
        "three_ds_cancellation_reason": "01"
      }
    },
    "payment_method": {
      "card": {
        "card_name": "john doe",
        "card_number": "541333******4047",
        "brand": "visa",
        "bin": "541333",
        "last4": "4047",
        "expiry_month": "12",
        "expiry_year": "2027",
        "billing": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "address": {
            "country_code": "SG",
            "city": "Singapore",
            "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
            "postcode": "924011",
            "state": ""
          },
          "phone_number": "12025550123"
        },
        "auto_capture": true
      }
    },
    "failure_code": "",
    "attempt_status": "INITIATED"
  }
}

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.

授权

​
x-auth-token
string
header
必填

The API token for login provided by UQPay.

请求头

​
x-on-behalf-of
string

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

​
x-idempotency-key
string<uuid>
必填

A unique identifier (UUID) used to maintain operation idempotency, ensuring that repeated executions of the same operation do not result in unintended effects or duplication. It helps preserve data consistency in the face of network errors, retries, or failures.

​
x-client-id
string
必填

The API client id generated by UQPAY

请求体

application/json
​
amount
string
必填

Amount intended to be collected by this PaymentIntent.

示例:

"10.12"

​
currency
string
必填

Three-letter currency code

示例:

"SGD"

​
merchant_order_id
string
必填

The merchant reference id created in merchant's system that corresponds to this PaymentIntent

Maximum string length: 36
​
description
string
必填

Descriptor that will display to the customer. Maximum length is 32.

Maximum string length: 32
​
return_url
string
必填

The web page URL or application scheme URI to redirect the customer after payment authentication.

Maximum string length: 1024
​
payment_method
card · object

The payment method details to confirm the PaymentIntent. The PaymentIntent will be confirmed automatically when payment_method is set.

​
ip_address
string

IPv4 or IPv6 address of the device.

Required when payment_method.card.three_ds_action=enforce_3ds. Optional otherwise.

Maximum string length: 45
示例:

"212.121.222.123"

​
customer
object

Inline customer details. Supply this on the first PaymentIntent for a shopper to enable Card on File on the hosted payment page. UQPay creates a customer record using these details and returns the resulting customer_id in the response. Ignored when customer_id is also supplied — see customer_id for precedence rules.

​
customer_id
string

ID of an existing UQPay customer returned by a previous Create PaymentIntent call. Pass this on subsequent payments for the same shopper so the hosted payment page can offer their saved cards. When both customer_id and customer are supplied, customer_id takes precedence. Leave empty for guest checkout (the PaymentIntent will not participate in Card on File).

Maximum string length: 36
示例:

"cus_asyknf3wlfxhs1s6plamk80i8v"

​
payment_orders
object

Purchase order related to this PaymentIntent

​
browser_info
object

Browser information collected for risk and fraud prevention. Required when three_ds_action=enforce_3ds

​
metadata
object

Any key-value object. Max length = 512 bytes. This must be valid JSON data.

示例:
{ "key1": "value1", "key2": "value2" }

响应

200 - application/json

Payment intent created successfully

​
payment_intent_id
string
必填

Unique identifier for the PaymentIntent

Maximum string length: 36
示例:

"b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6"

​
amount
string
必填

Payment amount. This is the order amount you would like to charge your customer.

示例:

"10.12"

​
currency
string
必填

Three-letter currency code

示例:

"SGD"

​
intent_status
enum<string>
必填

Status of this PaymentIntent.

可用选项:
REQUIRES_PAYMENT_METHOD,
REQUIRES_CUSTOMER_ACTION,
REQUIRES_CAPTURE,
PENDING,
SUCCEEDED,
CANCELLED,
FAILED
​
description
string

Descriptor while creating a PaymentIntent.

Maximum string length: 255
​
available_payment_method_types
string[] | null

Available payment method types for this PaymentIntent.

​
captured_amount
string

Amount that captured from this PaymentIntent.

示例:

"10.12"

​
customer
object

Snapshot of the customer associated with this PaymentIntent. Returned when customer or customer_id was supplied at creation time. The customer's unique identifier is exposed at the top level as customer_id; the id field is not included inside this object.

​
customer_id
string

ID of the customer associated with this PaymentIntent. Empty for guest checkout.

Maximum string length: 36
示例:

"cus_asyknf3wlfxhs1s6plamk80i8v"

​
cancel_time
string<date/time>

Last time at which this PaymentIntent was cancelled. Only present when the PaymentIntent was successfully cancelled, i.e. status is CANCELLED.

示例:

"2024-03-01T00:00:00+08:00"

​
cancellation_reason
string

Reason for canceling this PaymentIntent.

示例:

"Order cancelled"

​
client_secret
string

PaymentIntent's client secret for browser or app. Returned by PaymentIntent create API or PaymentIntent retrieve API. The provided client_secret is valid for 60 minutes.

示例:

"eyJhbGciOiJI***********ujNdZ1DF9CqWEfF1jphxI"

​
merchant_order_id
string

The merchant reference id created in merchant's system that corresponds to this PaymentIntent

Maximum string length: 36
示例:

"1bf70d90-9ed0-48ce-9370-9bd7ef6ab9ee"

​
metadata
object

Any key-value object. Max length = 512 bytes. This must be valid JSON data.

示例:
{ "key1": "value1", "key2": "value2" }
​
next_action
object

If present, this property tells you what actions you need to take in order for your customer to fulfill a payment using the provided source.

​
return_url
string

The web page URL or application scheme URI to redirect the customer after payment authentication.

示例:

"https://127.0.0.1:8080/api/v1/callback"

​
create_time
string<date/time>

Time at which this PaymentIntent was created.

示例:

"2024-03-01T00:00:00+08:00"

​
complete_time
string<date/time>

Time at which this PaymentIntent reached its final state.

示例:

"2024-03-01T00:00:00+08:00"

​
update_time
string<date/time>

Last time at which this PaymentIntent was updated or operated on.

示例:

"2024-03-01T00:00:00+08:00"

​
latest_payment_attempt
object

Latest PaymentAttempt that was created under the PaymentIntent.