flatrender/deploy/PAYMENTS.md

# FlatRender Pay — ZarinPal Broker Integration Guide

`pay.flatrender.ir` is a **standalone, multi-client ZarinPal gateway**. Any site
(FlatRender, meezi.ir, bargevasat.ir, …) routes payments through it, because
ZarinPal only accepts callbacks on the single verified domain `pay.flatrender.ir`.

```
your site ──POST /v1/pay/request──►  pay.flatrender.ir  ──►  ZarinPal request.json
   ▲  (api key + HMAC)                      │                       │
   │                                        ▼                  authority
   └──◄ 302 return_url (signed) ◄── /callback/zarinpal ◄── user pays on ZarinPal
   └──◄ POST webhook_url (signed) ◄────────┘  (verify.json → ref_id)
```

You get a **client app** from the FlatRender admin (Admin → پرداخت → اپلیکیشن‌ها):

- `api_key`   — public id, sent as `X-Api-Key` (e.g. `pk_…`)
- `secret`    — shown **once**; signs your requests AND verifies broker callbacks (`sk_…`)
- `webhook_url` — optional server-to-server result endpoint
- `allowed_return_origins` — the origins your `return_url` may use (empty = any)

---

## 1. Create a payment

`POST https://pay.flatrender.ir/v1/pay/request`

Headers:

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `X-Api-Key` | your `api_key` |
| `X-Signature` | `hex( HMAC_SHA256(secret, <raw request body bytes>) )` |

Body:

```json
{
  "amount": 50000,
  "currency": "IRT",
  "description": "خرید اشتراک طلایی",
  "client_ref": "order-1234",
  "return_url": "https://meezi.ir/payment/return",
  "mobile": "09120000000",
  "email": "user@example.com",
  "metadata": { "user_id": "42", "plan": "gold" }
}
```

- `amount` — integer. `currency` is `"IRR"` (Rial, default) or `"IRT"` (Toman). The
  broker stores the canonical Rial value and converts for ZarinPal.
- `client_ref` — your own order id (echoed back everywhere).
- `return_url` — where the user's browser is sent after payment. Must match an
  `allowed_return_origins` entry if you configured any.
- `metadata` — arbitrary JSON, echoed back in the redirect signature scope + webhook.

Response `200`:

```json
{
  "id": "9b2c…",            // broker transaction id
  "status": "Pending",
  "payment_url": "https://www.zarinpal.com/pg/StartPay/A000…",
  "authority": "A000…",
  "amount_rial": 500000
}
```

**Redirect the user's browser to `payment_url`.**

---

## 2. The user comes back (browser redirect)

After ZarinPal, the broker verifies the payment and `302`-redirects the browser to
your `return_url` with a **signed** result appended:

```
https://meezi.ir/payment/return?status=Paid&id=9b2c…&ref_id=123456789&sign=<hex>
```

- `status` — `Paid` | `Failed` | `Cancelled`
- `ref_id` — ZarinPal receipt (only when paid)
- `sign`   — `hex( HMAC_SHA256(secret, "{id}.{status}.{ref_id}.{amount_rial}") )`

⚠️ The redirect is **not** proof of payment on its own (a user can craft a URL).
Treat it as a UX hint, then **confirm with the webhook (§3) or the inquiry API (§4)**.

To verify the redirect signature you need `amount_rial`; fetch it via the inquiry
API, or just rely on the webhook / inquiry as the source of truth.

---

## 3. Webhook (recommended — the source of truth)

If `webhook_url` is set, the broker POSTs a **signed** JSON body to it when a payment
finishes (with retry + exponential backoff up to ~1h):

Headers: `X-FlatPay-Signature: <hex>`, `X-FlatPay-Event: payment`

```json
{
  "event": "payment.paid",
  "id": "9b2c…",
  "status": "Paid",
  "amount_rial": 500000,
  "currency": "IRR",
  "client_ref": "order-1234",
  "ref_id": "123456789",
  "authority": "A000…",
  "card_pan": "6037********1234",
  "metadata": { "user_id": "42", "plan": "gold" },
  "paid_at": "2026-06-15T14:00:00Z",
  "ts": 1750000000
}
```

Verify: `HMAC_SHA256(secret, <raw body bytes>) == X-FlatPay-Signature`. Respond `2xx`
to acknowledge (anything else is retried). Make handling **idempotent** (keyed on
`id` or `client_ref`) — duplicate deliveries are possible.

---

## 4. Inquiry (authoritative pull)

`POST https://pay.flatrender.ir/v1/pay/inquiry` (same `X-Api-Key` + `X-Signature` as §1)

```json
{ "id": "9b2c…" }
```

Returns the full transaction (status, `ref_id`, `amount_rial`, …). Use this from your
`return_url` handler to confirm before granting the user anything.

---

## Reference signature recipe

```
signature = hex( HMAC_SHA256(client_secret, message_bytes) )
```

- **request / inquiry**: `message_bytes` = the exact raw JSON body you send.
- **return redirect**: `message_bytes` = UTF-8 of `"{id}.{status}.{ref_id}.{amount_rial}"`.
- **webhook**: `message_bytes` = the exact raw JSON body received.

See [`sdk/flatpay.js`](./sdk/flatpay.js) for a drop-in Node client + Express webhook
verifier.