Skip to main content
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 typeWhen
SHIPMENT_PRELIMINARY_INVOICEWith preliminary invoice data (initial submission)
SHIPMENT_INVOICEWith 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:
TypeWhen
PAYMENT_BANK_TRANSFER_SCREENSHOTScreenshot / PDF of the bank-transfer transaction
PAYMENT_CONFIRMATIONFormal payment-confirmation document from the bank
PAYMENT_SOURCE_OF_FUNDS_DECLARATIONAML / 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.

​
Next

Transport

Pickup and delivery milestones.

Finalization

Final invoice + Export File.