external_invoice en Create payment. Funciona para facturas únicas y para las facturas de las suscripciones de Stripe Billing. Las reglas de monto son diferentes entre ambas.
Cómo funciona
- Crea la factura en Stripe. Crea y finaliza la factura para que quede abierta. Guarda el id de la factura (
in_...) y el id del cliente (cus_...). - Cobra el pago con Yuno. Crea el pago desde tu backend con el objeto
external_invoice(consulta Crear el pago). Antes de cobrar, Yuno verifica la factura en Stripe. Luego Yuno cobra a través de tus proveedores y tu enrutamiento. - Yuno informa el resultado. Poco después de que el pago sea exitoso, Yuno lo informa a la factura en Stripe. Cuando cubre el monto pendiente, Stripe marca la factura como paid. Un pago rechazado se registra como un intento fallido y la factura sigue open, para que puedas intentarlo de nuevo.
Requisitos previos
- Una cuenta de Yuno con tus proveedores conectados y el enrutamiento publicado.
- El mismo onboarding que las suscripciones de Stripe Billing: Yuno guarda una clave restringida de Stripe que puede leer facturas, informar pagos y reembolsos, adjuntar pagos a facturas y crear notas de crédito, y tu cuenta de Yuno está habilitada para esta función (consulta la nota anterior).
Crear el pago
Crea el pago como de costumbre y agrega el objetoexternal_invoice:
Cosas que debes saber:
- Envía el monto en unidades principales (50.00, no 5000).
- Envía un
X-Idempotency-Keycon la solicitud. Si repites la misma solicitud con la misma clave, Yuno devuelve el mismo pago y no cobra dos veces. - Un pago puede incluir como máximo uno de
external_subscription,external_invoiceysubscription. Enviarexternal_invoicejunto con alguno de los otros devuelve400 INVALID_REQUEST. - La cuenta en
account_iddebe estar habilitada para esta función (consulta la nota al inicio de la página).
external_invoice no tiene esa clave.
Reglas de monto
Lo que Yuno acepta depende de la factura y del monto que envías, en comparación con el monto pendiente de la factura.
Un monto mayor que el monto pendiente se rechaza antes del cobro siempre que Yuno pueda verificar la factura (consulta Qué verifica Yuno antes de cobrar).
Facturas únicas y facturas cobradas por factura
Un monto menor se acepta y la factura sigue abierta por el resto, con el monto pendiente reducido por lo que se pagó. Tú cobras el resto. Yuno nunca cobra el resto por sí mismo. Para cobrarlo, envía otro pago con el mismoexternal_invoice por el monto pendiente. Puedes repetir esto las veces que sea necesario, hasta que la factura se pague. Cada pago exitoso tiene su propio registro de pago en Stripe, y la factura queda pagada cuando no queda nada pendiente.
Si lo que queda es menor que el cobro mínimo de Stripe para la moneda (USD 0.50 para dólares estadounidenses), Stripe marca la factura como pagada, reduce su monto adeudado y agrega el remanente al saldo del cliente en Stripe, para cobrarlo con la siguiente factura del cliente.
Facturas de suscripciones que Stripe cobra automáticamente
La primera factura, cualquier factura posterior y cada factura de renovación de una suscripción cuyo método de cobro escharge_automatically requieren el monto pendiente exacto, porque Stripe no acepta un pago por un monto diferente en estas facturas.
- Un monto menor devuelve
400 EXTERNAL_INVOICE_REJECTED. - Un monto mayor devuelve
400 EXTERNAL_INVOICE_AMOUNT_EXCEEDS_REMAINING. - El monto exacto se acepta y la factura se paga. Cuando era la primera factura de la suscripción, la suscripción pasa a estar activa.
EXTERNAL_INVOICE_NOT_OPEN.
Qué verifica Yuno antes de cobrar
Antes de tocar cualquier tarjeta, Yuno verifica la factura en Stripe. Cuando la verificación rechaza el pago, no se cobra nada y no se crea ningún pago. La respuesta es un HTTP 400 con este cuerpo:
Yuno también valida el objeto en sí, antes de verificar la factura:
Si Yuno no puede verificar la factura en ese momento, por ejemplo porque Stripe no responde a tiempo, el pago continúa sin la verificación y Yuno lo informa a la factura después. Si la factura no puede aceptarlo entonces, por ejemplo porque el monto es mayor que lo que queda o la factura ya está pagada, se cobra al cliente pero el pago no se aplica a la factura, y Yuno no lo reembolsa automáticamente. En ese caso, contacta a tu Technical Account Manager.
Reintentos y duplicados
- Repite la misma solicitud. Un reintento con el mismo
X-Idempotency-Keydevuelve el mismo pago y no se cobra dos veces. - Intenta de nuevo después de un rechazo. Un pago rechazado deja la factura abierta. Para intentarlo de nuevo, crea un nuevo pago para la factura con un nuevo
X-Idempotency-Key. - No pagues una factura dos veces. Una vez que Stripe muestra la factura como pagada, un nuevo pago para ella se rechaza con
EXTERNAL_INVOICE_NOT_OPEN. Yuno informa un pago a Stripe poco después de que es exitoso, no en el momento de la respuesta de la API, por lo que un segundo pago enviado antes de eso no se rechaza. Envía un pago a la vez por cada factura y espera hasta que Stripe lo muestre en la factura antes de enviar otro. Si se cobra dos veces a un cliente, contacta a tu Technical Account Manager.
Reembolsos
Reembolsa un pago hecho conexternal_invoice a través de la API de Yuno o del Dashboard, como con cualquier pago. Yuno informa el reembolso a Stripe en el registro del pago. Lo que hace además depende de la factura:
- La factura está pagada. Yuno informa el reembolso en el registro del pago y agrega a la factura una nota de crédito por el monto reembolsado, para que tus libros contables de Stripe se mantengan consistentes. Se admiten reembolsos parciales, cada uno con su propia nota de crédito, y los reembolsos de un pago nunca suman más que el pago.
- La factura sigue abierta (pagada en parte). Yuno informa el reembolso en el registro del pago y no agrega nota de crédito. En Stripe, la factura sigue contando ese pago como pagado, y cualquier nota de crédito que agregues allí también reduce lo que el cliente aún debe, por lo que cómo saldar el resto de la factura es una decisión tuya en Stripe.
Paga una factura de Stripe con un enlace de pago
POST /v1/payment-links acepta un objeto external_invoice opcional. id es obligatorio y debe tener de 3 a 255 caracteres después de quitar los espacios. customer_id es opcional y debe tener de 3 a 255 caracteres. La respuesta del enlace devuelve el objeto.
external_invoiceno se puede combinar con el bloquesubscription, ni con una listataxesque no esté vacía. Cualquiera de los dos devuelve400.- Tu cuenta debe estar habilitada para facturas externas (consulta la nota al inicio de la página). Yuno no rechaza un enlace de una cuenta que no está habilitada, pero no puede verificar la factura cuando el cliente paga ni informar el pago a Stripe.
- Si envías un encabezado
X-Account-Code, debe ser la cuenta enaccount_id. De lo contrario, la API devuelve400 INVALID_REQUEST: “Invalid Request. The account-code header does not match account_id. With external_invoice, send the same account in both or omit the header.” external_invoiceno se puede cambiar después de crear el enlace. Una actualización que lo incluya devuelve400.
customer_id, debe ser el cliente de la factura. Si la verificación rechaza el pago, no se cobra nada, Yuno cancela el enlace y el intento de pago se rechaza con 400 y uno de estos códigos. Crea un nuevo enlace cuando la factura se pueda pagar. Crear un enlace no verifica la factura, y si Yuno no puede verificarla cuando el cliente paga (por ejemplo, Stripe no responde a tiempo), el pago continúa sin la verificación.
Cuando el pago es exitoso, Yuno lo informa a la factura en Stripe y lo adjunta, y Stripe marca la factura como pagada. Si un intento automático anterior en la factura falló y dejó un registro de pago con el mismo monto y moneda, el pago se agrega a ese registro. De lo contrario, Yuno crea uno nuevo.
Para una factura de una suscripción cuyos pagos gestiona Yuno, la tarjeta utilizada pasa a ser el método de pago predeterminado de la suscripción para las próximas renovaciones cuando creaste el enlace con
vault_on_success: true (esto requiere customer_payer.id y one_time_use: true) y el pagador es el cliente de la suscripción. De lo contrario, el pago se informa igualmente y la suscripción conserva su método de pago.
Para una factura que pertenece a una suscripción, Yuno retiene el siguiente reintento automático de Stripe de la factura mientras un pago en el enlace está en curso, para que el cliente no sea cobrado dos veces. La retención termina cuando el pago es exitoso, es rechazado o falla, o el enlace expira o se cancela, y en cualquier caso después de 24 horas.
Tus metadatos de pago en el registro de pago de Stripe
Yuno puede copiar elmetadata que envías en un pago al registro de pago de Stripe. Esto se habilita por organización, para todas sus cuentas: pídelo a tu Technical Account Manager o Key Account Manager. Cubre:
- el primer pago de una suscripción, y cada renovación, reintento y cierre de esa suscripción, incluida una renovación cuyo resultado llega tarde;
- el reembolso de un pago y su nota de crédito, que llevan el
metadatadel pago reembolsado (un pago de renovación no tienemetadatapropio, por lo que el reembolso de una renovación no lleva ninguno); - los pagos de recarga.
metadata del pago que inició la suscripción. Las suscripciones que comenzaron antes de que esto se habilitara para tu organización, y las suscripciones que comienzan con una prueba gratuita (sin primer pago), no llevan metadata en sus renovaciones.
metadata es una lista de objetos {key, value}. Un objeto en lugar de una lista devuelve 400. Los metadatos se envían en el primer informe de un pago y en cada intento posterior, para que el registro siempre lleve el conjunto completo.
Create payment acepta hasta 120 entradas, con claves de hasta 48 caracteres y valores de hasta 512. Stripe acepta menos, por lo que cada registro de pago toma como máximo 47 entradas tuyas:
- claves de hasta 40 caracteres y valores de hasta 500 caracteres, contados en caracteres (puntos de código Unicode);
- un valor de más de 500 caracteres se corta a 500 caracteres;
- las claves de más de 40 caracteres, y las claves que contienen
[o], se omiten; - si una clave aparece más de una vez, solo se conserva uno de sus valores;
- si envías más de 47 entradas válidas, se conservan las primeras 47 y el resto se descarta.
yuno_payment_id y external_invoice_id, y merchant_order_id cuando el pago lo tiene. Tienen prioridad sobre tus entradas con el mismo nombre y no cuentan para las 47.
Copiar los metadatos a Stripe nunca hace que un pago o su registro de Stripe falle: las entradas que exceden los límites de Stripe se cortan o se omiten.
No compatible
external_invoicejunto conexternal_subscriptionosubscription. Cada uno de estos objetos le dice a Yuno dónde informar el pago:external_invoicea una factura de Stripe,external_subscriptiona una suscripción de Stripe Billing ysubscriptiona una suscripción de Yuno. Un pago solo se puede informar a un lugar, por lo que Yuno rechaza la combinación con400 INVALID_REQUEST. Para pagar una factura de una suscripción de Stripe, envía soloexternal_invoice: Stripe ya vincula la factura con su suscripción.external_invoiceenPOST /v2/payments(pagos con múltiples métodos de pago). SoloPOST /v1/paymentsleeexternal_invoice. La ruta de múltiples métodos de pago no tiene ese campo y lo ignora sin error: el pago se cobra, pero no se vincula a la factura y Stripe no se actualiza. UsaPOST /v1/payments.- Una cotización de promoción de Yuno en un pago con
external_invoice. Las promociones no se aplican al pago de una factura de Stripe. El monto de ese pago lo fija la factura en Stripe, por lo que Yuno rechaza la cotización con422 PROMOTION_SUBSCRIPTION_UNSUPPORTEDen lugar de cobrar un monto con descuento que la factura no espera. Para dar un descuento, aplícalo a la factura en Stripe antes de cobrar el pago. - Pagos que solo están autorizados o capturados parcialmente. Yuno informa un pago a la factura solo una vez que se captura por completo, porque solo entonces su monto es final. Una autorización aún puede liberarse o capturarse por menos, por lo que informarla podría marcar la factura como pagada con dinero que nunca se cobra. Captura el monto completo.