Best Practice

Handling HTTP Notification is crucial in order to make sure that your integration's business logic works as expected. Here are some best practices that you need to implement :

Handling Notification Implementation

Acknowledge HTTP Notification immediately

If your HTTP Notification endpoint performs complex logic, or makes network calls, it's possible that the endpoint would time out before DOKU sees its complete execution. Ideally, your HTTP Notification handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that notification.

Verify HTTP Notification authenticity

You must verify the HTTP Notification to make sure that it is coming from DOKU. To do that, you need to check the Signature on the Request Header that sent to you.

Before generating Signature, merchant need to prepare all the component required.

1. Set Client-Id, Request-Id, Request-Timestamp.

Use the Client-Id, Request-Id, Request-Timestamp that is placed on the Request Header.

1. Set Request-Target

The Request-Target is the path of merchant Notification URL or the Inquiry URL. For instance, if merchant set the Notification URL: https://yourdomain.com/payments/notifications. Therefore, the Request-Target value is /payments/notifications.

1. Generate Digest

Digest is the hashed of the request body. To generate the Digest:

Calculate SHA256 base64 hash from the JSON Body

1. Generating Signature

After all the Signature component has been set, merchant can now generate it:

• Arrange the signature components to one component and its value per line by adding escape character. Don't add at the end of the string. Sample of the raw format:

Client-Id:MCH-0001-10791114622547\nRequest-Id:cc682442-6c22-493e-8121-b9ef6b3fa728\nRequest-Timestamp:2020-08-11T08:45:42Z\nRequest-Target:/doku-virtual-account/v2/payment-code\nDigest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=

This is how merchant see :

Client-Id:MCH-0001-10791114622547
Request-Id:cc682442-6c22-493e-8121-b9ef6b3fa728
Request-Timestamp:2020-08-11T08:45:42Z
Request-Target:/doku-virtual-account/v2/payment-code
Digest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=

• Calculate HMAC-SHA256 base64 from all the components above using the Secret Key from DOKU Back Office

• Put encoded value and prepend HMACSHA256= to the Signature. Sample:

Signature: HMACSHA256=OvIRJs/jH8BIcGsktr4d8nnYtxY6E0Uzdm9d1GVgv5s=

Update the transaction status based on the transaction.status

All of the notifications that we send always have transaction.status parameter. The possible value is SUCCESS or FAILED. Update the transaction status on your side based on this value.

CHECKOUT IMPLEMENTATION

Checkout User Experience is designed to increase your payment success rate, meaning that it allows your customers to change payment method if one is failed. Therefore, if you are integrating with Checkout, you must ignore the transaction.status FAILED.

Handle duplicate events

HTTP Notification endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events.

Parse HTTP Notification in non-strict format​

DOKU sends the notification body as JSON, please parse the JSON with a JSON parser. Always expect new fields will be added to the notification body, so parse it in a non strict format. This prevents the parser from throwing an exception for new fields. It should gracefully ignore the new fields. This allows us to extend our notification system for newer use cases without breaking old clients.