Skip to main content
Yuno bills a Brazilian Pix Automático mandate as an ordinary subscription: you enroll the mandate first, then create the subscription against the resulting vaulted_token — or, with a plan, set up the mandate and the subscription in the first payment (Signing up from a plan). 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

Send payment_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. 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 with payment_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 CREATED until the provider confirms the mandate, then becomes active. If the first payment is refused, the subscription stays CREATED and 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 at 0.00, and the subscription’s amount stays the regular price. The subscription starts TRIALING at billing cycle 0 and bills nothing until the customer approves the mandate. The trial starts when the customer approves (or at availability.start_at, if that is later), and the first paid debit comes after the trial.
The plan must fit what one Pix Automático mandate can express: either no trial, or a free trial on the same cadence as the regular phase. Anything else is rejected before the provider is called:
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_STATE until the mandate is approved. If the setup is canceled without an approval, they stay rejected.

​
Accepted billing cadences

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
A subscription billed on a fixed date — the 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 inline frequency, 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

Sending frequency.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
To bill a Pix Automático subscription yearly, create it from a plan whose frequency is YEAR × 1. The Pix cadence rule accepts it; only the inline route is closed.

​
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 as billing_cycles.scheduling_date. scheduling_date is exactly billing_cycles.next_at minus four days:
billing_cycles on a Pix Automático subscription
On every other payment method the key is absent, not 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’s retries 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.