Create your first Checkout

This tutorial creates a Hosted Checkout session with a manual amount. Your backend receives a URL and returns it to the frontend.

Gather the requirements

You need:

A SimplePay account
A merchant with an active sandbox environment
A key with hosted_checkout:write
A backend that protects the key

Never include a SimplePay key in browser JavaScript, a mobile app, or a repository.

Configure your terminal

Set the sandbox host. Read the key without storing it in shell history:

export SIMPLEPAY_API_BASE="https://api.test.simplepay.mx"
read -rs SIMPLEPAY_API_KEY
export SIMPLEPAY_API_KEY

Create the session

Send the amount in the currency’s minor unit. 50000 represents MXN 500.00:

curl -sS -X POST "$SIMPLEPAY_API_BASE/v1/hosted-checkout/sessions" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1001_checkout_v1" \
  --data '{
    "manual_amount": 50000,
    "currency": "mxn",
    "payment_method_types": ["card"],
    "metadata": {"order_id": "order_1001"}
  }'

The response includes id, public_reference, and url. Store id for authenticated reads and redirect to url.

Confirm the result

The browser does not confirm a payment. Update your order after payment.succeeded or an equivalent authenticated read.

Configure webhooks

Verify signatures and process events without duplicating effects.

Last modified on August 22, 2026

Get started

Essentials

Accept payments

Catalog

Webhooks

Platform

Agents

Create your first Checkout

Gather the requirements

Configure your terminal

Create the session

Confirm the result

Configure webhooks

​Gather the requirements

​Configure your terminal

​Create the session

​Confirm the result

Configure webhooks

Gather the requirements

Configure your terminal

Create the session

Confirm the result