ZarinPalInstall

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, ensuring the payment was successful.

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

Example:

• After creating a payment, the node provides a URL to redirect the customer.
• Upon receiving a callback, the node verifies the payment status and outputs detailed transaction information.

Properties

Output

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

• Create Payment output includes:

  • status: "success" if creation succeeded.
  • authority: Unique authority code for the payment.
  • 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:

  • If verification succeeds:
    • status: "verified".
    • authority: Authority code.
    • refId: Reference ID from ZarinPal.
    • cardHash, cardPan: Card details (masked).
    • amount and amountInRial.
    • zarinpalStatus: Numeric status code.
    • message: Human-readable status message.
    • verifiedAt: Verification timestamp.
    • transactionData: Summary of transaction including merchant ID, authority, refId, amount, status, and paid date.
  • If verification fails or payment was cancelled:
    • status: "failed" or "verification_failed".
    • message: Explanation of failure.
    • authority, amount, zarinpalStatus (if available).
    • verifiedAt: Timestamp.

The node does not output binary data.

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 a valid merchant ID from credentials.
• For webhook callbacks, it either uses a user-provided callback URL or auto-generates one based on the n8n instance URL.

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 can cause operation failures.

• Error messages:

  • "Amount is required and must be greater than 0": Ensure the amount input is positive and provided.
  • "Description is required": Provide a non-empty description for the payment.
  • "ZarinPal API Error: <code> - <message>": Indicates an error response from ZarinPal; check API credentials and parameters.
  • Verification failure messages include codes and localized Persian explanations for common error codes (e.g., invalid request, merchant issues).

• Resolution tips:

  • Verify API credentials and merchant ID are correct.
  • Confirm that the callback URL is reachable and correctly configured.
  • Use the sandbox mode for testing before switching to production.
  • Handle the "failed" status gracefully in workflows to manage cancelled or unsuccessful payments.

Links and References

• ZarinPal Official Documentation
• ZarinPal API Reference
• n8n Webhook Documentation (for setting up callback URLs)