vaulted_token — or, with a plan, set up
the mandate and the subscription in the first payment
(Signing up from a plan). With EBANX you can also
collect it through the PIX payment method and charge it yourself
(Pix with vault on success). Three things behave
differently from a card subscription, and all three are set by the Pix rail rather than by your
request — the billing cadences the mandate can express, the date the debit instruction is handed to
the rail, and the retry ladder that runs when a debit is refused.
Creating a Pix Automático subscription
Sendpayment_method.type as PIX_AUTOMATIC with the vaulted_token of an already-enrolled
mandate, exactly as you would for a card:
Create a monthly Pix Automático subscription
payment_method.type is matched case-insensitively, so pix_automatic resolves to the same payment
method — and to the same cadence rules — as PIX_AUTOMATIC.
Except for Pix with vault on success, everything on this page
describes subscriptions Yuno executes: frequency.execution is YUNO,
so Yuno generates each debit instruction on schedule. On the one-call route with inline terms,
frequency.execution is sent explicitly and has no default; with a plan_id it defaults to YUNO — see
Start a subscription with the first payment.
Where frequency.execution is MERCHANT you generate each charge yourself, the scheduling and
retry behavior below does not apply, and the subscription cannot
schedule a cancellation.
Signing up from a plan with the first payment
The call above needs a mandate that is already enrolled. To set up the mandate and create the subscription in one call, send Create Payment withpayment_method.type PIX_AUTOMATIC and subscription.plan_id. The request is described in
Create a subscription from a plan. The
customer approves the Pix Automático request in their bank app, and that approval authorizes the
mandate.
What the first payment does depends on the plan:
- Plan without a trial: the payment is the first charge, at the plan’s price. When the customer
approves, the payment succeeds and counts as billing cycle 1. The next debit is one cadence later.
The subscription stays
CREATEDuntil the provider confirms the mandate, then becomes active. If the first payment is refused, the subscription staysCREATEDand is never billed; cancel it with Cancel Subscription. If it expires, a late approval from the bank can still complete it and activate the subscription; cancel it only if you don’t want that. - Plan with a free trial: send the regular price as the payment
amount. The mandate setup is sent to the provider at0.00, and the subscription’s amount stays the regular price. The subscription startsTRIALINGat billing cycle 0 and bills nothing until the customer approves the mandate. The trial starts when the customer approves (or atavailability.start_at, if that is later), and the first paid debit comes after the trial.
Priced trial, or a trial on another cadence
While a free-trial setup awaits approval
These rules apply to free-trial plans only, where nothing is collected until the customer approves.- The provider refuses the setup: Yuno cancels the subscription. It is never billed.
- The customer never approves: Yuno cancels the subscription 31 days after the payment was created. If an approval still arrives after that, Yuno asks the provider to revoke the mandate and logs an alert.
- The payment shows
EXPIRED: this alone does not cancel the subscription. The bank can still deliver an approval after the QR code expires, so Yuno keeps waiting until the 31-day limit. - Pause, resume, reactivate and Change Subscription Plan
are rejected with
400 INVALID_STATEuntil the mandate is approved. If the setup is canceled without an approval, they stay rejected.
Pix with vault on success
With EBANX you can also collect Pix Automático through thePIX payment method: the first payment
creates the recurring authorization and saves it as a vaulted_token, and later charges use that
token. PIX_AUTOMATIC remains a separate payment method; enable in your checkout only the ones you
want to offer. Here your system decides when to charge (frequency.execution MERCHANT).
1. First payment. Send payment_method.vault_on_success: true and a subscription block that
describes what the customer authorizes:
frequency.typeandfrequency.value: the same cadences as Pix Automático (WEEK,MONTH,QUARTER,HALF_YEARorYEARwith value1), plusMONTH3,6or12for quarterly, half-yearly or yearly.frequency.executionMERCHANT: your system decides when to charge. Yuno does not rejectYUNO, but this flow is documented forMERCHANTonly.availabilityandamount, withamount.type. A request without one of them is rejected withHTTP 400before any charge. Withamount.typeFIXED,subscription.amount.valuemust equal the paymentamount.value; useVARIABLEto authorize later charges larger than the first one.
amount and subscription.amount (when both use the
same currency) as the authorization’s minimum limit. When approving, the customer sets the maximum per-charge amount in their bank app,
and it cannot be lower than that value.
The customer referenced by customer_payer.id must have a first and last name, an email and a CPF
or CNPJ in document. Yuno sends them to EBANX to create the authorization and on every later
charge; it does not validate them first, and EBANX declines the payment if they are missing.
Create the first Pix payment
subscription block, or with a frequency other than the ones above (for example
MONTH 2), the payment is created as DECLINED and the provider is not called. The
transaction’s response_message starts with
vault_on_success on PIX requires a subscription to enroll the recurring authorization and lists
the accepted frequencies.
The response is READY_TO_PAY (sub_status CREATED) with a redirect: send the customer to
payment_method.payment_method_detail.bank_transfer.redirect_url, the EBANX page that shows the
Pix QR code. The response has no QR code field for you to render. The customer pays once in their
bank app, which settles this payment and approves the recurring authorization.
The subscription block also creates a Yuno subscription, returned as subscription_code. Charge
the authorization with the vaulted token as shown below, not with subscription.id.
2. The vaulted token. Yuno saves the customer’s Pix payment method when this payment is
created, before the customer approves it. Its token is in
Retrieve Enrolled Payment Methods
right away, and in transactions[].payment_method.vaulted_token from
Retrieve Payment once the payment reaches
SUCCEEDED. Charge it only after this payment is SUCCEEDED: until the customer approves, a charge
with the token is declined.
Each customer has one saved Pix payment method. A new first payment with vault_on_success
replaces its authorization with the new one and keeps the same vaulted_token, so charges with
that token are declined until the customer approves the new payment.
3. Later charges. Charge the stored authorization with the vaulted token. No QR code and no
customer approval are needed:
Charge with the vaulted token
PENDING with
sub_status PENDING_PROVIDER_CONFIRMATION, and Yuno asks EBANX to debit the customer on a due
date two days after the request. The final status arrives by webhook: SUCCEEDED when the debit
settles, otherwise DECLINED or EXPIRED. EBANX does not retry a failed debit on authorizations
created through Yuno. If EBANX rejects the charge when it is created, for example because the
customer has not approved the authorization, the payment is DECLINED in the create response and
no money moves.
In the checkout. When you create the checkout session with the customer’s customer_id and Pix
is enabled in your checkout, the saved Pix appears as its own option, labeled with the last four
digits of the customer’s document (for example Pix ****6893), next to the regular Pix option that
shows a new QR code. Paying with the saved option needs no QR code: the SDK shows the payment as in
progress, and the final status arrives by webhook.
Authorizations created before Yuno. If you already hold Pix Automático authorizations created
with EBANX, contact your Yuno representative before charging them through Yuno.
Accepted billing cadences
These rules apply toPIX_AUTOMATIC. For PIX with vault on success, see
Pix with vault on success.
A Pix Automático mandate can only express the periodicities the Pix rail defines, so a cadence the
mandate could not execute is rejected when the subscription is created rather than failing at the
first debit.
Accepted today: WEEK × 1, MONTH × 1, QUARTER × 1, HALF_YEAR × 1 and YEAR × 1 —
frequency.type is one of those five and frequency.value is exactly 1. Daily does not exist for
Pix Automático — this is a BCB restriction on the rail itself, not a Yuno or Adyen limitation.
The rejection is the same on every path,
HTTP 400:
Rejected cadence
billing_date object instead of frequency — is not
affected: it has no frequency.type for the rule to judge, so PREPAID, POSTDATE, DAY and
PLAN_CREATION_DATE all stay available on Pix Automático.
Where the rule applies
The cadence is judged whenever a subscription resolves to a Pix Automático payment method — on the requested cadence for an inlinefrequency, and on the plan’s cadence when the subscription is
created from a plan_id. It is judged again on the target cadence of a plan change: on
Change Subscription Plan, and on
PATCH /v1/subscriptions/{id} with a plan_change block, for both NEXT_BILLING_CYCLE and
IMMEDIATE.
Plans themselves are unaffected. A plan on any cadence stays creatable — the rule gates the
subscription, not the plan — so a DAY plan is only refused at the moment a Pix Automático
subscription tries to bill from it.
Existing subscriptions are never re-judged
Only the cadence being requested is judged; a subscription already in flight is never re-judged. A Pix Automático subscription created before this rule existed keeps billing on its original cadence, and can still be moved onto a plan — that move is judged on the target plan’s cadence, so it succeeds whenever the target is one of the five accepted cadences.Yearly needs a plan
Sendingfrequency.type as YEAR inline — with no plan_id and no phases — is refused by a
separate, older rule that applies to every payment method, not just Pix Automático:
Inline YEAR, any payment method
YEAR × 1.
The Pix cadence rule accepts it; only the inline route is closed. This does not apply to
Pix with vault on success, which accepts YEAR 1 in the payment’s
subscription block.
The scheduling date
A Pix debit is not taken on demand — the instruction has to reach the rail ahead of the debit date. For a Pix Automático subscription that Yuno executes, Yuno schedules the instruction four days before the debit date and reports that moment asbilling_cycles.scheduling_date.
scheduling_date is exactly billing_cycles.next_at minus four days:
billing_cycles on a Pix Automático subscription
null — a card subscription’s
billing_cycles carries total, current, paid and next_at and nothing else. Read it from
Retrieve Subscription, from the items of
List Subscriptions, and from subscription webhook
payloads, which carry it inside the same billing_cycles block.
subscription.close_to_renewal moves with it: for these subscriptions the notice is counted from
scheduling_date rather than from next_at, so it arrives four days earlier than it would for a
card subscription with the same next_at and the same renewal_notification_days.
When the scheduling date has already passed at the moment the subscription is created — the first
debit is less than four days out — there is nothing to wait for and the instruction is scheduled
straight away instead.
Allowlisted organizations onlyThe four-day scheduling lead and the
scheduling_date field are enabled per organization. Where
they are not enabled, scheduling_date is absent from every read and the instruction is scheduled
on Yuno’s standard renewal lead instead. Contact your Yuno representative to have it enabled.The retry ladder
A refused Pix debit is retried on the Pix rail’s own terms rather than on the Smart Retries schedule. Yuno reports the ladder it applies on the subscription’sretries object:
amount reads 3 on these subscriptions rather than the card default of 6, matching
max_attempts. The four fields above are absent, not null, on CARD and on every other
payment method.
min_gap_hours counts debit dates, not dispatches
min_gap_hours: 24 is the gap between debit dates — the ladder runs on D, D+1, D+2, D+3,
the original debit on D and up to three retries on the three days after it. It is not a gap between
dispatch attempts, and it does not mean Yuno waits 24 hours before sending the next instruction.
When the provider refuses an instruction synchronously, the instruction for the next debit date can
go out seconds later, so against a provider that rejects everything the whole ladder can be
dispatched almost at once. That is the ladder working as specified, not a fault. Check the debit
dates carried on the attempts — D, D+1, D+2, D+3 — not the times at which they were sent.
The ladder is not configurable
retries.retry_on_decline is the one input these subscriptions accept, in both directions: false
suppresses the ladder entirely and leaves a single attempt per cycle. Sending amount, strategy,
schedule, stop_on_hard_decline or cancel_on_exhausted_retries on a Pix Automático subscription
— at creation or on Update Subscription — is
rejected:
Configuring the Pix ladder
Fields Yuno computes
billing_cycles.scheduling_date and the retries.stopped, retries.attempts_made,
retries.outcome and retries.next_retry_at snapshot are computed by Yuno from the subscription’s
own state and are ignored on create and update — sending them changes nothing, and the values you
read back are always Yuno’s. See
The Subscription Object for the full field
reference.