vaulted_token resultante, o, con un plan, configuras
el mandato y la suscripción en el primer pago
(Registro desde un plan). Con EBANX también puedes
cobrarlo a través del método de pago PIX y realizar tú mismo el cobro
(Pix con vault al tener éxito). Tres aspectos se comportan
de forma distinta a una suscripción con tarjeta, y los tres los define el rail de Pix y no tu
solicitud: las cadencias de cobro que el mandato puede expresar, la fecha en que la instrucción de débito se entrega
al rail y la escalera de reintentos que se ejecuta cuando se rechaza un débito.
Creación de una suscripción de Pix Automático
Envíapayment_method.type como PIX_AUTOMATIC con el vaulted_token de un mandato
ya inscrito, igual que lo harías con una tarjeta:
Create a monthly Pix Automático subscription
payment_method.type se compara sin distinguir mayúsculas y minúsculas, por lo que pix_automatic se resuelve en el mismo método de pago
(y con las mismas reglas de cadencia) que PIX_AUTOMATIC.
Excepto en Pix con vault al tener éxito, todo lo que se describe en esta página
corresponde a suscripciones que Yuno ejecuta: frequency.execution es YUNO,
por lo que Yuno genera cada instrucción de débito según el calendario. En la ruta de una sola llamada con términos en línea,
frequency.execution se envía de forma explícita y no tiene valor por defecto; con un plan_id el valor por defecto es YUNO. Consulta
Iniciar una suscripción con el primer pago.
Cuando frequency.execution es MERCHANT, generas tú mismo cada cobro, el comportamiento de programación y
reintentos que se describe a continuación no aplica, y la suscripción no puede
programar una cancelación.
Registro desde un plan con el primer pago
La llamada anterior requiere un mandato que ya esté inscrito. Para configurar el mandato y crear la suscripción en una sola llamada, envía Create Payment conpayment_method.type PIX_AUTOMATIC y subscription.plan_id. La solicitud se describe en
Crear una suscripción desde un plan. El
cliente aprueba la solicitud de Pix Automático en la app de su banco, y esa aprobación autoriza el
mandato.
Lo que hace el primer pago depende del plan:
- Plan sin periodo de prueba: el pago es el primer cobro, al precio del plan. Cuando el cliente
aprueba, el pago es exitoso y cuenta como el ciclo de facturación 1. El siguiente débito ocurre una cadencia después.
La suscripción permanece en
CREATEDhasta que el proveedor confirma el mandato, y luego pasa a activa. Si el primer pago es rechazado, la suscripción permanece enCREATEDy nunca se cobra; cancélala con Cancel Subscription. Si expira, una aprobación tardía del banco aún puede completarlo y activar la suscripción; cancélala solo si no quieres que eso ocurra. - Plan con periodo de prueba gratuito: envía el precio regular como
amountdel pago. La configuración del mandato se envía al proveedor con0.00, y el monto de la suscripción sigue siendo el precio regular. La suscripción inicia enTRIALINGen el ciclo de facturación 0 y no cobra nada hasta que el cliente apruebe el mandato. El periodo de prueba inicia cuando el cliente aprueba (o enavailability.start_at, si esa fecha es posterior), y el primer débito de pago llega después del periodo de prueba.
Priced trial, or a trial on another cadence
Mientras la configuración de un periodo de prueba gratuito espera aprobación
Estas reglas aplican solo a los planes con periodo de prueba gratuito, en los que no se cobra nada hasta que el cliente apruebe.- El proveedor rechaza la configuración: Yuno cancela la suscripción. Nunca se cobra.
- El cliente nunca aprueba: Yuno cancela la suscripción 31 días después de que se creó el pago. Si aun así llega una aprobación después de ese plazo, Yuno solicita al proveedor que revoque el mandato y registra una alerta.
- El pago muestra
EXPIRED: esto por sí solo no cancela la suscripción. El banco aún puede entregar una aprobación después de que expire el código QR, por lo que Yuno sigue esperando hasta el límite de 31 días. - Pausar, reanudar, reactivar y Change Subscription Plan
se rechazan con
400 INVALID_STATEhasta que se apruebe el mandato. Si la configuración se cancela sin una aprobación, siguen rechazándose.
Pix con vault al tener éxito
Con EBANX también puedes cobrar Pix Automático a través del método de pagoPIX: el primer pago
crea la autorización recurrente y la guarda como un vaulted_token, y los cobros posteriores usan ese
token. PIX_AUTOMATIC sigue siendo un método de pago independiente; habilita en tu checkout solo los que
quieras ofrecer. Aquí tu sistema decide cuándo cobrar (frequency.execution MERCHANT).
1. Primer pago. Envía payment_method.vault_on_success: true y un bloque subscription que
describa lo que el cliente autoriza:
frequency.typeyfrequency.value: las mismas cadencias que Pix Automático (WEEK,MONTH,QUARTER,HALF_YEARoYEARcon valor1), además deMONTH3,6o12para trimestral, semestral o anual.frequency.executionMERCHANT: tu sistema decide cuándo cobrar. Yuno no rechazaYUNO, pero este flujo está documentado solo paraMERCHANT.availabilityyamount, conamount.type. Una solicitud sin alguno de ellos se rechaza conHTTP 400antes de cualquier cobro. Conamount.typeFIXED,subscription.amount.valuedebe ser igual aamount.valuedel pago; usaVARIABLEpara autorizar cobros posteriores mayores que el primero.
amount del pago y subscription.amount (cuando ambos usan la
misma moneda) como límite mínimo de la autorización. Al aprobar, el cliente define el monto máximo por cobro en la app de su banco,
y no puede ser menor que ese valor.
El cliente al que hace referencia customer_payer.id debe tener nombre y apellido, un email y un CPF
o CNPJ en document. Yuno los envía a EBANX para crear la autorización y en cada cobro
posterior; no los valida antes, y EBANX rechaza el pago si faltan.
Create the first Pix payment
subscription, o con una frecuencia distinta de las anteriores (por ejemplo
MONTH 2), el pago se crea como DECLINED y no se llama al proveedor. El
response_message de la transacción comienza con
vault_on_success on PIX requires a subscription to enroll the recurring authorization y enumera
las frecuencias aceptadas.
La respuesta es READY_TO_PAY (sub_status CREATED) con una redirección: envía al cliente a
payment_method.payment_method_detail.bank_transfer.redirect_url, la página de EBANX que muestra el
código QR de Pix. La respuesta no tiene un campo de código QR para que lo muestres. El cliente paga una sola vez en la
app de su banco, lo que liquida este pago y aprueba la autorización recurrente.
El bloque subscription también crea una suscripción de Yuno, que se devuelve como subscription_code. Cobra
la autorización con el vaulted token como se muestra a continuación, no con subscription.id.
2. El vaulted token. Yuno guarda el método de pago Pix del cliente cuando se crea este pago,
antes de que el cliente lo apruebe. Su token está disponible de inmediato en
Retrieve Enrolled Payment Methods,
y en transactions[].payment_method.vaulted_token de
Retrieve Payment una vez que el pago llega a
SUCCEEDED. Cóbralo solo después de que este pago esté en SUCCEEDED: hasta que el cliente apruebe, un cobro
con el token es rechazado.
Cada cliente tiene un método de pago Pix guardado. Un nuevo primer pago con vault_on_success
reemplaza su autorización por la nueva y conserva el mismo vaulted_token, por lo que los cobros con
ese token son rechazados hasta que el cliente apruebe el nuevo pago.
3. Cobros posteriores. Cobra la autorización almacenada con el vaulted token. No se necesitan código QR ni
aprobación del cliente:
Charge with the vaulted token
PENDING con
sub_status PENDING_PROVIDER_CONFIRMATION, y Yuno solicita a EBANX debitar al cliente en una fecha de
vencimiento dos días después de la solicitud. El estado final llega por webhook: SUCCEEDED cuando el débito
se liquida, o bien DECLINED o EXPIRED. EBANX no reintenta un débito fallido en autorizaciones
creadas a través de Yuno. Si EBANX rechaza el cobro cuando se crea, por ejemplo porque el
cliente no ha aprobado la autorización, el pago queda DECLINED en la respuesta de creación y
no se mueve dinero.
En el checkout. Cuando creas la sesión de checkout con el customer_id del cliente y Pix
está habilitado en tu checkout, el Pix guardado aparece como una opción propia, identificada con los últimos cuatro
dígitos del documento del cliente (por ejemplo Pix ****6893), junto a la opción regular de Pix que
muestra un nuevo código QR. Pagar con la opción guardada no requiere código QR: el SDK muestra el pago como
en curso, y el estado final llega por webhook.
Autorizaciones creadas antes de Yuno. Si ya tienes autorizaciones de Pix Automático creadas
con EBANX, comunícate con tu representante de Yuno antes de cobrarlas a través de Yuno.
Cadencias de cobro aceptadas
Estas reglas aplican aPIX_AUTOMATIC. Para PIX con vault al tener éxito, consulta
Pix con vault al tener éxito.
Un mandato de Pix Automático solo puede expresar las periodicidades que define el rail de Pix, por lo que una cadencia que el
mandato no podría ejecutar se rechaza al crear la suscripción en lugar de fallar en el
primer débito.
Aceptadas hoy: WEEK × 1, MONTH × 1, QUARTER × 1, HALF_YEAR × 1 y YEAR × 1.
frequency.type es uno de esos cinco y frequency.value es exactamente 1. La cadencia diaria no existe para
Pix Automático: es una restricción del BCB sobre el propio rail, no una limitación de Yuno ni de Adyen.
El rechazo es el mismo en todas las rutas,
HTTP 400:
Rejected cadence
billing_date en lugar de frequency) no se
ve afectada: no tiene frequency.type que la regla pueda evaluar, por lo que PREPAID, POSTDATE, DAY y
PLAN_CREATION_DATE siguen disponibles en Pix Automático.
Dónde aplica la regla
La cadencia se evalúa siempre que una suscripción se resuelve en un método de pago de Pix Automático: sobre la cadencia solicitada para unfrequency en línea, y sobre la cadencia del plan cuando la suscripción se
crea desde un plan_id. Se evalúa de nuevo sobre la cadencia de destino de un cambio de plan: en
Change Subscription Plan, y en
PATCH /v1/subscriptions/{id} con un bloque plan_change, tanto para NEXT_BILLING_CYCLE como para
IMMEDIATE.
Los planes en sí no se ven afectados. Un plan con cualquier cadencia se puede seguir creando (la regla restringe la
suscripción, no el plan), por lo que un plan DAY solo se rechaza en el momento en que una suscripción de Pix Automático
intenta cobrar a partir de él.
Las suscripciones existentes nunca se reevalúan
Solo se evalúa la cadencia que se solicita; una suscripción que ya está en curso nunca se reevalúa. Una suscripción de Pix Automático creada antes de que existiera esta regla sigue cobrando con su cadencia original, y aún se puede pasar a un plan. Ese cambio se evalúa sobre la cadencia del plan de destino, por lo que tiene éxito siempre que el destino sea una de las cinco cadencias aceptadas.Anual requiere un plan
Enviarfrequency.type como YEAR en línea, sin plan_id y sin fases, es rechazado por una
regla distinta y más antigua que aplica a todos los métodos de pago, no solo a Pix Automático:
Inline YEAR, any payment method
YEAR × 1.
La regla de cadencia de Pix la acepta; solo la ruta en línea está cerrada. Esto no aplica a
Pix con vault al tener éxito, que acepta YEAR 1 en el bloque
subscription del pago.
La fecha de programación
Un débito de Pix no se realiza a demanda: la instrucción debe llegar al rail antes de la fecha de débito. Para una suscripción de Pix Automático que Yuno ejecuta, Yuno programa la instrucción cuatro días antes de la fecha de débito e informa ese momento comobilling_cycles.scheduling_date.
scheduling_date es exactamente billing_cycles.next_at menos cuatro días:
billing_cycles on a Pix Automático subscription
null: el
billing_cycles de una suscripción con tarjeta contiene total, current, paid y next_at y nada más. Léela desde
Retrieve Subscription, desde los elementos de
List Subscriptions y desde los payloads de webhook de
suscripciones, que la incluyen dentro del mismo bloque billing_cycles.
subscription.close_to_renewal se mueve con ella: para estas suscripciones el aviso se cuenta desde
scheduling_date en lugar de desde next_at, por lo que llega cuatro días antes que para
una suscripción con tarjeta con el mismo next_at y el mismo renewal_notification_days.
Cuando la fecha de programación ya pasó en el momento en que se crea la suscripción (el primer
débito está a menos de cuatro días), no hay nada que esperar y la instrucción se programa
de inmediato.
Solo organizaciones en la lista de permitidasEl plazo de programación de cuatro días y el campo
scheduling_date se habilitan por organización. Cuando
no están habilitados, scheduling_date está ausente de todas las lecturas y la instrucción se programa
con el plazo de renovación estándar de Yuno. Comunícate con tu representante de Yuno para que lo habiliten.La escalera de reintentos
Un débito de Pix rechazado se reintenta según los términos propios del rail de Pix y no según el calendario de Smart Retries. Yuno informa la escalera que aplica en el objetoretries de la suscripción:
amount es 3 en estas suscripciones en lugar del valor por defecto de 6 de las tarjetas, igual que
max_attempts. Los cuatro campos anteriores están ausentes, no son null, en CARD y en cualquier otro
método de pago.
min_gap_hours cuenta fechas de débito, no envíos
min_gap_hours: 24 es el intervalo entre fechas de débito: la escalera se ejecuta en D, D+1, D+2, D+3,
el débito original en D y hasta tres reintentos en los tres días siguientes. No es un intervalo entre
intentos de envío, y no significa que Yuno espere 24 horas antes de enviar la siguiente instrucción.
Cuando el proveedor rechaza una instrucción de forma síncrona, la instrucción para la siguiente fecha de débito puede
salir segundos después, por lo que, con un proveedor que rechaza todo, toda la escalera puede
enviarse casi de inmediato. Así funciona la escalera según lo especificado, no es una falla. Revisa las fechas
de débito que llevan los intentos (D, D+1, D+2, D+3) y no los momentos en que se enviaron.
La escalera no es configurable
retries.retry_on_decline es la única entrada que aceptan estas suscripciones, en ambos sentidos: false
suprime la escalera por completo y deja un solo intento por ciclo. Enviar amount, strategy,
schedule, stop_on_hard_decline o cancel_on_exhausted_retries en una suscripción de Pix Automático
(al crearla o en Update Subscription) se
rechaza:
Configuring the Pix ladder
Campos que calcula Yuno
billing_cycles.scheduling_date y la instantánea de retries.stopped, retries.attempts_made,
retries.outcome y retries.next_retry_at los calcula Yuno a partir del estado propio de la
suscripción y se ignoran al crear y actualizar: enviarlos no cambia nada, y los valores que
lees siempre son los de Yuno. Consulta
The Subscription Object para ver la referencia completa
de campos.