Checkout API

The Checkout API is a small REST surface for taking a single payment. You create a checkout session for an amount, Payer returns a hosted payment page, the customer pays there, and you read the session's status (or let a webhook tell you) to know when it's done.

All endpoints live under /checkout and authenticate with a publishable or secret key holding the checkout:write scope. Everything on this page is also modelled in the machine-readable OpenAPI spec.

Create a session

POST /checkout/sessions

Creates a checkout session and returns a hosted payment link. Send an Idempotency-Key so a retried create replays the first response instead of making a second session. Requires the checkout:write scope.

Body parameters

curl https://api.payer.app/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order_10482" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2490,
    "title": "Order #10482",
    "reference": "order_10482",
    "return_url": "https://example.com/thanks"
  }'

{
  "id": "9b1c8f2e-3d4a-4f11-a0c2-1e2d3c4b5a69",
  "reference": "order_10482",
  "url": "https://api.payer.app/9b1c8f2e-3d4a-4f11-a0c2-1e2d3c4b5a69"
}

Redirect the customer to url. A session expires 24 hours after it's created if it hasn't been paid.

Retrieve a session

GET /checkout/sessions/{id}

Returns the current state of a session. The {id} may be the session UUID or the reference you set when creating it.

curl https://api.payer.app/checkout/sessions/9b1c8f2e-3d4a-4f11-a0c2-1e2d3c4b5a69 \
  -H "Authorization: Bearer sk_test_..."

{
  "id": "9b1c8f2e-3d4a-4f11-a0c2-1e2d3c4b5a69",
  "reference": "order_10482",
  "status": "COMPLETED",
  "fee": 62
}

status is one of:

The fee

fee is the fee Payer charged for the payment, in laari, deducted from the amount settled to you. It is null until the session is COMPLETED (and stays null for sessions that end unpaid), then holds the fee that was actually charged. The fee depends on how the customer chose to pay, so it is never quoted upfront: read it here after settlement, or take it from the `checkout.session.completed` webhook, which also carries the net_amount you received.

Cancel a session

POST /checkout/sessions/{id}/cancel

Cancels a session that hasn't been paid. Requires the checkout:write scope. Send an Idempotency-Key so a retried cancel is safe.

curl -X POST https://api.payer.app/checkout/sessions/9b1c8f2e-.../cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: cancel_order_10482"

{ "message": "Checkout session cancelled" }

A session that is already cancelled, or already in another terminal state, returns 400:

{ "message": "Checkout session already cancelled" }

Try it live

The panel below runs real requests from your browser straight to api.payer.app. Paste an sk_test_ key, edit the inputs, and send. Nothing is proxied through this site, and the key stays in this browser tab.