Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
Payment Intents

Create a PaymentIntent

Creates a new payment intent to process a payment. After the PaymentIntent is created, attach a payment method and confirm API to continue the payment.

post/v2/payment_intents/create

Headers

x-on-behalf-ofstring

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 API. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

x-idempotency-keystring 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-idstring required

The API client id generated by UQPAY

Request body

amountstring required
currencystring required

Three-letter currency code

ip_addressstring

IPv4 or IPv6 address of the device.

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

customer_idstring

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

merchant_order_idstring required

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

descriptionstring required

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

metadataMetadata

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

return_urlstring required

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

Example request

{
  "payment_method": {
    "card": {
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "12025550123",
        "address": {
          "country_code": "SG",
          "city": "Singapore",
          "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
          "postcode": "924011"
        }
      }
    }
  },
  "ip_address": "212.121.222.123",
  "customer": {
    "business_name": "Acme Corp",
    "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"
    },
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "customer_id": "cus_asyknf3wlfxhs1s6plamk80i8v",
  "payment_orders": {
    "type": "physical_goods"
  },
  "browser_info": {
    "accept_header": "*/*",
    "browser": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
    },
    "device_id": "00000000-000000000000000",
    "language": "en-US",
    "location": {
      "lat": "-37.81892",
      "lon": "144.95913"
    },
    "mobile": {
      "device_model": "Apple IPHONE 7",
      "os_version": "IOS 14.5"
    },
    "screen_color_depth": 24,
    "screen_height": 1080,
    "screen_width": 1920,
    "timezone": "-2"
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

Response

Payment intent created successfully

payment_intent_idstring required

Unique identifier for the PaymentIntent

amountstring required
currencystring required

Three-letter currency code

descriptionstring

Descriptor while creating a PaymentIntent.

available_payment_method_typesstring[] nullable

Available payment method types for this PaymentIntent.

captured_amountstring
customer_idstring

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

cancel_timestring date/time
cancellation_reasonstring

Reason for canceling this PaymentIntent.

client_secretstring

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.

merchant_order_idstring

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

metadataMetadata

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

return_urlstring

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

create_timestring date/time
complete_timestring date/time
update_timestring date/time
intent_status'REQUIRES_PAYMENT_METHOD' | 'REQUIRES_CUSTOMER_ACTION' | 'REQUIRES_CAPTURE' | 'PENDING' | 'SUCCEEDED' | 'CANCELLED' | 'FAILED' required

Status of this PaymentIntent.

  • REQUIRES_PAYMENT_METHOD: The PaymentIntent is waiting for the confirm request.
  • REQUIRES_CUSTOMER_ACTION: The PaymentIntent is waiting for further customer action of authentication, e.g. 3DS verification and QR code scan. Please check the next_action.
  • REQUIRES_CAPTURE: The PaymentIntent is waiting for your capture to complete the payment.
  • PENDING: The PaymentIntent is pending the final result from the provider. No further action is required.
  • SUCCEEDED: The PaymentIntent has succeeded. The payment is complete.
  • CANCELLED: The PaymentIntent has been canceled by your request. The payment is closed.
  • FAILED: The PaymentIntent has failed.

Example response

{
  "payment_intent_id": "b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6",
  "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"
    },
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "create_time": "2024-03-01T00:00:00+08:00",
    "update_time": "2024-03-01T00:00:00+08:00"
  },
  "customer_id": "cus_asyknf3wlfxhs1s6plamk80i8v",
  "cancel_time": "2024-03-01T00:00:00+08:00",
  "cancellation_reason": "Order cancelled",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "next_action": {
    "redirect_to_url": {
      "url": "https://example.checkout-page.com",
      "return_url": "https://example.payment-result-page.com"
    },
    "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"
    },
    "display_bank_details": {
      "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",
    "create_time": "2024-03-01T00:00:00+08:00",
    "update_time": "2024-03-01T00:00:00+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",
          "phone_number": "12025550123",
          "address": {
            "country_code": "SG",
            "city": "Singapore",
            "street": "444 Orchard Rd, Midpoint Orchard, Singapore ",
            "postcode": "924011"
          }
        }
      }
    },
    "attempt_status": "INITIATED"
  }
}