The /v1 API. Payments, refunds and saved cards.

Send your secret key as a Bearer token on every request. Call the API from your server. It doesn’t allow calls from web pages (there is no CORS), and the key must never reach a browser.

• Create keys under API keys in the dashboard. You give each key a name and a mode. The full secret is shown once; ZopPay keeps only a hash of it and shows the last four characters. Revoked keys stop working straight away.
• sk_test_… keys send every payment through the built-in test gateway. No real money moves.
• sk_live_… keys use the live gateway that is turned on for the payment’s currency.
• Test and live are kept apart. A key only sees payments, refunds and cards of its own mode; asking for one of the other mode gets the same answer as asking for one that doesn’t exist.

A wrong key answers 401. A suspended account answers 403 on every call, with a body of a different shape: error is a string and code is organisation_suspended.

• Send bodies as JSON with Content-Type: application/json. A body sent with any other content type is ignored, so the request fails as if the fields were missing.
• Every successful answer wraps its result in data. Creating something answers 201 Created, reading answers 200 OK and deleting answers 204 No Content with no body.
• Amounts are whole numbers in the currency’s smallest unit: paise for INR, cents for USD, halalas for SAR. 49900 in INR is ₹499.00.
• Currencies are three-letter ISO 4217 codes. Any case is accepted; answers use capitals.
• Ids start with their type: pay_, rfd_, card_. Times are RFC 3339 in UTC, such as 2026-10-19T10:21:03Z.
• The API has no list endpoints for payments or refunds, so there is no paging. Lists and CSV exports are in the dashboard.

Errors use the HTTP status code and a body with one readable message. The messages below are the API’s own wording.

One exception to note: POST /v1/refunds for a payment it can’t find answers 400 with payment not found, not 404.

Creating a payment and creating a refund accept an optional Idempotency-Key header. If a request times out, send it again with the same key and the same body: you get the first answer back instead of a second payment or refund.

• A key is kept for 24 hours, separately for each endpoint and each mode.
• The key is tied to the exact request body. The same key with a different body answers 422; while the first request is still running, a repeat answers 409.
• If the first request ended in an error, nothing is kept and a retry runs again.
• Use an id your own system already has, such as the order id for a payment and your refund id for a refund.

Creating a payment also checks your reference; see below.

Each API key can make 300 requests a minute. Each IP address can make 1,200 requests a minute to /v1, counted before the key is checked. Over either limit the answer is 429 Too Many Requests with Retry-After: 60.

Creates an order and a payment, and returns a checkout_url. Send the shopper’s browser there. The link works for 30 minutes; use it exactly as returned.

amountintegerrequired

In the currency’s smallest unit. More than 0 and at most 100,000,000,000.

currencystringrequired

Three-letter ISO 4217 code. For a live key, a live gateway for this currency must be turned on in your dashboard.

referencestringrequired

Your order id, up to 255 characters. Kept separately for test and live.

return_urlstringrequired

Where the shopper comes back after the checkout. A full https:// address.

customerobject

Optional name, email and phone, passed on to the gateway.

metadataobject

Optional JSON object, stored with the order. It is not returned by the API or sent in webhooks, so match on reference and payment id.

• Same reference again. With the same amount and currency you get the existing payment back while it is pending or paid. If that payment failed, or its link expired, a new payment is made for the same order, with a new link if the old one had expired. A different amount or currency answers 400.
• Live keys. The payment goes to the gateway that is turned on for its currency. Before your account is live it answers 403 and lists what is missing.
• Gateway trouble. If the gateway won’t start the payment, the answer is 500 and the payment is marked failed, so a retry with the same reference makes a new one.

{
  "amount": 49900,
  "currency": "INR",
  "reference": "order_1042",
  "return_url": "https://shop.example.com/orders/1042/complete",
  "customer": {
    "name": "Asha Rao",
    "email": "asha@example.com",
    "phone": "+919876543210"
  },
  "metadata": {
    "cart_id": "cart_88213"
  }
}

When the shopper finishes, the browser goes to your return_url with these added to the query string. Any query string you put in return_url is kept.

payment_idpay_…

The payment.

statuscaptured | failed | pending

What the checkout saw. pending means the gateway hasn’t confirmed yet.

pp_outcomepayment-success | payment-failure

For older mobile apps. Ignore it.

Treat these as a hint only. Confirm the payment from your server with GET /v1/payments/{id} or a webhook before you ship.

Returns one payment of your key’s mode. Use it to confirm a payment and to catch up if you missed a webhook. A payment of the other mode answers 404.

idstring

The payment id.

statusstring

See Statuses. captured means paid.

amountinteger

In the smallest unit.

amount_refundedinteger

The total of refunds that succeeded. Pending refunds are not counted.

currencystring

Three-letter code.

referencestring

Your order reference.

modestring

test or live.

gateway_transaction_idstring

The gateway’s own id. Left out until there is one.

created_at, updated_atstring

RFC 3339, UTC.

Refunds all or part of a paid payment. The refund goes back through the gateway account that took the payment, even if you have switched gateways since.

payment_idstringrequired

The payment to refund.

amountinteger

Optional. Leave it out (or send 0) to refund everything not yet refunded. Otherwise at most what is left.

reasonstring

Optional free text, kept with the refund.

• The payment must be paid (captured). One refund at a time per payment: a second while one is pending answers 400.
• succeeded means the gateway confirmed it straight away. pending means the result comes later, as a refund.succeeded or refund.failed webhook.
• If the gateway refuses, the answer is 422 with the gateway’s reason, the refund is recorded as failed and refund.failed is sent. Fix the cause and refund again.
• TechProcess connections can’t refund through ZopPay; refund those from TechProcess’s own panel.

{
  "payment_id": "pay_01JD3V8Q4M6Y2C9T7K5W1R0BNA",
  "amount": 10000,
  "reason": "Item returned"
}

Returns one refund whose payment is of your key’s mode; otherwise 404. It has the same fields as the create answer, plus gateway_refund_id once the gateway has given one and completed_at once it has finished.

Stores a card that a shopper registered with a gateway that supports saved cards. Today that is HyperPay only. Your own app runs HyperPay’s card registration; you then send its id here and ZopPay keeps the gateway’s token with the card brand, the first digits (BIN), the last four digits and the expiry date.

• POST/v1/cards

  Body: customer_reference, gateway_slug (hyperpay), currency and registration_context, all required, plus an optional is_debit. Your HyperPay connection must be the one turned on for that currency and mode.

• GET/v1/cards?customer_reference=…

  Lists that customer’s cards in your key’s mode, under data.

• DELETE/v1/cards/{id}

  Removes the card, and asks the gateway to delete its token. Answers 204.