Introduction

Cartino Pay is the internal payment orchestration layer of the Cartino ecosystem. It sits between Cartino applications (cartino.net, cartino.cloud, …) and external Iranian payment gateways (Zarinpal, Zibal, MrPay, …).

Instead of every application integrating each gateway, all applications talk to one API at https://pay.cartino.net. Cartino Pay holds the gateway credentials, creates payments at the gateway, verifies them server-to-server, stores every transaction and notifies your application with a signed webhook.

Cartino Pay is not a public payment aggregator and not a wallet. Applications are registered manually by Cartino administrators.

How a payment flows

 CLIENT APPLICATION            CARTINO PAY                 EXTERNAL GATEWAY
 ─────────────────            ───────────                 ────────────────
 1. POST /api/v1/payments ──▶ authenticate app
                              select gateway
                              register payment ─────────▶ (merchant credentials
                              ◀──────────────────────────  stay here)
 2. ◀── payment_url ────────
 3. redirect payer ─────────────────────────────────────▶ payer pays at the bank
                              ◀── browser callback ──────
                              verify server-to-server ──▶
                              ◀── confirmed ─────────────
 4. ◀── redirect payer to your callback_url (?payment_id=&status=)
 5. ◀── signed webhook  payment.paid / failed / cancelled / expired
 6. (optional) GET /api/v1/payments/{id}   or   POST …/verify

What you get

Concern Handled by Cartino Pay
Gateway credentials Stored encrypted; never exposed to applications
Switching gateways Admin changes the application's default gateway; your integration does not change
Verification Always server-to-server; the browser callback is never trusted
Duplicate requests Idempotency-Key header
Notifications HMAC-signed webhooks with retries
Audit Full per-payment event trace available to admins

What you need to do

  1. Ask a Cartino Pay admin to register your application and give you an API token.
  2. Register your callback URL(s) and webhook URL.
  3. Call POST /api/v1/payments, redirect the payer to payment_url.
  4. Handle the webhook (or poll status) and fulfil the order.

Continue with the Quick Start.

Legal / compliance note

Cartino Pay is a technical building block. Whether a given Cartino application or domain may legally process payments through a given merchant account or gateway is confirmed separately by the business and legal team. Nothing in this system automatically satisfies Shaparak, PSP or merchant compliance requirements.

Quick Start →