Invoice & Payment

Invoice and Payment are sub-resources on the order. They carry the commercial artifacts Novatrade24 uses to validate VAT applicability at compliance evaluation time.

Invoice

One preliminary invoice per order. A final invoice is submitted later during finalization when the compliance verdict is known.

Submit invoice data

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/invoice" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PRELIMINARY",
    "invoiceDate": "2026-04-18",
    "invoiceNumber": "INV-2026-04-00451",
    "vatIncluded": false,
    "marginScheme": false,
    "amount": { "value": 1850000, "currency": "EUR" }
  }'

Upsert key: (orderUuid, type). Re-submitting with the same body is idempotent; different body returns 409 — use PATCH to update.

Upload the invoice PDF

Attached as a typed document:

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/invoice/documents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "type=SHIPMENT_PRELIMINARY_INVOICE" \
  -F "documentDate=2026-04-18" \
  -F "file=@/path/to/preliminary-invoice.pdf"

Document type	When
`SHIPMENT_PRELIMINARY_INVOICE`	With preliminary invoice data (initial submission)
`SHIPMENT_INVOICE`	With final invoice during finalization

Validation performed

At compliance time, NT24 checks:

Invoice total matches order total (modulo currency).
VAT structure matches the invoice type claim (vatIncluded, marginScheme).
Buyer name on the invoice matches the buyer record.
PDF is attached.

Mismatches surface as blockers[] in the compliance rollup.

Payment

One payment record per order. The record carries amount, date, IBAN, and optionally the breakdown between bank transfer and cash.

Submit payment data

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/payment" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentDate": "2026-04-19",
    "bankAmount": { "value": 1850000, "currency": "EUR" },
    "cashAmount":  { "value": 0,        "currency": "EUR" },
    "sourceIban":  "DE89370400440532013000"
  }'

Upsert key: orderUuid. One payment per order.

Upload proof of payment

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/payment/documents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "type=PAYMENT_BANK_TRANSFER_SCREENSHOT" \
  -F "documentDate=2026-04-19" \
  -F "file=@/path/to/bank-screenshot.pdf"

Allowed types:

Type	When
`PAYMENT_BANK_TRANSFER_SCREENSHOT`	Screenshot / PDF of the bank-transfer transaction
`PAYMENT_CONFIRMATION`	Formal payment-confirmation document from the bank
`PAYMENT_SOURCE_OF_FUNDS_DECLARATION`	AML / source-of-funds document

Mark ready for pickup

Once payment is received and verified on your side, signal readiness for pickup:

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/payment/ready-for-pickup" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)"

This triggers the daily VIES re-check workflow on the buyer’s VAT number. NT24 re-validates VIES every 24 hours until pickup is confirmed. If VIES fails during this window, kyc.vies_check_failed fires and the order’s compliance moves to INVALID unless resolved.

Validation performed

Amount matches invoice total.
Source IBAN consistent with previously-seen IBANs for this buyer (or a declared new one).
bankAmount + cashAmount = totalAmount.
Proof document attached.

Cross-module validation

The compliance rollup surfaces issues that span modules:

Invoice amount ≠ Payment amount → blockers: [{module: payment, code: AMOUNT_MISMATCH}]
Buyer name on invoice ≠ buyer record → blockers: [{module: invoice, code: BUYER_NAME_MISMATCH}]
IBAN on payment inconsistent with known → blockers: [{module: payment, code: IBAN_UNKNOWN}]

Resolution is to upload corrected data / document or submit a reason via a PATCH where the field supports it.

Transport

Pickup and delivery milestones.

Finalization

Final invoice + Export File.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

Invoice

Submit invoice data

Upload the invoice PDF

Validation performed

Payment

Submit payment data

Upload proof of payment

Mark ready for pickup

Validation performed

Cross-module validation

Next

Transport

Finalization

​Invoice

​Submit invoice data

​Upload the invoice PDF

​Validation performed

​Payment

​Submit payment data

​Upload proof of payment

​Mark ready for pickup

​Validation performed

​Cross-module validation

​Next

Transport

Finalization

Invoice

Submit invoice data

Upload the invoice PDF

Validation performed

Payment

Submit payment data

Upload proof of payment

Mark ready for pickup

Validation performed

Cross-module validation

Next