Skip to main content
Let’s process a test payment end-to-end using Hosted Checkout — the fastest path, with no need to handle card data yourself. Everything happens in the sandbox, so no real money is moved.
Prefer a direct API integration (submitting the payment straight through the API)? Check out Transactions after finishing this guide.

​
Prerequisites

  • A Z2Pay account with access to the test environment (sandbox). See Environments.
  • Your sandbox API key (z2_chk_sk_... or z2_psp_sk_...). See Authentication.
1

Create a checkout link

A Checkout Link is a reusable billing template. Every time someone opens the URL, a new purchase (Session) is created.
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/links \
  -H "x-api-key: z2_chk_sk_suachavedesandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu primeiro produto",
    "items": [
      { "name": "Plano Pro", "quantity": 1, "unitAmount": 4990 }
    ],
    "paymentMethods": {
      "card":   { "enabled": true, "installments": { "maxInstallments": 12 } },
      "pix":    { "enabled": true },
      "boleto": { "enabled": true }
    }
  }'
Response (201):
{
  "id": "chk_abc123...",
  "status": "active",
  "url": "https://pay.sandbox.z2pay.com/c/chk_abc123...",
  "createdAt": "2026-06-24T12:00:00.000Z"
}
unitAmount is an integer in cents: R$ 49.90 = 4990. Never send a float (49.90) — it will be rejected by validation.
2

Open the URL and pay with a test card

Open the returned url in your browser. You will see Z2Pay’s hosted payment page.Use the generator below to create a valid card number that will be approved:→ Generate a test cardFill in:
  • Number: the generated card (scenario “Approved”).
  • Expiry: any future date, e.g. 12/30.
  • CVV: any value, e.g. 123.
  • Name / buyer details: any valid value.
To test a decline, generate a card with the “Card declined” scenario.
3

Confirm the payment

After the payment, look up the transaction via the API. The referenceCode/id appears in webhooks and in the checkout response.
curl https://api.sandbox.z2pay.com/transactions/txn_abc123 \
  -H "x-api-key: z2_psp_sk_suachavedesandbox"
Response (200):
{
  "id": "txn_abc123",
  "status": "paid",
  "amount": 4990,
  "currency": "BRL",
  "paidAt": "2026-06-24T12:01:30.000Z"
}
status: "paid" — payment approved in the sandbox. 🎉
4

(Recommended) Receive webhooks

In production you don’t poll for status — you receive a notification on every status change. Register a webhook and listen for events such as transaction.paid:
curl -X POST https://api.sandbox.z2pay.com/webhooks \
  -H "x-api-key: z2_psp_sk_suachavedesandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu endpoint",
    "url": "https://meusite.com/webhooks/z2pay",
    "events": ["transaction.paid", "transaction.refused"]
  }'
See Webhooks for the full event catalog and instructions on how to validate the signature.

​
Next steps

Test cards and scenarios

Every card that passes and every card that fails, with a built-in generator.

Direct API (Transactions)

Create and process payments without the hosted checkout.

Subscriptions

Recurring billing, plans, and invoices.

Payment splits

Divide a payment amount among multiple recipients.