Subscriptions

Yuno’s subscription service lets you manage recurring payments and automate subscription billing for your customers.

​

Yuno subscriptions

A subscription in Yuno’s environment can go through several stages, starting with its creation status. When a subscription is created, it automatically receives the CREATED status. However, it is a transitory status that is active while the payment isn’t processed. After that, the subscription will be ACTIVE or CANCELED, depending on the payment confirmation. When the payment related to the subscription is confirmed, the subscription status changes to ACTIVE — or to TRIALING if it starts inside a plan’s trial phase, which becomes ACTIVE on its own once the trial ends. It remains active while the subscription is within its availability date range and the customer pays the bills. From there it can change to four different statuses:

• COMPLETED: The subscription finish date was reached. In this case, the current subscription is terminated, and it is not possible to reactivate it. If your client wants to continue using your product/service using recurring payments, you need to create a new subscription.
• PAUSED: At any moment, you can pause the subscription. Use this option in case your customer has delayed a payment, for example. You can always activate a paused subscription.
• PAST_DUE: A recurring charge failed and the subscription is awaiting recovery. It keeps billing, and the next successful charge returns it to the status it came from. This status is enabled per account — where it is not enabled, a failed charge leaves the subscription active while the retries run.
• CANCELED: If your customer decides to cancel the recurring payment, you can cancel the subscription. After canceling it, the subscription is terminated, and it is not possible to reactivate it.

A subscription in the trial phase behaves like an active one: it can be paused, it enters PAST_DUE on a failed charge and returns to TRIALING when a later charge succeeds. Any non-terminal status can be canceled, and a subscription created with initial_payment_validation: true goes straight from CREATED to CANCELED if the first payment fails. Learn more about the status of the subscription on the Subscription Status page.

​

Subscription integration

To start using the subscriptions feature, you need a Yuno account and integration with the Yuno API. The Yuno API provides the following operations to manage your subscriptions:

• Create: Use the Create a Subscription endpoint to subscribe a customer.
• Create with the first payment: Send a subscription block on Create Payment to charge the customer and create the subscription in a single call. See Start a subscription with the first payment.
• Pause: Pause an active subscription with the Pause Subscription endpoint.
• Resume: Resume a previously paused subscription with the Resume Subscription endpoint.
• Cancel: Cancel an active subscription with the Cancel Subscription endpoint.
• Retrieve: Use the Retrieve Subscription endpoint to get the details of a subscription.
• List: Use the List Subscriptions endpoint to page through an account’s subscriptions, filtered by customer, status, plan, creation date or payment method type.

​

New concepts

• Subscriptions: A subscription involves recurring charges directly tied to a customer and a particular payment method. When stopping or updating, the impact is solely on the same.
• Payment methods available
  • Enrolled: Customers can pay with a previously enrolled payment method. Only the vaulted token is needed when creating the subscription to associate it with the charges.
• Capabilities:
  • Frequency: Define the frequency at which subscription charges will occur — daily, weekly, monthly, or yearly (see Create Subscription for the values each endpoint accepts) — specifying the amount that needs to be charged for the next billing cycle.
  • Billing cycles: The number of billing cycles (following the frequency criterion) that will be completed to fulfill the subscription. If neither an end_date is sent nor defined, we will continue attempting charges until it is stopped.
  • Billing date: By specifying the billing_date object, the merchant can define the logic behind the exact date for the billing of the subscription. This is mutually exclusive with the frequency object.
  • Availability: The start and end dates of the subscription. If they are not defined, nor the billing cycles, charges will continue until it is stopped.
    • The fields billing_cycles and availability.finish_at impact each other. If both are completed during the subscription creation, it will transition to the COMPLETED state upon reaching the nearest event defined in these fields, whether it is the billing cycle or the corresponding finish_at.
  • Trial periods: This feature lets you define a period where your customers can benefit from a reduced amount. It could be partial or total (for example, a free trial). You need to determine the value to be reduced from the total amount of each subscription charge and the billing cycles it should apply to.
  • Initial payment validation: A flag to identify if the subscription should wait for the first payment to continue. False by default. If the field is set to true, the subscription should remain in the CREATED status while waiting for the first payment of the subscription.
    • If the first payment succeeds (SUCCEEDED), the subscription transitions to ACTIVE.
    • If the first payment fails (DECLINED/REJECTED), the subscription transitions to CANCELED.

​

Using Yuno subscription solution

Yuno provides subscription management functionalities through its API. You can use this API to create, update, and manage subscriptions, as well as retrieve subscription details and usage. To use the subscription solution, normally, you will follow the steps described below:

1. To begin, Create a Customer. You will need to provide personal customer information and the merchant_customer_id, a unique identifier for the customer used in your system. Upon completing the customer creation process, you will receive an id that identifies the user within the Yuno system. This id will be used to create the subscription.
2. After creating the customer, you will need to enroll a credit card to generate a vaulted_token for use in the subscription creation.
3. Create a Subscription for your customer and the enrolled card. At this step, you will configure the subscription and define the payment method. When creating the subscription, you can customize:
   • The amount the subscription charges.
   • The billing frequency: daily, weekly, monthly, or yearly (see Create Subscription for the values each endpoint accepts).
   • The total number of billing cycles.
   • The subscription availability to define the start and end date.

In the response to the Create Subscription endpoint, you receive an id which is used to identify the created subscription. You will use the id if you decide to pause, resume, or cancel the subscription. If you created the subscription with the first payment, the same identifier comes back as subscription_code on the payment response.

​

Renewal events

subscription.active is sent when the subscription first becomes active (at billing_cycles.current = 2); it is not re-sent on subsequent renewals. Track each renewal via the per-cycle payment.purchase webhook (outcome in status/sub_status). $0/trial cycles generate no payment webhook by design — on plan-based subscriptions they are reported as subscription.cycle_executed instead. A failed renewal charge also emits subscription.past_due where that status is enabled for the account, and subscription.active — or subscription.trialing — again once a later charge recovers the subscription. See Webhooks for the full event list.