Skip to main content
WEBHOOK
v1
/
client-invoices
Qonto webhook
curl --request POST \
  --url https://thirdparty.qonto.com/v1/client-invoices \
  --header 'Content-Type: application/json' \
  --header 'X-Qonto-Signature: <api-key>' \
  --data @- <<EOF
{
  "id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
  "number": "INV001",
  "purchase_order": "<string>",
  "status": "paid",
  "contact_email": "[email protected]",
  "terms_and_conditions": "This is an example.",
  "discount_conditions": "Pas d’escompte accordé pour paiement anticipé.",
  "late_payment_penalties": "En cas de non-paiement à la date d'échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées.",
  "legal_fixed_compensation": "Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€.",
  "header": "This is an example.",
  "footer": "This is an example.",
  "currency": "EUR",
  "total_amount": {
    "value": "12.52",
    "currency": "EUR"
  },
  "vat_amount": {
    "value": "0.51",
    "currency": "EUR"
  },
  "issue_date": "2022-03-01",
  "due_date": "2022-03-01",
  "performance_date": "2022-03-01",
  "performance_start_date": "2022-03-01",
  "performance_end_date": "2022-03-31",
  "created_at": "2022-03-04T17:58:30+02:00",
  "finalized_at": "2022-03-04T17:58:30+02:00",
  "paid_at": "2022-03-04T17:58:30+02:00",
  "stamp_duty_amount": "1.00",
  "items": [
    {
      "title": "Plastic tables",
      "description": "Plastic tables for McDonald’s restaurants",
      "quantity": "1.5",
      "unit": "meter",
      "unit_price": {
        "value": "10.0",
        "currency": "EUR"
      },
      "vat_rate": "0.1",
      "vat_exemption_reason": "N1",
      "discount": {
        "type": "percentage",
        "amount": {
          "value": "120",
          "currency": "EUR"
        }
      },
      "total_vat": {
        "value": "120",
        "currency": "EUR"
      },
      "total_amount": {
        "value": "300.50",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "120",
        "currency": "EUR"
      }
    }
  ],
  "client": {
    "id": "33v418bb-bd0d-4df4-865c-c07afab8bb48",
    "name": "McDonald's",
    "first_name": "Jane",
    "last_name": "Doe",
    "type": "individual",
    "email": "[email protected]",
    "vat_number": "FR32123456789",
    "tax_identification_number": "123456789",
    "address": "1 place de l’Opéra",
    "city": "Paris",
    "zip_code": "75009",
    "province_code": "<string>",
    "country_code": "fr",
    "recipient_code": "<string>",
    "locale": "fr",
    "billing_address": {
      "street_address": "123 Main Street",
      "city": "Paris",
      "zip_code": "75009",
      "province_code": "<string>",
      "country_code": "FR"
    },
    "delivery_address": {
      "street_address": "123 Main Street",
      "city": "Paris",
      "zip_code": "75009",
      "province_code": "<string>",
      "country_code": "FR"
    }
  },
  "payment_methods": [
    {
      "beneficiary_name": "John Doe",
      "bic": "ABCDEFG1XXX",
      "iban": "FR1420041010050500013M02606",
      "type": "transfer"
    }
  ],
  "organization": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "legal_name": "<string>",
    "legal_number": "<string>",
    "legal_country": "<string>",
    "address_line_1": "<string>",
    "address_line_2": "<string>",
    "address_zipcode": "<string>",
    "address_city": "<string>",
    "address_country": "<string>",
    "company_leadership": "Jan Mueller",
    "district_court": "Munich",
    "commercial_register_number": "HRB12345B",
    "vat_number": "FR123456789",
    "tax_number": "123/123/1234",
    "legal_capital_share": {
      "value": "10000.00",
      "currency": "EUR"
    },
    "transaction_type": "goods",
    "vat_payment_condition": "on_receipts"
  },
  "invoice_type": "standard",
  "attachment_id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
  "discount": {
    "type": "percentage",
    "amount": {
      "value": "10.00",
      "currency": "EUR"
    }
  },
  "einvoicing_status": "pending",
  "welfare_fund": {
    "type": "TC01",
    "rate": "0.0001"
  },
  "withholding_tax": {
    "reason": "RF01",
    "rate": "0.01",
    "amount": "1.00"
  }
}
EOF
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "membership_id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "v1/client-invoices",
    "created_at": "2025-01-27T22:05:07.000Z",
    "data": {
        "id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
        "number": "INV001",
        "purchase_order": "<string>",
        "status": "paid",
        "contact_email": "[email protected]",
        "terms_and_conditions": "This is an example.",
        "discount_conditions": "Pas d’escompte accordé pour paiement anticipé.",
        "late_payment_penalties": "En cas de non-paiement à la date d'échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées.",
        "legal_fixed_compensation": "Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€.",
        "header": "This is an example.",
        "footer": "This is an example.",
        "currency": "EUR",
        "total_amount": {
            "value": "12.52",
            "currency": "EUR"
        },
        "vat_amount": {
            "value": "0.51",
            "currency": "EUR"
        },
        "issue_date": "2022-03-01",
        "due_date": "2022-03-01",
        "performance_date": "2022-03-01",
        "performance_start_date": "2022-03-01",
        "performance_end_date": "2022-03-31",
        "created_at": "2022-03-04T17:58:30+02:00",
        "finalized_at": "2022-03-04T17:58:30+02:00",
        "paid_at": "2022-03-04T17:58:30+02:00",
        "stamp_duty_amount": "1.00",
        "items": [
            {
                "title": "Plastic tables",
                "description": "Plastic tables for McDonald’s restaurants",
                "quantity": "1.5",
                "unit": "meter",
                "unit_price": {
                    "value": "10.0",
                    "currency": "EUR"
                },
                "vat_rate": "0.1",
                "vat_exemption_reason": "N1",
                "discount": {
                    "type": "percentage",
                    "amount": {
                        "value": "120",
                        "currency": "EUR"
                    }
                },
                "total_vat": {
                    "value": "120",
                    "currency": "EUR"
                },
                "total_amount": {
                    "value": "300.50",
                    "currency": "EUR"
                },
                "subtotal": {
                    "value": "120",
                    "currency": "EUR"
                }
            }
        ],
        "client": {
            "id": "33v418bb-bd0d-4df4-865c-c07afab8bb48",
            "name": "McDonald's",
            "first_name": "Jane",
            "last_name": "Doe",
            "type": "individual",
            "email": "[email protected]",
            "vat_number": "FR32123456789",
            "tax_identification_number": "123456789",
            "address": "1 place de l’Opéra",
            "city": "Paris",
            "zip_code": "75009",
            "province_code": "<string>",
            "country_code": "fr",
            "recipient_code": "<string>",
            "locale": "fr",
            "billing_address": {
                "street_address": "123 Main Street",
                "city": "Paris",
                "zip_code": "75009",
                "province_code": "<string>",
                "country_code": "FR"
            },
            "delivery_address": {
                "street_address": "123 Main Street",
                "city": "Paris",
                "zip_code": "75009",
                "province_code": "<string>",
                "country_code": "FR"
            }
        },
        "payment_methods": [
            {
                "beneficiary_name": "John Doe",
                "bic": "ABCDEFG1XXX",
                "iban": "FR1420041010050500013M02606",
                "type": "transfer"
            }
        ],
        "organization": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "legal_name": "<string>",
            "legal_number": "<string>",
            "legal_country": "<string>",
            "address_line_1": "<string>",
            "address_line_2": "<string>",
            "address_zipcode": "<string>",
            "address_city": "<string>",
            "address_country": "<string>",
            "company_leadership": "Jan Mueller",
            "district_court": "Munich",
            "commercial_register_number": "HRB12345B",
            "vat_number": "FR123456789",
            "tax_number": "123/123/1234",
            "legal_capital_share": {
                "value": "10000.00",
                "currency": "EUR"
            },
            "transaction_type": "goods",
            "vat_payment_condition": "on_receipts"
        },
        "invoice_type": "standard",
        "attachment_id": "4d5418bb-bd0d-4df4-865c-c07afab8bb48",
        "discount": {
            "type": "percentage",
            "value": "0.1",
            "amount": {
                "value": "10.00",
                "currency": "EUR"
            }
        },
        "einvoicing_status": "pending",
        "welfare_fund": {
            "type": "TC01",
            "rate": "0.0001"
        },
        "withholding_tax": {
            "reason": "RF01",
            "rate": "0.01",
            "amount": "1.00"
        }
    }
}

