ZarinPal

Interact with ZarinPal payment gateway
Join our community

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 collection and confirmation.

Practical example:
A store owner uses this node to create a payment request when a customer places an order. The customer is redirected to the payment page via the returned URL. After payment, the node verifies the transaction to confirm success and update order status accordingly.

Properties

Name Meaning
Amount Payment amount in Toman (minimum 1000).
Description Description of the payment (e.g., "Payment for order #123").
Order ID Optional order identifier for tracking purposes (e.g., "ORD-123456").
Callback URL URL to which ZarinPal will send payment result callbacks. If empty, an auto-generated webhook URL is used.
Mobile Optional customer mobile number.
Email Optional customer email address.

Output

The node outputs JSON data describing the result of the operation:

  • Create Payment:

    • status: "success" if the payment request was created successfully.
    • 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 (Toman × 10).
    • description, orderId, merchantId, callbackUrl: Details of the payment.
    • webhookInstructions: Guidance on setting up a webhook node in n8n to handle payment verification.
    • Optional customer info: mobile, email.
    • createdAt: Timestamp of creation.

  • Verify Payment:

    • On success:
      • status: "verified".
      • authority: Authority code.
      • refId: Reference ID from ZarinPal.
      • cardHash, cardPan: Card details (masked).
      • amount, amountInRial: Payment amounts.
      • zarinpalStatus: Status code (100 or 101).
      • message: Verification message.
      • verifiedAt: Timestamp of verification.
      • transactionData: Object summarizing transaction details.
    • On failure or cancellation:
      • status: "failed" or "verification_failed".
      • message: Explanation of failure or cancellation.
      • authority, callbackStatus, amount, zarinpalStatus as applicable.
      • verifiedAt: Timestamp.

No binary data output is produced by this node.

Dependencies

  • Requires an API key credential for authenticating with the ZarinPal payment gateway.
  • Needs network access to ZarinPal's API endpoints.
  • The node optionally uses the n8n instance base URL to generate callback URLs if none are provided.
  • For sandbox testing, the node switches to ZarinPal’s sandbox environment based on credential configuration.

Troubleshooting

  • Common issues:

    • Missing or invalid amount: The node throws an error if the amount is not provided or less than 1000 Toman.
    • Missing description: The node requires a non-empty description.
    • Invalid callback URL: If no callback URL is provided, the node generates one; ensure your n8n instance is accessible externally for callbacks.
    • API errors: The node surfaces ZarinPal API error codes and messages. Common error codes include authentication failures, invalid parameters, or transaction issues.

  • Error messages:

    • "Amount is required and must be greater than 0": Provide a valid amount ≥ 1000.
    • "Description is required": Provide a meaningful description.
    • "ZarinPal API Error: <code> - <message>": Check the error code and message returned by ZarinPal; refer to ZarinPal documentation or the node’s error code mapping for details.
    • Verification failures return detailed status and messages indicating reasons such as cancelled payments or mismatched amounts.

  • Resolution tips:

    • Verify credentials and merchant ID correctness.
    • Ensure the callback URL is reachable by ZarinPal.
    • Confirm the amount matches between creation and verification steps.
    • Use sandbox mode for testing without real transactions.

Links and References

Discussion