Pardakht 💰

Pardakht is a simple Python library to integrate bots or applications with payment gateways.
Currently, it supports ZarinPal, PayPing, and Zibal.

Installation

pip install pardakht

Usage

1️⃣ ZarinPal Integration

Import and Initialize

from pardakht.dargah import ZarinPal

# Settings
MERCHANT_ID = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
CALLBACK_URL = "https://yourdomain.com/check-payment"

# Create an instance of ZarinPal
zarinpal = ZarinPal(merchant_id=MERCHANT_ID, callback_url=CALLBACK_URL, sandbox=True)

Create a Payment and Get the Payment Link

amount = 10000  # Amount in Tomans
uuid_code = "some-unique-id-1234"  # You can use uuid.uuid4() for unique transactions
description = "Premium subscription purchase"

pay_url = zarinpal.make_payment(amount, uuid_code, description)

if pay_url.startswith("http"):
    print("Payment link:", pay_url)
else:
    print("Error:", pay_url)

⚡ If there is an issue connecting to the gateway, it will return:
"Failed to connect to the payment gateway."

Verify the Payment After User Returns from Gateway

authority = "A1B2C3D4E5"  # Obtained from query params or gateway payload
result = zarinpal.verify_payment(authority, amount)

if result["success"]:
    print("Payment successful ✅")
    print("Tracking code:", result["ref_id"])
else:
    print("Payment failed ❌")
    print("Message:", result["message"])

2️⃣ PayPing Integration

Import and Initialize

from pardakht.dargah import PayPing

# Settings
API_KEY = "YOUR_PAYPING_API_KEY"

# Create an instance of PayPing
payping = PayPing(api_key=API_KEY)

Create a Payment and Get the Payment Link

amount = 10000  # Amount in your currency unit
return_url = "https://yourdomain.com/callback"
payer_identity = "user@example.com"
description = "Premium subscription purchase"

payment_data = payping.create_payment(
    amount=amount,
    return_url=return_url,
    payer_identity=payer_identity,
    description=description
)

# Extract payment code to start the payment
payment_code = payment_data.get("metaData", {}).get("code")

if payment_code:
    pay_url = payping.start_payment(payment_code)
    print("Payment link:", pay_url)
else:
    print("Error creating payment:", payment_data)

Verify the Payment After User Returns from Gateway

ref_id = "REF_ID_FROM_CALLBACK"  # Obtained from callback parameters
payment_code = "PAYMENT_CODE"    # The same code returned from create_payment

result = payping.verify_payment(ref_id, payment_code)

if result.get("status") == 0:
    print("Payment verified successfully ✅")
else:
    print("Payment verification failed ❌")
    print("Details:", result)

3️⃣ Zibal Integration

Import and Initialize

from pardakht.dargah import Zibal

# Settings
MERCHANT = "zibal"  # Or your specific merchant code / zibal sandbox merchant "zibal"

# Create an instance of Zibal
zibal = Zibal(merchant=MERCHANT)

Create a Payment and Get the Payment Link

amount = 10000  # Amount in Rials or Tomans based on your merchant account config
callback_url = "https://yourdomain.com/zibal-callback"
order_id = "12345"
description = "Python Course Subscription"
mobile = "09123456789"

# Send request to Zibal
response = zibal.request_payment(
    amount=amount,
    callback_url=callback_url,
    order_id=order_id,
    description=description,
    mobile=mobile
)

if response.get("result") == 100:
    track_id = response.get("trackId")
    pay_url = zibal.start_payment(track_id)
    print("Payment link:", pay_url)
    print("Track ID (save this):", track_id)
else:
    print("Error creating Zibal payment:", response.get("message"))

Verify the Payment After User Returns from Gateway

track_id = 123456789  # Obtained from callback query parameters (?trackId=...)
amount = 10000        # The exact transaction amount

result = zibal.verify_payment(track_id=track_id, amount=amount)

result_code = result.get("result")
if result_code == 1:
    print("Payment verified successfully ✅")
    print("Reference Number (RefID):", result.get("refNumber"))
    print("Card Number:", result.get("cardNumber"))
else:
    # Get human-readable status message using status_message helper
    error_msg = Zibal.status_message(result_code)
    print("Payment verification failed ❌")
    print(f"Status Code: {result_code} - Message: {error_msg}")

4️⃣ Notes

• Always generate a unique ID (uuid) for each ZarinPal transaction to track it in your database.
• Store payment code and ref_id for PayPing transactions to verify later.
• Store trackId for Zibal transactions to verify or inquiry them later.
• In Telegram bots, you can use pay_url as an inline button for users to click.
• Use sandbox=True during testing in ZarinPal to avoid real transactions (Zibal also supports test merchant "zibal" for sandbox usage).
• Handle errors gracefully and validate the response from each gateway before confirming the transaction.