[POST] Send Webhooks — Noventiq Payments

Noventiq PaymentsIntegrationWebhooks

[POST] Send Webhooks

Request description

The webhooks are sent when triggered by the events.

Request contains:

Webhook signature
Payment data
Customer data
(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

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

string

required

Customer's email

customer

first_name

string

required

Customer's name

customer

last_name

string

required

Customer's last name

customer

phone

string

Customer's phone number
If the parameter contains no value on our end, it is transferred empty ("").

customer

vat_number

string

Taxpayer identification number
E.g., it is used to transfer:

DNI/CUIL/CUIT when payments are made in Argentine pesos

If the parameter contains no value on our end, it is transferred empty ("").

customer

company_name

string

Company name
If the parameter contains no value on our end, it is transferred empty ("").

customer

company_billing_address

string

Company's registered office address
If the parameter contains no value on our end, it is transferred empty ("").

customer

company_delivery_address

string

Company’s physical address
If the parameter contains no value on our end, it is transferred empty ("").

product

object

required

Payment data

product

string

required

It is not applicable (a technical value is transferred).

product

vendor_code

string

It is not applicable (an empty value ("") 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