ZarinPal

Overview

This node integrates with the ZarinPal payment gateway, enabling users to create and verify payments within an n8n workflow. It supports two main operations:

• Create Payment: Initiates a new payment request by specifying amount, description, and optional customer details. It returns a payment URL for redirecting customers to complete the payment.
• Verify Payment: Confirms the status of a payment after the user is redirected back from the payment gateway callback, using authority code and status received from the callback.

Typical use cases include automating online payment processing in e-commerce workflows, subscription services, or any scenario requiring seamless payment handling and verification without manual intervention.

Example:

• Create a payment request for an order, send the payment URL to the customer.
• After payment completion, verify the payment status automatically via webhook callback data.

Properties

Output

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

• For Create Payment:

  • status: "success" if creation succeeded.
  • authority: Unique authority code for the payment.
  • paymentUrl: URL where the customer can complete the payment.
  • amount: Payment amount in Toman.
  • amountInRial: Payment amount converted to Rial (amount * 10).
  • 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.

• For Verify Payment:

  • If status is not "OK", outputs failure status with message indicating cancellation or failure.
  • On successful verification (code 100 or 101):
    • status: "verified".
    • authority: Authority code.
    • refId: Reference ID from ZarinPal.
    • cardHash, cardPan: Card details (masked).
    • amount, amountInRial: Payment amounts.
    • zarinpalStatus: Numeric status code.
    • message: Human-readable verification message.
    • verifiedAt: Verification timestamp.
    • transactionData: Summary of transaction including merchant ID, authority, refId, amount, status, and paid timestamp.
  • On verification failure:
    • status: "verification_failed".
    • authority, amount, zarinpalStatus, message: Error details.
    • verifiedAt: Timestamp.

No binary data output is produced by this node.

Dependencies

• Requires an API key credential for authenticating with the ZarinPal payment gateway.
• Uses HTTP requests to ZarinPal's sandbox or production endpoints depending on configuration.
• The node expects the n8n instance base URL for generating callback URLs if none is provided.
• Requires proper webhook setup in n8n to handle payment callbacks for verification.

Troubleshooting

• Common issues:

  • Missing or invalid amount during payment creation will cause errors.
  • Empty or invalid description during payment creation will cause errors.
  • Incorrect authority or status values during verification may lead to failed verification.
  • Network or API errors from ZarinPal may cause operation failures.

• Error messages:

  • "Amount is required and must be greater than 0": Ensure the amount input is positive and set.
  • "Description is required": Provide a non-empty description for the payment.
  • "ZarinPal API Error: <code> - <message>": Indicates an error response from ZarinPal API; check credentials, parameters, and network connectivity.
  • Verification failure messages include detailed codes and Persian descriptions explaining the error cause (e.g., invalid request, IP restrictions, duplicate transactions).

• To resolve errors, verify all required inputs, ensure valid API credentials, and confirm that the callback URL is accessible and correctly configured.

Links and References

• ZarinPal Official Documentation
• ZarinPal API Reference
• n8n Webhook Documentation