Payment webhooks

Payment webhooks

If you set the notifications.webhook parameter when you create a payment request, you will receive a notification every time a payment is completed. In other words, HandCash will send an HTTP request to your server under the defined URL.

The endpoint you specified will receive a POST request with the following parameters:

  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)

Your server must return 200 once you have successfully processed the notification. Otherwise, HandCash will retry exponentially for 24 hours.

Payment webhooks provide you with all the flexibility you need to trigger any custom process in your product:

  • Unlock premium content - Build your custom paywall
  • Send a digital good like an ebook via email
  • Send a confirmation email and ship the product
  • Build your own Point-of-Sale system
  • Any custom online checkout


Keep it secure

Anyone could send an HTTP request to your server and fake a payment confirmation.
So make sure the appSecret included in the body of the webhook matches your appSecret. That would confirm that the HTTP call is invoked directly from HandCash to your service.

Updating the payment status in your application

HandCash Cloud will send a webhook notification to your server. However, your application still needs to be aware of the payment status to update the UI. The diagram below proposes a simple integration of components based on polling.

You can define an endpoint in your server that exposes the payment status given its id. On the other hand, your front end would query that endpoint every few seconds until the payment status is confirmed.

Another more sophisticated approach you might consider is using real-time communication services like Pusher.

Eventually, it's up to you to decide whatever suits best your needs.