Test / Sandbox Mode

You can build and test the full integration without moving real money.

Two ingredients

  1. A test token (cp_test_…) issued by an admin. Payments created with it are flagged "test": true and are excluded from production statistics.
  2. A sandbox gateway configured as your application's default gateway. A test token refuses to work with a live gateway (GATEWAY_NOT_CONFIGURED), so you can never accidentally hit a real merchant account from a test environment.

Two kinds of sandbox gateway exist:

Gateway Behaviour
Sandbox simulator (fake driver) Built into Cartino Pay. payment_url points to a simulator page on Cartino Pay itself with Pay / Cancel / Fail buttons. No external calls at all. Perfect for CI and local development.
Gateway sandbox (e.g. Zarinpal sandbox, Zibal with the zibal test merchant) Real provider sandbox; exercises the provider's own pages. Use before going live.

Typical setup

Environment Application Token Default gateway
Local / CI cartino-cloud-dev cp_test_… Sandbox simulator
Staging cartino-cloud-staging cp_test_… Zarinpal sandbox
Production cartino-cloud cp_live_… Zarinpal live

Because gateways are configured per application, the same code runs in every environment; only the token and base URL differ.

Driving the simulator

  1. POST /api/v1/payments → payment_url like https://pay.cartino.net/sandbox/pay/FAKE…
  2. Open it. Click Pay → you are redirected to your callback_url?…&status=paid and a payment.paid webhook is sent. Cancel → cancelled. Fail → failed.
  3. For automated tests, POST the simulator's form directly: POST https://pay.cartino.net/callbacks/{gateway-slug}?p={payment_id} with authority=<value from the simulator page> and status=OK|CANCEL|FAIL.

Receiving webhooks locally

Expose your local server with a tunnel (e.g. ngrok http 8000) and ask an admin to set the tunnel URL as the webhook URL of your dev application. Webhook secrets and signatures behave exactly as in production.

Going live checklist

← Metadata Gateway Configuration →