Checkout sessions

Choose a checkout mode

The shop's checkout setting determines who collects customer details and handles payment:

Sessions are available in hosted and payment mode. The selected mode is stored on each session so a later shop-setting change does not alter a purchase in progress.

Create a hosted session

POST /api/store/checkout-sessions

Call the endpoint using your shop's publishable key. The following example assumes hosted mode:

curl "$SELLFORGE_CHECKOUT_URL/api/store/checkout-sessions" \
  -H "Authorization: Bearer $SELLFORGE_PUBLIC_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      { "product_id": "prod_example", "quantity": 2 }
    ],
    "return_url": "https://shop.example.com/checkout/result",
    "customer_email": "[email protected]"
  }'

Replace prod_example with a real product ID. Each item can include an optional variant_id. The request accepts 1–100 items with quantities from 1–999.

The return_url must satisfy the shop's domain allowlist. Products must belong to the shop. Sellforge calculates prices; the request does not accept caller-supplied item prices.

Response

{
  "id": "cs_example",
  "url": "https://checkout.example.com/c/cs_example"
}

The actual host comes from the deployment's checkout configuration. Redirect the customer to the returned url instead of constructing it yourself.

Payment-only mode

In payment mode, the storefront supplies the customer object. A shipping_address is required. The object also accepts email, customer_id, billing_address, shipping_method, and discount_code.

Address and shipping information are used to calculate tax and delivery charges. Supply the applicable shipping method for the order. The server remains responsible for totals and discount validation.

Session lifecycle

An open session has a 30-minute lifetime. The hosted checkout reads it through GET /api/checkout/:id, collects the required information, and initiates payment.

POST /api/checkout/:id/complete checks payment state. A customer returning from 3-D Secure or a redirect payment method must complete this step through the checkout flow. Reading an open session with an already paid order can also reconcile it to completed.

Confirm the outcome

A browser redirect alone is not an authoritative payment confirmation. Use the signed checkout notification and the order state on the backend to decide when to fulfill an order.