Saltar al contenido principal
La mayoría de las integraciones de suscripciones necesitan dos viajes de ida y vuelta: inscribir la tarjeta para obtener un vaulted_token y luego llamar a Create Subscription con ese token. Funciona, pero divide el registro en dos llamadas, y te deja con una credencial almacenada antes de saber si la tarjeta del cliente realmente se autorizará. El bloque subscription en Create Payment lo reduce a una sola llamada. Envías el instrumento y las instrucciones de recurrencia juntos; Yuno cobra al cliente y, a partir de ese mismo cobro, crea la suscripción. Ese pago queda vinculado a la suscripción y registrado como su primer ciclo de facturación, y nada comienza a facturarse si el pago no se completa.
¿Qué ruta debes usar?
  • Una llamada (esta página): el cliente se registra y paga ahora mismo, y quieres que el registro tenga éxito o falle como una sola unidad. Ideal para flujos de checkout.
  • Create Subscription: ya tienes un vaulted_token del cliente, por ejemplo, porque inscribió una tarjeta antes. Consulta la descripción general de suscripciones para ese flujo. Para pasar a un suscriptor existente a otro plan, usa Change Subscription Plan: crear una segunda suscripción deja la primera activa y facturando.
  • Enlaces de pago: el bloque subscription no es compatible al crear un enlace de pago: se ignora en lugar de rechazarse, por lo que el enlace devuelve 201 y nunca se crea ninguna suscripción. Toma el pago en el enlace con vault_on_success y luego llama a Create Subscription con el vaulted_token resultante.
Ambas rutas producen una suscripción que gestionas con los mismos endpoints: pausar, reanudar, cancelar, consultar. No se configuran de forma idéntica: el bloque subscription de Create Payment tiene un conjunto de campos más reducido y no puede definir trial_period, soft_descriptor ni un name de suscripción. metadata solo se lee junto con plan_id, y una suscripción creada a partir de un plan toma la configuración de reintentos del plan; consulta Crear una suscripción a partir de un plan. Cuando envías los términos de la suscripción en la llamada (frequency, availability y amount, llamados términos en línea en esta página), retries y metadata se ignoran, y los Smart Retries están desactivados en una suscripción creada de esta forma: una renovación rechazada no se reintenta hasta que los actives con Update Subscription.

Cómo funciona la llamada única

Estos pasos aplican cuando envías los términos de la suscripción en la propia llamada: frequency, availability y amount. Si envías un plan_id en su lugar, el orden cambia y Yuno crea la suscripción antes del cobro. Consulta Crear una suscripción a partir de un plan.
  1. Llamas a Create Payment con el pago que enviarías de todos modos (monto, país, método de pago, cliente), más un objeto subscription que describe la recurrencia.
  2. Yuno cobra al cliente. Es un pago normal con tarjeta: se enruta y puede ser rechazado.
  3. Si el cobro se completa, Yuno crea la suscripción y registra ese pago como su primer ciclo de facturación. La respuesta del pago incluye subscription_code, el id de la nueva suscripción.
  4. Yuno factura cada ciclo siguiente por su cuenta, con la cadencia que definiste en frequency, hasta que la suscripción se completa, se cancela o se queda sin ciclos de facturación.
Si el cobro no se completa, no se crea ninguna suscripción: recibes un pago rechazado y ese es todo el resultado. Cuando el cobro sí se completa, el pago queda vinculado a la nueva suscripción como su primer ciclo de facturación; confirma ese vínculo con subscription_code en la respuesta del pago y con Retrieve Subscription en lugar de darlo por sentado. Aplica esa verificación solo cuando el pago alcance un estado terminal. Si el pago devuelve PENDING, la suscripción aún no se ha creado y la respuesta llega con subscription_code: null: espera el resultado terminal antes de conciliar. En un pago que ya es terminal y exitoso, subscription_code: null significa que la suscripción no se creó. Consulta Errores.

Reintentar la llamada

Create Payment requiere un encabezado X-idempotency-key: la solicitud se rechaza antes de procesar el cuerpo si falta. Reintentar con la misma clave devuelve el pago original y no crea una segunda suscripción. Reintentar con una clave nueva cobra al cliente otra vez. Por lo tanto, si un pago fue exitoso sin un subscription_code, repetir la llamada no es una solución: la misma clave te devuelve el pago original y una clave nueva genera un segundo pago. Concilia en su lugar; consulta Errores.
Métodos de pago disponiblesConsulta Suscripciones para ver los métodos de pago que admiten las suscripciones. Para registrar a un cliente de Pix Automático desde un plan con el primer pago, consulta Crear una suscripción a partir de un plan.

El bloque subscription

