Loading…
Callback endpoint for the Zibal payment gateway to verify a deposit transaction.
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| deposit-id | int | Yes | ID of the deposit to verify. An ID that matches no payment redirects to the app URL like any refused callback (it is never a 404) | 123 |
| Name | Type | Required | Description |
|---|
| Example |
|---|
| trackId | string | Yes | Track ID from Zibal | "123456789" |
| success | string | Yes | Payment result from Zibal ("1" = success, "0" = failed) | "1" |
GET /api/v1/payments/verify-deposit/123?trackId=123456789&success=1
Deposit was successfully verified.
You get redirected to the app URL.
On a successful verification the deposit record is finalized (is_done becomes true) and the
gateway's reference code is stored in two places:
description as a localized line (Reference code: … /
کد پیگیری: …), so the user can read it wherever the payment is listedmeta, alongside the track ID, masked card number, payment time and the Rial amount the
gateway charged: merged into the fee breakdown already stored when the deposit was createdA repeated callback never appends the reference code twice.
This route is public and unauthenticated (both the payment ID and trackId arrive from the
outside world) so a callback is finalized only when all of the following hold. Every refusal
redirects to the app URL exactly like a failed payment: the outcomes are deliberately
indistinguishable to the caller, so none of them can be used to probe another user's payments.
| Condition | Behaviour |
|---|---|
success is not 1 | Refused; the deposit stays unfinalized. |
| No payment has that ID | Redirects without contacting the gateway, so an unknown ID cannot be told apart from a refused one. |
The payment is already is_done | Short-circuits before the gateway is contacted. A replayed callback cannot credit the balance twice. |
trackId does not equal the track_id recorded on the payment when it was created | Refused. A payment with no recorded track_id is refused outright. |
| The gateway's settled amount does not equal the payment's gross amount (amount + gateway fee) | Refused. This stops a trackId from a smaller settled charge finalizing a larger deposit. |
| More than 30 callbacks in a minute for this payment ID, or more than 300 in a minute from one IP | Throttled: redirects without contacting the gateway, and the deposit stays unfinalized on that request. The budget is per payment, so payers sharing an IP do not spend each other's. |
The two track-ID values and the settlement amounts are gateway-sensitive and are deliberately kept out of the logs.
You get redirected to the app URL.
Error message will be shown in the app.
There is no JSON error response on this route: a throttled callback redirects as well (see the table above), because the caller is the payer's browser following the gateway.