Skip to content

Checkout sessions and payment links

A checkout session is one shopper's visit to a published checkout with a given cart. Create it on your server and redirect the shopper to url:

HTTP
POST /v1/checkout-sessions
Authorization: Bearer giep_sk_…
Idempotency-Key: order-1042-session-v1
Content-Type: application/json

{
  "checkoutId": "<published checkout id>",
  "currency": "USD",
  "lineItems": [{ "title": "Trail shoes", "quantity": 1, "unitAmount": 8900 }],
  "customer": { "email": "[email protected]", "country": "US" },
  "externalOrderRef": "1042",
  "successUrl": "https://shop.example/thanks",
  "failureUrl": "https://shop.example/cart",
  "cancelUrl": "https://shop.example/cart",
  "total": 8900,
  "expiresInMinutes": 60
}

Response 201: { "id", "token", "url" }. The token is a capability: keep it out of logs.

  • GIEP prices the session: line items, accepted bumps, discounts, shipping and tax. total is optional; when given, the session is refused unless GIEP's computed total equals it (protects against stale carts).
  • taxLines lets a store that computes its own tax (Shopify, WooCommerce) send it; it then replaces GIEP's tax rules.
  • prices on a line item gives explicit prices in other presentment currencies; nothing is converted.
  • Return URLs must be https and on the store's return-URL allow-list. After the outcome is confirmed on GIEP's server the shopper is sent to successUrl, failureUrl or cancelUrl with giep_* parameters, signed when the store has a signing secret: see Verifying GIEP's signed return URLs. The redirect is a pointer, never proof of payment.
  • Confirm the outcome with the order.paid / checkout_session.paid webhook or GET /v1/checkout-sessions/{id} (status open, processing, paid, expired, cancelled, with totals, discount and tax lines, paymentId, orderId, and your externalOrderRef).

A payment link (POST /v1/payment-links, or Sell > Payment links) is a URL for a fixed amount: each visit creates a new 60-minute session of the linked checkout. Links are reusable by default; with reusable: false the link is marked used once it is paid. expiresAt ends it at a given time.