Hosted Checkout Integration Guide

Hosted Checkout lets you redirect customers to a UseePay-hosted payment page. Your server creates a PaymentIntent and receives a cashier URL — no payment UI to build.

How It Works

Step 1 — Create a PaymentIntent

Call POST /payment_intents from your server with the payment details.

Request

Response

{
  "id": "pi_1234567890",
  "status": "requires_payment_method",
  "nextAction": {
      "type": "redirect",
      "redirect": {
          "url" : ""https://cashier.useepay.com/pay?token=xxx"
      }
  },
  "clientSecret": "pi_1234567890_secret_xxx",
  "amount": 1000,
  "currency": "USD"
}

Step 2 — Redirect the Customer

Redirect the customer to cashierUrl returned in the PaymentIntent response.

The customer will see UseePay's hosted payment page with the payment methods you specified. UseePay handles:

Card number input and validation

3DS authentication

Apple Pay / Google Pay wallet sheets

Payment result display

Step 3 — Handle the Return

After payment, UseePay redirects the customer to your returnUrl with the result appended as query parameters.

https://yoursite.com/payment/result?payment_intent=pi_1234567890&redirect_status=succeeded

Parameter	Value	Description
`payment_intent`	`pi_xxx`	PaymentIntent ID
`redirect_status`	`succeeded` / `failed` / `canceled`	Payment outcome

⚠️ Do not rely solely on the redirect to confirm payment. Always verify the final status server-side via Webhook or by querying the PaymentIntent.

Verify via API

Step 4 — Receive Webhook Events

Configure a Webhook endpoint in your Merchant Dashboard to receive real-time payment notifications.

Key events

Event	Description
`payment_intent.succeeded`	Payment completed successfully
`payment_intent.payment_failed`	Payment failed
`payment_intent.requires_capture`	Auth succeeded, awaiting capture (manual mode)
`payment_intent.canceled`	Payment canceled

Webhook payload example

{
  "event": "payment_intent.succeeded",
  "data": {
    "id": "pi_1234567890",
    "status": "succeeded",
    "amount": 1000,
    "currency": "USD",
    "merchantOrderId": "ORDER_20240101_001"
  }
}

Optional — Auth + Capture (Two-Step Payment)

Set captureMethod: "manual" to authorize the card without charging. Capture later when you are ready to fulfill the order.

The authorization hold expires if not captured within the allowed window. Capture as soon as you confirm fulfillment.

PaymentIntent Status Lifecycle

requires_payment_method
        │
        ▼
requires_confirmation
        │
        ▼
  requires_action  ──── (3DS / wallet auth) ────┐
        │                                        │
        ▼                                        │
requires_capture (manual mode)                  │
        │                                        │
        ▼                                        │
    succeeded  ◄────────────────────────────────┘
        
    canceled / failed  (terminal states)

Supported Payment Methods

Payment Method	Type	Regions
Credit / Debit Card	Card	Global
Apple Pay	Wallet	iOS / macOS Safari
Google Pay	Wallet	Android / Chrome
Klarna	BNPL	EU, US, AU
Affirm	BNPL	US
Naver Pay	Local wallet	South Korea
Kakao Pay	Local wallet	South Korea
Toss Pay	Local wallet	South Korea
Payco	Local wallet	South Korea
Blik	Local payment	Poland
Trustly	Bank transfer	EU
CashApp	Wallet	US
Pay with Link	Saved cards	Global

Quick Checklist

Obtain API keys from the Merchant Dashboard

Call POST /payment_intents from your server (never from the browser)

Redirect customer to cashierUrl

Implement returnUrl handler to show result page

Set up Webhook endpoint and verify payment server-side

Test with test card numbers before going live

Hosted Checkout Integration Guide

How It Works#

Step 1 — Create a PaymentIntent#

Step 2 — Redirect the Customer#

Step 3 — Handle the Return#

Step 4 — Receive Webhook Events#

Optional — Auth + Capture (Two-Step Payment)#

PaymentIntent Status Lifecycle#

Supported Payment Methods#

Quick Checklist#