Envía subscription junto con los campos normales de Create Payment. El bloque tiene tres formas y debes enviar exactamente una: checkout.session es obligatorio en Create Payment a menos que envíes "workflow": "DIRECT" o "workflow": "REDIRECT": el bloque subscription no cambia eso. Crea una sesión con Create checkout session y envía su identificador como checkout.session.
Con términos en línea, el objeto availability en sí es obligatorio, pero ambos campos dentro de él son opcionales: envía {} si quieres que la suscripción comience ahora y se ejecute hasta que la canceles. Con plan_id, availability es completamente opcional; consulta Campos que puedes enviar con plan_id.
customer_payer es obligatorio para este flujoUna suscripción siempre pertenece a un cliente, por lo que debe haber un objeto customer_payer cuando envías un bloque subscription. Puedes identificar a un cliente existente con customer_payer.id, o enviar el cliente en línea (email, merchant_customer_id, document) y dejar que Yuno lo cree: id no es obligatorio. Crea el cliente de antemano con Create Customer si prefieres conservar el identificador tú mismo.
billing_cycles y availability.finish_at se afectan entre síSi defines ambos, la suscripción llega a COMPLETED en lo que ocurra primero: el último ciclo de facturación o finish_at. Si no defines ninguno, Yuno sigue cobrando hasta que canceles.

Ejemplo completo

Create Payment with a new subscription
payment_method.token es el token de un solo uso que la sesión de checkout produce para la tarjeta que el cliente acaba de ingresar: ese es el instrumento de registro en esta ruta. Usa vaulted_token solo cuando la tarjeta ya está almacenada, como en Cobrar una suscripción existente. La respuesta es un objeto de pago normal con un campo adicional completado:
Response (excerpt) — illustrative
Ilustrativo: aún no existe una captura de la superficie del comercio para este flujo. Los nombres de los campos y su anidación son los que añade esta ruta; los valores son marcadores de posición.
Conserva subscription_code: es el id de la suscripción y lo que pasas a Retrieve, Pause, Resume y Cancel.

execution decide quién factura

frequency.execution le indica a Yuno quién es responsable de generar cada cobro recurrente. Con términos en línea es obligatorio: no hay valor predeterminado. Con plan_id el valor predeterminado es YUNO.
  • YUNO: el motor de Yuno es dueño del calendario. Genera cada cobro posterior al primero y emite los webhooks payment.purchase de cada ciclo. Esto es lo que quieres para este flujo.
  • MERCHANT: tú eres dueño del calendario. Yuno almacena la suscripción como un registro del acuerdo, pero nunca cobra sobre ella; tú envías cada recobro como un pago iniciado por el comercio. Las operaciones del ciclo de vida que solo tienen sentido con un calendario ejecutado por Yuno (Pause, Resume, Update, Retry y Change plan) se rechazan con 400 BAD_REQUEST.
Los reintentos son la única excepción a “el mismo objeto de suscripción”Con términos en línea, el bloque subscription de Create Payment no lee ningún objeto retries, por lo que una suscripción creada de esta forma comienza con retry_on_decline: false: una renovación rechazada no se reintenta, con ninguno de los valores de execution. Con plan_id, consulta Crear una suscripción a partir de un plan. Activa los Smart Retries después con Update Subscription.
Las suscripciones MERCHANT nunca facturan por su cuentaSi envías "execution": "MERCHANT" esperando que Yuno cobre al cliente el próximo mes, no ocurrirá nada: la suscripción se crea, parece estar sana y nunca se genera ningún cobro. Si Yuno debe encargarse de la facturación, envía "execution": "YUNO".Si realmente quieres manejar la recurrencia tú mismo, no necesitas una suscripción: usa Credenciales almacenadas y envía cada recobro como un pago con stored_credentials.reason = SUBSCRIPTION.

Autenticación en el primer cobro

El primer cobro es una transacción iniciada por el cliente (CIT) en la superficie de pago, por lo que es elegible para 3DS de una forma en que no lo es un recobro de Create Subscription: ese endpoint toma un vaulted_token e inicia un calendario, sin una sesión de cliente asociada y sin una superficie en la que presentar un desafío.
Solo sin fricción, por ahoraEsta ruta está documentada solo para autenticación sin fricción. Un pago que requiere un desafío 3DS se completa de forma asíncrona después de que el cliente se autentica, y el viaje de una llamada más desafío no se ha validado de extremo a extremo: no construyas un registro de suscripción sobre él todavía. Mantén el primer cobro sin fricción, o usa el flujo de dos llamadas (Create Payment y luego Create Subscription con el vaulted_token resultante) cuando se espere un desafío. Consulta Configuración y pruebas de 3DS.
Uso de credenciales en los recobrosEl primer cobro es una CIT. Cada cobro que Yuno genera después es una transacción iniciada por el comercio contra la misma credencial almacenada. Yuno configura esto por ti en esta ruta, pero si alguna vez armas el flujo de dos llamadas a mano (primero el pago CIT y luego Create Subscription con el token resultante), debes definir tú mismo el uso de la credencial en ese pago CIT: payment_method.detail.card.stored_credentials.usage (payment_method.detail.wallet.stored_credentials.usage para una CIT de Apple Pay o Google Pay), y en la llamada a Create Subscription el campo plano payment_method.card.usage: "USED" (consulta Create Subscription); de lo contrario, los recobros se enviarán como CIT y serán rechazados. Consulta Credenciales almacenadas.

