Migrate to New Subscription Version

We introduce a new version of our subscription product. It consolidate the experiences with our Payment Sessions product for a smoother UI experience and more uniform payment experiences.

Feature Comparison

Feature	Legacy Subscription	New Subscription
Payment Link and Component Support	Limited only on Payment Link	Both Payment Link and Component
Payment Channels Availability	Limited to legacy payment methods and specific regions	Availability for all existing channels and new channels in all regions Xendit supported
New design for hosted page	Old design style, payment channel categorization is outdated	Fresh new design with improvement in user experience
Uniform experiences on payment interfaces	Separate payment lifecycle overview on `payment_method` and UI experiences	One integration principle on each lifecycle on payment interfaces and payment object
Support on initial payment	Only available via legacy parameter `immediate_action_type`	Recommended to use `PAY_AND_SAVE` flow (learn more) with also backward compatibility with parameter `immediate_payment`

Create Subscription via Dashboard
Creation and list of subscription activities will only display the legacy subscription, the new version will currently only supported via API.
We will have an update in the upcoming timeline to support the new version as well.

How to migrate

Update your integration

Overall Flow

Conditions	Legacy Subscription	New Subscription
Using Xendit Hosted URL
Create Subscription Plan	`POST /recurring/plans` with: empty `payment_method` required `success_return_url` and `failure_return_url` Response will return `actions.url` to proceed the linking process	`POST /sessions` with: `session_type: “SUBSCRIPTION”` to initate the session Response will return either `payment_link_url` or `components_sdk_key` depending on your integration `MODE`
Using current payment token	Using legacy `payment_methods` parameter	Using current `payment_tokens` parameter

Conditions

Legacy Subscription

New Subscription

Using Xendit Hosted URL

Create Subscription Plan

POST /recurring/plans with:

empty payment_method
required success_return_url and failure_return_url

Response will return actions.url to proceed the linking process

POST /sessions with:

session_type: “SUBSCRIPTION” to initate the session

Response will return either payment_link_url or components_sdk_key depending on your integration MODE

Using current payment token

Using legacy payment_methods parameter

Using current payment_tokens parameter

Header

Parameters	Legacy Subscription	New Subscription
`api-version`	`2022-10-01`	`2026-01-01`

Parameter Conversion

The new subscription supports most of the functionality of the legacy subscription. The following table maps the parameters and configuration differences between the two versions. Please refer to the API docs for the full lists

Legacy Subscription	New Subscription	Notes
`payment_methods`	`payment_tokens`	Support the new payment tokens object
`immediate_action_type`	`immediate_payment`	Defined as a boolean type to support immediate payment
`recurring_action`	-	Simplified action with only `PAYMENT`
`notification_config.recurring_created, notification_config.recurring_created and notification_config.recurring_failed`	`notification_channels`	Simplified into one parameter to configure the notification channel

Handle New Errors

Adapt on your server’s logic to handle errors in Payment Sessions response upon creation and Subscriptions response

Adjust and handle your webhook setup

Legacy Subscription

Available on the legacy webhook configuration page

New Subscription

Available on the new webhook configuration

Optional but recommended

Adjust the webhook URL to receive the information upon your subscription lifecycle.

Payment v3 – Payment Status

Xendit sends webhooks whenever there is a status update on a Payment object.

payment.succeeded Identifies successful payments and includes full payment details.
payment.failure Identifies failed payment attempts, including failures that occur on the Xendit hosted page.

Payment Tokens v3 – Payment Token Status

Xendit sends webhooks whenever there is a status update on a Payment Token object.