v1/transactions

Qonto webhook

curl --request POST \
  --url https://thirdparty.qonto.com/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-Qonto-Signature: <api-key>' \
  --data '
{
  "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/transactions",
  "created_at": "2025-01-24T10:55:00Z",
  "data": {
    "event": "created",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "transaction_id": "super-transaction-6576",
    "amount": 50,
    "currency": "EUR",
    "local_amount": 45,
    "local_currency": "USD",
    "side": "debit",
    "operation_type": "card",
    "status": "completed",
    "label": "ACME Corp",
    "clean_counterparty_name": "ACME Corp",
    "emitted_at": "2025-01-24T10:54:00Z",
    "created_at": "2025-01-24T10:54:00Z",
    "updated_at": "2025-01-24T10:55:00Z",
    "attachment_ids": [
      "<string>"
    ],
    "subject_type": "Card",
    "bank_account": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "iban": "FR7616798000010000005663951",
      "bic": "TRZOFR21XXX",
      "name": "Main Account"
    },
    "settled_balance": 100,
    "note": "Business lunch",
    "reference": "INV-1234",
    "settled_at": "2025-01-24T10:54:00Z",
    "card_last_digits": "<string>",
    "transfer": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "income": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "swift_income": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "direct_debit": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "direct_debit_collection": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "check": {
      "check_number": "<string>",
      "check_key": "<string>"
    },
    "financing_installment": {
      "total_installments_number": 123,
      "current_installment_number": 123
    },
    "pagopa_payment": {
      "notice_number": "<string>",
      "creditor_fiscal_code": "<string>",
      "iuv": "<string>"
    },
    "direct_debit_hold": {
      "guarding_rate": "<string>"
    }
  }
}
'

{}

POST

transactions

Qonto webhook

curl --request POST \
  --url https://thirdparty.qonto.com/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-Qonto-Signature: <api-key>' \
  --data '
{
  "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/transactions",
  "created_at": "2025-01-24T10:55:00Z",
  "data": {
    "event": "created",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "transaction_id": "super-transaction-6576",
    "amount": 50,
    "currency": "EUR",
    "local_amount": 45,
    "local_currency": "USD",
    "side": "debit",
    "operation_type": "card",
    "status": "completed",
    "label": "ACME Corp",
    "clean_counterparty_name": "ACME Corp",
    "emitted_at": "2025-01-24T10:54:00Z",
    "created_at": "2025-01-24T10:54:00Z",
    "updated_at": "2025-01-24T10:55:00Z",
    "attachment_ids": [
      "<string>"
    ],
    "subject_type": "Card",
    "bank_account": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "iban": "FR7616798000010000005663951",
      "bic": "TRZOFR21XXX",
      "name": "Main Account"
    },
    "settled_balance": 100,
    "note": "Business lunch",
    "reference": "INV-1234",
    "settled_at": "2025-01-24T10:54:00Z",
    "card_last_digits": "<string>",
    "transfer": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "income": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "swift_income": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "direct_debit": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "direct_debit_collection": {
      "counterparty_account_number": "<string>",
      "counterparty_account_number_format": "iban",
      "counterparty_bank_identifier": "<string>",
      "counterparty_bank_identifier_format": "bic"
    },
    "check": {
      "check_number": "<string>",
      "check_key": "<string>"
    },
    "financing_installment": {
      "total_installments_number": 123,
      "current_installment_number": 123
    },
    "pagopa_payment": {
      "notice_number": "<string>",
      "creditor_fiscal_code": "<string>",
      "iuv": "<string>"
    },
    "direct_debit_hold": {
      "guarding_rate": "<string>"
    }
  }
}
'

{}