Authorizations

​
X-Qonto-Signature
string
header
required

The signature header follows the format t={timestamp},v1={signature}.

Verification steps:

  1. Extract the timestamp and signature from the signature header
  2. Reject the request if the timestamp is older than 5 minutes
  3. Recreate the signed payload: '{timestamp}.{raw_request_body}'
  4. Compute HMAC-SHA256 of the signed payload using your webhook secret as the key
  5. Compare the computed signature with the one in the header

Body

application/json
​
id
string<uuid>
required
Example:

"4d5418bb-bd0d-4df4-865c-c07afab8bb48"

​
number
string
required
Example:

"INV001"

​
purchase_order
string
required

Purchase order data added by the invoice’s initiator.

​
status
enum<string>
required
Available options:
draft,
unpaid,
paid,
canceled
Example:

"paid"

​
contact_email
string<email>
required

E-mail address of the invoice’s initiator.

Example:

"[email protected]"

​
terms_and_conditions
string
required

The T&C data added by the invoice’s initiator.

Example:

"This is an example."

​
discount_conditions
string | null
required

Any discount for advance payment of the invoice. It is optional and is only for French organizations.

Example:

"Pas d’escompte accordé pour paiement anticipé."

​
late_payment_penalties
string | null
required

Late payment penalties applied in case of non-payment invoice. It is optional and is only for French organizations.

