POST
/
api
/
v1
/
payment-sessions
Create a payment session
curl --request POST \
  --url https://api.switchflows.net/api/v1/payment-sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "amountMinor": 123,
  "currency": "<string>",
  "orderRef": "<string>",
  "customerEmail": "<string>"
}
'
{
  "sessionId": "<string>",
  "clientSecret": "<string>",
  "status": "<string>",
  "expiresAt": {},
  "vault": {}
}
Creates a payment session for one checkout. Call this from your backend when the customer reaches your payment step, then pass the returned sessionId, clientSecret, and vault block to the widget.

​
Request

curl https://api.switchflows.net/api/v1/payment-sessions \
  -X POST \
  -H "Authorization: Bearer $SWITCHFLOW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c2f6a-6d1e-4b3a-9e64-1f2ab33c9d10" \
  -d '{
    "amountMinor": 4900,
    "currency": "USD",
    "orderRef": "ORDER-10023",
    "customerEmail": "buyer@example.com"
  }'
​
amountMinor
integer
required
Amount in minor units (e.g. 4900 = 49.00). Must be a positive integer.
​
currency
string
required
ISO 4217 alpha-3 currency code, e.g. "USD".
​
orderRef
string
required
Your order reference. Echoed on the session, in webhooks, and in the dashboard — use it to correlate SwitchFlow events with your orders.
​
customerEmail
string
The paying customer’s email.
​
Idempotency-Key
string
Optional but strongly recommended. Retrying with the same key returns the original session instead of creating a duplicate.

​
Response

{
  "sessionId": "ps_1a2b3c4d",
  "clientSecret": "ps_1a2b3c4d_secret_e5f6g7h8",
  "status": "CREATED",
  "expiresAt": "2026-07-06T11:12:31Z",
  "vault": {
    "mode": "saas",
    "publishableKey": "pk_snd_...",
    "profileId": "pro_...",
    "sdkAuthorization": "...",
    "sdkUrl": "https://..."
  }
}
​
sessionId
string
Session identifier — pass to the widget; use it to query status later.
​
clientSecret
string
Single-session credential for the widget. Deliver it to your checkout page; never log it.
​
status
string
CREATED on creation. Later transitions: SUCCEEDED, DECLINED, DEGRADED, EXPIRED.
​
expiresAt
string (ISO 8601)
When the session stops accepting submission. Create a fresh session if the customer returns after expiry.
​
vault
object
Tokenization configuration for the widget. Pass it to SwitchFlow.mount() verbatim — its fields vary by vault mode and you should treat it as opaque. See widget reference.