Atributos del webhook
A continuación se listan los atributos JSON de los webhooks de Yuno. Consulta Events and Triggers para ver el campo trigger que selecciona cada evento.Especifica el pago (para el tipo payment) o el objeto de método de pago (para inscripciones y otros objetos).
Opcional. La firma HMAC-SHA256 que se envía en el encabezado HTTP para la verificación del webhook cuando la autenticación HMAC está habilitada.
Webhooks de actualización de split
Estos ejemplos abreviados muestran solo los campos necesarios para interpretarpayment.split_update; también se incluyen los campos normales del pago. Este evento requiere una suscripción explícita y está pendiente de disponibilidad en el catálogo de producción.
En v2, el sobre identifica type_event: "payment.split_update" y el bloque de la operación es data.split_update:
split_marketplace de la operación es []. Un reemplazo aplicado incluye en su lugar las entradas de split de esa operación. transactions es un único objeto, no un arreglo.
El v1 heredado envía el cuerpo del pago sin el sobre v2 ni type_event. Identifica este evento por el bloque split_update junto a payment:
Si
transactions_history está habilitado, su entrada para la transacción afectada incluye el mismo split de la operación. El evento no habilita el historial ni reemplaza el payment.split_marketplace a nivel de pago; no uses ese campo a nivel de pago como la instantánea de esta operación. Los demás campos reflejan la lectura del pago cuando se prepara la notificación y pueden incluir cambios posteriores. Usa GET /v1/payments/{payment_id} para obtener el estado más reciente del pago.
No se garantiza que la instantánea de la operación se serialice igual que una lectura posterior del pago. La escala numérica puede variar (por ejemplo, 5 frente a 5.0) y un objeto de responsabilidad que contenga solo chargebacks puede representarse de forma distinta en el mapeo del pago activo. Compara los valores y su significado, en lugar de exigir igualdad byte por byte del JSON. Estas diferencias de representación no identifican una nueva operación de split.
Solo este evento agrega split_update; los payloads de compra y de reembolso no incorporan el bloque. Consulta Split update notifications para conocer el comportamiento de suscripción, emisión, orden y entrega.
Ejemplos
Yuno ofrece varios webhooks relacionados con notificaciones de inscripción y de pago. Aquí encontrarás algunos ejemplos de estructuras de datos relacionadas con cada evento.Webhook de pago V2
Webhook de pago V1
Webhook de contracargo V2
Webhook de contracargo V1
Inscripción
Payouts
Suscripciones
Onboardings
Reembolsos
Transferencias de split de marketplace
HMAC - Autorización
Pago
Webhook de pago V2
Payload de ejemplo:Los payloads de webhook de los eventos correspondientes a un método de pago de transferencia bancaria incluyen
payment.payment_method.payment_method_detail.bank_transfer.bank_id. El campo refleja el bank_id enviado en la solicitud de pago original y se omite cuando no se seleccionó ningún banco.Cuando el pago incluye una selección de envío (por ejemplo, elegida dentro de un widget de billetera con Fast Checkout shipping), el payload incluye un nodo
payment.shipping de nivel superior (con la misma forma que en el objeto de pago) tanto en la versión V1 como en la V2, y payment.customer_payer.shipping_address se completa a partir de él cuando el pagador no tenía ninguna. La clave shipping se omite cuando el pago no tiene una selección.Cada transacción incluye
connection_data, que identifica la conexión del proveedor que la procesó. Usa connection_data.id como identificador estable para atribuir las transacciones a una conexión específica cuando operas varias conexiones para el mismo proveedor. connection_data.name es el nombre para mostrar configurado en el Dashboard de Yuno y puede ser null en algunos eventos, como las transacciones de seguimiento.El campo
transactions tiene un significado distinto según la superficie. En los payloads de webhook, data.payment.transactions es un único objeto (la transacción que activó el evento), y transactions_history incluye la lista completa de las transacciones del pago cuando está habilitado para el pago (consulta la nota siguiente). En los endpoints de consulta de pagos (GET /payments/{payment_id} y GET /payments?merchant_order_id=), transactions es un arreglo que contiene todas las transacciones del pago.transactions_history es opt-in: solo se completa cuando el pago se creó con response_additional_data.transactions_history: true en la solicitud de Create Payment. De lo contrario, los webhooks lo entregan como un arreglo vacío [] (el valor predeterminado, que mantiene pequeño el tamaño de los payloads). Esto importa en los pagos que tu enrutamiento reintenta entre proveedores: sin el indicador, el webhook final muestra solo la última transacción, y los intentos anteriores solo se ven mediante GET /payments/{payment_id}. Los pagos creados por flujos administrados por Yuno que no establecen el indicador (por ejemplo, las renovaciones de suscripción) también entregan []. Los eventos de contracargo siempre incluyen el historial completo.Nombre de los campos: la geolocalización del cliente se serializa como
geo_location en los payloads de webhook y como geolocation en los endpoints de consulta de pagos. Procesa cada superficie según corresponda.Los pagos creados con un objeto
external_subscription (consulta Create payment) lo incluyen en el payload del webhook dentro del objeto de pago (data.payment en el payload v2), como una clave external_subscription con id y customer_id. La clave se omite (no se envía como null) cuando el pago se creó sin ella, por eso el ejemplo anterior no la muestra. Ambas versiones del webhook incluyen el campo.Los pagos creados con un objeto external_invoice (consulta Pay a Stripe invoice (top-ups)) lo incluyen en los webhooks de pago, por ejemplo payment.purchase, como una clave external_invoice con id y customer_id. En el payload v2 anterior, la clave está dentro de data.payment. Se omite cuando el pago se creó sin ella.Cuando el pago incluye una promoción de Yuno, el payload también incluye
payment.discount_amount (currency y value, el descuento total), ubicado justo después de amount. La línea de descuento de Yuno aparece primero en payment.additional_data.order.discounts (type: YUNO_PROMOTION, quote_id, id, unit_amount y name cuando Yuno lo tiene), y tus propias líneas de descuento van a continuación con type: MERCHANT. payment.amount.value sigue siendo el monto que enviaste, y payment.transactions.amount es el monto cobrado. Sin una promoción, discount_amount se omite y las líneas de descuento son exactamente las que enviaste. Ambas versiones del webhook incluyen el campo. El extracto siguiente muestra solo los campos que cambian.Payment with a Yuno promotion (excerpt)
Webhook de pago V1
Payload de ejemplo:JSON
Webhook de contracargo V2
Payload de ejemplo:Webhook de contracargo V1
Payload de ejemplo:JSON
payment.pre_chargeback
Se envía cuando se recibe un aviso de precontracargo o una alerta de fraude para un pago, antes de un contracargo completo. Actualmente se envía a cualquier webhook con al menos un valor enpayment_triggers, sin importar si PRECHARGEBACK está seleccionado; se planea un trigger dedicado para una versión futura.
Inscripción
El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento de inscripción.Cuando una inscripción se crea con
verify.external_subscription (consulta Enroll payment method), el objeto se devuelve en la respuesta de la inscripción y se conserva en el pago de verificación; no forma parte del payload del webhook de inscripción. Para correlacionarlo después, usa el pago de verificación: su id viene en la respuesta de la inscripción (verify.payment.id) y el objeto se devuelve en Retrieve payment y en los webhooks de pago.Payouts
El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento de payout.JSON
Reportes
report_triggers suscribe a los eventos del ciclo de vida de los reportes. Actualmente solo report.update es emitido por algún servicio; report.create se puede suscribir, pero aún no tiene emisor.
JSON
Suscripciones
El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un eventosubscription.create.
JSON
subscription.active
Se envía cuando una suscripción pasa de cualquier otro estado válido aACTIVE. Usa este evento para activar procesos posteriores a la activación sin necesidad de sondeo.
JSON
subscription.trialing
Se envía cuando una suscripción entra en la fase de prueba de un plan desde otro estado. Entrar en la prueba al momento de la creación se informa comosubscription.create, y salir de una pausa hacia la prueba, como subscription.resume.
JSON
subscription.past_due
Se envía cuando un cobro recurrente falla y la suscripción pasa aPAST_DUE. La suscripción sigue facturando mientras se ejecutan los reintentos y aún se puede cancelar. Cuando un cobro posterior es exitoso, vuelve a ACTIVE (o a TRIALING si la fase de prueba sigue en curso) y se envía el evento correspondiente, subscription.active o subscription.trialing.
Este evento solo se emite para las cuentas que tienen habilitado el estado PAST_DUE. Donde no lo está, un cobro fallido deja la suscripción en ACTIVE y solo el webhook payment.purchase informa el rechazo. Consulta Subscription Status.
JSON
subscription.pause
Se envía cuando una suscripción se pausa. Usa este evento para actualizar el estado en tu sistema y pausar los servicios relacionados.La ventana de una suscripción pausada queda congelada donde estaba, no se mueve hacia adelante.
current_period_start/current_period_end (y current_phase_end, si la suscripción está dentro de una fase) conservan la ventana que estaba vigente en el momento de la pausa: Yuno no los avanza mientras la facturación está suspendida. Cuanto más tiempo permanece pausada una suscripción, más se aleja current_period_end en el pasado; en producción, la gran mayoría de las suscripciones actualmente pausadas ya muestran una ventana vencida. No trates current_period_end como “la próxima fecha de cobro” sin revisar también status: para una suscripción pausada, no lo es.JSON
subscription.resume
Se envía cuando una suscripción pausada se reanuda y vuelve al estado con el que facturaba:ACTIVE, o TRIALING si todavía está dentro de una fase de prueba.
El payload incluye resume_reason, presente solo en este evento: MERCHANT cuando se llamó a Resume Subscription, SCHEDULED cuando la pausa llegó a su pause_until y la suscripción volvió por sí sola. El evento también incluye el billing_cycles.next_at resultante.
Los payloads de suscripción incluyen refund_rule y pause_until siempre que el objeto de suscripción los incluya. Consulta the Subscription object.
JSON
pause_until por sí sola) envía el mismo evento con "resume_reason": "SCHEDULED" en su lugar, sin ninguna otra diferencia estructural en el payload (la variante SCHEDULED se describe a partir de la definición del evento del servicio, no de una entrega capturada).
subscription.reactivate
Se envía cuando una suscripciónCANCELED o COMPLETED vuelve a ACTIVE (o a TRIALING cuando una fase de prueba cubre el ciclo reactivado) mediante Reactivate Subscription. El payload es el objeto de suscripción.
JSON
subscription.auto_resume_failed
Se envía cuando la reanudación automática de una suscripción pausada no pudo completarse después de sus reintentos; la suscripción permanecePAUSED. El payload es el objeto de suscripción. Disponible para las organizaciones habilitadas; contacta a Yuno.
Todavía no existe una captura real de este evento. El ejemplo siguiente reutiliza el cuerpo de una suscripción
PAUSED capturada (la misma forma que muestra subscription.pause, con pause_until de una pausa basada en duración), con los identificadores reemplazados por los de la suscripción de ejemplo de esta página.JSON
auto_resume_failed no es un estado en sí mismo: la suscripción lo es, y sigue siendo PAUSED. Llama a Resume Subscription para terminar la pausa manualmente una vez que llegue este evento.
subscription.creation_failed
Se envía para los pagos de Stripe Billing cuando un pagoSUCCEEDED que incluye external_subscription no pudo crear su suscripción de Stripe. El dinero está capturado y no se creó ni se activó ninguna suscripción de Stripe. Se envía una vez por cada falla. No se envía cuando el pago ya está reembolsado o reembolsado parcialmente. Suscríbete con el valor CREATION_FAILED en subscription_triggers.
A diferencia de los demás eventos de suscripción, data no incluye un objeto de suscripción de Yuno, porque no existe ninguno:
Todavía no existe una captura real de este evento. El ejemplo siguiente se construye a partir del contrato del evento; los identificadores son ilustrativos.
JSON
SUCCEEDED: Yuno no lo reembolsa. Corrige la causa y reintenta el registro con un nuevo pago, reembolsando el original, o reembolsa el original. Consulta If the subscription cannot be created.
subscription.cancel
Se envía cuando una suscripción se cancela. Una suscripción cancelada se puede recuperar con Reactivate Subscription, que conserva la misma suscripción y su historial de pagos. El objeto de suscripción incluye un campocancellation_source que describe qué desencadenó la cancelación: MERCHANT, SYSTEM, PLAN_CHANGE o RETRIES_EXHAUSTED. Consulta the subscription object para ver qué significa cada valor.
Trata
cancellation_source como un valor abierto. Se pueden agregar nuevos valores a medida que Yuno introduzca nuevos comportamientos de cancelación, así que maneja un valor no reconocido de forma controlada en lugar de usar un switch exhaustivo sobre la lista actual. RETRIES_EXHAUSTED es la incorporación más reciente: se envía cuando los reintentos de un ciclo de facturación terminan sin un pago exitoso en una suscripción creada con retries.cancel_on_exhausted_retries establecido en true.JSON
CANCELED, de la misma forma en que una suscripción PAUSED congela su ventana (consulta la nota de subscription.pause).
subscription.complete
Se envía cuando una suscripción llega a su fecha de finalización o a su total de ciclos de facturación y pasa al estadoCOMPLETED.
JSON
subscription.close_to_renewal
Se envía antes de una renovación próxima. El momento lo controlarenewal_notification_days en la suscripción.
JSON
subscription.cycle_executed
Se envía para las suscripciones basadas en planes cuando se ejecuta un ciclo de$0, ya sea un ciclo de prueba o uno con descuento total. Esos ciclos no generan un webhook payment.purchase, por lo que este evento es el único comprobante de ellos. reason es TRIAL o FULL_DISCOUNT, phase es la fase a la que pertenece el ciclo y breakdown incluye el mismo detalle de líneas que un ciclo pagado, con un total de cero.
JSON
subscription.phase_completed
Se envía para las suscripciones basadas en planes cuando termina una fase de facturación, inmediatamente antes delsubscription.phase_started de la fase que la reemplaza. No se envía para la primera fase, que no tiene antecesora. phase es la fase que acaba de terminar.
JSON
subscription.phase_started
Se envía para las suscripciones basadas en planes cuando comienza una fase de facturación, incluida la primera.phase es la fase que está comenzando y previous_phase es la que reemplaza, o null para la primera fase.
JSON
subscription.plan_change_scheduled
Se envía cuando se programa un cambio de plan para el próximo ciclo de facturación. El bloqueplan_change describe el cambio pendiente; applies_at es la próxima fecha de facturación en la que el cambio entrará en vigor.
JSON
subscription.plan_change_canceled
Se envía cuando un cambio de plan pendiente se deshace o se aborta. Elreason dentro de plan_change es MERCHANT_UNDO cuando el comercio envió "plan_change": null, o TARGET_PLAN_CANCELED cuando el plan de destino se canceló antes de que se aplicara el cambio; en ambos casos la suscripción permanece en su plan actual. Si la propia suscripción se cancela, el cambio pendiente se descarta silenciosamente y solo se envía subscription.cancel.
JSON
subscription.plan_changed
Se envía cuando un cambio de plan entra en vigor.previous_plan_id identifica el plan del que se alejó la suscripción; la suscripción incluida ya refleja el nuevo plan.
Un cambio programado se aplica en la renovación que factura por primera vez el nuevo plan, en el mismo lugar: la suscripción incluida conserva el mismo code. En cambio, POST /v1/subscriptions/{id}/plan reemplaza la suscripción: el payload incluye un nuevo code con previous_subscription_id establecido, y se dispara un subscription.cancel aparte (cancellation_source: PLAN_CHANGE) para la original.
JSON
subscription.cancel_scheduled
Se envía cuando se programa una cancelación mediantePOST /v1/subscriptions/{id}/cancel con un bloque schedule. cancel_scheduled describe la programación pendiente. Consulta Cancel Subscription.
JSON
subscription.cancel_schedule_canceled
Se envía cuando una cancelación programada pendiente se deshace mediante"schedule": null en POST /v1/subscriptions/{id}/cancel. No se envía cuando la programación se ejecuta; en ese caso se dispara subscription.cancel.
JSON
Cobros de renovación y fallas (sin subscription.error)
El cobro de la renovación siempre se señala mediante un webhook
payment.purchase, nunca mediante un webhook de suscripción. El arreglo payments dentro del objeto de suscripción está siempre vacío actualmente en los payloads de webhook. subscription.active se envía cuando la suscripción se activa por primera vez (en billing_cycles.current = 2), no en cada renovación; solo se envía de nuevo cuando una suscripción se recupera de PAST_DUE.Una renovación fallida sí genera un webhook de suscripción en dos casos. Donde el estado
PAST_DUE está habilitado para la cuenta, el primer cobro fallido de un ciclo pasa la suscripción a PAST_DUE y emite subscription.past_due. Y si la suscripción tiene retries.cancel_on_exhausted_retries establecido en true, cuando los reintentos de ese ciclo terminan sin un pago exitoso la suscripción se cancela y se emite un único subscription.cancel con cancellation_source establecido en RETRIES_EXHAUSTED. Esto sigue sin ser un subscription.error: los intentos fallidos individuales siguen siendo webhooks payment.purchase. Solo la cancelación final se señala en la suscripción.Onboardings
El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un evento de onboarding, en este casoonboarding.error.
Example
Transferencias de split de marketplace
Las notificaciones de transferencias independientes incluyen eldirection guardado en el nivel superior del cuerpo JSON entregado. Las transferencias existentes usan PLATFORM_TO_RECIPIENT. La disponibilidad de destinatario a plataforma sigue lo indicado en el endpoint de creación.
Los ejemplos siguientes muestran campos seleccionados del cuerpo entregado. Los encabezados son los tipos de evento de suscripción; el cuerpo entregado es el propio objeto de transferencia, sin sobre y sin un campo de tipo de evento. Identifica una notificación de reversión por su status (REVERSED o REVERSED_PARTIAL) y por una transacción de tipo SPLIT_TRANSFER_REVERSE. provider_data describe la cuenta del proveedor que procesó la transferencia; el raw_response de cada transacción incluye la respuesta sin procesar del proveedor, serializada en JSON como una cadena.
Según ingeniería, el
type_event bajo el cual se registran internamente estos dos eventos es transfer.transfer; el cuerpo del webhook entregado no incluye ningún sobre type/type_event, como se indicó antes.split_transfer.succeeded
Se envía cuando una transferencia de split de marketplace se completa correctamente.split_transfer_reverse.succeeded
La notificación identifica la transferencia original, conserva su dirección e incluye tanto la transacción original como la de reversión. En este ejemplo de reversión parcial,status es REVERSED_PARTIAL y amount es el monto de reversión de USD 1. La transacción de reversión apunta a la transacción original mediante parent_transaction_code. Esta notificación es distinta de la respuesta HTTP de la reversión, que no incluye la dirección. Se entrega bajo el id de la transferencia original; description y merchant_reference contienen los valores enviados en la solicitud de reversión.
Reembolsos
El siguiente objeto JSON presenta un ejemplo de una estructura de datos relacionada con un eventopayment.refund.
Example
HMAC - Autorización
El siguiente ejemplo muestra una solicitud de webhook sin procesar con el encabezadox-hmac-signature que Yuno incluye cuando la autenticación HMAC está habilitada.