{
    "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/transactions",
    "created_at": "2025-01-24T10:55:00Z",
    "data": {
        "event": "created",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "transaction_id": "super-transaction-6576",
        "amount": 50.01,
        "currency": "EUR",
        "local_amount": 45.01,
        "local_currency": "USD",
        "side": "debit",
        "settled_balance": 100.02,
        "operation_type": "transfer",
        "status": "completed",
        "label": "ACME Corp",
        "clean_counterparty_name": "ACME Corp",
        "note": "Business lunch",
        "reference": "INV-1234",
        "settled_at": "2025-01-24T10:54:00Z",
        "emitted_at": "2025-01-24T10:54:00Z",
        "updated_at": "2025-01-24T10:55:00Z",
        "attachment_ids": [
            "attachment-1",
            "attachment-2"
        ],
        "subject_type": "Transfer",
        "bank_account_id": "123e4567-e89b-12d3-a456-426614174000",
        "transfer": {
            "counterparty_account_number": "123456789",
            "counterparty_account_number_format": "account_number",
            "counterparty_bank_identifier": "987654321",
            "counterparty_bank_identifier_format": "bic"
        }
    }
}

Authorizations

X-Qonto-Signature

string

header

required

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

Verification steps:

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

Body

application/json

string<uuid>

required

Unique identifier for this webhook event

Example:

"123e4567-e89b-12d3-a456-426614174000"

subscription_id

string<uuid>

required

ID of the webhook subscription that received the event

Example:

"123e4567-e89b-12d3-a456-426614174000"

organization_id

string<uuid>

required

ID of the organization that owns the bank account

Example:

"123e4567-e89b-12d3-a456-426614174000"

membership_id

string<uuid>

required

ID of the membership associated with subscription

Example:

"123e4567-e89b-12d3-a456-426614174000"

type

enum<string>

required

Available options:

v1/transactions,

v1/accounts,

v1/organizations,

v1/memberships,

v1/consent-revocations,

v1/cards,

v1/payment-links,

v1/payment-links-connections,

v1/beneficiaries

Example:

"v1/transactions"

created_at

string<date-time>

required

Timestamp when the webhook event was created

Example:

"2025-01-24T10:55:00Z"

data

v1/transaction · object

required

Show child attributes

data.event

enum<string>

required

Event triggering the webhook

Available options:

created,

updated

Example:

"created"

data.id

string<uuid>

required

Unique identifier for the transaction

Example:

"123e4567-e89b-12d3-a456-426614174000"

data.transaction_id

string

required

Unique identifier of the transaction

Example:

"super-transaction-6576"

data.amount

number

required

Positive transaction amount as string, with a period as decimal separator and N decimal places (related to currency).

Example:

50

data.currency

string

required

Transaction currency (ISO 4217)

Example:

"EUR"

data.local_amount

number

required

Positive amount of the transaction in the foreign currency (if any) as string, with a period as decimal separator and N decimal places (related to currency)

Example:

45

data.local_currency

string

required

Local currency code (ISO 4217)

Example:

"USD"

data.side

enum<string>

required

Transaction direction

Available options:

credit,

debit

Example:

"debit"

data.operation_type

string

required

Type of the transaction

Example:

"card"

data.status

string

required

Current status of the transaction

Example:

"completed"

data.label

string

required

Name of the counterparty of the transaction

Example:

"ACME Corp"

data.clean_counterparty_name

string

required

Simplified and standardized version of the counterparty's name.

Example:

"ACME Corp"

data.emitted_at

string<date-time>

required

When the transaction was initiated

Example:

"2025-01-24T10:54:00Z"

data.created_at

string<date-time>

required

When the transaction was created

Example:

"2025-01-24T10:54:00Z"

data.updated_at

string<date-time>

required

When the transaction was last updated

Example:

"2025-01-24T10:55:00Z"

data.attachment_ids

string[]

required

List of attachment IDs associated with the transaction

data.subject_type

enum<string>

required

Type of the transaction that determines which additional fields will be present

Available options:

Card,

Transfer,

Income,

DirectDebit,

DirectDebitCollection,

DirectDebitHold,

WalletToWallet,

Check,

SwiftIncome,

PagopaPayment,

F24Payment,

BillingTransfer,

FinancingIncome,

FinancingInstallment,

Other

data.bank_account

object

required

