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. 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.

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.