Payment Requests
Payment Webhooks
Receive real-time notifications for completed payment requests
When you create a payment request with the notifications.webhook
parameter set, you’ll receive a notification each time a payment is completed. HandCash will send an HTTP POST request to the URL you specified.
Webhook Payload
Your endpoint will receive a POST request with the following JSON payload:
{
"appSecret": "your-app-secret",
"paymentRequestId": "9ac9182acae19902",
"transactionId": "cc066a86e48f9f5715ba12f37c2cee0f525daf310eada76217b41771d6e67e66",
"customParameters": {
// The specified customParameters in the PaymentRequest notifications (if any)
},
"userData": {
// The requested user data (if any)
}
}
Handling Webhooks
- Your server must return a
200
status code once you have successfully processed the notification. - If HandCash doesn’t receive a
200
response, it will retry with exponential backoff for 24 hours.
Security
To ensure the webhook is genuinely from HandCash:
- Verify that the
appSecret
in the webhook payload matches your app’s secret. - This confirmation ensures the HTTP call is invoked directly from HandCash to your service.
🔐 Keep it secure: Anyone could potentially send an HTTP request to your server and fake a payment confirmation. Always verify the appSecret
.
Best Practices
- Implement proper error handling in your webhook endpoint.
- Use HTTPS for your webhook URL to ensure secure communication.
- Consider implementing a queue system if you expect high volumes of webhooks.
- Log all received webhooks for debugging and auditing purposes.
- Implement idempotency to handle potential duplicate webhooks.