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 for 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 returned 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 x-sp-digest HTTP header and is calculated using HMAC-SHA256 from the whole request body using ApiSecret as a secret.
When the status of invoice changes to
Paid or SimplePaid SMARTy Pay notifies the external e-commerce system via webhook.Payload attributes:
Attribute | Required | Description |
|---|---|---|
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:
{
"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 |
|---|---|---|
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:
{
"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 |
|---|---|---|
eventType | Yes | Type of 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:
{
"eventType": "SubscriptionCreated",
"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:
{
"eventType": "SubscriptionStatusChanged",
"sid": "0x5692cf273644f77ea1bcc06b1fe25be4c4ad298a",
"oldStatus": "Pending",
"newStatus": "Active"
}
On subscription charge:
{
"eventType": "SubscriptionCharged",
"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