Overview
This node acts as a webhook trigger for ZarinPal payment callbacks. It listens for payment status events sent by the ZarinPal payment gateway and triggers workflows based on those events. The node is useful in scenarios where you want to automate processes after receiving payment confirmations or failures, such as updating order statuses, sending notifications, or logging transactions.
Practical examples:
- Trigger a workflow when a payment is successful to update an order's status in your database.
- Trigger a workflow on payment failure to notify customers or retry payment.
- Handle all payment callback events to maintain comprehensive payment logs.
Properties
| Name | Meaning |
|---|---|
| Events | Select which payment events to listen for: "Payment Success", "Payment Failed", or "All Events". |
| Return HTML Page | Boolean option to decide whether to return an HTML page to the user after payment callback. |
| Success Page URL | URL to redirect the user to upon successful payment (used only if "Return HTML Page" is false). |
| Failed Page URL | URL to redirect the user to upon failed payment (used only if "Return HTML Page" is false). |
Output
The node outputs JSON data containing details about the payment callback event. The structure includes:
authority: A unique code identifying the payment transaction.status: The raw status string received from the payment gateway.isSuccess: Boolean indicating if the payment was successful (trueif status is "OK").eventType: Either"paymentSuccess"or"paymentFailed"depending on the payment result.receivedAt: ISO timestamp of when the callback was processed.queryParameters: The full set of query parameters received in the webhook request.
If configured to return HTML, the node responds with a styled success or failure page in Persian language. Otherwise, it can redirect the user to specified URLs on success or failure.
Dependencies
- Requires a publicly accessible webhook endpoint to receive HTTP GET requests from ZarinPal.
- No external API keys or credentials are needed within this node itself since it only handles incoming callbacks.
- The node depends on n8n’s webhook infrastructure to function properly.
Troubleshooting
- No workflow trigger: Ensure that the webhook URL is correctly registered in ZarinPal and that the payment gateway sends callbacks to the exact path.
- Events not triggering: Verify that the selected "Events" property includes the event type being sent by ZarinPal. If "All Events" is not selected, specific events must be chosen.
- HTML page not showing: If "Return HTML Page" is disabled but no redirect URLs are provided, the node will output JSON instead of redirecting or showing a page.
- Unexpected status values: The node expects the
Statusquery parameter to be"OK"(case-insensitive) for success; other values are treated as failure. If ZarinPal changes their response format, the node may need updates.