Integration Guides
Integration GuidesAPI SpecificationsGithubOur Releases

Instant Payment Notification

Real-time Payment Notifications

Webhooks allow you to build e-commerce applications which subscribe to certain events against your bKash account. When one of these events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. bKash signs each notification message that it delivers to your webhook listener.

Events

bKash Payment Gateway automatically notifies merchants of events related to bKash payment transactions that includes payments received from customers via:

  • bKash Checkout or Direct products
  • bKash Menu (*247#)
  • bKash App
  • bKash QR scan

Merchants can use this service to automate back-office and administrative functions, including automatically fulfilling orders and providing customers with order status.

Configure Webhook listener

A webhook listener is a server at merchant side that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. After you have completed your server setup, please share the listener URL with our technical support team during on-boarding or integration process.

Subscribe to Events

Our technical support team will setup the listener URL API provisioning against your e-commerce application.

You should receive subscription confirmation message to the configured listener URL, which should be acknowledged.

Once subscription is successful, you will now receive realtime payment notification messages to your configured URL.

Sample Payloads

Subscription Confirmation Payload

POST / HTTP/1.1
x-amz-sns-message-type: SubscriptionConfirmation
x-amz-sns-message-id: 165545c9-2a5c-472c-8df2-7ff2be2b3b1b
x-amz-sns-topic-arn: arn:aws:sns:us-west-2:123456789012:MyTopic
Content-Length: 1336
Content-Type: text/plain; charset=UTF-8
Host: example.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent

{
"Type" : "SubscriptionConfirmation",
"MessageId" : "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
"Token" : "2336412f37fb687f5d51e6e241d09c805a5a57b30d712f794cc5f6a988666d92768dd60a747ba6f3beb71854e285d6ad02428b09ceece29417f1f02d609c582afbacc99c583a916b9981dd2728f4ae6fdb82efd087cc3b7849e05798d2d2785c03b0879594eeac82c01f235d0e717736",
"TopicArn" : "arn:aws:sns:us-west-2:123456789012:MyTopic",
"Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:123456789012:MyTopic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
"SubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:123456789012:MyTopic&Token=2336412f37fb687f5d51e6e241d09c805a5a57b30d712f794cc5f6a988666d92768dd60a747ba6f3beb71854e285d6ad02428b09ceece29417f1f02d609c582afbacc99c583a916b9981dd2728f4ae6fdb82efd087cc3b7849e05798d2d2785c03b0879594eeac82c01f235d0e717736",
"Timestamp" : "2012-04-26T20:45:04.751Z",
"SignatureVersion" : "1",
"Signature" : "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
"SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem"
}

Regular Payment Payload:

{
  "Type" : "Notification",
  "MessageId" : "20d48143-6af4-571d-b7cb-d211e6a2ac69",
  "TopicArn" : "arn:aws:sns:ap-southeast-1:354285753755:bpt_01823072645",
  "Message" :
       "{
         "dateTime":"20180419122246",
         "debitMSISDN":"8801700000001",
         "creditOrganizationName":"Org 01",
         "creditShortCode":"01929918***",
         "trxID":"4J420ANOXC",
         "transactionStatus":"Completed",
         "transactionType":"1003",
         "amount":"100", 
         "currency":"BDT",
         "transactionReference":"Test_Payment",//User provided data
         "merchantInvoiceNumber": "orderId1233"
       }",
  "Timestamp" : "2018-04-19T12:22:46.236Z",
  "SignatureVersion" : "1",
  "Signature" : "jZBoouSuStaUqYZY+mruc3r3ST58CPkzjOu8i65dDIReWDcNAvPGUpNDSCBBMVLLA6UIJ9KtvTmop+JefiAd/8+YOxR738j0AXDcWc0A4u1EaMWqnmLvFufC0rAkEQuHdzn+XpHSET8Vn9SsnDJMsmdnWIiqH6JDsuPImuzP6V4Fh9/EKOYVOSks5aNChD1fwPQ1Z6DmtpEVaEXKagWXO8yPPAgs5meDArV7qIm93devI3DzfJboF1DOqHL9JkIrj5S9+ZqybCNKl3ay1JkgY9BXPoRe3XCzUSd4zTXa6GDbH7+3KZ3wmsiaa2zfwYCmrFNvzuE5o6OkeNHE/mqyCA==",
  "SigningCertURL" : "https://sns.ap-southeast-1.amazonaws.com/SimpleNotificationService-ac565b8b1a6c5d002d285f9598aa1d9b.pem",
  "UnsubscribeURL" : "https://sns.ap-southeast-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:ap-southeast-1:354285753755:bpt_01823072645:ddc1093b-2885-4179-ae8f-961577b564bd"
}

