SETSimple Easy Transactions
SET DocsAPI reference and complianceUpdated 2026-11-09
Browse: SET Merchant API

SET Merchant API · Card payments

Open a card checkout

POST/v1/card_checkouts

Key scope: write · Success: 201

A Stripe-hosted Checkout for one card (or Stripe bank debit) payment on the merchant's own SET Connect account, with SET's fee as the application fee. Send the payer to url.

Headers

Idempotency-Key string
Optional. The same key and body run once; a replay answers with Idempotent-Replayed: true. Kept 24 hours.

Body

amount decimal stringrequired
USD, 0.50 to 999,999.99.
successUrl https URLrequired
Where the payer lands after paying.
cancelUrl https URLrequired
Where the payer lands on cancel.
description string
Shown on the Checkout.
reference string
Passed to Stripe's metadata only; SET does not store it.

Notes

  • The payment appears in GET /v1/card_payments with checkoutSession set to this id. Events: card_payment.<state>, card_payment.refunded, card_payment.fee_refunded, card_payment.dispute.<status>.
  • Only payments SET started (this call, or the merchant's embedded payment form) are recorded; the merchant's other Stripe business is never read into SET.

Errors

  • 400 amount_invalid
  • 400 url_invalid
  • 400 description_invalid
  • 400 reference_invalid
  • 403 card_payments_merchant_only
  • 409 set_connect_not_linked
  • 409 set_connect_not_ready
  • 502 stripe_unavailable
  • 503 set_connect_unavailable
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.