Links

Webhooks

General

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. 1.
    Webhook is fired using HTTP POST.
  2. 2.
    Payload/body is in JSON format (see table below for attributes).
  3. 3.
    Payload is signed by SMARTy Pay using API Secret.
  4. 4.
    Webhook is considered successfully delivered when the remote endpoint returns HTTP 200.
  5. 5.
    Webhook is delivered with at least-once semantics.
  6. 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.

Invoicing

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"
}

Recharge Payments

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"
}

Subscriptions

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"
}

Subscription Charges

When a subscription charge is scheduled (created) and later processed the following events are dispatched via webhook.
On subscription charge created:
{
"eventId": "Exxc54kqygZo7ouTHep8Zo",
"eventType": "SubscriptionChargeCreated",
"eventTs": "2024-01-16T10:13:49.463181849+03:00",
"charge": {
"id": "e8b596cc-5189-4c53-944f-d51a8ad848c5",
"contractAddress": "0x76368Eafc5Ce663BeF7aBd4DD425f0431f9307b1",
"companyId": 1,
"amount": "0.01 bUSDT",
"planId": "g-nT6MdYTo2UhTLH4R3bow",
"chargeDate": "2024-01-16T07:13:21Z",
"status": "Succeeded"
}
}
On subscription charge status changed:
{
"eventId": "KtnqGyNxxWoAC589DyzX2v",
"eventType": "SubscriptionChargeStatusChanged",
"eventTs": "2024-01-16T10:13:49.510298645+03:00",
"charge": {
"id": "e8b596cc-5189-4c53-944f-d51a8ad848c5",
"contractAddress": "0x76368Eafc5Ce663BeF7aBd4DD425f0431f9307b1",
"amount": "0.01 bUSDT",
"planId": "g-nT6MdYTo2UhTLH4R3bow",
"chargeDate": "2024-01-16T07:13:21Z",
"oldStatus": "Pending",
"newStatus": "Succeeded"
}
}
All possible charge statuses can be found here.
Last modified 1mo ago