- Created by user-5c3b0, last modified on Jul 18, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 3 Next »
As a fintech, you will be performing the following actions to set up a webhook against the available Fusion event types. In this tutorial, you will learn about how to set up a webhook that can be used to receive a payment event notification.
For the complete list of Payment Webhook APIs, see Payment Core API Reference.
Configure a webhook
Keep a webhook endpoint ready that can receive JSON objects and support basic HTTP authentication. Share this endpoint with Zeta. Zeta will register the webhook endpoint in Fusion platform and share a secret token with you to validate the incoming webhook messages.
Select a Payment Event
Before creating a webhook, let's find out Fusion events that are available for you to configure a webhook. See Supported Events for a list of events that you can subscribe to.
Add a webhook
Set up your webhook to handle incoming payment messages using /payment/events/{eventName}/subscribe
endpoint and pass the event object, eventName
, in the path parameter that you obtained from Select a Payment Event step. Specify a webhook endpoint, callbackUrl
in the body parameter.
To add a webhook against a payment event, use the following endpoint:
POST | api/v1/ifi/{ifiID}/payment/events/{eventName}/subscribe |
Example
Request
Response
curl -X POST \ https://fusion.preprod.zeta.in/api/v1/ifi/140827/payment/event/PAYMENT_REQUESTED/subscribe \ -H 'authorization: {{auth-token}} \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "callbackUrl": "http://customer-prod-api.in/callback" } }'
N/A
Test a webhook
After you've subscribed for a payment and A2A transfer event notification, simulate an Ecom, ATM or POS transaction and check the webhook endpoint for any possible notification. The webhook endpoint is the callbackUrl
you've configured in the previous step against a payment event (eventName
). If you receive a webhook message, proceed to the next step to verify that the incoming message delivered from a secured Fusion endpoint.
Contact Zeta Support to simulate and test a payment webhook.
Payment Event
A2A Transfer Event
A new sample payment event would look something like this after the webhook configuration and subscription. Note the topic
, name
, eventID
, source
, origin
and data
objects in the payload below:
{ "topic": "_tenant_140827_RESOURCE", "name": "RESOURCE_PAYMENT_CREATED", "eventID": "fc529204-126e-4b37-8308-02bdd1a29b52", "source": { "uri": "resource://140827/0c97e84f-999d-4fdf-a53f-24cb99b11e76/870544000001", "tags": [ "tag://VBO/ABC001", "tag://VBO/ABC001" ], "state": "PAYMENT_REQUESTED" }, "origin": { "instance": "instance://default/payment/870544", "time": 1582108024106, "flowID": "4807977e-fe36-4f03-be80-3b67dfbf23a9" }, "data": { "paymentID": 870544000001, "currentState": "PAYMENT_REQUESTED", "stateTransitions": { "PAYMENT_REQUESTED": { "time": 1582108023741 } }, "payerInfo": { "resourceID": "0c97e84f-999d-4fdf-a53f-24cb99b11e76", "formFactorURI": "card://ff936322-287f-43e4-9497-a86d94bd97a9", "targetURI": "account://6b2dfb83-9276-422c-8781-07eda71fc261", "type": "RESOURCE" }, "payeeInfo": { "type": "EXTERNAL_BUSINESS", "name": "TEST MERCHANT", "location": "MUMBAI" }, "receipt": [], "attributes": { "super-card.trans-id": "M00001_T00001_111111_022030_486837818528_200219102702", "super-card.rrn": "486837818528", "super-card.ifi": "140827", "super-card.card-6x4": "508645-xxxxxx-0289", "super-card.merchant-country": "IN", "journal.voucherCode": "RUPAY-508645_ECOM_AUTH", "super-card.merchant-city": "MUMBAI", "super-card.acquirer": "111111", "super-card.acs-txnId": "028852720888773631103971827607", "super-card.merchant-lat": "18.975", "super-card.card-bin": "508645", "credentials.signatory": "10276@zetauser.zeta.in/1", "super-card.stan": "022030", "super-card.mid": "M00001", "super-card.tid": "T00001", "super-card.mcc": "5411", "super-card.merchant-lon": "72.825833", "super-card.txn-type": "ECOM", "super-card.otp-enter-mode": "manual", "supercard-card.authentication-type": "DYNAMIC_PIN", "super-card.merchant-name": "TEST MERCHANT", "super-card.card-id": "resource://0c97e84f-999d-4fdf-a53f-24cb99b11e76_ff936322-287f-43e4-9497-a86d94bd97a9", "super-card.ink": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36", "super-card.init-time": "200219102702" } }, "publisher": { "appDomain": "services.fusion", "serviceName": "payment", "nodeId": "870544" } }
A new A2A transfer event would look something like this after the webhook configuration and subscription. Note the topic
, name
, eventID
, source
, origin
and data
objects in the payload below:
{ "data": { "topic": "_tenant_140827_a2aTransfer", "name": "TRANSFER_CREATED", "eventID": "f62fa71f-7cc0-478d-b896-abf74e675e0f", "source": { "uri": "a2aTransfer://140827/c8b0ffbe-93f6-46a1-86e9-bb3213d42a38?publishingApp=fusion", "tags": [ "tag://vbo-id/4fa18593-d2d9-4bf3-bea7-7f6deb9f2ca4?publishingApp=fusion" ], "state": "COMPLETED" }, "origin": { "instance": "instance://default/fusion/295411", "time": 1590736346458, "flowID": "64e276bc-3908-43f7-978a-b58155da5127" }, "data": { "ifiId": 140827, "transferRequest": { "requestID": "c8b0ffbe-93f6-46a1-86e9-bb3213d42a38", "currency": "INR", "amount": 1000000, "transferCode": "ATLAS_P2M_AUTH", "debitAccountID": "3867f3ac-fa4b-4f7c-859c-41bbeb586c45", "creditAccountID": "0e7381cc-a1f3-4af7-9a50-f120be76b1b8", "transferTime": 12324254832342, "remarks": "TEST", "attributes": {} }, "transferResponse": { "requestID": "c8b0ffbe-93f6-46a1-86e9-bb3213d42a38", "transferID": "20200529071226316_28033_c8b0ffbe-93f6-46a1-86e9-bb3213d42a38", "status": "SUCCESS" } }, "publisher": { "appDomain": "services.olympus", "serviceName": "fusion", "nodeId": "295411" }, "emitterType": "EVENT" }, "attributes": { "topic": "_tenant_140827_a2aTransfer" } }
Validate a webhook
Ensure that you have already shared the webhook endpoint with Zeta. Zeta will register the webhook endpoint in Fusion platform.
You must verify every incoming event to ensure the messages are delivering from a secured Fusion endpoint. Zeta will share a secret token with you to verify the authenticity of the message. Using the secret token, you can generate an HMAC (Hash-based Message Authentication Code) signature to match with the X-Zeta-HMAC that is passed in the header along with the event message.
To validate a webhook
You can use the ZetaHmacVerificationUtil
class to validate the webhook:
package com.company.mypackage; import static com.google.common.hash.Hashing.sha256; import static java.nio.charset.StandardCharsets.UTF_8; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Base64; import javax.annotation.Nonnull; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class ZetaHmacVerificationUtil { private static final String HMAC_SHA_512 = "HmacSHA512"; /** * @param data - the raw bytes extracted from the received event body * @param secretBase64 - the secret shared by Zeta, Base64 encoded * @param nonce - the Nonce value from the HTTP header with the key X-Zeta-Nonce * @param incomingZetaHmac - the HMAC value extracted from the HTTP header with the key X-Zeta-HMAC * @return - true if the incoming HMAC is equal to the Zeta-computed HMAC, false otherwise */ public static boolean verifyZetaHmac( @Nonnull byte[] data, @Nonnull String secretBase64, @Nonnull String nonce, @Nonnull String incomingZetaHmac) { return incomingZetaHmac.equals(computeZetaHmac(data, secretBase64, nonce)); } /** * @param data - the raw bytes extracted from the received event body * @param secretBase64 - the secret shared by Zeta, Base64 encoded * @param nonce - the Nonce value from the HTTP header with the key X-Zeta-Nonce * @return - the Zeta-computed HMAC */ public static String computeZetaHmac(byte[] data, String secretBase64, String nonce) { byte[] nonceBytes = nonce.getBytes(UTF_8); byte[] hmacDataWithNonce = computeHMAC512(data, hashSha256(nonceBytes)); byte[] secretBytes = base64Decode(secretBase64.getBytes(UTF_8)); return new String(base64Encode(computeHMAC512(hmacDataWithNonce, secretBytes))); } private static byte[] computeHMAC512(byte[] data, byte[] secret) { try { final Mac sha512_HMAC = Mac.getInstance(HMAC_SHA_512); final SecretKeySpec keySpec = new SecretKeySpec(secret, HMAC_SHA_512); sha512_HMAC.init(keySpec); return sha512_HMAC.doFinal(data); } catch (NoSuchAlgorithmException | InvalidKeyException e) { throw new RuntimeException("FAILED_TO_COMPUTE_HMAC"); } } private static byte[] hashSha256(byte[] toHash) { byte[] hash = new byte[32]; sha256().hashBytes(toHash) .writeBytesTo(hash, 0, 32); return hash; } private static byte[] base64Decode(byte[] bytes) { return Base64.getDecoder().decode(bytes); } private static byte[] base64Encode(byte[] bytes) { return Base64.getEncoder().encode(bytes); } }
- Extract the raw bytes from the received event body
- Extract the Nonce value from the HTTP header with the key
X-Zeta-Nonce
- Extract the HMAC value from the HTTP header with the key
X-Zeta-HMAC
- Invoke the
verifyZetaHmac
function of theZetaHmacVerificationUtil
class, with the argumentsdata
(from step 1),base64EncodedSecret
(shared by Zeta),nonce
(from step 2),hmac
(from step 3). The method returns true if the incoming HMAC is equal to the Zeta-computed HMAC, and false otherwise. If the method returns true, you can consider the event message is valid and sent over secured Fusion connection. If it returns false, reject the message and report to Zeta for further analysis. - Alternatively, you can invoke
ZetaHmacVerificationUtil#computeZetaHmac
with the data from steps 1 and 2, along with the secret token shared by Zeta, to generate the HMAC on your own. Compare the generated HMAC with the extracted HMAC (from step 3). If both are identical, the message is valid and authentic.
Contact Zeta Support to obtain the secret token or any help to validate a payment webhook.
Related articles
About EventsLearn about supported Fusion events. |
Webhook APIsLearn more about webhook APIs |
Payment LifecycleKnow about various payment events and its lifecycle. |
- No labels