Quick Start#

Five minutes from zero to a completed sandbox payment.

1. Get credentials#

A Cartino Pay administrator creates your application and issues:

• an API token — cp_test_… (sandbox) or cp_live_… (production). Shown once; store it as a secret.
• a webhook secret — whsec_…, used to verify webhook signatures. Also shown once.

They also register your callback URL (where the payer's browser returns) and webhook URL (where Cartino Pay POSTs the outcome).

Check your setup:

curl https://pay.cartino.net/api/v1/me \
  -H "Authorization: Bearer cp_test_xxxxxxxx"

2. Create a payment#

curl -X POST https://pay.cartino.net/api/v1/payments \
  -H "Authorization: Bearer cp_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-CLOUD-12345" \
  -d '{
    "amount": 500000,
    "currency": "IRR",
    "order_id": "CLOUD-12345",
    "description": "Cartino Cloud subscription",
    "callback_url": "https://cartino.cloud/payment/callback",
    "metadata": { "user_id": 123, "plan": "pro" }
  }'

{
  "success": true,
  "data": {
    "payment_id": "PAY_01J9X4Z8K3M2N5P7Q9R1S3T5V7",
    "status": "pending",
    "payment_url": "https://payment.zarinpal.com/pg/StartPay/A0000…",
    "expires_at": "2026-09-14T10:30:00+03:30",
    "…": "…"
  }
}

Store payment_id against your order.

3. Redirect the payer#

return redirect()->away($response['data']['payment_url']);

4. Receive the outcome#

When the payer finishes, Cartino Pay verifies with the gateway and then:

• redirects the payer to https://cartino.cloud/payment/callback?payment_id=PAY_…&order_id=CLOUD-12345&status=paid
• POSTs a signed webhook to your webhook URL:

{
  "event": "payment.paid",
  "event_id": "7f3c9a2e-…",
  "payment_id": "PAY_01J9X4Z8K3M2N5P7Q9R1S3T5V7",
  "order_id": "CLOUD-12345",
  "status": "paid",
  "amount": 500000,
  "currency": "IRR",
  "tracking_code": "123456789",
  "metadata": { "user_id": 123, "plan": "pro" }
}

Fulfil the order from the webhook (after verifying its signature — see Webhooks), not from the browser redirect.

5. (Optional) Check or verify#

curl https://pay.cartino.net/api/v1/payments/PAY_01J9X4Z8K3M2N5P7Q9R1S3T5V7 \
  -H "Authorization: Bearer cp_test_xxxxxxxx"

If you never received a webhook, force a verification:

curl -X POST https://pay.cartino.net/api/v1/payments/PAY_01J9X4Z8K3M2N5P7Q9R1S3T5V7/verify \
  -H "Authorization: Bearer cp_test_xxxxxxxx"

That's the whole integration. Full code in Examples.