Payment Methods

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

Method	Internal Reference	UBL	Facturae	FatturaPA	Description
CASH	1	10	01	MP01	Payment by currency (including bills and coins) in circulation, including checking account deposits.
DEBIT	2	49	02	MP19	Direct debit (The amount is to be, or has been, directly debited from the customer’s bank account).
HOLD	3	8	03	MP12	Indicates that the bank should hold the payment for collection by the beneficiary or other instructions.
TRANSFER	4	30	04	MP05	Bank transfer (The amount is to be, or has been, directly credited to the supplier’s bank account).
AWARDING	7	ZZZ	07		Payment by assignment or award
PAGARE N O	10	60	10	MP06	Non transferable promissory note. Payment by an unconditional promise in writing made by one person to another, signed by the maker, engaging to pay on demand or at a fixed or determinable future time a sum certain in money, to order or to bearer.
CHEQUE	11	20	11	MP02	Payment by a pre-printed form on which instructions are given to an account holder (a bank or building society) to pay a stated sum to a named recipient.
REPOSITION	12	ZZZ	12	MP22	Open account reimbursement.
SPECIAL/OTHER	13	ZZZ	13	MP22	Defines any other payment method; use `payment_method_text` for custom descriptions.
COMPENSATION	14	97	14	MP22	Amounts which two partners owe to each other to be compensated in order to avoid useless payments.
PLUSGIRO	15	50	15	MP18	A standard Swedish payment method using the postal giro system.
CHEQUE B	17	23	17	MP03	Payment by a pre-printed form, which has been completed by a financial institution, on which instructions are given to an account holder (a bank or building society) to pay a stated sum to a named recipient.
BANK CARD	19	48	19	MP08	Payment by means of a card issued by a bank or other financial institution.
DEBIT TRANSFER	31	31	04	MP13	Payment by debit movement of funds from one account to another.
CREDIT CARD	54	54	19	MP08	Payment made by means of credit card
BANKGIRO	56	56	04	MP03	Payment method using the bank giro network.
TRANSFER SEPA	58	58	04	MP05	SEPA credit transfer (Funds are credited to the supplier’s bank account).
DEBIT SEPA	59	59	02	MP19	SEPA direct debit (Funds are debited from the customer’s bank account; mandate may be required).
GIRO	101	ZZZ	13		Giro
PAY NOW	102	ZZZ	13		Immediate payment (Pay Now)

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) and mandate reference: DEBIT (2), DEBIT SEPA (59). Neither the payer IBAN (invoice.contact_iban, or the IBAN on the contact) nor mandate_reference_identifier is required universally: the export format decides. See Special cases (export format) below (Facturae, Peppol BIS 3.0, XRechnung). An IBAN you provide must be valid. When the payment is collected through a payment provider that only gives you the mandate reference (for example GoCardless), send mandate_reference_identifier alone: UBL EN 16931, Peppol BIS 3.0 (France CIUS included) and CII carry the mandate reference (BT-89) without the payer account (BT-91), which is optional in EN 16931. Invoices without a payer IBAN are not included in the SEPA direct debit files that B2Brouter generates (Banks → SEPA files), because the file needs the debtor IBAN.
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 the invoice; an update reads only bank_account_id).
Custom description: SPECIAL/OTHER (13).
Provide payment_method_text.
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. It is not required when the self-invoice is sent as PDF.
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 IBAN must be available (invoice.contact_iban, or the IBAN on the contact). It is checked when you save the invoice.
- If the invoice is TRANSFER (4), the company bank account must be available (via bank_account_id / bank_account) and contain a valid account number/IBAN. It is checked when you send the invoice.
Peppol BIS 3.0 and Peppol SG: if the invoice is DEBIT/DEBIT SEPA, mandate_reference_identifier is required (rule PEPPOL-EN16931-R061), and it is checked when you save the invoice. The payer IBAN is optional.
Svefaktura: debit payments (DEBIT/DEBIT SEPA) are not supported.
FatturaPA: COMPENSATION (14) is not allowed.
XRechnung 2.3 and 3.0 (UBL/CII): checked when you save the invoice.
- If the invoice is DEBIT/DEBIT SEPA, you must provide bank_assigned_creditor_reference and invoice.contact_iban.
- In version 3.0, mandate_reference_identifier is also required.
- Versions earlier than 2.3 do not run these checks when you save the invoice.
CII formats (XRechnung CII, ZUGFeRD, Factur-X): if the amount due is positive, the document must carry due_date or payment_terms (rule BR-CO-25). The rule also applies to credit notes.
- To create a credit note without a due date, send payment_terms with a text and do not send due_date.
- If the document has neither a due date nor payment_terms, the request is refused with an error on the terms parameter.
- In UBL formats, such as Peppol BIS 3.0 or XRechnung UBL, credit notes are not checked against this rule.
Netherlands (UBL, such as Peppol BIS 3 or NLCIUS / SI-UBL): applies when the issuing company is established in the Netherlands.
- payment_method is required (BR-NL-11). Without it, the invoice is refused with “Payment method can’t be blank”.
- Only methods with UBL code 30, 48, 49, 57, 58 or 59 are accepted (BR-NL-12): TRANSFER (4), TRANSFER SEPA (58), DEBIT (2), DEBIT SEPA (59) and BANK CARD (19). Methods exported as ZZZ, for example SPECIAL/OTHER (13), are refused with “Payment method is invalid”.
- In NLCIUS the list applies to every document. In Peppol BIS 3, only when the customer is also established in the Netherlands.
- The same validation applies when you save the invoice from the web.

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'
'

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.

Each request creates a new account, even if an account with the same IBAN already exists: the API does not check for an existing account. Create each account once and reuse its id.

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'
'

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'
    '

If you don’t provide bank_account_id, you can include the bank_account object when you create the invoice:

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

If you send the bank_account object instead of bank_account_id, B2Brouter looks for an existing company account:

If the object includes name, the account is reused only when iban, bic and name match (or number and name). A different name for the same IBAN creates a new account.
If it has no name, the account is looked up by iban and bic, then by iban alone (or by number).
If no account matches, a new one is created.

The bank_account object is read only when the invoice is created. On an update, the object is ignored and only bank_account_id is applied. If a saved invoice with a transfer-like method has no bank account, every update is refused until the same request carries bank_account_id. You can also select the account on the invoice in the web application.

In an integration, send bank_account_id on every invoice and keep the bank_account object for occasional cases. This prevents repeated accounts with the same IBAN.

If you delete a duplicate account, the invoices and contacts that pointed to it are left without a bank account and without a payment method.