Encontrar el primer cobro más adelante

El pago que hiciste en la llamada única no es una transacción suelta junto a la suscripción: queda registrado como el primer ciclo de facturación de la suscripción. Eso importa para los reportes: si no estuviera vinculado, tus cifras de ingresos recurrentes omitirían el primer mes de cada suscripción. Hay dos formas de seguir el vínculo:
  • Desde el pago: subscription_code en el objeto de pago es el id de la suscripción. Está en la respuesta de Create Payment y en Retrieve Payment.
  • Desde la suscripción: List Subscription Payments devuelve el historial de cobros de la suscripción, y el pago de la llamada única aparece vinculado allí como el primer ciclo de facturación de la suscripción, con el mismo id de pago que recibiste de la llamada.
Webhooks de renovaciónsubscription.active se dispara una sola vez, cuando la suscripción se activa por primera vez. No se vuelve a enviar en renovaciones posteriores. Haz seguimiento de cada renovación con el webhook payment.purchase de cada ciclo. Consulta Suscripciones.

Crear una suscripción a partir de un plan

Si ya tienes un plan, puedes registrar a un cliente en él en la misma llamada que toma su primer pago. Envía el id del plan como subscription.plan_id en Create Payment. La suscripción toma su precio, cadencia y periodo de prueba del plan, por lo que no envías amount ni una cadencia dentro del bloque subscription. Esto funciona con cualquier método de pago que el plan permita, incluidas las tarjetas y Pix Automático:
  • Tarjeta: envía el pago con tarjeta como en el ejemplo completo, con plan_id como único campo en el bloque subscription. El plan no puede tener un periodo de prueba ni otras fases: con un método de pago distinto de Pix Automático, un plan con fases se rechaza con 400 INVALID_PARAMETERS.
  • Pix Automático: el pago es la configuración del mandato, y el plan decide qué aprueba el cliente. Se admiten planes con periodo de prueba gratuito.
Con un plan, la suscripción existe antes de que el cliente pagueCon plan_id, Yuno crea la suscripción antes del cobro, apenas pasan las verificaciones del plan. La primera respuesta ya incluye subscription_code, incluso mientras el pago sigue pendiente. La regla del resto de esta página, “ninguna suscripción a menos que el cobro se complete”, no aplica aquí. Consulta Si el primer pago falla para saber qué limpiar.

La solicitud

Create Payment from a plan
El amount del pago debe ser igual al precio del plan para el country del pago, en la misma moneda. Yuno resuelve ese precio en este orden: el precio de la fase regular para el país, luego la entrada country_prices del plan para el país y, por último, el base_amount del plan. En un plan con periodo de prueba gratuito, igualmente envías el precio regular; el periodo de prueba decide qué se cobra primero.

Campos que puedes enviar con plan_id

Los reintentos vienen del plan. La suscripción toma la configuración de reintentos del plan, por lo que retries no es un campo de esta llamada: enviarlo se rechaza con 400 INVALID_PARAMETERS. En una suscripción de Pix Automático que ejecuta Yuno, para organizaciones con la programación de Pix Automático habilitada, se aplica la escalera de reintentos de Pix (retry_on_decline: true).

Campos que no puedes enviar con plan_id

El plan ya define estos campos, por lo que cada uno se rechaza con 400 INVALID_REQUEST, incluso cuando su valor es null: id, amount, frequency.type, frequency.value, billing_date, trial, trial_period, phases El mensaje de error nombra el campo:
plan_id with a forbidden field
Para frequency.type y frequency.value, el mensaje dice “Only ‘subscription.frequency.execution’ can be sent with ‘subscription.plan_id’”.

Qué agrega la respuesta

La respuesta del pago incluye tres campos para esta ruta:
  • subscription_code: el id de la nueva suscripción.
  • plan_id: el plan de la suscripción cuando se creó este pago.
  • plan_assigned_at: cuándo se asignó el plan a la suscripción.
