Métodos de pago

Esta guía describe los códigos de método de pago internos de B2Brouter y su codificación correspondiente en UBL, Facturae y FatturaPA.

Equivalencias:

• Campo interno de B2Brouter: payment_method
• Campo Facturae: PaymentMeans (elemento en /facturae:Facturae/Invoices/Invoice/PaymentDetails/Installment/PaymentMeans)
• Campo UBL: cbc:PaymentMeansCode (elemento en /Invoice/cac:PaymentMeans/cbc:PaymentMeansCode)
• Campo FatturaPA: ModalitaPagamento (elemento en /p:FatturaElettronica/FatturaElettronicaBody/DatiPagamento/DettaglioPagamento/ModalitaPagamento)
• Campo CII: TypeCode (elemento en rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode)
• ID de términos de negocio: BT-81

1. Tabla de códigos de pago

Método	Referencia interna	UBL	Facturae	FatturaPA	Descripción
CASH	1	10	01	MP01	Pago en moneda (incluyendo billetes y monedas) en circulación, incluidos los depósitos en cuentas corrientes.
DEBIT	2	49	02	MP19	Débito directo (el importe se adeudará o se ha adeudado directamente desde la cuenta bancaria del cliente).
HOLD	3	8	03	MP12	Indica que el banco debe retener el pago para su cobro por el beneficiario u otras instrucciones.
TRANSFER	4	30	04	MP05	Transferencia bancaria (el importe se abonará o se ha abonado directamente en la cuenta bancaria del proveedor).
AWARDING	7	ZZZ	07		Pago por cesión o adjudicación.
PAGARE N O	10	60	10	MP06	Pagaré no transferible. Pago mediante una promesa incondicional por escrito hecha por una persona a otra, firmada por el librador, comprometiéndose a pagar a la vista o en una fecha futura fija o determinable una cantidad cierta de dinero, a la orden o al portador.
CHEQUE	11	20	11	MP02	Pago mediante un formulario preimpreso en el que se dan instrucciones al titular de una cuenta (banco o sociedad de construcción) para pagar una cantidad determinada a un beneficiario designado.
REPOSITION	12	ZZZ	12	MP22	Reembolso en cuenta abierta.
SPECIAL/OTHER	13	ZZZ	13	MP22	Define cualquier otro método de pago; usa payment_method_text para descripciones personalizadas.
COMPENSATION	14	97	14	MP22	Importes que dos socios se deben mutuamente y que se compensan para evitar pagos innecesarios.
PLUSGIRO	15	50	15	MP18	Método de pago sueco estándar que utiliza el sistema de giro postal.
CHEQUE B	17	23	17	MP03	Pago mediante un formulario preimpreso, completado por una entidad financiera, en el que se dan instrucciones al titular de una cuenta (banco o sociedad de construcción) para pagar una cantidad determinada a un beneficiario designado.
BANK CARD	19	48	19	MP08	Pago mediante una tarjeta emitida por un banco u otra entidad financiera.
DEBIT TRANSFER	31	31	04	MP13	Pago mediante movimiento de débito de fondos de una cuenta a otra.
CREDIT CARD	54	54	19	MP08	Pago realizado mediante tarjeta de crédito.
BANKGIRO	56	56	04	MP03	Método de pago que utiliza la red bancaria de giro.
TRANSFER SEPA	58	58	04	MP05	Transferencia de crédito SEPA (los fondos se abonan en la cuenta bancaria del proveedor).
DEBIT SEPA	59	59	02	MP19	Débito directo SEPA (los fondos se adeudan en la cuenta bancaria del cliente; puede requerirse mandato).
GIRO	101	ZZZ	13		Giro.
PAY NOW	102	ZZZ	13		Pago inmediato (Pay Now).

1.1 Campos adicionales requeridos (API)

Según el payment_method, puede que necesites proporcionar campos adicionales para que la factura pueda generarse/exportarse correctamente.
Esta sección se centra en los requisitos universales de datos bancarios/de pago; algunos formatos de factura electrónica pueden restringir aún más los códigos de pago aceptados.

Requisitos universales

