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 for 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 returned 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 x-sp-digest HTTP header and is calculated using HMAC-SHA256 from the whole request body using ApiSecret as a secret.

Invoicing

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

Recharge Payments

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

Subscriptions

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