Notifications¶
An important part of Vigla functionality are notifications. These are sent to your defined callback
notification URL
as soon as Vigla detects a new payment or a status change of existing one.
Note
Although Vigla accepts plain http
notification URLs, it’s strongly recommended that
you provide a https
endpoint.
Notification payload¶
The callback carries JSON data of the received payment:
-
POST
<notification URL>
¶ Example request:
{ "amount": "1.234500000000", "height": null, "address": "78NjmbohsQNBJdJ7kyMBki4YMnHFAT91mX2jgGEEP2bEVmVYVjLwXBX9ZSMauGvijcUwAxGqxoBTa4Yq2MrwqdkR9Aswtku", "txid": "0c1d11bbf12b394fa832eb755fd189adb748c40cd46e04ba180ac390746d89b4", "signature": "sha256:08f96f3d613cf6b8bc24798eeb7d121f85ab3b5bc8441436339e4ad8741dae0d", "status": "pool", "confirmations": 0 }
Request Headers: - Content-Type – application/json
Response JSON Object: - amount (string) – the received amount formatted as string of
.12f
precision. A float is not used intentionally to avoid potential rounding errors. The trailing zeroes are always included to make the representation uniform and easy to process in signature verification (see below). - height (int) – the height of the block containing the transaction,
null
if the transaction is still in mempool - address (string) – the destination address
- txid (string) – the ID (hash) of the transaction
- signature (string) – the signature of the notification
- status (string) – payment status, one of three values (
pool
,mined
,unlocked
) described below - confirmations (int) – number of network confirmations (mined blocks) for the payment
Expected response¶
The notification expects a HTTP 200
response from the callback URL. If other status is
returned or connection fails, it will retry after about 2 seconds. Each subsequent failure
will double retry delay time until 15 attempts elapse. Then the notification will be dropped
as undeliverable.
Signature¶
The signature is supplied to ensure the request comes from authentic Vigla software. Users should always validate the request. The signature consists of two parts:
Currently only sha256
algorithm is supported.
The hash
is calculated by running the specified hash function on a colon-separated string
consisting of the most important parts of the information:
- Where:
amount
is the payment amount formatted exactly as received in the request (.12f
in printf() notation),height
is decimal height of the transaction’s block or an empty string when height isnull
,address
is the destination address,txid
is the hexadecimal transaction ID (hash),access_token
is the wallet access token in the UUID form.
Warning
Never process data received from a notification with invalid checksum. Please report such incidents to us (info@vigla.biz).
Payment statuses¶
There are three levels each payment may reach:
pool:
The transaction is in the memory pool, a kind of storage where new transactions await being confirmed and registered on the blockchain. This level indicates a payment has been sent to you and validated by the network nodes to be properly constructed and spending funds the sender actually possesses. However, in rare circumstances this may not be enough. There are potential attack scenarios, requiring some technical knowledge but little investment, where such transaction would get replaced and invalidated.
Generally speaking, you may use this status to confirm orders where delivery speed is crucial and you may accept the risk of funds loss (although unlikely). A good scenario is coffee shop where drinks should be served ASAP but occasional loss of payment is not critical for the business.
mined:
The transaction has been signed into a block and became a part of the blockchain. Usually it means the payment is secured but in a very unlikely event of chain reorganization the transaction may become invalidated and funds would return to the sender.
Freshly mined funds are locked, which means it’s impossible to spend them further. With each subsequent mined block the likelihood of reorganization shrinks drastically, making the transaction eventually reach the last status:
unlocked:
Per standard of the Monero network, after 10 blocks have been mined, the funds become unlocked and the recipient may spend them in subsequent transaction. This is the last and most secure status of the payment.
If the transaction has custom
unlock_time
set by the sender, this notification respects the setting and will arrive later, once the unlocking block has been mined.
Even though Vigla sends you notifications, you are free to check status of your payments at any given time.