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.

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"
}

status is one of:

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" }

Read a session over GraphQL

The session is also readable at POST /graphql, and this query is public — the UUID is the capability, so no key is needed. This is the same data the hosted checkout page loads.

query CheckoutSession($id: UUID!) {
  checkoutSession(id: $id) {
    id
    merchantName
    reference
    title
    description
    amount
    currency
    status
    expiresAt
    returnUrl
  }
}

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.