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_tokendel 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
subscriptionno es compatible al crear un enlace de pago: se ignora en lugar de rechazarse, por lo que el enlace devuelve201y nunca se crea ninguna suscripción. Toma el pago en el enlace convault_on_successy luego llama a Create Subscription con elvaulted_tokenresultante.
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.
- 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
subscriptionque describe la recurrencia. - Yuno cobra al cliente. Es un pago normal con tarjeta: se enruta y puede ser rechazado.
- 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, elidde la nueva suscripción. - 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.
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 encabezadoX-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:
- Nueva suscripción con términos en línea: envía
frequency,availabilityyamount, y omiteidyplan_id. La tabla de abajo describe esta forma. - Nueva suscripción a partir de un plan: envía
plan_id. Consulta Crear una suscripción a partir de un plan. - Suscripción existente: envía
id. Consulta Cobrar una suscripción existente.
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.
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.
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.
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 webhookspayment.purchasede 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 con400 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.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 unvaulted_token e inicia un calendario, sin una sesión de cliente asociada y sin una superficie en la que presentar un desafío.
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_codeen el objeto de pago es elidde 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
idde pago que recibiste de la llamada.
Webhooks de renovación
subscription.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 elid 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_idcomo único campo en el bloquesubscription. 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 con400 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.
La solicitud
Create Payment from a plan
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
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
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: elidde 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.
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 con400 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 bloquesubscription 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
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 un400, no se mueve dinero y no se crea ninguna suscripción:
frequency.executionausente, o con cualquier valor distinto deYUNO/MERCHANT.frequency.typedefinido con algo distinto deMONTH.amount.typedefinido con algo distinto deFIXED/VARIABLE.amount.valueoamount.currencyausentes, o una moneda que no es un código ISO 4217 válido.subscription.amount.currencydistinta delamount.currencydel pago.subscription.amount.type=FIXEDcon unsubscription.amount.valuedistinto delamount.valuedel pago.frequency,availabilityoamountausentes al crear una nueva suscripción (los tres son obligatorios a menos que envíesidoplan_id).customer_payerausente: 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_aten el pasado, ofinish_atigual o anterior astart_at.billing_cycles.totaldefinido en0o en un número negativo.frequency.valueausente, o definido con un número fraccionario.