Zibal API Reference
This page documents the available methods and data models for the Zibal payment gateway integration using the Payman package. It includes detailed parameter tables and exception mappings.
Methods
payment(request: PaymentRequest) -> PaymentResponse
Initiates a new payment request to Zibal.
Parameters
request
(PaymentRequest
)
Field | Type | Required | Description |
---|---|---|---|
amount |
int (≥ 100) |
✅ | Payment amount in Rial (minimum: 100) |
callback_url |
HttpUrl |
✅ | URL to redirect the user after payment |
description |
str | None |
❌ | Optional payment description |
order_id |
str | None |
❌ | Optional merchant order identifier |
mobile |
constr(min_length=11, max_length=11, pattern="^09\d{9}$") \| None |
❌ | Optional buyer mobile number |
allowed_cards |
List[constr(min_length=16, max_length=16, pattern="^\d{16}$")]\| None |
❌ | Optional list of allowed card PANs |
ledger_id |
str | None |
❌ | Optional ledger identifier |
national_code |
constr(min_length=10, max_length=10, pattern="^\d{10}$") \| None |
❌ | Optional national code of the buyer |
check_mobile_with_card |
bool | None |
❌ | Optional mobile/card cross-check flag |
percent_mode |
Literal[0,1] (default: 0 ) |
❌ | Revenue-sharing mode: 0=fixed, 1=percent |
fee_mode |
Literal[0,1,2] (default: 0 ) |
❌ | Fee payer mode: 0=shopper, 1=merchant, 2=split |
multiplexingInfos |
List[MultiplexingInfo] (default: [] ) |
❌ | Optional multiplexing (split payment) configuration |
Returns
PaymentResponse
Field | Type | Description |
---|---|---|
status |
Status (enum) |
Payment status code (e.g., SUCCESS , etc.) |
track_id |
int |
Unique transaction tracking ID |
message |
str |
Human-readable result message |
Raises
ZibalError
(base error) and its subclasses depending on error code
lazy_payment(request: PaymentRequest) -> PaymentResponse
Initiates a delayed-verification payment. Identical signature and models to payment()
.
verify(request: VerifyRequest) -> VerifyResponse
Verifies payment after user redirect or callback.
Parameters
request
(VerifyRequest
)
Field | Type | Required | Description |
---|---|---|---|
track_id |
int |
✅ | Transaction tracking ID returned by Zibal |
Returns
VerifyResponse
Field | Type | Description |
---|---|---|
result |
int |
Response status code (100 = success) |
message |
str |
Result message |
amount |
int | None |
Paid amount in Rial |
status |
int | None |
Bank transaction status (1=success,2=canceled) |
paid_at |
str | None |
ISO 8601 payment timestamp |
card_number |
str | None |
Masked payer card number |
ref_number |
str | None |
Bank reference number |
order_id |
str | None |
Merchant order ID |
description |
str | None |
Additional description |
track_id |
int | None |
Tracking ID |
multiplexingInfos |
List[MultiplexingInfo] |
Optional split payment details |
Raises
ZibalError
or subclasses
callback_verify(callback: CallbackParams) -> VerifyResponse
Server-to-server verification using callback payload.
Parameters
callback
(CallbackParams
)
Field | Type | Description |
---|---|---|
track_id |
int |
Transaction ID from callback |
success |
int |
1 = success, 0 = failure |
order_id |
str |
Merchant order ID |
status |
Status | int |
Payment status code |
Returns
VerifyResponse
(same as above)
Raises
ZibalError
or subclasses
inquiry(request: InquiryRequest) -> InquiryResponse
Fetches current transaction status.
Parameters
request
(InquiryRequest
)
Field | Type | Required | Description |
---|---|---|---|
track_id |
int |
✅ | Transaction tracking ID |
Returns
InquiryResponse
Field | Type | Description |
---|---|---|
result |
int |
Response status code |
message |
str |
Status message |
ref_number |
int | None |
Bank reference number |
paid_at |
str | None |
Payment timestamp (ISO 8601) |
verified_at |
str | None |
Verification timestamp |
status |
int |
Payment status |
amount |
int |
Amount of transaction |
order_id |
str |
Merchant order ID |
description |
str |
Transaction description |
card_number |
str | None |
Masked card number |
wage |
int |
Associated wage |
created_at |
str |
Transaction creation timestamp |
multiplexingInfos |
List[MultiplexingInfo] |
Revenue sharing details |
get_payment_redirect_url(track_id: int) -> str
Builds the URL for redirecting the user to Zibal’s payment page.
Parameters
track_id
(int
): Tracking ID frompayment()
orlazy_payment()
.
Returns
str
: Complete redirect URL.
Example:
Result: https://gateway.zibal.ir/start/123456
Note: Methods can be used in synchronous or asynchronous contexts. Just use
await
in async functions.
Exception Handling
All Zibal-specific errors inherit from ZibalError
. The gateway automatically raises the proper subclass based on the status code.
Zibal error subclasses:
MerchantNotFoundError
MerchantInactiveError
InvalidMerchantError
AmountTooLowError
InvalidCallbackUrlError
InvalidPercentModeError
InvalidMultiplexingBeneficiariesError
InactiveMultiplexingBeneficiaryError
MissingSelfBeneficiaryError
AmountMismatchInMultiplexingError
InsufficientWalletBalanceForFeesError
AmountExceedsLimitError
InvalidNationalCodeError
AlreadyConfirmedError
PaymentNotSuccessfulError
InvalidTrackIdError
Sandbox Testing
🧪 Test Mode: To use Zibal in sandbox mode, set your
merchant_id
to the string"zibal"
. This simulates transactions for development purposes.
This lets you safely test the entire payment flow without processing real transactions.