• Cuenta bancaria del cliente (pagador) y referencia del mandato: DEBIT (2), DEBIT SEPA (59). Ni el IBAN del pagador (invoice.contact_iban, o el IBAN del contacto) ni mandate_reference_identifier son obligatorios en general: lo decide el formato de exportación. Consulta Casos especiales (formato de exportación) más abajo (Facturae, Peppol BIS 3.0, XRechnung). Un IBAN que proporciones debe ser válido. Si el cobro se hace a través de un proveedor de pagos que solo te da la referencia del mandato (por ejemplo GoCardless), envía solo mandate_reference_identifier: UBL EN 16931, Peppol BIS 3.0 (incluida la France CIUS) y CII llevan la referencia del mandato (BT-89) sin la cuenta del pagador (BT-91), que es opcional en EN 16931. Las facturas sin IBAN del pagador no se incluyen en los ficheros SEPA de domiciliación que genera B2Brouter (Bancos → Archivos SEPA), porque el fichero necesita el IBAN del deudor.
• Condiciones de pago: DEBIT (2). Proporciona terms (no puede ser 0 ni estar en blanco).
• Fecha de vencimiento del pago (la mayoría de las exportaciones):
  Si estableces un payment_method y usas terms = "custom", debes proporcionar due_date (excepto para algunos transportes como Peppol y SDI). Si usas un terms no personalizado, el sistema calcula due_date automáticamente.
• Cuenta bancaria de la empresa (beneficiario): TRANSFER (4), TRANSFER SEPA (58), DEBIT TRANSFER (31), PLUSGIRO (15), BANKGIRO (56), AWARDING (7).
  Proporciona bank_account_id (o incluye el objeto bank_account al crear la factura; al actualizarla, solo se lee bank_account_id).
• Descripción personalizada: SPECIAL/OTHER (13).
  Proporciona payment_method_text.
• Todos los demás métodos de pago no requieren campos bancarios/de pago adicionales.

Casos especiales (tipo de factura)

• IssuedSelfInvoice:
  • DEBIT (2) / DEBIT SEPA (59) requieren bank_account_id (cuenta bancaria de la empresa).
  • Los métodos de tipo transferencia (TRANSFER (4), TRANSFER SEPA (58), DEBIT TRANSFER (31), PLUSGIRO (15), BANKGIRO (56), AWARDING (7)) requieren invoice.contact_iban. Si la autofactura se envía en PDF, no es necesario.
• IssuedSimplifiedInvoice: DEBIT (2) / DEBIT SEPA (59) no requieren invoice.contact_iban.

Casos especiales (formato de exportación)

• Facturae:

  • Si estableces un payment_method y la factura no es una nota de crédito, debes proporcionar un terms válido (no personalizado) o due_date (cuando uses terms = "custom").
  • Si la factura es DEBIT/DEBIT SEPA, el IBAN del cliente debe estar disponible (invoice.contact_iban, o el IBAN del contacto). Se comprueba al guardar la factura.
  • Si la factura es TRANSFER (4), la cuenta bancaria de la empresa debe estar disponible (mediante bank_account_id / bank_account) y contener un número de cuenta/IBAN válido. Se comprueba al enviar la factura.

• Peppol BIS 3.0 y Peppol SG: si la factura es DEBIT/DEBIT SEPA, se requiere mandate_reference_identifier (regla PEPPOL-EN16931-R061), y se comprueba al guardar la factura. El IBAN del pagador es opcional.

• Svefaktura: los pagos por débito (DEBIT/DEBIT SEPA) no están admitidos.

• FatturaPA: COMPENSATION (14) no está permitido.

• XRechnung 2.3 y 3.0 (UBL/CII): se comprueba al guardar la factura.

  • Si la factura es DEBIT/DEBIT SEPA, debes proporcionar bank_assigned_creditor_reference e invoice.contact_iban.
  • En la versión 3.0, también se requiere mandate_reference_identifier.
  • Las versiones anteriores a la 2.3 no hacen estas comprobaciones al guardar la factura.

