Payment Methods Guide

Introduction

This guide describes the internal payment method codes in B2Brouter and their corresponding encoding in UBL, Facturae, and FatturaPA.

Equivalencies:

• B2Brouter internal field: payment_method
• Facturae field: PaymentMeans (element at /facturae:Facturae/Invoices/Invoice/PaymentDetails/Installment/PaymentMeans)
• UBL field: cbc:PaymentMeansCode (element at /Invoice/cac:PaymentMeans/cbc:PaymentMeansCode)
• FatturaPA field: ModalitaPagamento (element at /p:FatturaElettronica/FatturaElettronicaBody/DatiPagamento/DettaglioPagamento/ModalitaPagamento)
• CII field: TypeCode (element at rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode)
• Business Terms ID: BT-81

1. Payment Codes Table

1.1 Additional required fields (API)

Depending on the payment_method, you may need to provide extra fields so the invoice can be generated/exported correctly.
This section focuses on universal bank/payment data requirements; some e-invoice formats may still restrict which payment codes are accepted.

Universal requirements

• Customer bank account (payer): DEBIT (2), DEBIT SEPA (59). Required in specific formats/flows, not universally. For example, XRechnung \common_xrechnung_v23 requires invoice.contact_iban, XRechnung v3 also requires mandate_reference_identifier, and Facturae requires the customer bank account (contact.bank_account_number or a valid invoice.contact_iban). This does not apply to IssuedSimplifiedInvoice.`
• Payment terms: DEBIT (2) . Provide terms (it cannot be 0/blank).
• Payment due date (most exports):
  If you set a payment_method and use terms = "custom", you must provide due_date (except for some transports like PEPPOL and SDI). If you use a non-custom terms, the system derives due_date automatically.
• Company bank account (payee): TRANSFER (4), TRANSFER SEPA (58), DEBIT TRANSFER (31), PLUSGIRO (15), BANKGIRO (56), AWARDING (7).
  Provide bank_account_id (or include the bank_account object when creating/updating the invoice).
• Custom description: SPECIAL/OTHER (13).
  Provide payment_method_text (it is only kept when payment_method = 13).
• All other payment methods do not require additional bank/payment fields.

Special cases (invoice type)

• IssuedSelfInvoice:
  • DEBIT (2) / DEBIT SEPA (59) require bank_account_id (company bank account).
  • Transfer-like methods (TRANSFER (4), TRANSFER SEPA (58), DEBIT TRANSFER (31), PLUSGIRO (15), BANKGIRO (56), AWARDING (7)) require invoice.contact_iban (some PDF-only flows may not require it, but most e-invoice exports do).
• IssuedSimplifiedInvoice: DEBIT (2) / DEBIT SEPA (59) do not require invoice.contact_iban.

Special cases (export format)

• Facturae:
  • If you set a payment_method and the invoice is not a credit note, you must provide either a valid terms (non-custom) or due_date (when using terms = "custom").
  • If the invoice is DEBIT/DEBIT SEPA, the customer bank account must be available (the contact’s bank_account_number or a valid invoice.contact_iban).
  • If the invoice is TRANSFER (including transfer-like methods), the company bank account must be available (via bank_account_id / bank_account) and contain a valid account number/IBAN.
• Svefaktura: debit payments (DEBIT/DEBIT SEPA) are not supported.
• FatturaPA: COMPENSATION (14) is not allowed.
• XRechnung (UBL/CII):
  • If the invoice is DEBIT/DEBIT SEPA, you must provide bank_assigned_creditor_reference and invoice.contact_iban.
  • For v3 profiles, mandate_reference_identifier is also required.

2. Using the Endpoints

Below we show how to use the main endpoints to manage payments and bank accounts associated with contacts and invoices.

2.1. Create Bank Accounts

When creating a bank account, you must specify the account type to indicate which fields to use:

• number: use the number field only.
  • number: Bank account number.
• iban: use iban and bic.
  • iban: International Bank Account Number.
  • bic: SWIFT code of the bank.

Request Example:

curl --request POST \
     --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/bank_accounts \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "bank_account": {
    "type": "number",
    "number": "ES9121000418450200051332",
    "name": "Ejemplo S.L.",
    "sufix": 123
  }
}
'

sufix is the suffix used for the creditor identifier in SEPA files.

Sample Response:

{
  "bank_account": {
    "type": "number",
    "id": 3296,
    "name": "Ejemplo S.L.",
    "number": "ES9121000418450200051332",
    "sufix": 123,
    "country": "es",
    "created_at": "2025-07-14T11:37:02.000Z",
    "updated_at": "2025-07-14T11:37:02.000Z"
  }
}

Keep bank_account.id to reference this account in future requests.

Bank Account API Reference

2.2. Create Contact

Configuring the payment details for invoices sent to a contact is useful to avoid managing this information each time you need to send a document.

Request Example:

curl --request POST \
     --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "contact": {
	    ...
	    "terms": "custom",
	    "payment_method": 4,
	    "payment_reminder_days": 2,
	    "payment_method_text": "Example text",
	    "bank_account_id": 3296,
	    "bank_account_number": "IT12345678901"
	    ...
	  }
}
'

Contact API Reference

2.3. Create Invoice

You don’t need to re-specify any payment fields that were already set on the contact unless you need to override them. To minimize API calls, include all required payment details—such as payment_method, bank_account_id, payment_terms, etc.—directly in the Create Invoice request instead of creating Contacts or Bank Accounts beforehand.

Request Example:

curl --request POST \
     --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
     --header 'content-type: application/json' \
     --data '

    {"invoice": {
        ...
        "payment_method": 4,
        "contact_iban": "DE44100000000123456789",
        "payment_reminder_days": 5,
        "bank_account_id": 3296
        ...
    }}
    '

And if you haven’t provided bank_account_id, you can always include the bank_account object:

    {"invoice": {
        ...
        "bank_account": {
            "type": "number",
            "number": "ES9121000418450200051332"
    },
        ...
    }}
    '