Mètodes de pagament

Aquesta guia descriu els codis de mètode de pagament interns a B2Brouter i la seva codificació corresponent en UBL, Facturae i FatturaPA.

Equivalències:

Camp intern de B2Brouter: payment_method
Camp Facturae: PaymentMeans (element a /facturae:Facturae/Invoices/Invoice/PaymentDetails/Installment/PaymentMeans)
Camp UBL: cbc:PaymentMeansCode (element a /Invoice/cac:PaymentMeans/cbc:PaymentMeansCode)
Camp FatturaPA: ModalitaPagamento (element a /p:FatturaElettronica/FatturaElettronicaBody/DatiPagamento/DettaglioPagamento/ModalitaPagamento)
Camp CII: TypeCode (element a rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode)
ID de Business Term: BT-81

1. Taula de codis de pagament

Mètode	Referència interna	UBL	Facturae	FatturaPA	Descripció
CASH	1	10	01	MP01	Pagament en moneda (inclosos bitllets i monedes) en circulació, inclosos els dipòsits en compte corrent.
DEBIT	2	49	02	MP19	Dèbit directe (l’import s’ha de, o s’ha deduït directament del compte bancari del client).
HOLD	3	8	03	MP12	Indica que el banc ha de retenir el pagament per a la seva recollida pel beneficiari o d’altres instruccions.
TRANSFER	4	30	04	MP05	Transferència bancària (l’import s’ha de, o s’ha acreditat directament al compte bancari del proveïdor).
AWARDING	7	ZZZ	07		Pagament per cessió o adjudicació
PAGARE N O	10	60	10	MP06	Pagaré no transferible.
CHEQUE	11	20	11	MP02	Pagament amb xec.
REPOSITION	12	ZZZ	12	MP22	Reemborsament en compte obert.
SPECIAL/OTHER	13	ZZZ	13	MP22	Defineix qualsevol altre mètode de pagament; usa `payment_method_text` per a descripcions personalitzades.
COMPENSATION	14	97	14	MP22	Imports que dos socis es deuen mútuament per compensar-se i evitar pagaments innecessaris.
PLUSGIRO	15	50	15	MP18	Mètode de pagament suec estàndard que utilitza el sistema de gir postal.
CHEQUE B	17	23	17	MP03	Pagament amb xec de caixa emès per una entitat financera.
BANK CARD	19	48	19	MP08	Pagament amb targeta emesa per un banc o altra entitat financera.
DEBIT TRANSFER	31	31	04	MP13	Pagament per moviment de dèbit de fons d’un compte a un altre.
CREDIT CARD	54	54	19	MP08	Pagament amb targeta de crèdit
BANKGIRO	56	56	04	MP03	Mètode de pagament que utilitza la xarxa bancgiro.
TRANSFER SEPA	58	58	04	MP05	Transferència de crèdit SEPA (els fons s’acrediten al compte bancari del proveïdor).
DEBIT SEPA	59	59	02	MP19	Dèbit directe SEPA (els fons es dedueixen del compte bancari del client; pot ser necessari un mandat).
GIRO	101	ZZZ	13		Giro
PAY NOW	102	ZZZ	13		Pagament immediat (Pay Now)

1.1 Camps addicionals requerits (API)

Depenent del payment_method, pot ser necessari proporcionar camps addicionals perquè la factura es pugui generar/exportar correctament.
Aquesta secció tracta els requisits generals de dades bancàries i de pagament; alguns formats de factura electrònica també limiten els codis de pagament que accepten.

Requisits universals

Compte bancari del client (pagador) i referència del mandat: DEBIT (2), DEBIT SEPA (59). Ni l’IBAN del pagador (invoice.contact_iban, o l’IBAN del contacte) ni mandate_reference_identifier són obligatoris en general: ho decideix el format d’exportació. Consulta Casos especials (format d’exportació) més avall (Facturae, Peppol BIS 3.0, XRechnung). Un IBAN que proporcionis ha de ser vàlid. Si el cobrament es fa a través d’un proveïdor de pagaments que només et dona la referència del mandat (per exemple GoCardless), envia només mandate_reference_identifier: UBL EN 16931, Peppol BIS 3.0 (inclosa la France CIUS) i CII porten la referència del mandat (BT-89) sense el compte del pagador (BT-91), que és opcional a EN 16931. Les factures sense IBAN del pagador no s’inclouen als fitxers SEPA de domiciliació que genera B2Brouter (Bancs → Arxius SEPA), perquè el fitxer necessita l’IBAN del deutor.
Termes de pagament: DEBIT (2). Proporciona terms (no pot ser 0/buit).
Data de venciment del pagament (la majoria d’exportacions): si defineixes un payment_method i fas servir terms = "custom", has de proporcionar due_date. Les factures que s’envien per Peppol o per SDI no ho necessiten. Si fas servir un terms que no és custom, B2Brouter calcula la due_date automàticament.
Compte bancari de l’empresa (beneficiari): TRANSFER (4), TRANSFER SEPA (58), DEBIT TRANSFER (31), PLUSGIRO (15), BANKGIRO (56), AWARDING (7). Proporciona bank_account_id (o l’objecte bank_account en crear la factura; en actualitzar-la, només es llegeix bank_account_id).
Descripció personalitzada: SPECIAL/OTHER (13). Proporciona payment_method_text.
La resta de mètodes de pagament no requereixen camps bancaris o de pagament addicionals.

