---
title: "Start a provider-agnostic checkout"
method: POST
path: "/v2/payments/checkout"
tags: ["Payments"]
---

# Start a provider-agnostic checkout

`POST /v2/payments/checkout`

Returns either embedded-SDK config (FunnelFox) or a hosted payment page redirect (Unlimit), discriminated by `mode`.

## Request body

- CreateCheckoutDto
  - `purpose` 'subscription' | 'coins' | 'card_update', required
  - `productId` string — What to buy: provider price point id for subscriptions, web coin productId for coins. Not required for card_update.
  - `returnPath` string — Relative frontend path to return the user to after a redirect payment.
  - `customerEmail` string — Buyer email captured client-side (funnel store). Last-resort fallback when the user record has no email yet — anonymous funnel users are provisioned after the funnel email sync ran.
  - `funnelId` string — Funnel the checkout was started from (the `/ob/:funnelId` segment). Upgate resolves the payment methods it asks for per funnel (UPGATE_CHECKOUT_METHODS_BY_FUNNEL) — omitted (in-app surfaces) means the default set. Ignored by the other providers.
  - `wallets` CheckoutWalletHintsDto
    - `applePay` boolean — Device can run Apple Pay (`ApplePaySession.canMakePayments()`).
    - `googlePay` boolean — Device can run Google Pay. Only an explicit `false` has an effect (drops GOOGLE_PAY).

## Response `200`

- CheckoutResponseDto
  - `provider` 'funnelfox' | 'unlimit' | 'upgate', required
  - `mode` 'embedded' | 'redirect', required
  - `pricePointIdent` string — FunnelFox price point to mount the embedded SDK with.
  - `orderId` string — Payment order id (redirect mode / upgate).
  - `redirectUrl` string — Hosted payment page URL to redirect the user to.
  - `checkoutUrl` string — Upgate checkout session URL — the embedded payment element mounts with it (also works as a hosted page).
  - `availableMethods` string[] — Payment methods the Upgate form will render ('CARD', 'APPLE_PAY', …), as the gateway echoed them. Upgate silently drops methods disabled on the merchant account, so this — not the requested list — tells whether the buyer is offered a wallet. Absent for the other providers.

---

[API](https://skmtc.dev/miaai/apis/backend-template-api.md) · [All operations](https://skmtc.dev/miaai/apis/backend-template-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/miaai/backend-template-api/revisions/2a8d88a5124f/schema)