E-INVOICE - How to represent payments on an invoice

Payments are carried in payments[] on the invoice operation. The array accepts between 1 and 10 entries. Which fields you provide depends on whether the invoice has already been settled.

Payment already received

Select the payment type that applies — CASH, CARD, ONLINE, VOUCHER or OTHER — and provide details.amount.  Some types require additional fields:

Optionally, details can also carry date , discount and properties. The currency of the first payment in the array sets the currency of the whole invoice and  EUR is the only accepted value.

Payments of these types count as already settled — they reduce the amount the buyer still owes on the invoice. There are 2 possible scenarios:

• If they cover the invoice total, nothing further is needed.
•  If they don't, add an OUTSTANDING payment for the remainder; otherwise the invoice is rejected because the amounts don't add up.

Payment still outstanding

Use payments[].type: "OUTSTANDING". payments[].concept is required and indicates whether the outstanding amount concerns a GOOD, a SERVICE, or an INVOICE. 

OUTSTANDING takes a details object: 

• details.amount is required and carries the amount still due. 
• details.date is also required and sets the payment due date — an outstanding payment without a due date is rejected.

• Payment instruction
  The instruction object is optional. Add it when the invoice should tell the buyer how to pay — for a bank transfer, it carries the IBAN the buyer should send the money to.

  If you leave it out, the invoice is still accepted and transmitted. fiskaly then reports the payment method as a bank transfer, without any account details. So include an instruction when you want your account details on the invoice, or when the buyer is meant to pay some other way (by SEPA direct debit, for example).

  When instruction is provided, instruction.type is CREDIT_TRANSFER or DIRECT_DEBIT. An instruction missing any of these fields is rejected:

   

  • CREDIT_TRANSFER requires type, account, name and payment_service_provider — all four. The IBAN goes in account, in ISO 13616 format (15–34 characters). payment_service_provider is the bank's BIC/SWIFT code (e.g. BCITITMM) — a bank name is not accepted.

  • DIRECT_DEBIT requires type, mandate_reference, creditor_id and debited_account, with the IBAN in debited_account. 

    Note that creditor_id is an object rather than a string — { "type": "SEPA", "identifier": "IT05ZZZ12345678901" } — and the identifier is to match the SEPA creditor identifier format (9–35 characters), where the character following the three-letter business code is a digit.

    Both variants also accept the optional fields text and properties.  Properties has a different shape depending on where it appears: on details it is an object of up to 16 entries whose values are strings of up to 64 characters, while on instruction it is a single string of up to 128 characters.

Example of outstanding payment via bank transfer

{
  "payments": [
    {
      "type": "OUTSTANDING",
      "concept": "INVOICE",
      "details": {
        "amount": "122.00",
        "date": "2026-09-30"
      },
      "instruction": {
        "type": "CREDIT_TRANSFER",
        "account": "IT60X0542811101000000123456",
        "name": "Officina Rossi S.r.l.",
        "payment_service_provider": "BCITITMM"
      }
    }
  ]
}

Example of outstanding payment via SEPA direct debit

Only the instruction object differs from the bank transfer example above; type, concept and details are unchanged.

{
  "instruction": {
    "type": "DIRECT_DEBIT",
    "mandate_reference": "MANDATE-2026-0042",
    "creditor_id": {
      "type": "SEPA",
      "identifier": "IT05ZZZ12345678901"
    },
    "debited_account": "IT60X0542811101000000123456"
  }
}