API reference

Payments

Accept cards and wallets through one unified entry point, or hand card entry to the hosted checkout page. Results arrive as signed notifications.

Methods & modes

payment_method	Direct (/payments/create)	Checkout (/payments/checkout)
`CARD`	Yes — you collect card details	Yes — customer enters card on the hosted page
`APPLE_PAY`	Yes — redirect to pay_url	Not recommended
`GOOGLE_PAY`	Yes — redirect to pay_url	Not recommended
`CASH_APP`	Yes — redirect to pay_url	Not recommended
`PAYPAL`	Yes — redirect to pay_url	Not recommended

Direct payments post everything in one call. For wallets you then redirect the customer to the returned pay_url. Checkout payments return a checkout_url where the customer enters their card.

Direct card payments put card data on your servers

Sending card.card_number and card.cvc through your backend brings your systems into PCI DSS scope. Unless you already operate a PCI-validated environment, use Checkout for cards — no card data touches your infrastructure.

Create a payment

POST/api/v1/payments/create

The unified entry point. StablePay routes the request according to payment_method. These fields apply to every method:

Field	Type	Required	Description
`payment_method`	string	Yes	One of `CARD`, `CASH_APP`, `PAYPAL`, `APPLE_PAY`, `GOOGLE_PAY`. Routes the request.
`merchant_order_no`	string	Yes	Your order number. Unique on your side; used for idempotency.
`trans_amount.currency`	string	Yes	3-letter uppercase currency, e.g. `USD`.
`trans_amount.value`	string	Yes	Amount as a decimal string, e.g. `99.99`.
`notify_url`	string	Yes	URL that receives the signed result notification.
`return_url`	string	No	Where the customer's browser returns after payment.
`trade_info.goods_name`	string	Yes	Product name.
`trade_info.description`	string	No	Product description.
`metadata`	string	No	Opaque passthrough, returned unchanged in notifications.
`client_ip`	string	No	Client IP as recorded by your server.

Direct card payment

When payment_method=CARD, add the card, billing address, device IP, and optionally browser details for risk screening.

Field	Type	Required	Description
`payer.email`	string	No	Payer email.
`payer.mobile`	string	No	Payer mobile number.
`payer.user_name`	string	No	Payer name.
`payer.user_agent`	string	No	Payer browser user agent.
`payer.ext_type`	string	No	Method-specific extra field.
`payer.payer_id`	string	No	Wallet-side payer identifier.
`card.card_number`	string	Yes	Primary account number, digits only.
`card.cardholder_name`	string	Yes	Name as printed on the card.
`card.exp_month`	int	Yes	Expiry month, 1–12.
`card.exp_year`	int	Yes	Expiry year, 4 digits.
`card.cvc`	string	Yes	CVV / CVC.
`billing_address.country`	string	Yes	2-letter country code, e.g. `US`.
`billing_address.first_name`	string	No	First name.
`billing_address.last_name`	string	No	Last name.
`billing_address.email`	string	No	Email.
`billing_address.phone`	string	No	Phone.
`billing_address.state`	string	No	State / province.
`billing_address.city`	string	No	City.
`billing_address.address`	string	No	Street address.
`billing_address.street_number`	string	No	Street number.
`billing_address.postal_code`	string	No	Postal code.
`billing_address.document`	string	No	Local document ID where required.
`shipping_address.*`	object	No	Same shape as billing_address. If provided, full shipping-address validation applies.
`device_ip`	string	Yes	Public IP of the customer's device.
`browser.accept`	string	No	Browser Accept header.
`browser.user_agent`	string	No	Browser user agent.
`browser.accept_language`	string	No	Browser language.
`browser.java_enabled`	bool	No	Whether Java is enabled.
`browser.color_depth`	string	No	Screen color depth.
`browser.screen_height`	string	No	Screen height.
`browser.screen_width`	string	No	Screen width.
`browser.time_zone_offset`	string	No	Timezone offset in minutes.
`browser.referer`	string	No	Referer.

{
  "payment_method": "CARD",
  "merchant_order_no": "M202606240001",
  "trans_amount": {
    "currency": "USD",
    "value": "99.99"
  },
  "notify_url": "https://merchant.example.com/callback/payment",
  "return_url": "https://merchant.example.com/pay/success",
  "trade_info": {
    "goods_name": "VIP Membership",
    "description": "Monthly subscription"
  },
  "metadata": "biz=member&uid=10001",
  "card": {
    "card_number": "4111111111111111",
    "cardholder_name": "JOHN DOE",
    "exp_month": 12,
    "exp_year": 2028,
    "cvc": "123"
  },
  "billing_address": {
    "country": "US",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "15551234567",
    "state": "CA",
    "city": "San Francisco",
    "address": "Market Street",
    "street_number": "1355",
    "postal_code": "94103"
  },
  "device_ip": "203.0.113.10",
  "client_ip": "203.0.113.10"
}

Direct wallet payment

For CASH_APP, PAYPAL, APPLE_PAY and GOOGLE_PAY, the only additional fields are the optional payer details. Wallet payments do not use the checkout flow.

Field	Type	Required	Description
`payer.email`	string	No	Payer email.
`payer.mobile`	string	No	Payer mobile number.
`payer.user_name`	string	No	Payer name.
`payer.user_agent`	string	No	Payer browser user agent.
`payer.ext_type`	string	No	Method-specific extra field.
`payer.payer_id`	string	No	Wallet-side payer identifier.

