[POST] Send Webhooks
Request description
The webhooks are sent when triggered by the events.
Request contains:
(Optional) Payment additional parameters
(Optional) Refund data
Request Specification:
Request Method: POST
Data Transfer Format: JSON
Encoding: UTF-8
Header Parameters
content-type
string
required
MIME-type
It must be equal to "application/json".
signature
string
required
Webhook signature
Webhook signature verification allows you to rest assured that the webhooks received are from Noventiq
Format: hash, hash, generated with algorithm SHA-512, from string:
[secret key];[event];[order_id];[create_date];[payment_method];[currency];[customer.email]where:
secret key - when setting up webhooks
event; order_id; create_date; payment_method; currency; customer.email - the values coincide with the values of the corresponding webhook parameters
See the signature generation example.
Body Parameters
event
string
required
Notification-triggering event
For the value options, see the reference guide.
event_date
string
required
Date and time of event
The system send a webhook on this event.
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
order_id
number
required
Payment identifier
You also receive this identifier in response to the request used for creating payment object (order_id) or auto-payment processing (order_id).
order_name
string
required
Extended payment identifier
In such a format prefixes can be added to identifiers.
status
string
required
Payment status
More details on payment statuses.
Value options:
not paid
paid - payment successfully completed
deleted (the status is also used if a full refund has been made)
external_id
string
required
Payment identifiers on your end
This identifier you transferred when creating a payment (payment_id) or processing an auto-payment (payment_id).
create_date
string
required
Date and time of creation for payment object
If a webhook is sent on the order.created event, the date and time values in this parameter will be equal to the values transferred in event_date.
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
pay_date
string
Date and time of successful payment completion
If a webhook is sent on the order.payment.succeeded, the date and time values in this parameter will be equal to the values transferred in event_date.
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
If no payment has been made, the parameter is transferred having an empty value ("").
currency
string
required
Currency code of payment
Format: ISO 4217 alpha-3, 3 characters
For the value options, see the reference guide
locale
locale
required
Payment form interface language
For the value options, see the reference guide.
order_detail_url
string
required
Link leading to the payment form page
When receiving webhooks in the test environment - links will be intended for the test environment (links will have the .demoslweb.com suffix added).
customer
object
required
Customer data
customer / country
string
required
Customer's country code
Format: ISO 3166-1 alpha-2
For the value options, see the reference guide
customer / type
string
required
Customer type
Value options:
physical - natural person
juridical - legal person
customer / email
string
required
Customer's email
This is the value that you passed in the parameter customer.email when creating the payment.
customer / first_name
string
required
Customer's name
This is the value that you passed in the parameter customer.first_name when creating the payment.
customer / last_name
string
required
Customer's last name
This is the value that you passed in the parameter customer.last_name when creating the payment.
customer / phone
string
Customer's phone number
This is the value that you passed in the parameter customer.phone when creating the payment. If the parameter contains no value on our end, it is transferred empty ("").
customer / vat_number
string
Taxpayer identification number
This is the value that you passed in the parameter customer.vat_number when creating the payment. If the parameter contains no value on our end, it is transferred empty ("").
customer / company_name
string
Company name
This is the value that you passed in the parameter customer.company_name when creating the payment. If the parameter contains no value on our end, it is transferred empty ("").
customer / company_billing_address
string
Company's registered office address
This is the value that you passed in the parameter customer.company_billing_address when creating the payment. If the parameter contains no value on our end, it is transferred empty ("").
customer / company_delivery_address
string
Company’s physical address
This is the value that you passed in the parameter customer.company_delivery_address when creating the payment. If the parameter contains no value on our end, it is transferred empty ("").
product
object
required
Payment data
product / id
string
required
It is not applicable (a technical value is transferred).
product / vendor_code
string
It is not applicable (an empty value (NULL) or a technical value is transferred).
product / sku
string
It is not applicable (an empty value ("") or a technical value is transferred).
product / business_segment
string
It is not applicable (an empty value ("") or a technical value is transferred).
product / name
string
required
Payment descriptions
This description is filled with values of the payment_description parameter when creating a payment object (payment_description) or processing an auto-payment (payment_description).
product / price
string
required
Payment amount excluding VAT
Format: String contains numerals; value separating by point, with two decimal places.
product / quantity
number
required
It is not applicable. "1" is always transferred.
product / discount_percent
string
It is not applicable. Empty value ("") is always transferred.
product / discount_amount
string
It is not applicable. Empty value ("") is always transferred.
product / vat_percent
string
required
VAT percentage
product / vat_amount
string
required
VAT amount in payment currency
Format: String contains numerals; value separating by point, with two decimal places.
product / amount
string
required
Total payment amount in payment currency
Including VAT
Format: String contains numerals; value separating by point, with two decimal places
product / margin
string
required
Your profit margin from sales in payment currency
Format: String contains numerals; value separating by point, with two decimal places.
payment
object
required
Payment data
payment / payment_method
string
required
Payment method code
For the value options, see the reference guide.
payment / payment_system_name
string
required
Payment method name (technical value)
payment / payment_error_code
string
required*
Payment error code
* - Required if a webhook is sent on the order.payment.failed event. Otherwise, it is not transferred.
payment / payment_error_description
string
required*
Payment error description
* - Required if a webhook is sent on the order.payment.failed event. Otherwise, it is not transferred.
payment / card_type
string
Сard type
Example: Visa, MASTERCARD.
The value can be transferred if the customer has paid with a bank card. Otherwise, the parameter is transferred having an empty value ("").
payment / card_last_4
string
Last 4 digits of card number
The value can be transferred if the customer has paid with a bank card. Otherwise, the parameter is transferred having an empty value (null).
payment / card_expiration_date
string
Card expiration date
The value can be transferred if the customer has paid with a bank card. Otherwise, the parameter is transferred having an empty value ("").
Format: MM/YYYY. Example: 12/2026.
payment / is_card_expired
boolean
required
It is not applicable. False value is always transferred.
payment / is_installment_payment
boolean
required
It is not applicable. False value is always transferred.
additional_data
array [objects]
Additional parameters
These parameters can be filled out when creating payment objects (additional_data) or during processing. More details on additional parameters. Please note that the time for storing additional parameters in payments is limited.
additional_data / [object] / name
string
required*
Parameter name
* - Required, if the additional_data parameter is transferred.
additional_data / [object] / value
string
required*
Parameter value
* - Required, if the additional_data parameter is transferred.
return
object
Refund data
It is transferred if a webhook is sent on the product.returned event. Otherwise, it is not transferred.
return / type
string
required*
Action type
* - Required, if the return parameter is transferred.
Value options:
returned - refund/chargeback
removed - not used in Noventiq Payments
return / date
required*
Date and time of event.
If a webhook is sent on the product.returned event, the date and time values in this parameter will be equal to the values transferred in event_date.
* - Required, if the return parameter is transferred
Format: YYYY-MM-DDThh:mm:ss±hh:mm
return / reason
string
required*
Reason description for event
* - Required, if the return parameter is transferred.
document_part
string
required
It is not applicable. "1-of-1" is always transferred.
Response
If a webhook is successfully received, your web service should return a response to the received webhook. Response time: 1 minute.
Possible responses:
HTTP/1.1 200 OK - webhook successfully received
Any other response or no response - webhook not received
If no webhook has been received, then:
Sending is repeated according to the following schedule: once every 20 minutes
Retries continue until the HTTP/1.1 200 OK response code is received or 10 attempts are made
When re-sending, webhook data is not updated. If an order/payment object changes when a webhook is being sent, the contents of the webhook are not changed
Noventiq Payments
Support |