Note: "transactionReference" value is currently available only for checkout iframe and customer app payment

Coupon Associated Payment Payload

Merchants will get two extra parameters for coupon-associated transactions. One is Copoun amount and another is the Merchant's share amount (if any) for this coupon.

{
  "Type": "Notification",
  "MessageId": "c78a138d-3501-566f-948b-4f1b20ab4d31",
  "TopicArn": "arn:aws:sns:ap-southeast-1:797962984373:bpt_01929918374_UAT",
  "Message": 
	"{
       "dateTime":"20180419122246",
       "debitMSISDN":"8801700000001", // Customer wallet
       "creditOrganizationName":"Org 01",
       "creditShortCode":"ORG001",
       "trxID":"4J420ANOXC",
       "transactionStatus":"Completed",
       "transactionType":" 10002294", // Transaction type defines transaction channels
       "amount":"90", // Transaction Amount (Actual Amount - Coupon Amount)
       "couponAmount":"10", // Coupon Amount
       "merchantShareAmount":"5", // Merchant end contribution portion of this coupn
       "saleAmount":"100.00", //Actual Payment Amount
       "currency":"BDT",
       "transactionReference":"User inputed reference value." 
	}",
  "Timestamp": "2023-03-23T08:52:58.779Z",
  "SignatureVersion": "1",
  "Signature": "Jc6NKHTyMh2vC1gUt6EyMbm2LnDcCNd6lfQgiHwFMFL5aCwdbvArEpahI15FKMo/NYXIaZTnXSNOvfCDWWa6wUDFAjBUMJ1kOI+EQ8QJjwIITyzxhuQVT0Jtwh9Jc+Q49zXwj5GIrIWoWXgyGVKvmcVu+az1oW90itFtEHEs/Wem3sseHQBMR2mrOOoLwy5lfWkogJtbszGq8rBaSRrbEAR193qaPXI2kbiM8dVSVMLozqgBsmLSvZSC5BGHEiSh89sXNCN/FmPhWnK7Gph5gefm2y9wjq+/j2XcX6+mUq0FdBJYdvqSujqF58kvmBJRhS2UCTTgJlCgYiMfijp5ZQ==",
  "SigningCertURL": "https://sns.ap-southeast-1.amazonaws.com/SimpleNotificationService-56e67fcb41f6fec09b0196692625d385.pem",
  "UnsubscribeURL": "https://sns.ap-southeast-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:ap-southeast-1:797962984373:bpt_01929918374_UAT:b71180a0-b608-45a0-a3cf-2051d2c74101"
}

Note: Transaction Type defines which type of transaction happened to the merchant account. For example: If the merchant found transaction type value 10002175 then the merchant can understand that this transaction happened through the USSD channel.

Transaction Type:

  1. Payment via API: 10002294
  2. Payment via QR: 10003126
  3. Payment via USSD: 10002175
  4. Redeem Voucher: 10002809
  5. M2M Transfer via API : 10002264
  6. M2M Transfer via QR: 10003209
  7. M2M Transfer via USSD: 10002177
  8. Payment via Bank: 10003476
  9. B2B Collection Wallet to Merchant Plus (BC2M): 10003237
  10. Distributor to B2B Collection Wallet Transfer via USSD (D2BC): 10003236
  11. DSO to Merchant Plus-B2BC via API: 10004036
📘

Merchant shall receive notifications for successfully completed payment transactions only. The payload contains basic transaction info. If additional data (e.g. reference) is required, then merchant needs to use the Search Transaction Details API call.

Updated over 1 year ago