Recurring Billing Subscription Data Migration Guide {#rb-subs-migration-about-guide} ==================================================================================== This section presents the guide usage and additional information sources. Audience and Purpose : This guide is for merchants who use the `Token Management Service` (`TMS`) and transition recurring billing data and workflows from their current provider to `Cybersource` Recurring Billing. Conventions : This document uses this statement type: > IMPORTANT > An *Important* statement contains information essential to completing a task or learning a concept. Related Documentation : Visit the [`Cybersource` documentation hub](https://developer.cybersource.com/docs.md "") to find additional technical documentation. Customer Support : Visit the Support Center for service support information: Recent Revisions to This Document {#rb-subs-migration-doc-revisions} ==================================================================== 25.10.01 -------- Initial release. VISA Platform Connect: Specifications and Conditions for Resellers/Partners {#vpc-partner-reseller-disclaimer} ============================================================================================================== The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through Cybersource for Visa Platform Connect ("VPC") processing. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner's contract with Visa/Cybersource. 1. Before boarding merchants for payment processing on a VPC acquirer's connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer. 2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer. 3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer. 4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer. DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE Visa Platform Connect ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT Visa Platform Connect ACQUIRER. Introduction to Migrating Subscription Data to `Cybersource` Recurring Billing {#home-merch} ============================================================================================ Transitioning recurring billing subscriptions from another provider to the `Cybersource` Recurring Billing service improves payment processes and customer experience. This guide provides step-by-step instructions for migrating existing recurring billing data and workflows to the `Cybersource` platform. Migration Flow {#rb-subs-migration-0-flow} ========================================== The migration process involves writing and running a script that creates Recurring Billing subscriptions in the `Cybersource` account. This topic presents an overview of the process. **Prepare for the migration.** Before beginning the migration process, understand the limitations and ensure all migration prerequisites are met. Perform these five tasks twice: first in your `Cybersource` test environment and after validating the test migration, in your `Cybersource` production environment. * **Task 1: Enable the `Cybersource` Recurring Billing service.** After migration prerequisites are met, request activation of Recurring Billing for your `Cybersource` account. When you receive the confirmation notice, proceed to the next task. * **Task 2: Integrate with the `Cybersource` API.** Generate API keys for your preferred authentication method at the `Cybersource` `Business Center`. Integrate this authentication method into your migration script using the `Cybersource` API. * **Task 3: Export your current subscriptions to a file.** Export all active subscriptions from your current provider to a file. In the next task, you write and run a migration script that parses the export file and creates subscriptions on the `Cybersource` system. * **Task 4: Create new subscriptions in the `Cybersource` system.** Write and run a script that sends subscription creation requests to the `Cybersource` subscription service. The new subscriptions replicate the active subscriptions in your current subscriptions provider. * **Task 5: Validate the new subscriptions in your test environment.** After running the subscription creation script, verify that the newly created subscriptions match your exported subscription data. Within your test environment, send test transactions in order to validate proper setup. **Finalize the migration.** In your production environment, monitor the transactions of the new subscriptions. Verify that your subscriptions are successfully transitioned from your former subscriptions provider. To avoid creating duplicate charges, deactivate the recurring billing feature on the former subscriptions provider. Migration Limitations {#rb-subs-migration-0-limitations} ======================================================== Only subscriptions in the *active* state can be migrated to `Cybersource` Recurring Billing. Migration Prerequisites {#rb-subs-migration-0-prereqs} ====================================================== Before migrating subscriptions to `Cybersource` Recurring Billing, ensure these prerequisites are met. Understanding of Recurring Billing Subscription Management : Understand Recurring Billing subscription management in the `Cybersource` system. Review these guides for details: * [Recurring Billing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-dev/recur-bill-dev-intro.md "") * [Recurring Billing User Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/user/all/rest/recurring-billing-user/recur-bill-services-intro.md "") : `Cybersource` `Token Management Service` is Configured with a Token Vault : Recurring Billing requires that you have a `Cybersource` account with a properly configured `Token Management Service` (`TMS`) at the transacting MID level and with a configured token vault. For details, see the [Token Management Service Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/ctv/rest/tms/tms-overview.md ""). : Customer Tokens from Your Current Provider Are in the `Cybersource` `TMS` : `Cybersource` Recurring Billing uses only the **customer token** type. The customer tokens from your current subscriptions provider must be in `Cybersource` `TMS` before you begin to migrate subscription data from that provider to the `Cybersource` system. : > IMPORTANT > Token migration from a system outside the ` Cybersource ` system is a separate process that requires coordination with your ` Cybersource ` Account Manager. : Task 1: Enable Recurring Billing in Your `Cybersource` Account {#rb-subs-migration-1-enable} ============================================================================================ Recurring Billing requires that you have a `Cybersource` account with a properly configured `Token Management Service` (`TMS`) at the transacting MID level and with a configured token vault. In addition, customer tokens from the current provider must be in the `Cybersource` `TMS`. 1. To enable Recurring Billing: 2. Verify that you have a `Cybersource` account. 3. Confirm your account has a transacting MID with `TMS` and token vault configuration. See [Migration Prerequisites](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/home-merch/rb-subs-migration-0-prereqs.md "") for details. 4. Verify that customer tokens from the current provider exist in the `Cybersource` `TMS`. See [Migration Prerequisites](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/home-merch/rb-subs-migration-0-prereqs.md "") for details. 5. Contact your `Cybersource` Account Manager to request activation of Recurring Billing for your account. 6. After receiving the confirmation notice, proceed to [Task 2: Integrate with the Cybersource API](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-2-integrate.md ""). Task 2: Integrate with the `Cybersource` API {#rb-subs-migration-2-integrate} ============================================================================= Set up authentication using either JSON Web Token (JWT) or HTTP Signature. Generate API keys for your preferred authentication method at the `Cybersource` `Business Center`. Integrate this authentication method into your migration script using the `Cybersource` API. 1. To integrate with the `Cybersource` API: 2. Log in to your `Cybersource` account at the `Business Center`. * Production: ` `` ` * Test: ` `` ` 3. Set up your `Cybersource` account for secure communication of REST API messages using either JSON Web Token or HTTP Signature. Generate a P12 key for JWT or a shared secret key pair for HTTP Signature: [Set Up Your `Cybersource` Account](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-setup-workflow.md "") 4. Integrate the selected authentication method into the subscription creation script. * For JWT authentication, see [Set Up JSON Web Token Messaging](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-jwt-message-intro.md ""). * For HTTP Signature authentication, see [Set Up an HTTP Signature Message](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-http-message-intro.md ""). Task 3: Export Current Subscriptions to a File {#rb-subs-migration-3-export} ============================================================================ Export all active subscriptions from your current provider to a file. In the next task, you write and run a migration script that parses the export file and creates subscriptions on the `Cybersource` system. > IMPORTANT > Only subscriptions in the *active* state can be migrated to ` Cybersource ` Recurring Billing. 1. To export subscription data from your current provider: 2. Export all active subscriptions from your current provider to a local file. Use a flat text file, CSV file, or Excel spreadsheet. 3. Organize the exported data so that each subscription record is easily processed by the script that you write and run in [Task 4: Create New Subscriptions](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-4-new-subs.md ""). #### ADDITIONAL INFORMATION > TIP Optionally, include a JSON-formatted REST API request in each subscription record. 4. Ensure each subscription record in the export file includes information required to construct a `Cybersource` API request that creates an equivalent subscription in `Cybersource` Recurring Billing. #### ADDITIONAL INFORMATION The fields required in the API request message vary based on the plan options for the subscription. For lists of required fields in the `Cybersource` API request, see the example requests in [Reference Information](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-7-reference.md ""). IMPORTANT > A Recurring Billing subscription on the ` Cybersource ` platform begins billing on the date specified in the subscriptionInformation. startDate field of the request unless you manually **suspend** or **cancel** the subscription after it is created. 5. Save a copy of the export file. #### ADDITIONAL INFORMATION IMPORTANT You need this export file for subsequent migration tasks. Task 4: Create New Subscriptions {#rb-subs-migration-4-new-subs} ================================================================ Write and run a script that sends subscription creation requests to the `Cybersource` subscription service. The new subscriptions replicate the active subscriptions in your current subscriptions provider. This section contains information for writing the subscription creation script: * **Requirements for the subscription creation script.** Adhere to these requirements as you write the subscription creation script. * **Additional API field required for any credit or debit card subscription.** When migrating a credit or debit card payment subscription from a provider outside of the `Cybersource` system, include the network transaction ID of the authorized transaction from the previous provider system to avoid re-authorization for a new, zero-value credit card payment. * **Additional API field required for a Diners or Discover card.**For subscriptions on Diners cards or Discover cards, also include the authorized payment amount from your previous provider system. * **How to obtain the additional information required for a credit or debit card subscription.** The network transaction ID and the authorized payment amount are in the `Cybersource` `Token Management Service` (`TMS`), provided that the network transaction ID of the original subscription (from the previous provider) are now in `Cybersource` `TMS`. This condition is a prerequisite for migration. * **Construct your subscription creation script.** For each subscription record that you exported from your former subscription provider, your script must submit an API request to create a new Recurring Billing subscription in the `Cybersource` system. Requirements for the Subscription Creation Script {#rb-subs-migration-4-script-reqts} ===================================================================================== Adhere to these requirements as you write the subscription creation script. **Migration log file** : The script logs each API request message sent and the corresponding response information returned by the `Cybersource` subscription service. **Retry logic** : For failed subscription creation requests, correct the request and resubmit it to the subscription service. **Billing start date** : `Cybersource` Recurring Billing subscriptions begin billing on the date specified in the subscriptionInformation.startDate field. **Reusable set of billing periods and billing cycles** : Create a *subscription plan* that defines a billing period (or billing cycle) and a number of billing cycles. In the REST API, use these fields: * planInformation.billingCycles.total * [planInformation.billingPeriod.length](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-billing-period-length.md "") * [planInformation.billingPeriod.unit](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-billing-period-length.md "") * [planInformation.description](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-des.md "") * [planInformation.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-name.md "") **Plan options for new subscriptions** : `Cybersource` Recurring Billing subscriptions support these plan options: * Define a **one-time plan** for a subscription instead of creating a subscription plan. * Use the plan information defined in the **existing plan** referenced by the subscriptionInformation. planId field in the subscription creation message. * Specify **overrides** to some of the information in the referenced plan. For example, if the subscription was for a fixed period, specify the remaining number of billing cycles in the planInformation. billingCycles.total field. For detailed examples of how to create plan-specific subscriptions, see [Reference Information](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-7-reference.md ""). Additional Fields Required for Card Subscriptions {#rb-subs-migration-4-script-reqts-card-0} ============================================================================================ This section describes additional requirments for the subscription creation script. One or two additional fields must be included in a subscription creation request for a credit or debit card subscription. Additional API Field Required for Any Credit or Debit Card Subscription {#rb-subs-migration-4-script-reqts-card-1-any} ====================================================================================================================== If the subscription is for a credit or debit card, the subscription creation request must include the *network transaction ID* of the transaction that originally initialized the subscription (and allowed for the storage of payment information). Include the network transaction ID in this field of the subscription creation request message: subscriptionInformation. originalTransactionId For information about obtaining the network transaction ID, see [Obtaining Additional Values Required for Card Subscriptions](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-4-new-subs/rb-subs-migration-4-script-reqts-card-obtain.md ""). Continue to use this network transaction ID to uniquely identify future automatic payments for this subscription. > IMPORTANT > Including the network transaction ID in the subscription creation request obtains the payer's consent for you to make automatic (recurring) payments with the new subscription in the ` Cybersource ` system. Additional API Field Required for a Diners or Discover Card {#rb-subs-migration-4-script-reqts-card-2-diners} ============================================================================================================= If the subscription is for a Diners card or Discover card, also include the *payment amount* that was authorized in the provider system that initialized the subscription and allowed for the storage of payment information. Include the payment amount in this field of the subscription creation request message: subscriptionInformation. originalTransactionAuthorizedAmount For information about obtaining the payment amount, see [Obtaining Additional Values Required for Card Subscriptions](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-4-new-subs/rb-subs-migration-4-script-reqts-card-obtain.md ""). Obtaining Additional Values Required for Card Subscriptions {#rb-subs-migration-4-script-reqts-card-obtain} =========================================================================================================== The network transaction ID and the authorized payment amount are in the `Cybersource` `Token Management Service` (`TMS`), provided that the network transaction ID of the original subscription (from the previous provider) are now in `Cybersource` `TMS`. Three possibilities exist: * Original subscription data is in `Cybersource` `TMS` * Original subscription data is not in `Cybersource` `TMS` but it is available from the original subscription provider * Original subscription data is not available Retrieve Original Subscription Data from the `Cybersource` `TMS` {#rb-subs-migration-4-script-reqts-card-obtain-a-cybs-tms} =========================================================================================================================== As a prerequisite to migration, customer tokens from your original provider are in the `Cybersource` `TMS`. If this prerequisite is met, you can retrieve the additional data required for card subscriptions from the `Cybersource` `TMS`. This topic applies to migrating a credit or debit card subscription to `Cybersource` when the original subscription data (from the original subscription provider) is now in `Cybersource` `TMS`. 1. To retrieve original subscription data from the `Cybersource` `TMS`: 2. Perform this GET request: #### ADDITIONAL INFORMATION * Production: `GET ``https://api.cybersource.com``/tms/v2/customers/{customerId}` * Test: `GET ``https://apitest.cybersource.com``/tms/v2/customers/{customerId}` Replace the `{customerId}` portion of the URL with the ID of the customer associated with the subscription in the previous provider system 3. Retrieve the ID of the original transaction from this field of the response to the GET request: #### ADDITIONAL INFORMATION _embedded.defaultPaymentInstrument. _embedded.instrumentIdentifier. processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. previousTransactionId 4. Include the network transaction ID in this field of the subscription creation request message that the script sends to the `Cybersource` subscription service: #### ADDITIONAL INFORMATION subscriptionInformation. originalTransactionId 5. If the subscription is for a Diners card or Discover card: 1. Retrieve the authorized payment amount from this field of the response to the GET request: #### ADDITIONAL INFORMATION _embedded.defaultPaymentInstrument. _embedded.instrumentIdentifier. processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. originalAuthorizedAmount 2. Include the authorized payment amount in this field of the subscription creation request message that the script sends to the `Cybersource` subscription service: #### ADDITIONAL INFORMATION subscriptionInformation. originalTransactionAuthorizedAmount Retrieve Original Subscription Data from the Original Provider {#rb-subs-migration-4-script-reqts-card-obtain-b-orig-prov} ========================================================================================================================== This topic applies to migrating a credit or debit card subscription to `Cybersource` when the original subscription data is not in `Cybersource` `TMS` but it is available from the original subscription provider. 1. To retrieve original subscription data from the original subscription provider: 2. Contact the previous subscriptions provider to obtain data from the original subscription. 3. Request the network transaction ID for original subscription. 4. Include the network transaction ID in this field of the subscription creation request message that the script sends to the `Cybersource` subscription service: #### ADDITIONAL INFORMATION subscriptionInformation. originalTransactionId 5. If the subscription is for a Diners card or Discover card: 1. Request the authorized payment amount for the original subscription. 2. Include the authorized payment amount in this field of the subscription request that the script sends to the `Cybersource` subscription service: #### ADDITIONAL INFORMATION subscriptionInformation. originalTransactionAuthorizedAmount When Original Subscription Data Cannot Be Retrieved {#rb-subs-migration-4-script-reqts-card-obtain-c-not-avail} =============================================================================================================== To migrate a credit or debit card subscription when the original subscription data is not available in `Cybersource` `TMS` or from the original subscription provider, re-authorize a new, zero-value card payment. > IMPORTANT > Attempting to create a new subscription by re-authorizing a new, zero-value credit card payment often triggers indeterminate conditions, such as ` 3-D Secure ` authentication failure. Construct Your Subscription Creation Script {#rb-subs-migration-4-script-construct-request} =========================================================================================== For each subscription record that you exported from your former subscription provider, your script must submit an API request to create a new Recurring Billing subscription in the `Cybersource` system. 1. For each subscription, instructions in your script must: 2. Create the subscription creation request message with the required `REST` API fields. #### ADDITIONAL INFORMATION Follow these guidelines: * [Requirements for the Subscription Creation Script](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-4-new-subs/rb-subs-migration-4-script-reqts.md "") * [Additional API Field Required for Any Credit or Debit Card Subscription](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-4-new-subs/rb-subs-migration-4-script-reqts-card-0/rb-subs-migration-4-script-reqts-card-1-any.md "") * [Additional API Field Required for a Diners or Discover Card](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-4-new-subs/rb-subs-migration-4-script-reqts-card-0/rb-subs-migration-4-script-reqts-card-2-diners.md "") #### ADDITIONAL INFORMATION For reference information to help you to construct a request message through your script, see these topics: * [Using the Interactive REST API Reference](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-7-reference/rb-subs-migration-4-dev-ctr-api.md "") * [Creating a Subscription with a One-Time Plan](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-7-reference/rb-subs-migration-4a-plan-one-time.md "") * [Creating a Subscription with an Existing Plan](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-7-reference/rb-subs-migration-4b-plan-existing.md "") * [Creating a Subscription with Plan Overrides](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-7-reference/rb-subs-migration-4c-plan-overrides.md "") 3. Send the message to one of these endpoints: * Production: `POST ``https://api.cybersource.com``/rbs/v1/subscriptions` * Test: `POST ``https://apitest.cybersource.com``/rbs/v1/subscriptions` 4. Check the response messages to verify that the request was successful. #### ADDITIONAL INFORMATION A 200-level HTTP response code indicates success. See the [Transaction Response Codes](https://developer.cybersource.com/api/reference/response-codes.md ""). 5. Write the request and response information to the log file for troubleshooting and verification purposes. 6. For transaction errors, perform error handling and retry logic when appropriate. Task 5: Validate the New Subscriptions in the `Cybersource` System {#rb-subs-migration-5-validate} ================================================================================================== After running the subscription creation script, verify that the newly created subscriptions match your exported subscription data. Within your test environment, send test transactions in order to validate proper setup. Perform the validation at the `Cybersource` `Business Center` or using REST API requests. Use the `Business Center` to Validate Migrated Subscriptions {#rb-subs-migration-5-validate-ebc-ui} =================================================================================================== > IMPORTANT > To validate, compare the new ` Cybersource ` subscription details to the export file you created in [Task 3: Export Current Subscriptions to a File](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-3-export.md ""). 1. To validate migrated subscriptions using the `Cybersource` `Business Center`: 2. Log in to your `Cybersource` account at the `Business Center`. * Production: ` `` ` * Test: ` `` ` 3. On the left navigation panel, click Recurring Billing and Manage Subscriptions. #### ADDITIONAL INFORMATION The Recurring Billing Manage Subscriptions screen appears. The Search Results section lists all managed subscriptions that are accessible to your `Cybersource` account. 4. To validate the details of a specific subscription: 1. In the Recurring Billing Manage Subscriptions screen, click Add–Filter. 2. In the New Filter drop-down menu, choose the type of data on which you want to filter the subscription list and choose or enter the value on which to match subscriptions. #### ADDITIONAL INFORMATION You can filter the list by subscription code, account owner first or last name, plan name, or subscription status. 3. Click Search. 4. In the filtered list, click the subscription code of the subscription you want to view. #### ADDITIONAL INFORMATION The Subscription Details screen appears and displays this information: * **Subscription ID** is an identifier unique to this subscription. Use this ID to identify this subscription in API references and to assist in customer service. * **Subscription details** include the subscription start date, billing cycle, and setup fee. * **Customer details** include the customer token and the customer ID. * **Payment details** include the card type, card expiration date, billing address, and the payment instrument ID. * **Shipping details** are displayed if the information is available for the customer. 5. Compare the subscription details to the corresponding subscription details in the export file. 5. To validate subscriptions created for a specific customer: 1. On the left navigation panel, click Token Management and Customers. #### ADDITIONAL INFORMATION The Token Management Customers screen appears. 2. In the New Filter drop-down menu, choose the type of data on which you want to filter customer tokens and choose or enter the value on which to match tokens. #### ADDITIONAL INFORMATION To filter subscriptions on a customer email address, select Email and enter the address. 3. Click Search. 4. In the Search Results, click the token ID of the customer for which you want to view subscriptions. 5. In the Token Management Customer Details screen, click Manage Subscriptions. The Recurring Billing Manage Subscription screen appears and lists subscriptions associated with the customer token you viewed. 6. Compare the subscription details to the corresponding subscription details in the export file. 6. (Recommended in your test environment) Send test transactions to validate proper setup. Use the REST API to Validate Migrated Subscriptions {#rb-subs-migration-5-validate-rest-api} ============================================================================================ > IMPORTANT > To validate the migration, compare the new ` Cybersource ` subscription details to the export file you created in [Task 3: Export Current Subscriptions to a File](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-3-export.md ""). 1. Follow these steps to use the `Cybersource` REST API to validate the migrated subscriptions: 2. Follow these steps if you want to validate a specific subscription: 1. To obtain the details of a specific subscription, see [Retrieving a Subscription](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-dev/recur-bill-subscriptions/recur-bill-getting-a-subscription.md "") in the *Recurring Billing Developer Guide*. The subscription details are returned in the response message. 2. Compare the subscription details to the corresponding subscription details that you exported to a file in [Task 3: Export Current Subscriptions to a File](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-3-export.md ""). The subscription details are returned in the response message. 3. Follow these steps if you want to validate a list of all subscription details: 1. To obtain a list of all subscription details, see [Retrieving a List of Subscriptions](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-dev/recur-bill-subscriptions/recur-bill-getting-all-subscriptions.md "") in the *Recurring Billing Developer Guide*. The list of subscription details is returned in the response message. 2. Compare the `Cybersource` subscription details in the list to the subscription details in the export file from [Task 3: Export Current Subscriptions to a File](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-3-export.md ""). 4. (Optional) Complete these steps if you want to **cancel** a pending, active, suspended, or delinquent subscription: 1. In the subscription details, find the subscription ID. 2. Send the message to one of these endpoints, replacing the `{id}` portion of the URL with the value of the subscription ID: * Production: `POST ``https://api.cybersource.com``/rbs/v1/subscriptions/{id}/cancel` * Test: `POST ``https://apitest.cybersource.com``/rbs/v1/subscriptions/{id}/cancel` 3. Check the response message to verify that the request was successful. A 200-level HTTP response code indicates success. 5. (Recommended in your test environment) Send test transactions to validate proper setup. Finalize the Migration {#rb-subs-migration-6-finalize} ====================================================== In your production environment, monitor the transactions of the new subscriptions. Verify that your subscriptions are successfully transitioned from your former subscriptions provider. To avoid creating duplicate charges, deactivate the recurring billing feature on the former subscriptions provider. 1. To complete the migration: 2. Actively monitor the Recurring Billing subscription transactions on the `Cybersource` platform. #### ADDITIONAL INFORMATION For information about reports that contain Recurring Billing transaction details, see these topics in the *Reporting User Guide*: * [Recurring Billing Detail Report](https://developer.cybersource.com/docs/cybs/en-us/reporting/user/all/ebc/reporting-ug/c_Reports_Available_in_the_Business_Center/c_Recurring_Billing_Detail_Report.md "") * [Recurring Billing Report Fields](https://developer.cybersource.com/docs/cybs/en-us/reporting/user/all/ebc/reporting-ug/c_Report_Fields_and_Descriptions/Fields_Descriptions_Downloadable_Reports/c_Recurring_Billing_Fields.md "") * [Subscribing to Standard Reports](https://developer.cybersource.com/docs/cybs/en-us/reporting/user/all/ebc/reporting-ug/Creating_Accessing_Downloadable_Reports/c_Subscribing_to_Standard_Reports.md "") #### ADDITIONAL INFORMATION Recommendations: * Track subscriptions that have payments scheduled to occur over several consecutive days. Confirm that the payments complete successfully and that the subscriptions remain active. * Confirm that the rate of declined transactions is not elevated. 3. After verifying that all active subscriptions and subscription data are successfully transitioned to `Cybersource` Recurring Billing, deactivate Recurring Billing on the former subscriptions provider platform. Reference Information {#rb-subs-migration-7-reference} ====================================================== This section contains reference information for migrating subscriptions from the current subscriptions platform to Recurring Billing subscriptions on the `Cybersource` platform. This reference information is supplemental to [Task 4: Create New Subscriptions](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-4-new-subs.md ""). * **How to access and use the interactive REST API reference.** The `Cybersource` Developer Center includes an interactive *REST API Reference*. As you write your script, you can use the interactive module to help construct request messages for creating Recurring Billing plans and subscriptions. * **How to create a subscription for a one-time plan.**These topics provide detailed information about how to request the creation of a subscription that uses a one-time plan. * **How to create a subscription for an existing plan.**These topics provide detailed information about how to request the creation of a subscription that uses an existing plan. * **How to create a subscription with plan overrides.**These topics provide detailed information about how to request the creation of a subscription that uses plan overrides. Using the Interactive REST API Reference {#rb-subs-migration-4-dev-ctr-api} =========================================================================== After exporting subscription data from your current provider in [Task 3: Export Current Subscriptions to a File](/docs/cybs/en-us/recurring-billing/migration/all/rest/recurring-billing-migrate/rb-subs-migration-3-export.md ""), write a subscription creation script that accesses entries in your export file and recreates each subscription within Cybersource Recurring Billing. The `Cybersource` Developer Center includes an interactive *REST API Reference*. As you write your script, you can use the interactive module to help construct request messages for creating Recurring Billing plans and subscriptions. Build a Request to Create a Recurring Billing Plan {#rb-subs-migration-4-dev-ctr-plan} ====================================================================================== 1. Follow these steps to access the interactive REST API reference for creating a Recurring Billing plan: 2. Go to the [REST API Reference](https://developer.cybersource.com/api-reference-assets/index.md "") on the Cybersource Developer Center. 3. On the left navigation panel, click Payments and Recurring Billing Subscriptions. 4. Click Create a Plan. The [Create a Plan](https://developer.cybersource.com/api-reference-assets/index.md#recurring-billing-subscriptions_plans_create-a-plan "") screen appears. Build a Request to Create a Recurring Billing Subscription {#rb-subs-migration-4-dev-ctr-api-subs} ================================================================================================== 1. Follow these steps to access the interactive REST API reference for creating Recurring Billing subscriptions: 2. Go to the [REST API Reference](https://developer.cybersource.com/api-reference-assets/index.md "") on the Cybersource Developer Center. 3. On the left navigation panel, click Payments and Recurring Billing Subscriptions. 4. Click Create a Subscription. The [Create a Subscription](https://developer.cybersource.com/api-reference-assets/index.md#recurring-billing-subscriptions_plans_create-a-subscription "") screen appears. Creating a Subscription with a One-Time Plan {#rb-subs-migration-4a-plan-one-time} ================================================================================== As you write your script, refer to the information in this section as a guide for requesting creation of a subscription with a one-time plan: * Required and optional fields for the request to create subscription with a one-time plan * Example request to create a subscription with a one-time plan Required and Optional Fields {#rb-subs-migration-4a-plan-one-time-fields} ========================================================================= These fields are required for creating a subscription with a one-time plan: [orderInformation.amountDetails.billingAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-billing-amount.md "") : Amount charged during the billing period. [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.setupFee](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-set-up-fee.md "") : The subscription set-up fee charged by the merchant. [paymentInformation.customer.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-customer-id.md "") : planInformation.billingCycles.total : [planInformation.billingPeriod.length](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-billing-period-length.md "") : [planInformation.billingPeriod.unit](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-billing-period-unit.md "") : [subscriptionInformation.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/sub-info-aa/sub-info-name.md "") : [subscriptionInformation.startDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/sub-info-aa/sub-info-start-date.md "") : Optional Fields --------------- subscriptionInformation.originalTransactionId : Required to create any credit or debit card subscription. : Including this field ensures better authorization rates and Strong Customer Authentication (SCA) compliance where necessary. subscriptionInformation.originalTransactionAuthorizedAmount : Additional required field for a Diners or Discover card.. Related Information ------------------- * [API field reference guide for the REST API](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md "") REST Example: Create a Subscription with a One-Time Plan {#rb-subs-migration-4a-plan-one-time-code} =================================================================================================== This example creates a subscription with a one-time plan. Request ``` { "planInformation": { "billingPeriod": { "length": "1", "unit": "M" }, "billingCycles": { "total": "24" } }, "subscriptionInformation": { "name": "Subscription with one-time plan", "startDate": "2025-08-10", "originalTransactionId": "123456789", "originalTransactionAuthorizedAmount": "0.00" }, "paymentInformation": { "customer": { "id": "C24F5921EB870D99E053AF598E0A4105" } } } ``` Example Response to a Successful Request ``` { "_links": { "self": { "href": "/rbs/v1/subscriptions/1619214861", "method": "GET" }, "update": { "href": "/rbs/v1/subscriptions/1619214861", "method": "PATCH" }, "cancel": { "href": "/rbs/v1/subscriptions/1619214861/cancel", "method": "POST" } }, "id": "1619214861", "status": "COMPLETED", "subscriptionInformation": { "code": "AWC-49", "status": "PENDING" } } ``` Example Response to a Failed Request ``` { "status": "INVALID_REQUEST", "reason": "INVALID_DATA", "message": "One or more fields in the request contains invalid data.", "details": [ { "field": "planInformation.billingPeriod.length", "reason": "MAX_LENGTH" } ] } ``` Creating a Subscription with an Existing Plan {#rb-subs-migration-4b-plan-existing} =================================================================================== As you write your script, refer to the information in this section as a guide for requesting creation of a subscription with an existing plan: * Required and optional fields for the request to create subscription with an existing plan * Example request to create a subscription with an existing plan Required and Optional Fields {#rb-subs-migration-4b-plan-existing-fields} ========================================================================= These fields are required for creating a subscription with an existing plan: [paymentInformation.customer.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-customer-id.md "") : [subscriptionInformation.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/sub-info-aa/sub-info-name.md "") : subscriptionInformation.planId : Required when you are using a standard plan. [subscriptionInformation.startDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/sub-info-aa/sub-info-start-date.md "") : Optional Fields --------------- subscriptionInformation.originalTransactionId : Required to create any credit or debit card subscription. : Including this field ensures better authorization rates and Strong Customer Authentication (SCA) compliance where necessary. subscriptionInformation.originalTransactionAuthorizedAmount : Additional required field for a Diners or Discover card. Related Information ------------------- * [API field reference guide for the REST API](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md "") REST Example: Create a Subscription with an Existing Plan {#rb-subs-migration-4b-plan-existing-code} ==================================================================================================== This example creates a subscription that uses an existing plan. Request ``` { "subscriptionInformation": { "planId": "6868912495476705603955", "name": "Subscription with plan id", "startDate": "2025-08-10", "originalTransactionId": "123456789", "originalTransactionAuthorizedAmount": "0.00" }, "paymentInformation": { "customer": { "id": "C24F5921EB870D99E053AF598E0A4105" } } } ``` Example Response to a Successful Request ``` { "_links": { "self": { "href": "/rbs/v1/subscriptions/1619214690", "method": "GET" }, "update": { "href": "/rbs/v1/subscriptions/1619214690", "method": "PATCH" }, "cancel": { "href": "/rbs/v1/subscriptions/1619214690/cancel", "method": "POST" } }, "id": "1619214690", "status": "COMPLETED", "subscriptionInformation": { "code": "AWC-47", "status": "PENDING" } } ``` Example Response to a Failed Request ``` { "status": "INVALID_REQUEST", "reason": "INVALID_DATA", "message": "One or more fields in the request contains invalid data.", "details": [ { "field": "subscriptionInformation.startDate", "reason": "INVALID_DATA" } ] } ``` Creating a Subscription with Plan Overrides {#rb-subs-migration-4c-plan-overrides} ================================================================================== As you write your script, refer to the information in this section as a guide for requesting creation of a subscription with plan overrides. Required and Optional Fields {#rb-subs-migration-4c-plan-overrides-fields} ========================================================================== These fields are required for creating a subscription with plan overrides: [paymentInformation.customer.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-customer-id.md "") : [subscriptionInformation.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/sub-info-aa/sub-info-name.md "") : subscriptionInformation.planId : [subscriptionInformation.startDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/sub-info-aa/sub-info-start-date.md "") : Optional Fields --------------- [orderInformation.amountDetails.billingAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-billing-amount.md "") : Amount charged during the billing period. [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.setupFee](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-set-up-fee.md "") : The subscription set-up fee charged by the merchant. planInformation.billingCycles.total : [planInformation.billingPeriod.length](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-billing-period-length.md "") : [planInformation.billingPeriod.unit](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/plan-info-aa/plan-info-billing-period-unit.md "") : subscriptionInformation.originalTransactionId : Required to create any credit or debit card subscription. : Including this field ensures better authorization rates and Strong Customer Authentication (SCA) compliance where necessary. subscriptionInformation.originalTransactionAuthorizedAmount : Additional required field for a Diners or Discover card. Related Information ------------------- * [API field reference guide for the REST API](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md "") REST Example: Create a Subscription with Plan Overrides {#rb-subs-migration-4c-plan-overrides-code} =================================================================================================== This example creates a subscription that overrides part of an existing plan. For example, you can use an existing plan with an indefinite duration and a specific amount, and then, for a given subscription, specify the number of remaining billing cycles. Request ``` { "planInformation": { "billingCycles": { "total": "5" } }, "subscriptionInformation": { "planId": "6868912495476705603955", "name": "Subscription with plan id and new number of billing cycles", "startDate": "2025-08-10", "originalTransactionId": "123456789", "originalTransactionAuthorizedAmount": "0.00" }, "paymentInformation": { "customer": { "id": "C24F5921EB870D99E053AF598E0A4105" } } } ``` Example Response to a Successful Request ``` { "_links": { "self": { "href": "/rbs/v1/subscriptions/1619214795", "method": "GET" }, "update": { "href": "/rbs/v1/subscriptions/1619214795", "method": "PATCH" }, "cancel": { "href": "/rbs/v1/subscriptions/1619214795/cancel", "method": "POST" } }, "id": "1619214795", "status": "COMPLETED", "subscriptionInformation": { "code": "AWC-48", "status": "PENDING" } } ``` Example Response to a Failed Request ``` { "status": "INVALID_REQUEST", "reason": "DUPLICATE_REQUEST", "message": "Duplicate requests are not supported within 15 minutes.", "details": [ { "field": "subscriptionInformation.planId or paymentInformation.customer.id or subscriptionInformation.startDate or subscriptionInformation.name", "subscriptionId": "1619214795", "reason": "INVALID_DATA" } ] } ```