Casos especials (tipus de factura)

IssuedSelfInvoice:
- DEBIT (2) / DEBIT SEPA (59) requereixen bank_account_id (compte bancari de l’empresa).
- Els mètodes de tipus transferència (TRANSFER (4), TRANSFER SEPA (58), DEBIT TRANSFER (31), PLUSGIRO (15), BANKGIRO (56), AWARDING (7)) requereixen invoice.contact_iban. Si l’autofactura s’envia en PDF, no cal.
IssuedSimplifiedInvoice: DEBIT (2) / DEBIT SEPA (59) no requereixen invoice.contact_iban.

Casos especials (format d’exportació)

Facturae:
- Si defineixes un payment_method i la factura no és una nota de crèdit, has de proporcionar un terms vàlid (que no sigui custom) o due_date (si fas servir terms = "custom").
- Si la factura és DEBIT/DEBIT SEPA, l’IBAN del client ha d’estar disponible (invoice.contact_iban, o l’IBAN del contacte). Es comprova en desar la factura.
- Si la factura és TRANSFER (4), el compte bancari de l’empresa ha d’estar disponible (amb bank_account_id / bank_account) i ha de tenir un número de compte o un IBAN vàlid. Es comprova en enviar la factura.
Peppol BIS 3.0 i Peppol SG: si la factura és DEBIT/DEBIT SEPA, cal mandate_reference_identifier (regla PEPPOL-EN16931-R061), i es comprova en desar la factura. L’IBAN del pagador és opcional.
Svefaktura: els pagaments de dèbit (DEBIT/DEBIT SEPA) no estan admesos.
FatturaPA: COMPENSATION (14) no està permès.
XRechnung 2.3 i 3.0 (UBL/CII): es comprova en desar la factura.
- Si la factura és DEBIT/DEBIT SEPA, has de proporcionar bank_assigned_creditor_reference i invoice.contact_iban.
- A la versió 3.0, també cal mandate_reference_identifier.
- Les versions anteriors a la 2.3 no fan aquestes comprovacions en desar la factura.
Formats CII (XRechnung CII, ZUGFeRD, Factur-X): si l’import a pagar és positiu, el document ha de portar due_date o payment_terms (regla BR-CO-25). La regla també s’aplica a les notes de crèdit.
- Per crear una nota de crèdit sense data de venciment, envia payment_terms amb un text i no enviïs due_date.
- Si el document no té data de venciment ni payment_terms, la petició es rebutja amb un error al paràmetre terms.
- Als formats UBL, com Peppol BIS 3.0 o XRechnung UBL, les notes de crèdit no fan aquesta comprovació.
Països Baixos (UBL, com Peppol BIS 3 o NLCIUS / SI-UBL): s’aplica quan l’empresa emissora és dels Països Baixos.
- El payment_method és obligatori (BR-NL-11). Si no l’envies, la factura es rebutja amb «Payment method can’t be blank».
- Només s’accepten els mètodes amb codi UBL 30, 48, 49, 57, 58 o 59 (BR-NL-12): TRANSFER (4), TRANSFER SEPA (58), DEBIT (2), DEBIT SEPA (59) i BANK CARD (19). Els mètodes que s’exporten com a ZZZ, per exemple SPECIAL/OTHER (13), es rebutgen amb «Payment method is invalid».
- En NLCIUS la llista s’aplica a tots els documents. En Peppol BIS 3, només quan el client també és dels Països Baixos.
- La mateixa validació s’aplica quan deses la factura des del web.

2. Ús dels endpoints

2.1. Crear comptes bancaris

Quan creïs un compte bancari, has d’especificar el type del compte:

number: fes servir només el camp number.
iban: fes servir iban i bic.

Exemple de petició:

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

Resposta d’exemple:

{
  "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"
  }
}

Guarda bank_account.id per referenciar aquest compte en futures peticions.

Cada petició crea un compte nou, encara que ja n’existeixi un amb el mateix IBAN: l’API no comprova si el compte ja existeix. Crea cada compte una sola vegada i reutilitza’n l’id.

Referència de l’API de comptes bancaris

2.2. Crear contacte

Exemple de petició:

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

Referència de l’API de contactes

2.3. Crear factura

No cal tornar a especificar cap camp de pagament que ja s’hagi definit al contacte tret que els necessitis substituir.

Exemple de petició:

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

Si no proporciones bank_account_id, en crear la factura pots incloure l’objecte bank_account:

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

Si envies l’objecte bank_account en lloc de bank_account_id, B2Brouter busca un compte existent de l’empresa:

Si l’objecte porta name, només el reutilitza si coincideixen iban, bic i name (o number i name). Un nom diferent per al mateix IBAN crea un compte nou.
Si no porta name, el busca per iban i bic, i després només per iban (o per number).
Si no en troba cap, en crea un de nou.

L’objecte bank_account només es llegeix en crear la factura. En actualitzar-la, l’objecte s’ignora i només s’aplica bank_account_id. Si una factura desada amb un mètode de tipus transferència no té compte bancari, cada actualització es rebutja fins que la mateixa petició porti bank_account_id. També pots triar el compte a la factura des de l’aplicació web.

En una integració, envia bank_account_id a totes les factures i deixa l’objecte bank_account per a casos puntuals. Així evitaràs comptes repetits amb el mateix IBAN.

Si esborres un compte duplicat, les factures i els contactes que hi apuntaven es queden sense compte bancari i sense mètode de pagament.