Checkout Sessions

Checkout sessions let you create a hosted payment page with a shareable URL. You create a session with an amount and currency, then redirect your customer to the generated URL — or email it to them — to collect payment.

Checkout session lifecycle

Create a checkout session — a payment URL is generated
Redirect (or email) the customer to the URL
The customer completes payment on the hosted page
The session transitions to COMPLETE and a checkout_session.paid webhook is sent

Sessions expire after 24 hours if not completed.

Creating a checkout session

API reference

The Idempotency-Key header lets you safely retry the request if it fails — see Idempotency.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/checkout-sessions \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000",
    "currency": "GBP",
    "client_reference_id": "order_12345",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

Response

{
  "name": "accounts/acct_YOUR_ACCOUNT/checkout-sessions/cs_SESSION_ID",
  "state": "OPEN",
  "amount": "10000",
  "currency": "GBP",
  "client_reference_id": "order_12345",
  "url": "https://pay.synaptopay.com/checkout?s_checkout_session=cs_SESSION_ID",
  "payment_intent": "accounts/acct_YOUR_ACCOUNT/payment-intents/pi_PAYMENT_INTENT_ID",
  "paid": false,
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "expire_time": "2025-11-18T16:00:00Z",
  "create_time": "2025-11-17T16:00:00Z",
  "update_time": "2025-11-17T16:00:00Z"
}

Redirect your customer to the url to complete payment.

Key fields

Field	Description
`amount`	Amount in smallest currency unit (e.g. `10000` = 100.00 GBP)
`currency`	Three-letter ISO currency code
`client_reference_id`	Your own reference (e.g. order ID) for cross-referencing
`success_url`	URL to redirect the customer to after successful payment. If not set, a Synapto hosted success page is shown
`cancel_url`	When set, a "Back" link is shown on the checkout page that redirects here
`url`	The hosted payment page URL. Only present when state is `OPEN`
`payment_intent`	The payment intent created automatically for this session
`paid`	`true` once payment has succeeded
`metadata`	Key-value pairs for your own use (max 50 keys, key max 40 chars, value max 500 chars)

Checkout session states

State	Description
`OPEN`	Customer can visit the URL and complete payment
`COMPLETE`	Payment was completed successfully
`EXPIRED`	Session expired without payment (after 24 hours by default)

Expiring a session

API reference

If an order is canceled or changes before the customer pays, expire the session to invalidate the payment link:

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/checkout-sessions/cs_SESSION_ID:expire \
  -H "Authorization: Api-Key $API_KEY"

This cancels the associated payment intent and sets the session state to EXPIRED.

Webhooks

When a checkout session is completed, a checkout_session.paid event is sent to your webhook endpoints. See Webhooks for setup instructions.