Payment Webhooks

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

1. Your server must return a 200 status code once you have successfully processed the notification.
2. 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:

1. Verify that the appSecret in the webhook payload matches your app’s secret.
2. 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

1. Implement proper error handling in your webhook endpoint.
2. Use HTTPS for your webhook URL to ensure secure communication.
3. Consider implementing a queue system if you expect high volumes of webhooks.
4. Log all received webhooks for debugging and auditing purposes.
5. Implement idempotency to handle potential duplicate webhooks.