• Formatos CII (XRechnung CII, ZUGFeRD, Factur-X): si el importe a pagar es positivo, el documento debe llevar due_date o payment_terms (regla BR-CO-25). La regla también se aplica a las notas de crédito.

  • Para crear una nota de crédito sin fecha de vencimiento, envía payment_terms con un texto y no envíes due_date.
  • Si el documento no tiene fecha de vencimiento ni payment_terms, la petición se rechaza con un error en el parámetro terms.
  • En los formatos UBL, como Peppol BIS 3.0 o XRechnung UBL, las notas de crédito no hacen esta comprobación.

• Países Bajos (UBL, como Peppol BIS 3 o NLCIUS / SI-UBL): se aplica cuando la empresa emisora es de los Países Bajos.

  • El payment_method es obligatorio (BR-NL-11). Sin él, la factura se rechaza con «Payment method can’t be blank».
  • Solo se aceptan los métodos con código UBL 30, 48, 49, 57, 58 o 59 (BR-NL-12): TRANSFER (4), TRANSFER SEPA (58), DEBIT (2), DEBIT SEPA (59) y BANK CARD (19). Los métodos que se exportan como ZZZ, por ejemplo SPECIAL/OTHER (13), se rechazan con «Payment method is invalid».
  • En NLCIUS la lista se aplica a todos los documentos. En Peppol BIS 3, solo cuando el cliente también es de los Países Bajos.
  • La misma validación se aplica cuando guardas la factura desde la web.

2. Uso de los endpoints

A continuación se muestra cómo usar los principales endpoints para gestionar pagos y cuentas bancarias asociadas a contactos y facturas.

2.1. Crear cuentas bancarias

Al crear una cuenta bancaria, debes especificar el type de la cuenta para indicar qué campos usar:

• number: usa solo el campo number.
  • number: Número de cuenta bancaria.
• iban: usa iban y bic.
  • iban: Número de cuenta bancaria internacional.
  • bic: Código SWIFT del banco.

Ejemplo de solicitud:

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 es el sufijo utilizado para el identificador de acreedor en los archivos SEPA.

Respuesta de ejemplo:

{
  "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 el bank_account.id para hacer referencia a esta cuenta en solicitudes futuras.

Cada solicitud crea una cuenta nueva, aunque ya exista una con el mismo IBAN: la API no comprueba si la cuenta ya existe. Crea cada cuenta una sola vez y reutiliza su id.

Referencia de API de cuentas bancarias

2.2. Crear contacto

Configurar los datos de pago para las facturas enviadas a un contacto resulta útil para evitar gestionar esta información cada vez que necesites enviar un documento.

Ejemplo de solicitud:

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

Referencia de API de contactos

2.3. Crear factura

No necesitas volver a especificar los campos de pago que ya estaban establecidos en el contacto a menos que necesites sobreescribirlos. Para minimizar las llamadas a la API, incluye todos los datos de pago requeridos —como payment_method, bank_account_id, payment_terms, etc.— directamente en la solicitud de creación de factura en lugar de crear Contactos o Cuentas bancarias de antemano.

Ejemplo de solicitud:

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 proporcionas bank_account_id, al crear la factura puedes incluir el objeto bank_account:

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

Si envías el objeto bank_account en lugar de bank_account_id, B2Brouter busca una cuenta existente de la empresa:

• Si el objeto incluye name, solo la reutiliza si coinciden iban, bic y name (o number y name). Un nombre distinto para el mismo IBAN crea una cuenta nueva.
• Si no incluye name, la busca por iban y bic, y después solo por iban (o por number).
• Si no encuentra ninguna, crea una nueva.

El objeto bank_account solo se lee al crear la factura. Al actualizarla, el objeto se ignora y solo se aplica bank_account_id. Si una factura guardada con un método de tipo transferencia no tiene cuenta bancaria, cada actualización se rechaza hasta que la misma petición lleve bank_account_id. También puedes elegir la cuenta en la factura desde la aplicación web.

En una integración, envía bank_account_id en todas las facturas y deja el objeto bank_account para casos puntuales. Así evitarás cuentas repetidas con el mismo IBAN.

Si eliminas una cuenta duplicada, las facturas y los contactos que apuntaban a ella se quedan sin cuenta bancaria y sin método de pago.