ZarinPal

Interact with ZarinPal payment gateway

Actions2

Overview

This node integrates with the ZarinPal payment gateway to facilitate online payment processing. It supports two main operations: creating a new payment request and verifying a payment after the user completes or cancels it.

  • Create Payment: Generates a payment request with specified amount, description, and optional customer details. It returns a payment URL where the customer can complete the transaction.
  • Verify Payment: Confirms the status of a payment using an authority code received from the payment callback, ensuring the payment was successful and retrieving transaction details.

Common scenarios:

  • E-commerce platforms needing to initiate payments and verify them automatically.
  • Subscription services requiring payment verification before granting access.
  • Any workflow that requires integration with ZarinPal for payment handling within n8n automation.

Practical example:

  • A store owner uses this node to create a payment link for an order, sends it to the customer, then verifies the payment once the customer completes it, triggering further fulfillment steps.

Properties

Name Meaning
Amount Payment amount in Toman (minimum 1000).
Description Description of the payment purpose (required).
Order ID Optional order identifier for tracking payments.
Callback URL URL to which ZarinPal redirects after payment; leave empty to use auto-generated webhook.
Mobile Optional customer mobile number.
Email Optional customer email address.

Output

The node outputs JSON objects representing the result of the operation:

  • Create Payment output includes:

    • status: "success" if payment request created.
    • authority: Unique payment authority code.
    • paymentUrl: URL to redirect the customer for payment.
    • amount and amountInRial: Payment amount in Toman and Rial.
    • description, orderId, merchantId, callbackUrl: Metadata about the payment.
    • webhookInstructions: Guidance on setting up webhook nodes for verification.
    • Optional customer info (mobile, email).
    • createdAt: Timestamp of creation.

  • Verify Payment output includes:

    • status: "verified" if payment confirmed, or "failed"/"verification_failed" otherwise.
    • authority: Payment authority code.
    • refId: Reference ID from ZarinPal.
    • cardHash, cardPan: Card details (masked).
    • amount and amountInRial: Verified payment amount.
    • zarinpalStatus: Status code from ZarinPal.
    • message: Human-readable status message.
    • verifiedAt: Timestamp of verification.
    • transactionData: Detailed transaction info including merchant ID, refId, amount, status, and paid timestamp.

If the payment is cancelled or fails, the output reflects failure status with appropriate messages.

Dependencies

  • Requires an API key credential for ZarinPal (merchant ID).
  • Uses ZarinPal's REST API endpoints; supports sandbox and production modes.
  • Needs n8n instance base URL configured for generating callback URLs if not provided manually.
  • HTTP request helper from n8n framework for API communication.

Troubleshooting

  • Amount validation error: The amount must be greater than zero and at least 1000 Toman. Ensure correct input.
  • Description required: Description cannot be empty; provide meaningful text.
  • API errors: If ZarinPal API returns an error code, the node throws an error with the code and message. Common issues include invalid merchant ID, incorrect IP, or malformed requests.
  • Verification failures: If payment status is not "OK" or verification fails, the node outputs failure status with detailed error codes and messages.
  • Callback URL missing: If no callback URL is provided, the node generates one based on the n8n instance URL. Make sure your instance URL is correctly set.
  • Network issues: Ensure n8n server can reach ZarinPal endpoints; check firewall and proxy settings.

Links and References

Discussion