Example:

"En cas de non-paiement à la date d'échéance, des pénalités calculées à trois fois le taux d’intérêt légal seront appliquées."

​
legal_fixed_compensation
string | null
required

The legal fixed compensation applied in case late payment of the invoice. It is optional and is only for French organizations.

Example:

"Tout retard de paiement entraînera une indemnité forfaitaire pour frais de recouvrement de 40€."

​
header
string
required

The header text added by the credit note’s initiator.

Example:

"This is an example."

​
footer
string
required

The footer text added by the credit note’s initiator.

Example:

"This is an example."

​
currency
string
required
Example:

"EUR"

​
total_amount
object
required

Total amount that needs to be paid by the client.

​
vat_amount
object
required

VAT amount that is applicable to the invoice.

​
issue_date
string<date>
required

Date the initiator mentioned that the invoice was created.

Example:

"2022-03-01"

​
due_date
string<date>
required

Payment’s deadline added by the initiator.

Example:

"2022-03-01"

​
performance_date
string<date>
required
deprecated

DEPRECATED: This field is deprecated. Please use performance_start_date and performance_end_date instead.

The performance date represents when the job or service was completed by the client. Date the initiator mentioned that the contents of the invoice were performed.

Example:

"2022-03-01"

​
performance_start_date
string<date>
required

Start date of the performance period mentioned by the initiator for the invoice contents.

The performance period defines the date range during which the job or service was completed by the client. This field marks the beginning of that period and can be used together with performance_end_date to create a flexible date range instead of a single fixed date.

Example:

"2022-03-01"

​
performance_end_date
string<date>
required

End date of the performance period mentioned by the initiator for the invoice contents.

This field defines the end of the performance date range, allowing the work or service to have been completed anytime between performance_start_date and performance_end_date. When used together with performance_start_date, it creates a flexible time window rather than specifying completion on a single specific date.

Example:

"2022-03-31"

​
created_at
string<date-time>
required

Date the invoice was created. Note that this is a machine date.

Example:

"2022-03-04T17:58:30+02:00"

​
finalized_at
string<date-time>
required

Date the invoice was transitioned from Draft to Unpaid status.

Example:

"2022-03-04T17:58:30+02:00"

​
paid_at
string<date-time>
required

Date on which the invoice was paid.

Example:

"2022-03-04T17:58:30+02:00"

​
stamp_duty_amount
string
required
Required string length: 4 - 15
Example:

"1.00"

​
items
object[]
required
​
client
object
required

Client that needs to pay the invoice.

​
payment_methods
object[]
required
​
organization
object
required

Information of the organization at the time the document was issued.

​
invoice_type
enum<string>
required
Available options:
standard,
deposit,
balance
Example:

"standard"

​
attachment_id
string<uuid>

Attachment UUID corresponding to that particular invoice.
When creating the invoice (by calling the POST /v2/client_invoices endpoint), the attachment is generated asynchronously; which means that you have to wait ~10s and then call the GET /v2/client_invoices/{id} endpoint to get the attachment_id.
This property enables you to get the invoice file by using the GET /v2/attachments/{id} endpoint.

Example:

"4d5418bb-bd0d-4df4-865c-c07afab8bb48"

​
discount
object

Global discount that was applied to the invoice.

​
einvoicing_status
enum<string>
Available options:
pending,
submitted,
declined,
approved,
not_delivered,
submission_failed
​
welfare_fund
object
​
withholding_tax
object
  • Only applicable for Italian organizations and Spanish freelancers.
  • Object which relates to an amount of tax paid by the client, rather than the supplier, for specific cases.
  • This amount is a percentage deducted from the total amount of the invoice after VAT application.
  • The rate field specifies the percentage of tax and amount field specifies the total amount of the tax.

Response

200

Webhook received successfully