Checking Payment Status#

GET /api/v1/payments/{payment_id}
Authorization: Bearer cp_live_…

Returns the current state of a payment belonging to your application. It never contacts the gateway; it reflects what Cartino Pay has already verified.

{
  "success": true,
  "data": {
    "payment_id": "PAY_01J9X4Z8K3M2N5P7Q9R1S3T5V7",
    "application": "cartino-cloud",
    "order_id": "CLOUD-12345",
    "amount": 500000,
    "currency": "IRR",
    "status": "paid",
    "gateway": "zarinpal",
    "tracking_code": "123456789",
    "card_pan_masked": "603799******1234",
    "failure_code": null,
    "failure_reason": null,
    "test": false,
    "metadata": { "user_id": 123, "plan": "pro" },
    "callback_url": "https://cartino.cloud/payment/callback",
    "expires_at": "2026-09-14T10:30:00+03:30",
    "paid_at": "2026-09-14T10:05:10+03:30",
    "verified_at": "2026-09-14T10:05:10+03:30",
    "created_at": "2026-09-14T10:00:00+03:30",
    "updated_at": "2026-09-14T10:05:10+03:30"
  }
}

payment_url is omitted once the payment is final.

Listing payments#

GET /api/v1/payments?order_id=CLOUD-12345
GET /api/v1/payments?status=paid&from=2026-09-01T00:00:00Z&per_page=50

Filters: order_id, status, from, to, per_page (≤ 100), page. Results are newest first and include a meta object with pagination.

When to poll#

• On your callback page, to render the outcome (see Handling Callbacks).
• As a reconciliation job: list status=pending payments older than a few minutes and call verify on them.

Do not poll in a tight loop while the payer is at the bank; wait for the callback or webhook.

Errors#