Webhooks
SMARTy Pay can notify an external e-commerce system of different events occurring in the system via webhooks.
You can configure the notification URL in your BackOffice UI.
The following rules apply to webhook notifications:
- 1.Webhook is fired using HTTP POST.
- 2.Payload/body is in JSON format (see table below for attributes).
- 3.Payload is signed by SMARTy Pay using API Secret.
- 4.Webhook is considered successfully delivered when the remote endpoint returns HTTP 200.
- 5.Webhook is delivered with at least-once semantics.
- 6.SMARTy Pay retries webhook delivery several times with exponential backoff.
To ensure the authenticity of the webhook signature is placed inside the x-sp-digest HTTP header and is calculated using HMAC-SHA256 from the whole request body using ApiSecret as a secret.
It's important to ensure that the receiving system can handle events coming in out of order. This can happen due to network delays or other issues. If the order of events is critical, you can use an
eventTs attribute to restore order.In some cases, the same event might be sent more than once. You can use
eventId attribute for deduplication purposes.When the status of the invoice changes to
Paid or SimplePaid SMARTy Pay notifies the external e-commerce system via webhook.Payload attributes:
Attribute | Required | Description |
|---|---|---|
eventId | Yes | Unique Id of the event |
eventType | Yes | Type of the event |
eventTs | Yes | Timestamp (iso8601) of the event |
invoiceId | Yes | Identifier of this invoice |
amount | Yes | Amount with token code |
status | Yes | Invoice new status |
createdAt | Yes | Invoice creation date/time |
expiresAt | Yes | Expiration date/time |
paidAt | No | Paid date/time |
paidAmount | No | Paid amount |
errorCode | No | Error code |
metadata | No | External metadata |
Example payload:
{
"eventId": "PHLNhtC2g7GqQ2aVWE4bRk",
"eventType": "InvoiceStatusChanged",
"eventTs": "2022-08-29T16:13:53.875442729+03:00",
"invoiceId": "5d51062e-52a1-4aa3-9616-2d5835f32634",
"amount": "0.25 btBUSD",
"status": "SimplePaid",
"createdAt": "2021-06-21T14:44:58.098725Z",
"expiresAt": "2021-06-22T20:19:38.146071Z",
"paidAt": "2021-06-21T22:48:47.425728Z",
"paidAmount": "0.2125 btMNXe",
"metadata": "User defined data"
}
When a new recharge payment is detected SMARTy Pay notifies the external e-commerce system via webhook.
Payload attributes:
Attribute | Required | Description |
|---|---|---|
eventId | Yes | Unique Id of the event |
eventType | Yes | Type of the event |
eventTs | Yes | Timestamp (iso8601) of the event |
cid | Yes | Customer (external) id |
hash | Yes | Payment transaction hash |
fromAddress | Yes | Source address |
pushAddress | Yes | Destination push/recharge address |
amount | Yes | Funds amount |
ingestedAt | Yes | Data/Time when this payments was detected |
Example payload:
{
"eventId": "T9ymoH9pNzFT9ukv59JBEv",
"eventType": "RechargePaymentProvided",
"eventTs": "2022-08-29T16:13:53.875442729+03:00",
"cid": "1015",
"hash": "0x9f5cbcbb716bd892d771af7fca549449551e869e7fdba2669a9ac3d5aaa8830b",
"fromAddress": "0x14186c8215985f33845722730c6382443bf9ec65",
"pushAddress": "0x57cdfcc7f2fb0345f2cbcb8deb7c0cda96c1ed60",
"amount": "1 btUSDTv2",
"ingestedAt": "2022-04-27T21:39:19.711337+03:00"
}
When a subscription state change is detected SMARTy Pay notifies the external e-commerce system via webhook.
Payload attributes:
Attribute | Required | Description |
|---|---|---|
eventId | Yes | Unique Id of the event |
eventType | Yes | Type of event |
eventTs | Yes | Timestamp (iso8601) of the event |
contractAddress or sid | Yes | ID of subscription, contract address |
planId | Yes | ID of the plan |
asset | Yes | Token code |
blockchain | Yes | Blockchain mnemonic code |
customerId | Yes | Customer correlation ID |
payer | Yes | Payer address |
metadata | Yes | Additional correlation data |
newStatus | Yes | New subscription status |
oldStatus | Yes | Old subscription status |
Examples.
On new subscription creation:
{
"eventId": "5FRJRK9D492gpeWjiKAo4k",
"eventType": "SubscriptionCreated",
"eventTs": "2023-05-29T11:11:53.875442729+04:00",
"subscription": {
"contractAddress": "0xf265d80e9715f6f38b775af3bc859afcc54f8a59",
"planId": "zXA5uAniS3-fc743RE0yAg",
"asset": "btMNXe",
"blockchain": "BinanceTestNet",
"customerId": "customer-500060001",
"nextChargeAt": "2023-01-14T15:31:39.698Z",
"payer": "0x14186C8215985f33845722730c6382443Bf9EC65",
"mode": "Simple",
"status": "Draft",
"startFrom": "2023-01-13T15:31:39.698Z",
"maxPeriods": 24,
"createdAt": "2023-01-13T15:31:40.035098Z",
"metadata": "correlation-order-0012",
}
}
On subscription status change:
{
"eventId": "1FRJRK9D492gpeWjiKAo41",
"eventType": "SubscriptionStatusChanged",
"eventTs": "2023-05-29T11:11:53.875442729+04:00",
"sid": "0x5692cf273644f77ea1bcc06b1fe25be4c4ad298a",
"oldStatus": "Pending",
"newStatus": "Active"
}
On subscription charge:
{
"eventId": "RtQaYyQwKnRW2byUT9pJyG",
"eventType": "SubscriptionCharged",
"eventTs": "2023-08-11T11:11:53.875442123+04:00",
"charge": {
"id": "648223c0-4132-40fc-a724-4d7c5bb4ff5c",
"contractAddress": "0xf265d80e9715f6f38b775af3bc859afcc54f8a59",
"amount": "10 btUSDTv2",
"chargeDate": "2023-01-13T15:31:40.035098Z",
"status": "Succeeded",
"metadata": "correlation-order-0012",
}
}
Last modified 1mo ago