Gateway Configuration

This page is for Cartino Pay administrators. Application developers never see or configure gateways; the gateway is an implementation detail of Cartino Pay.

Gateways are managed through the admin API (/admin/api/v1/gateways) consumed by the Cartino admin panel.

Model

Field	Notes
`name`, `slug`	e.g. Zarinpal Live, `zarinpal-live`. The slug forms the gateway callback URL: `https://pay.cartino.net/callbacks/zarinpal-live`.
`driver`	One of the registered adapters: `zarinpal`, `zibal`, `mrpay`, `fake`. Fixed after creation.
`mode`	`sandbox` or `live`. Test tokens can only use sandbox gateways.
`enabled`	Disabled gateways reject new payments (`GATEWAY_DISABLED`); existing payments can still be verified.
`credentials`	Encrypted JSON. Write-only — reads return only which keys are set and a masked tail.
`settings`	Optional non-secret driver settings (e.g. MrPay base URL overrides).

You may create several gateways with the same driver (a sandbox and a live Zarinpal, or two live merchants) and assign each application its own default.

Drivers and credentials

Driver	Credentials	Sandbox	Reverse
`zarinpal`	`merchant_id`	`sandbox.zarinpal.com`	yes
`zibal`	`merchant`	test merchant `zibal` (credential ignored in sandbox)	no
`mrpay`	`api_key`	via `settings.base_url`	no
`fake`	—	built-in simulator	yes

GET /admin/api/v1/gateways/drivers returns this schema programmatically so the admin UI can render the right form.

Example: create a live Zarinpal gateway

curl -X POST https://pay.cartino.net/admin/api/v1/gateways \
  -H "Authorization: Bearer cpa_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zarinpal Live",
    "slug": "zarinpal-live",
    "driver": "zarinpal",
    "mode": "live",
    "enabled": true,
    "credentials": { "merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
  }'

Then set it as an application's default:

curl -X PATCH https://pay.cartino.net/admin/api/v1/applications/12 \
  -H "Authorization: Bearer cpa_…" -H "Content-Type: application/json" \
  -d '{ "default_gateway_id": 3 }'

The application's next POST /api/v1/payments uses the new gateway. In-flight payments keep the gateway they were created with.

Provider-side configuration

https://pay.cartino.net/callbacks/{gateway-slug}

Cartino Pay appends ?p={payment_id} per payment; providers must be allowed to redirect to that URL.

Adding a new gateway (developers)

Create app/Gateways/Drivers/SamanGateway.php extending AbstractGateway and implementing createPayment, parseCallback, verifyPayment, getPaymentStatus, reversePayment, plus driver(), displayName(), credentialSchema().
Register it in config/cartino_pay.php under gateways.
Add unit tests with Http::fake() (never call the provider in tests).

Nothing in the payment flow, controllers or documentation for applications changes.

Compliance reminder

Configuring a gateway is a technical act. Whether a given application/domain may transact through a given merchant account is decided by the business/legal team.

Gateway Configuration#

Model#

Drivers and credentials#

Example: create a live Zarinpal gateway#

Provider-side configuration#

Adding a new gateway (developers)#