Public endpoint that lets partner sites confirm a payment matches a transaction recorded in GatePay, and stamp it with the verifier's business identity.
GatePay exposes two primary flows and supporting endpoints for partner sites:
unverified.callback_url, and on a 2xx response stamps them as verified.All endpoints require an API key via the Authorization: Bearer header (except health & OpenAPI spec). Manage keys from Admin → API Keys. The full token is shown only once on creation.
Creates an unverified transaction in GatePay. Call this when an order is placed on your end. Safe to retry with the Idempotency-Key header.
POST https://pay.darvizlabs.com/api/v1/public/transactions/submitAuthorization: Bearer YOUR_API_KEY| Field | Type | Required | Notes |
|---|---|---|---|
transaction_ref | string (1–120) | Yes | Your unique transaction ID. |
amount | number ≥ 0 | Yes | Payment amount. |
currency | string (≤8) | No | Defaults to 'BDT'. |
occurred_at | ISO 8601 datetime | No | Defaults to now(). |
method | string (≤40) | No | e.g. 'bkash', 'card', 'nagad'. |
business_name | string (1–160) | No* | Falls back to the API key's business_name. |
external_user_id | string (≤160) | No | Your end-user ID for cross-reference. |
source | string (≤160) | No | Free-form tag, e.g. 'web-checkout'. |
notes | string (≤2000) | No | Free-form notes. |
{
"transaction_ref": "INV-2026-00482",
"amount": 1499,
"currency": "BDT",
"method": "bkash",
"business_name": "Nerdy",
"external_user_id": "user_8821",
"source": "web-checkout",
"occurred_at": "2026-05-27T10:00:00Z"
}Checks if a submitted transaction matches a known ref. Returns the transaction details if found. Use when you need to confirm a specific payment on demand.
POST https://pay.darvizlabs.com/api/v1/public/transactions/verifyAuthorization: Bearer YOUR_API_KEY| Field | Type | Required | Notes |
|---|---|---|---|
transaction_ref | string (1–120) | Yes | Transaction ID to look up. Case-insensitive. |
business_name | string (1–160) | Yes | Must match the API key's business_name. |
external_user_id | string (≤160) | No | Your internal user ID, stored on the transaction. |
date | ISO date / datetime | No | If set, must match the transaction's UTC day. |
amount | number ≥ 0 | No | If set, must equal recorded amount exactly. |
source | string (≤160) | No | Free-form audit label. |
{
"transaction_ref": "INV-2026-00482",
"business_name": "Nerdy",
"external_user_id": "user_8821",
"date": "2026-05-27",
"amount": 1499,
"source": "web-checkout"
}Submits a client-side review (confirmed amount + note) against an existing transaction. Use when you want your customer or internal team to confirm or annotate a recorded transaction.
POST https://pay.darvizlabs.com/api/v1/public/transactions/reviewAuthorization: Bearer YOUR_API_KEY| Field | Type | Required | Notes |
|---|---|---|---|
transaction_id | string | Yes | Transaction ID returned by the submit endpoint. |
amount | number ≥ 0 | Yes | Confirmed amount for the transaction. |
note | string (≤2000) | Yes | Review note or feedback. |
{
"transaction_id": "jf3m2k9x1p",
"amount": 1499,
"note": "Payment confirmed by customer — project setup fee."
}When an admin clicks Trigger verify in the dashboard, GatePay groups the selected transactions by business name, finds the matching API key's callback_url, and POSTs each group to that URL. Your 2xx response is the verification — nothing more needed.
What is a callback URL?
A callback URL is an HTTP endpoint on your own server that GatePay calls to confirm a batch of transactions. Example: https://api.nerdy.com/gatekeepr/verify. It must be HTTPS, must return a 2xx to confirm verification, and you can verify the request via the X-GatePay-Signature HMAC header.
If your API key has no callback_url set, or the URL is unreachable (like https://example.com/verify), the admin verification will show skipped_no_callback or callback_timeout. Set a real callback URL on your API key in Admin → API Keys.
POST <your callback_url>
Content-Type: application/json
X-GatePay-Signature: sha256=<hex hmac>
User-Agent: GatePay-Verify/1.0
{
"business_name": "Nerdy",
"sent_at": "2026-05-27T16:30:00.000Z",
"transactions": [
{
"transaction_ref": "INV-2026-00482",
"amount": 1499.00,
"currency": "BDT",
"occurred_at": "2026-05-27T10:00:00.000Z",
"method": "bkash",
"external_user_id": "user_8821",
"source": "web-checkout"
}
]
}X-GatePay-Signature HMAC (optional but recommended).2xx if everything checks out — GatePay stamps the batch as verified.Lightweight endpoint to verify the API is operational. No auth required.
GET https://pay.darvizlabs.com/api/v1/public/health{"status":"ok"}| Status | Response | Meaning |
|---|---|---|
| 201 | {"received":true,"status":"unverified"} | Submit success |
| 200 | {"verified":true,"transaction":{...}} | Transaction matches |
| 200 | {"verified":false,"reason":"not_found"} | No matching transaction |
| 200 | {"verified":false,"reason":"date_mismatch"} | Date doesn't match |
| 200 | {"verified":false,"reason":"amount_mismatch"} | Amount doesn't match |
| 400 | {"error":"invalid_body","issues":[...]} | Zod validation failed |
| 400 | {"error":"invalid_json"} | Body is not valid JSON |
| 401 | {"error":"missing_api_key"} | No Authorization header |
| 401 | {"error":"invalid_api_key"} | Token unknown or revoked |
| 409 | {"error":"duplicate_ref"} | Ref already exists (submit) |
| 413 | {"error":"body_too_large"} | Body exceeds 10 KB |
| 429 | {"error":"rate_limited"} | IP rate limit hit (30/60 req/min) |
| 429 | {"error":"key_rate_limited"} | Key rate limit hit (100 req/min) |
| 500 | {"verified":false,"reason":"lookup_error"} | Server / DB error |
Every response includes an x-request-id header. Include this when reporting issues.
business_name.Strict-Transport-Security and X-Content-Type-Options.signing_secret.