Close
    logo

    Webhook

    Receive payment and refund event notification with webhook

    Listen for payment and refund event on your website so your integration can automatically trigger reactions.

    Kashier uses webhook to notify your application when an payment and refund event happens in your account. Webhook are particularly useful for asynchronous events.

    Our notifications are webhook informing you of payment status updates. Notifications are crucial for a successful integration with Kashier, and the only way you'll receive automatic updates about payment event that are processed asynchronously. For example, for many local payment methods such as paymentRequest, the outcome of a payment request might take several hours to confirm. After we know whether the payment attempt was initiated, we send you a notification to inform you of this.

    You can use notifications to automate business processes, for example order management or downloading reports for accounting.

    Begin using webhook with your Kashier integration in just two steps:

    What are webhooks

    Webhooks refers to a combination of elements that collectively create a notification and reaction system within a larger integration.

    Metaphorically, webhooks are like a phone number that Kashier calls to notify you of activity in your Kashier account. The activity could be successful transaction. The webhook endpoint is the person answering that call who takes actions based upon the specific information it receives.

    Non-metaphorically, the webhook endpoint is just more code on your server, which could be written in Ruby, PHP, Node.js, or whatever. The webhook endpoint has an associated URL (e.g., https://example.com/webhooks). The Kashier notifications are Payment and refund Event object. This Event object contains all the relevant information about transaction just happened, including the data associated with that event. The webhook endpoint uses the event details to take any required actions.

    Webhooks can also be used to provide state and API responses to services or systems that use Kashier data for things like replication, analytics, or alerting.

    Build a webhook endpoint

    Learn how to set up and deploy a webhook to listen to event from Kashier. Use webhook for post-payment commerce event such as sending custom email receipts, fulfilling orders, or updating your database.

    Setp 1: Set up an endpoint

    setting your webhook by passing your webhook url to Payment UI and Kashier API.

    Setp 2: Create a webhook endpoint on your server.


    A webhook is an endpoint on your server that receives requests from kashier, notifying you about payment and refund event that happen on your account. Add a new endpoint to your server and make sure it's publicly accessible so we can send unauthenticated POST requests.

    Read the event data

    Kashier sends the event data in the request body. Each event is structured as an Event object with a payload that contains transaction details.

    • pay
    • refund
    • authorize
    • void
    • capture

    Click here to expandClick here to shrink
    1{
    2 "event": "pay",
    3 "data": {
    4 "merchantOrderId": "1642935044835",
    5 "kashierOrderId": "efb3d440-e3bf-4c86-b98e-c7bb1cbbcca1",
    6 "orderReference": "TEST-ORD-33581",
    7 "transactionId": "TX-249893122",
    8 "status": "SUCCESS",
    9 "method": "card",
    10 "creationDate": "2022-01-23T10:50:54.261Z",
    11 "amount": 11334,
    12 "currency": "EGP",
    13 "card": {
    14 "cardInfo": {
    15 "cardHolderName": "John Doe",
    16 "cardBrand": "Mastercard",
    17 "maskedCard": "511111******1118"
    18 },
    19 "merchant": { "merchantRedirectURL": "http://localhost:9000/callback" },
    20 "amount": 11334,
    21 "currency": "EGP"
    22 },
    23 "metaData": { "time": "2022-01-23T10:50:52.562Z" },
    24 "sourceOfFunds": {
    25 "cardInfo": {
    26 "maskedCard": "511111******1118",
    27 "cardBrand": "Mastercard",
    28 "cardHash": "b506253054c1bd027e272d6f9bf78cdb5087d4c7e56f5c2be7a45361ea274b1c",
    29 "expiryYear": "06",
    30 "expiryMonth": "22",
    31 "cardHolderName": "John Doe",
    32 "ccvToken": "02c989be-456a-451a-aab4-bebab8a8189d",
    33 "cardDataToken": "796f2c37-1dc8-473e-a4c3-44905b21fda0"
    34 },
    35 "3DSecure": { "processACSRedirectURL": "https://test-iframe.payformance.io/v2/3ds" }
    36 },
    37 "transactionResponseCode": "00",
    38 "transactionResponseMessage": { "en": "Approved", "ar": "تمت الموافقة" },
    39 "channel": "online | e-commerce",
    40 "merchantDetails": {
    41 "MCC": "1731",
    42 "businessIndustry": "tourism_hotels",
    43 "merchantId": "MID-24-989",
    44 "storeName": "Test-Kashier"
    45 },
    46 "signatureKeys": [
    47 "amount",
    48 "channel",
    49 "currency",
    50 "kashierOrderId",
    51 "merchantOrderId",
    52 "method",
    53 "orderReference",
    54 "status",
    55 "transactionId",
    56 "transactionResponseCode"
    57 ],
    58 "platform": {}
    59 }
    60}
    You can reconcile your orders by passing merchantOrderId key to kashier. Learn more about order reconciliation

    Responding to an event

    You should respond to an event with a 200 OK. We consider this an acknowledgement by your application. If your application responds with any status outside of the 2xx range, we will consider it unacknowledged and thus, continue to send it every 5 minute for 15 minutes then send again every 8 hours for 24 hours. You don't need to send a request body or some other parameter as it would be discarded - we only pay attention to the status code.

    If your application is likely to start a long running task in response to the event, Kashier may timeout waiting for the response and would ultimately consider the event unacknowledged and queue to be raised later. You can mitigate duplicity by having your application respond immediately with a 200 before it goes on to perform the rest of the task.

    Signature

    Kashier uses hashing to ensure that connection shared between your server and Kashier over network have not been tampered with. We use SHA256 hashing to ensure the safety of transaction data.

    To generate the signature of this model, you should order only elements of signatureKeys array in data payload alphabetic. Elements of signatureKeys array represent keys of data object which using them to caculate the HAMC Signature, So you should select those keys and their values from received data object from received payload. After that you should generate signature payload like below.

    amount=1&channel=online%20%7C%20e-commerce&currency=EGP&kashierOrderId=9ad06b17-755b-4e21-9774-aff3e2726ac9&merchantOrderId=1653481557813&method=card&orderReference=TEST-ORD-38855&status=SUCCESS&transactionId=TX-249893963&transactionResponseCode=00

    Now you can encrypt signature payload by the Payment Api key then compare both Signature values, the one you received with the sent request from kashier in request headers associated with key called x-kashier-signature and the one you generated out of this request if both are equal, you can safely save this data and use it in your system. see expamles

    You must use The payment Api Key That you uses it to create Payment Hash. You can find Payment Api Key in your dashboard under Integrations Section.


    Click here to expandClick here to shrink
    1const app = require('express')();
    2// Use body-parser to retrieve the raw body as a buffer
    3const bodyParser = require('body-parser');
    4const crypto = require('crypto');
    5const queryString = require('query-string');
    6const _ = require('underscore');
    7
    8router.post('/', (req, res) => {
    9 const { data, event } = req.body;
    10 data.signatureKeys.sort();
    11 const objectSignaturePayload = _.pick(data, data.signatureKeys);
    12
    13 const signaturePayload = queryString.stringify(objectSignaturePayload);
    14
    15 const signature = crypto
    16 .createHmac('sha256', PaymentApiKey)
    17 .update(signaturePayload)
    18 .digest('hex');
    19
    20 const kashierSignature = req.header('x-kashier-signature');
    21
    22 if (kashierSignature === signature) {
    23 console.log('valid signature');
    24 } else {
    25 console.log('invalid signature');
    26 }
    27});
    28
    29app.listen(8000, () => console.log('Running on port 8000'));

    Congratulations!

    You have a basic webhook endpoint ready to accept payment and refund event from Kashier. Now add the application logic that your business needs to handle the event.

    Payment — Previous
    Void
    Next — Payment
    Order Reconciliation