{
  "payment_method": "PAYPAL",
  "merchant_order_no": "M202606240003",
  "trans_amount": {
    "currency": "USD",
    "value": "49.99"
  },
  "notify_url": "https://merchant.example.com/callback/payment",
  "return_url": "https://merchant.example.com/pay/success",
  "trade_info": {
    "goods_name": "Gift Card",
    "description": "PayPal checkout"
  },
  "metadata": "src=paypal",
  "payer": {
    "email": "buyer@example.com",
    "payer_id": "PAYER123456"
  },
  "client_ip": "203.0.113.10"
}

Response

Field	Type	Description
`payment_method`	string	Payment method.
`order_no`	string	StablePay order number.
`merchant_order_no`	string	Your order number.
`status`	string	`PENDING`, `SUCCESS` or `FAILED`.
`trans_amount`	object	Amount and currency.
`psp_order_no`	string	StablePay processing reference; may be empty.
`next_action`	string	`REDIRECT`, `SUCCESS` or `FAILED`.
`pay_url`	string	Wallet redirect URL. Present when next_action is REDIRECT.
`created_at`	string	RFC 3339 creation time.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "PAYPAL",
    "order_no": "O202606240003",
    "merchant_order_no": "M202606240003",
    "status": "PENDING",
    "trans_amount": {
      "currency": "USD",
      "value": "49.99"
    },
    "psp_order_no": "SPR_PP_123456",
    "next_action": "REDIRECT",
    "pay_url": "https://wallet.example.com/redirect/pay_abc123",
    "created_at": "2026-06-24T10:03:00Z"
  }
}

When next_action is REDIRECT, send the customer to pay_url immediately.
When it is SUCCESS (possible for direct card payments), the charge is already complete — but keep handling the notification as the final record.
code=2006 means the amount is outside the current amount limits — see amount limits.

Checkout payment

POST/api/v1/payments/checkout

Creates a pending card order and returns a hosted checkout page. Compared with a direct payment there is no card, no billing_address and no device_ip — the customer enters those on the checkout page. Checkout currently supports payment_method=CARD only; use the direct endpoint for wallets.

Field	Type	Required	Description
`payment_method`	string	Yes	Must be `CARD`.
`merchant_order_no`	string	Yes	Your order number. Unique; used for idempotency.
`trans_amount`	object	Yes	`currency` and `value`, as above.
`notify_url`	string	Yes	URL that receives the signed result notification.
`return_url`	string	No	Where the customer returns after payment.
`trade_info`	object	Yes	`goods_name` (required) and `description`.
`metadata`	string	No	Opaque passthrough.
`payer`	object	No	Payer information (same fields as direct payments).
`client_ip`	string	No	Client IP.

{
  "payment_method": "CARD",
  "merchant_order_no": "M202606240002",
  "trans_amount": {
    "currency": "USD",
    "value": "49.99"
  },
  "notify_url": "https://merchant.example.com/callback/payment",
  "return_url": "https://merchant.example.com/pay/success",
  "trade_info": {
    "goods_name": "VIP Membership",
    "description": "Monthly subscription"
  },
  "metadata": "biz=member&uid=10001",
  "payer": {
    "email": "buyer@example.com"
  },
  "client_ip": "203.0.113.10"
}

Field	Type	Description
`payment_method`	string	Always CARD.
`order_no`	string	StablePay order number.
`merchant_order_no`	string	Your order number.
`status`	string	Initially `PENDING`.
`trans_amount`	object	Amount and currency.
`psp_order_no`	string	StablePay processing reference; empty until the customer pays.
`next_action`	string	`CHECKOUT_REQUIRED` — redirect the customer.
`token`	string	Checkout token.
`checkout_url`	string	Hosted checkout page URL.
`created_at`	string	RFC 3339 creation time.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CARD",
    "order_no": "O202606240002",
    "merchant_order_no": "M202606240002",
    "status": "PENDING",
    "trans_amount": {
      "currency": "USD",
      "value": "49.99"
    },
    "psp_order_no": "",
    "next_action": "CHECKOUT_REQUIRED",
    "token": "ck_5c4f0f53c0e94d11",
    "checkout_url": "https://cashier.example.com/pay/ck_5c4f0f53c0e94d11",
    "created_at": "2026-06-24T10:05:00Z"
  }
}

Redirect the customer to checkout_url. After payment they return to return_url and the result is posted to notify_url.

Query a payment

POST/api/v1/payments/query

Provide exactly one identifier.

Field	Type	Required	Description
`order_no`	string	One of two	StablePay order number.
`merchant_order_no`	string	One of two	Your order number.

{
  "merchant_order_no": "M202606240001"
}

Field	Type	Description
`payment_method`	string	Payment method.
`order_no`	string	StablePay order number.
`merchant_order_no`	string	Your order number.
`status`	string	`PENDING`, `SUCCESS` or `FAILED`.
`trans_amount`	object	Amount and currency.
`paid_at`	string	Payment completion time.
`created_at`	string	Creation time.
`psp_order_no`	string	StablePay processing reference.
`masked_card_number`	string	e.g. `411111******1111`. Usually empty for wallets.
`trade_info`	object	Product information as submitted.
`metadata`	string	Your passthrough value.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CARD",
    "order_no": "O202606240001",
    "merchant_order_no": "M202606240001",
    "status": "SUCCESS",
    "trans_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "paid_at": "2026-06-24T10:01:23Z",
    "created_at": "2026-06-24T10:00:00Z",
    "psp_order_no": "SPR_123456",
    "masked_card_number": "411111******1111",
    "trade_info": {
      "goods_name": "VIP Membership",
      "description": "Monthly subscription"
    },
    "metadata": "biz=member&uid=10001"
  }
}

Query is for reconciliation

Notifications are the source of truth for status changes. Use query to reconcile, to recover after downtime, or when a notification has not arrived in the expected window.