When a payment is updated, Zelling can automatically forward the payment information to a user-defined webhook URL (payment.webhookUrl).This payload contains detailed information about the payment, including its current status, received cryptocurrency amounts, payment events, and any associated metadata.
Webhook Response Structure#
{
"tid": "TID123456",
"status": "CONFIRMED",
"payments": [
{
"uuid": "pay-001",
"txid": "tx123abc",
"value_coin": 0.005,
"confirmations": 3,
"status": "CONFIRMED",
"seen_at": "2025-09-01T19:00:00.000Z",
"value_forwarded_coin": null
}
],
"events": [
{
"type": "payment.seen",
"message": "Received 0.005 LTC (3/4 confirmations)",
"oldStatus": null,
"newStatus": null,
"createdAt": "2025-09-01T19:00:00.000Z"
},
{
"type": "invoice.status_changed",
"message": "Status changed: PENDING → CONFIRMED",
"oldStatus": "PENDING",
"newStatus": "CONFIRMED",
"createdAt": "2025-09-01T19:05:00.000Z"
}
],
"meta": {
"orderId": "ORD-001",
"customerId": "12345"
},
"cryptoCoin": "LTC",
"cryptoAmountExpected": 0.01234,
"cryptoAmountReceivedTotal": 0.005
}
Required Your Response#
⚠️ Both conditions must be met. Otherwise, Zelling will treat the webhook as failed and may retry or log an error.
Field Descriptions#
Unique transaction ID of the payment.
Current overall status of the payment. Possible values:Description: Invoice created, no payments received.
When it appears: From the moment the invoice is created, before any payment is made.
Description: Partial payment received (underpayment).
When it appears: When the total sum of payments is less than cryptoAmountExpected.
Description: Full amount has been paid, but confirmations are less than targetConfirmations.
When it appears: After the full amount is paid, but the blockchain has not yet provided the required minimum confirmations.
Description: Full amount paid and confirmed.
When it appears: When the total sum of payments is greater than or equal to cryptoAmountExpected and all payments have at least targetConfirmations confirmations.
array of objectsList of individual cryptocurrency payment transactions.
payments.uuid: stringUnique UUID of this payment entry.
payments.txid: string
Transaction ID on the blockchain.
payments.value_coin: number
Amount received in cryptocurrency for this entry.
payments.confirmations: integer
Number of confirmations received for this transaction.
payments.status: string
Status of this payment entry (PENDING or CONFIRMED).
payments.seen_at: string (ISO 8601)
Timestamp when this payment entry was first recorded.
payments.value_forwarded_coin: number | null
Amount forwarded to the target address, if any.
events: array of objects
List of events triggered during payment updates or status changes.
events.type: stringEvent type (e.g., payment.seen, invoice.status_changed, invoice.created).
events.message: string
Human-readable description of the event.
events.oldStatus: string | null
Previous payment status if it changed, otherwise null.
events.newStatus: string | null
New payment status if it changed, otherwise null.
events.createdAt: string (ISO 8601)
Timestamp when the event was created.
meta: object
Optional metadata attached to the payment (e.g., orderId, customerId).
cryptoCoin: string
Cryptocurrency used for the payment (e.g., LTC).
cryptoAmountExpected: number
Total amount of cryptocurrency expected for this payment.
cryptoAmountReceivedTotal: number
Sum of all received cryptocurrency amounts from individual payments.
Zelling forwards payment updates to your webhook URL only from approved IP addresses.
To ensure security, you should configure your server to accept requests only from the following IP addresses:Additional Security Measures:The User-Agent header is always set to Zelling/1.0.
Your server should verify that incoming requests come from one of the whitelisted IPs and have the correct User-Agent.
Requests from non-whitelisted IPs or with an incorrect User-Agent should be rejected with HTTP 403.
The webhook is called only if payment.webhookUrl is defined.Failed webhook requests are logged but do not interrupt the main payment processing.The payload is sent as JSON with Content-Type: application/json.Provides a real-time snapshot of the payment's status, confirmations, and events.Ideal for integration with dashboards, notifications, or automated processing systems.