Show child attributes

data.bank_account.id

string<uuid>

required

Bank account identifier

Example:

"123e4567-e89b-12d3-a456-426614174000"

data.bank_account.iban

string

required

Bank account IBAN

Example:

"FR7616798000010000005663951"

data.bank_account.bic

string

required

Bank account BIC

Example:

"TRZOFR21XXX"

data.bank_account.name

string

required

Name of the bank account

Example:

"Main Account"

data.settled_balance

number

Positive settled balance as string, with a period as decimal separator and N decimal places (related to currency)

Example:

100

data.note

string

User provided note for the transaction

Example:

"Business lunch"

data.reference

string

Reference of the transaction

Example:

"INV-1234"

data.settled_at

string<date-time>

When the transaction was settled

Example:

"2025-01-24T10:54:00Z"

data.card_last_digits

string

Last 4 digits of the card used for the transaction

data.transfer

object

Show child attributes

data.transfer.counterparty_account_number

string

required

Account number of the transaction's counterparty

data.transfer.counterparty_account_number_format

enum<string>

required

Available options:

iban,

account_number

data.transfer.counterparty_bank_identifier

string

required

Bank identifier of the transaction's counterparty

data.transfer.counterparty_bank_identifier_format

enum<string>

required

Available options:

bic,

routing_number

data.income

object

Show child attributes

data.income.counterparty_account_number

string

required

Account number of the transaction's counterparty

data.income.counterparty_account_number_format

enum<string>

required

Available options:

iban,

account_number

data.income.counterparty_bank_identifier

string

required

Bank identifier of the transaction's counterparty

data.income.counterparty_bank_identifier_format

enum<string>

required

Available options:

bic,

routing_number

data.swift_income

object

Show child attributes

data.swift_income.counterparty_account_number

string

required

Account number of the transaction's counterparty

data.swift_income.counterparty_account_number_format

enum<string>

required

Available options:

iban,

account_number

data.swift_income.counterparty_bank_identifier

string

required

Bank identifier of the transaction's counterparty

data.swift_income.counterparty_bank_identifier_format

enum<string>

required

Available options:

bic,

routing_number

data.direct_debit

object

Show child attributes

data.direct_debit.counterparty_account_number

string

required

Account number of the transaction's counterparty

data.direct_debit.counterparty_account_number_format

enum<string>

required

Available options:

iban,

account_number

data.direct_debit.counterparty_bank_identifier

string

required

Bank identifier of the transaction's counterparty

data.direct_debit.counterparty_bank_identifier_format

enum<string>

required

Available options:

bic,

routing_number

data.direct_debit_collection

object

Show child attributes

data.direct_debit_collection.counterparty_account_number

string

required

Account number of the transaction's counterparty

data.direct_debit_collection.counterparty_account_number_format

enum<string>

required

Available options:

iban,

account_number

data.direct_debit_collection.counterparty_bank_identifier

string

required

Bank identifier of the transaction's counterparty

data.direct_debit_collection.counterparty_bank_identifier_format

enum<string>

required

Available options:

bic,

routing_number

data.check

object

Show child attributes

data.check.check_number

string

required

Check number

data.check.check_key

string

required

Check key

data.financing_installment

object

Show child attributes

data.financing_installment.total_installments_number

integer

required

Total number of installments

data.financing_installment.current_installment_number

integer

required

Installment of the current transaction

data.pagopa_payment

object

Show child attributes

data.pagopa_payment.notice_number

string

required

Code in the PagoPA Payment Advice that identifies the payment notice

data.pagopa_payment.creditor_fiscal_code

string

required

Code that identifies the creditor institution

data.pagopa_payment.iuv

string

required

Unique Payment Identifier (UPI)

data.direct_debit_hold

object

Show child attributes

data.direct_debit_hold.guarding_rate

string

required

Guarding rate for the direct debit hold

Response

200

Webhook received successfully

Setup v1/accounts

⌘I

Business API

Onboarding API

v1/transactions

Authorizations

Body

Response