Los mismos tres campos están en Retrieve Payment y en los webhooks de pago. Los pagos de renovación que Yuno genera para la suscripción también incluyen plan_id y plan_assigned_at. En un pago hecho sin un plan, plan_id y plan_assigned_at están ausentes, no son null. En un plan con periodo de prueba gratuito, el pago muestra el precio regular en amount.value, mientras que su transacción es 0.00: esa es la configuración del mandato, que no cobra nada. Un reembolso de ese pago se rechaza con 400 INVALID_PARAMETERS, porque no se cobró nada.

Si el primer pago falla

  • Plan con periodo de prueba gratuito: consulta Pix Automático. Una configuración rechazada cancela la suscripción automáticamente.
  • Plan sin periodo de prueba: un primer pago rechazado deja la suscripción en CREATED. Nunca se factura, pero tampoco se cancela: cancélala con Cancel Subscription. Un primer pago vencido es distinto: el banco del cliente aún puede entregar una aprobación después de que el código QR venza, lo que completa el pago y activa la suscripción. Cancélala solo si no la quieres.

Errores de un plan

Las verificaciones de la solicitud fallan con 400 antes de que se cree nada. Las verificaciones del plan fallan con 400 antes de llamar al proveedor: no se mueve dinero, no se crea ninguna suscripción y el pago se almacena con estado ERROR.

Cobrar una suscripción existente

El mismo bloque subscription tiene una tercera forma: envía id con el UUID de una suscripción que ya existe, y el pago se asocia a esa suscripción en lugar de crear una nueva. En esa forma omites frequency, availability y amount: la suscripción ya los define.
Create Payment for an existing subscription
billing_date se ignora silenciosamente cuando creas una suscripciónEl bloque de la superficie de pagos acepta un objeto billing_date, pero solo junto con id para una suscripción que ya existe. Si lo envías al crear una nueva suscripción, no se rechaza: se acepta, se descarta y la nueva suscripción se crea sin él. Recibes un 201 y nada te indica que el día de facturación que pediste fue descartado.Define el día de facturación en la superficie de suscripciones con Create Subscription o Update Subscription, no en el bloque del lado de pagos que crea una. Esa superficie usa su propia forma de campo y su propio conjunto de valores de type, que difieren del objeto del lado de pagos; no copies un objeto billing_date de un pago a una llamada de suscripción.

Errores

Esta sección cubre una suscripción cuyos términos envías en la llamada (frequency, availability y amount). Para plan_id, consulta Errores de un plan. Un bloque subscription incorrecto puede fallar en dos momentos distintos, y la diferencia importa: uno ocurre antes de que se cobre al cliente, el otro después.

Rechazado antes de cualquier cobro

Estos casos se detectan cuando se valida la solicitud, por lo que la llamada falla con un 400, no se mueve dinero y no se crea ninguna suscripción:
  • frequency.execution ausente, o con cualquier valor distinto de YUNO / MERCHANT.
  • frequency.type definido con algo distinto de MONTH.
  • amount.type definido con algo distinto de FIXED / VARIABLE.
  • amount.value o amount.currency ausentes, o una moneda que no es un código ISO 4217 válido.
  • subscription.amount.currency distinta del amount.currency del pago.
  • subscription.amount.type = FIXED con un subscription.amount.value distinto del amount.value del pago.
  • frequency, availability o amount ausentes al crear una nueva suscripción (los tres son obligatorios a menos que envíes id o plan_id).
  • customer_payer ausente: un pago siempre necesita un pagador, por lo que se rechaza antes de cobrar nada.

Validado cuando se crea la suscripción

Estos se verifican en el momento de crear la suscripción, que ocurre después del cobro:
  • availability.start_at en el pasado, o finish_at igual o anterior a start_at.
  • billing_cycles.total definido en 0 o en un número negativo.
  • frequency.value ausente, o definido con un número fraccionario.
Para este momento el pago puede haber sido exitoso yaSi alguna de estas verificaciones falla, el cobro no se revierte. El pago se mantiene y la suscripción no se crea: tienes un pago único exitoso y ninguna recurrencia. La respuesta del pago llega con subscription_code: null.Aplica esta verificación solo cuando el pago alcance un estado terminal. Si el pago devuelve PENDING, la suscripción aún no se ha creado y subscription_code es null porque el resultado sigue abierto: espera el estado terminal antes de hacer cualquier cosa.En un pago que es terminal y exitoso, trata subscription_code: null como una señal para conciliar: reembolsa el pago o crea la suscripción por separado con Create Subscription. No reintentes la llamada original; consulta Reintentar la llamada. Verificar estos campos de tu lado antes de enviar la llamada reduce la ventana de riesgo, por lo que vale la pena hacerlo.
Consulta Códigos de respuesta HTTP para ver la lista completa.