On This Page

Recurring Billing Upgrade Guide

Use this guide to learn about the Recurring Billing upgrade process and find additional information.
Audience and Purpose
This guide is written for merchants who use the legacy Recurring Billing service with secure storage and must update their order management system and recurring billing processes to use the upgraded Recurring Billing service that is available through the
Business Center
 and the REST API.
Conventions
The following special statement is used in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
Related Documentation
Visit the
Cybersource
 documentation hub to find additional technical documentation.
Use the interactive REST API Reference in the
Cybersource
 Developer Center to create an example REST API request message.
Customer Support
For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.10.01

Introduction to Upgraded Recurring Billing
Added a graphic that presents an overview of Recurring Billing upgrade and migration. See Recurring Billing Upgrade and Migration Overview.
Added comparisons of legacy Recurring Billing, new Recurring Billing, and
Token Management Service
 (
TMS
) API fields. See Comparison of Business Center UI Sections and API Fields.
Updated the comparison of report fields. See Upgraded Report Fields.
Migration Activities
Added recommended subscription and system validations to perform after
Cybersource
 notifies you that your upgrade and migration is complete in the TEST or preproduction environment. See Test Checklist Recommendations.
Post-Migration Information

24.05

Post-Migration Information
Added information that you must be aware of immediately after completing migration to the new Recurring Billing. See these topics:

24.04

This revision contains only editorial changes and no technical updates.

24.03

This revision contains only editorial changes and no technical updates.

24.02

This revision contains only editorial changes and no technical updates.

24.01

Initial release.

Introduction to Upgrading the Recurring Billing Service

Cybersource
 is replacing the legacy Recurring Billing service with an upgraded Recurring Billing service. You can access the service in the
Business Center
 only, or you can access it in the
Business Center
 along with the REST API for Recurring Billing and the
Token Management Service
 (
TMS
).
The Recurring Billing service is available for the
REST
 API only. The service is not available in the
SCMP
 API or the
Simple Order
 API. If you use the
SCMP
 API or the
Simple Order
 API to create and manage subscriptions, you must integrate to the Recurring Billing service that uses the REST API.
With the upgraded Recurring Billing service, you can manage payment plans and subscriptions for recurring payment schedules. TMS stores your customer's payment information and personal data within secure Visa data centers, reducing storage risks and Payment Card Industry Data Security Standard (PCI DSS) compliance scope.
The upgraded Recurring Billing product benefits merchants and customers:
  • Reduces effort associated with automated payments and payment card updates
  • Decreases late payments with scheduled payments at set intervals
  • Improves customer relationships by providing a better online experience
  • Cuts costs and reduces waste with streamlined payment processes
  • Keeps payment information secure by using tokens

Recurring Billing Upgrade and Migration Overview

This topic provides a visual overview of the Recurring Billing upgrade and migration process.

Figure:

Recurring Billing Upgrade and Migration
Diagram that summarizes the RB upgrade and migration process

Upgraded Recurring Billing

The upgraded Recurring Billing consists of three key elements:
  • Customer Token
    : Stores customer billing, shipping, and payment details
  • Plan
    : Stores the billing schedule
  • Subscription
    : Combines the token and plan, and determines the subscription start date, name, and description
Components of automatic recurring payments:

Figure:

Recurring Payment Components
Components of automatic recurring billing

Plans

Plans are a new feature in the upgraded Recurring Billing. They help you manage setup costs and recurring amounts for multiple subscriptions. You can set up and manage plans in the
Business Center
 or through the API. A plan includes a setup fee and a recurring amount. When creating a subscription for a customer, you can assign them to a plan. If you change a plan, decide if the change applies to new subscriptions, or both new and existing subscriptions.
Individual subscriptions are still available, but require individual management.
Plans can be retrieved, amended, activated, deactivated, or deleted.
Recurring Billing supports two types of plans:
  • Standard plans
    : Created and stored within the recurring billing service for reuse. You can assign these plans to multiple subscriptions
  • One-time plans
    : Created specifically for a single subscription and not stored for reuse or assigned to other subscriptions
Plans have two billing cycle options:
  • The bill has a payment schedule with no end date
  • The bill has a payment schedule with a fixed number of payments
When creating or updating a plan, you can take these actions:
  • Define the billing schedule by setting amount, currency, and frequency
  • Specify the number of billing cycles for a fixed number of payments
  • Include an optional setup fee
  • Set up a single plan to apply to multiple individual subscriptions
  • Make changes to the plan and choose whether to apply them only to new subscriptions, or to all existing subscriptions

Subscriptions

Subscriptions can be retrieved, amended, suspended, reactivated, or cancelled.
When creating or updating a subscription, these actions are available:
  • Quickly create a subscription defining the billing schedule with an existing plan, or create a one-time plan
  • Assign the customer token that represents customer billing, shipping, and payment details
  • Move subscriptions from one plan to another plan
  • Set the start date

Legacy and Upgraded Recurring Billing Feature Comparison

This table compares key features of the legacy Recurring Billing to the new Recurring Billing service.
Feature Comparison
Feature
Legacy Recurring Billing
Upgraded Recurring Billing
Subscription management
Create, manage, edit, cancel, suspend, and skip or unskip subscriptions.
Create, retrieve, amend, reactivate, suspend, and cancel subscriptions. To skip a payment, you can suspend and reactivate the subscription.
Plan management with subscription templates
Not available.
Full plan management that includes create, retrieve, amend, activate, deactivate, and delete.
Integration methods
SCMP API
Simple Order API
Secure Acceptance
REST API
Online portal
Business Center
Create subscriptions in:
  • Recurring Billing
  • Virtual Terminal
  • Transaction management as a follow-on transaction
  • Batch upload
Business Center
Create subscriptions in:
  • Recurring Billing
  • Virtual Terminal (create customer token within Virtual Terminal One-time Payment and then use it to create a subscription from token management tab or create subscription using Existing Customer flow)
Data security
Secure storage tokenization, legacy with end-of-life plan
Token Management Service (TMS)
Failed transaction retry logic
Maximum of five system retries
Maximum of four system retries
Payment methods
Payment cards on major networks
Bank accounts (ACH)
Payment cards on major networks
Bank accounts (ACH)
Account Updater
Optional support on secure storage
Optional support on TMS

Legacy and Upgraded
Business Center
 and API Service Feature Comparison

This table lists common recurring billing key features and compares the legacy Recurring Billing service using the SCMP and Simple Order APIs to the upgraded Recurring Billing service and Token Management Service (TMS) that use the REST API and the Business Center.
API Service Feature Comparison
Feature
Legacy Recurring Billing
Upgraded Recurring Billing
Email notifications
Set up notifications in the Business Center
Notifications are sent automatically to the email address associated with the customer token. They contain information from the plan and subscription details for a prepayment, successful payment, or failed payment
Merchant-initiated transactions
Optional data storage
Other data storage where data is encrypted or not encrypted
Not possible
Replacement expiration dates
Contact customer support to enable your account
Not possible
Customer subscription sharing
Contact customer support to enable your account
Not possible
Account Updater
Integrated with Recurring Billing to keep card data current through SCMP API or Simple Order API batch uploads and automatic updates
Integrated with Recurring Billing to keep card data current through REST API batch uploads and automatic updates

Legacy and Upgraded Business Center and API Service Action Comparison

This table lists common recurring billing actions and compares the legacy Recurring Billing service using the SCMP and Simple Order APIs to the upgraded Recurring Billing service and Token Management Service (TMS) that use the REST API and the Business Center.
Legacy and Upgraded
Business Center
 API Service Action Comparison
Action
Legacy Recurring Billing
Upgraded Recurring Billing
Creating an on-demand customer profile token
Use the create subscription service to create a subscription ID
Use TMS with the REST API or the Business Center to create a customer token
Creating a customer profile token with a setup fee
Use the create subscription service to create a subscription ID and use the authorization and capture services to charge the setup fee
Use TMS with the REST API or the Business Center to create a customer token
Creating a customer profile token with a payment network token
Use the create subscription service to create a subscription ID and authorization service to validate the payment network token
Use TMS with the REST API or the Business Center to create a customer token
Creating an eCheck customer profile token
Use the create subscription service to create a subscription ID
Use TMS with the REST API or the Business Center to create a customer token
Creating an installment subscription with payment card or eCheck
Use the create subscription service to create a subscription ID and installment subscription
Use the REST API or the Business Center to create a plan with a fixed number of payments and to create a subscription with a customer token
Creating an installment subscription with a payment network token
Use the create subscription service and use the authorization service to create a subscription ID and installment subscription
Use the REST API or the Business Center to create a plan with a fixed number of payments and to create a subscription with a customer token
Creating a recurring subscription with a payment card or eCheck
Use the create subscription service to create a subscription ID and recurring subscription
Use the REST API or the Business Center to create a plan that bills indefinitely and to create a subscription
Creating a recurring subscription with a payment network token
Use the create subscription service and the authorization service to create a subscription ID and recurring subscription
Use the REST API or the Business Center to create a plan that bills indefinitely and to create a subscription
Retrieving a subscription
Use the retrieve subscription service to retrieve a subscription ID
Use the Recurring Billing REST API or the
Business Center
 to retrieve a subscription or a list of subscriptions
Updating a subscription with a payment card
Use the subscription update service to update a subscription payment card
Use TMS with the REST API or the Business Center to update the customer profile token
Removing a payment card expiration date
Use the update subscription service to remove a subscription payment card
Use TMS with the REST API or the Business Center to update a customer profile token
Replacing a payment card with a payment network token
Use the update subscription service to update a subscription ID
Use TMS with the REST API or the Business Center to update a customer profile token
Replacing a payment network token with a payment card
Use the update subscription service to replace a payment network token with a payment card
Use TMS with the REST API or the Business Center to update a customer profile token
Updating an eCheck account number
Use the update subscription service to update an eCheck account number
Use TMS with the REST API or the Business Center to update a customer profile token
Changing a payment method
Use the update subscription service to change a subscription payment method
Use TMS with the REST API or the Business Center to update a customer profile token
Updating subscription payments
Use the update subscription event service to edit a subscription
Edit a subscription plan in the Business Center or amend the plan using the REST API
On-demand transaction
Use the authorization and capture service for an on-demand payment
Use the Virtual Terminal in the
Business Center
Converting a transaction to a subscription
Use the create subscription service to create a subscription ID using an original transaction request ID
Use the Recurring Billing REST API or the
Business Center
 to create a Follow-On subscription using the original transaction ID
Cancelling a subscription
Use the update subscription service to cancel a subscription
Use the REST API or the Business Center to cancel a subscription
Deleting a subscription
Use the delete subscription service to delete a subscription
Use the REST API or the Business Center to cancel a subscription

Comparison of
Business Center
 UI Sections and API Fields

This table lists Recurring Billing elements as they are named in the legacy Recurring Billing system, both in the
Business Center
 and from the perspective of the Simple Order API. Each table row also shows how migration maps the legacy fields to the new system:
  • Corresponding
    Business Center
     elements in the upgraded system are in the 'Business Center Section' and 'Field Name' columns for 'New Recurring Billing' and for 'TMS'.
  • Corresponding API field names are in the 'REST API Field' columns for 'New Recurring Billing' and for 'TMS'.
Comparison of Legacy and New Recurring Billing Data
Legacy Recurring Billing
New Recurring Billing
TMS
Business Center Section
Field Name
Simple Order API Field
Business Center Section
Field Name
REST API Field
Business Center Section
Field Name
REST API Field
Type
Customer Information
City
billTo_city
Payment Details / Billing Address
City
—
Billing Information
City
billTo.locality
Payment Instrument
Company
billTo_company
Payment Details / Billing Address
Company
—
Billing Information
Company
billTo.company
Payment Instrument
—
billTo_companyTaxID
Payment Details / eCheck details / Buyer's details
Company Tax ID
—
Payment Information / Check
Company Tax ID
buyerInformation.companyTaxID
Payment Instrument
Billing Countries
billTo_country
Payment Details / Billing Address
Country
—
Billing Information
Country
billTo.country
Payment Instrument
Customer ID
billTo_customerID
Customer Details
Customer Reference
—
Customer Details
Customer Reference
buyerInformation.merchantCustomerID
Customer Token
Email Address
billTo_email
Payment Details / Billing Address
Email
—
Billing Information
Email
billTo.email
Payment Instrument
First Name
billTo_firstName
Payment Details / Billing Address
First Name
—
Billing Information
First Name
billTo.firstName
Payment Instrument
Last Name
billTo_lastName
Payment Details / Billing Address
Last Name
—
Billing Information
Last Name
billTo.lastName
Payment Instrument
Phone Number
billTo_phoneNumber
Payment Details / Billing Address
Phone
—
Billing Information
Phone Number
billTo.phoneNumber
Payment Instrument
Postal Code
billTo_postalCode
Payment Details / Billing Address
Zip/Postal Code
—
Billing Information
Postal Code
billTo.postalCode
Payment Instrument
State
billTo_state
Payment Details / Billing Address
County/Region
—
Billing Information
County/Region
billTo.administrativeArea
Payment Instrument
Street Address 1
billTo_street1
Payment Details / Billing Address
Address
—
Billing Information
Street Address 1
billTo.address1
Payment Instrument
Street Address 2
billTo_street2
Payment Details / Billing Address
Flat, Suite, Floor, Building, etc.
—
Billing Information
Street Address 2
billTo.address2
Payment Instrument
Legacy Recurring Billing
New Recurring Billing
Token Management Service
Business Center Section
Field Name
Simple Order API Field
Business Center Section
Field Name
REST API Field
Business Center Section
Field Name
REST API Field
Type
Payment Information
Payment Type
subscriptition_paymentMethod
Payment Details
Payment Methods
—
Payment Information
Payment Type
System automatically identifies the payment method based on default payment instrument associated to the customer token specified in the subscription.
Payment Information
Credit Card Number
card_accountNumber
Payment Details / Card Details
Card Number
—
Payment Information / Credit Card
Credit Card Number
card.number
Instrument Identifier
Card Type
card_cardType
Payment Details / Card Details
Card Types
—
Payment Information / Credit Card
Credit Card Type
card.type
Payment Instrument
—
card_cvIndicator
—
—
—
—
—
—
—
Card Verification Number
card_cvNumber
—
—
—
—
—
card.securityCode
Instrument Identifier
Card Expiry Date / Month
card_expirationMonth
Payment Details / Card Details
Expiry Month
—
Payment Information / Credit Card
Expiry Date
card.expirationMonth
Payment Instrument
Card Expiry Date / Year
card_expirationYear
Payment Details / Card Details
Expiry Year
—
Payment Information / Credit Card
Expiry Date
card.expirationYear
Payment Instrument
—
card_issueNumber
—
—
—
—
—
card.issueNumber
Payment Instrument
—
card_startMonth
—
—
—
—
—
card.startMonth
Payment Instrument
—
card_startYear
—
—
—
—
—
card.startYear
Payment Instrument
Date of Birth
billTo_dateOfBirth
Payment Details / eCheck Details / Buyer's Details
Date of Birth
—
Payment Information / Check
Date of Birth
buyerInformation.dateOfBirth
Payment Instrument
Driving Licence Number
billTo_driversLicenseNumber
Payment Details / eCheck Details / Buyer's Details
Driving Licence Number
—
Payment Information / Check
Driving Licence Number
buyerInformation.personalIdentification.id
Payment Instrument
County/Region
billTo_driversLicenseState
Payment Details / eCheck Details / Buyer's Details
Drivining Licence State
—
Payment Information / Check
Driving Licence State
buyerInformation.personalIdentification.issuedBy.administrativeArea
Payment Instrument
Account Number
check_accountNumber
Payment Details / eCheck Details
Account Number
—
Payment Information / Check
Account Number
bankAccount.number
Instrument Identifier
Account Type
check_accountType
Payment Details / eCheck details
Account Type
—
Payment Information / Check
k
Account Type
bankAccount.type
Payment Instrument
Cheque Routing Number
check_bankTransitNumber
Payment Details / eCheck details
Routing Number
—
Payment Information / Check
Routing Number
bankAccount.routingNumber
Instrument Identifier
SEC Code
check_secCode
Payment Details / eCheck details
Authorization Method (SEC Code)
—
Payment Information / Check
SEC Value
processingInformation.bankTransferOptions.SECCode
Payment Instrument
Bill Payment with Visa
recurringSubscriptionInfo_billPayment
—
—
—
—
—
processingInformation.billPaymentProgramEnabled
Payment Instrument
—
paymentNetworkToken_requestorID
—
—
—
—
—
card.tokenizedInformation.requestorID
PaymentInstrument
—
paymentNetworkToken_transactionType
—
—
—
—
—
card.tokenizedInformation.transactionType
PaymentInstrument
Legacy Recurring Billing
New Recurring Billing
Token Management Service
Business Center Section
Field Name
Simple Order API Field
Business Center Section
Field Name
REST API Field
Business Center Section
Field Name
REST API Field
Type
Order Information
Merchant Reference Number
merchantReferenceCode
Subscription Details
Merchant Reference Number
clientReferenceInformation.code
Customer Details
Merchant Reference Number
clientReferenceInformation.code
Customer Token
Merchant Defined Data Field 1
merchantDefinedData_field1
Customer Details
Merchant-Defined 1
—
Merchant-Defined Data Fields
Merchant-Defined 1
merchantDefinedInformation.[name]
Customer Token
Merchant Defined Data Field 2
merchantDefinedData_field2
Customer Details
Merchant-Defined 2
—
Merchant-Defined Data Fields
Merchant-Defined 2
merchantDefinedInformation.[name]
Customer Token
Merchant Defined Data Field 3
merchantDefinedData_field3
Customer Details
Merchant-Defined 3
—
Merchant-Defined Data Fields
Merchant-Defined 3
merchantDefinedInformation.[name]
Customer Token
Merchant Defined Data Field 4
merchantDefinedData_field4
Customer Details
Merchant-Defined 4
—
Merchant-Defined Data Fields
Merchant-Defined 4
merchantDefinedInformation.[name]
Customer Token
Comments
—
—
—
—
—
—
objectInformation.comment
Customer Token
Legacy Recurring Billing
New Recurring Billing
Token Management Service
Business Center Section
Field Name
Simple Order API Field
Business Center Section
Field Name
REST API Field
Business Center Section
Field Name
REST API Field
Type
Shipping Information
City
shipTo_city
Shipping Address Details
City
—
Shipping Information
City
shipTo.locality
Shipping Address
Shipping Countries
shipTo_country
Shipping Address Details
Country
—
Shipping Information
Country
shipTo.country
Shipping Address
First Name
shipTo_firstName
Shipping Address Details
First Name
—
Shipping Information
First Name
shipTo.firstName
Shipping Address
Last Name
shipTo_lastName
Shipping Address Details
Last Name
—
Shipping Information
Last Name
shipTo.lastName
Shipping Address
—
shipTo_phoneNumber
Shipping Address Details
Phone
—
Shipping Information
Phone Number
shipTo.phoneNumber
Shipping Address
Postal Code
shipTo_postalCode
Shipping Address Details
Zip/Postal Code
—
Shipping Information
Postal Code
shipTo.postalCode
Shipping Address
State
shipTo_state
Shipping Address Details
County/Region
—
Shipping Information
County/Region
shipTo.administrativeArea
Shipping Address
Street Address 1
shipTo_street1
Shipping Address Details
Address
—
Shipping Information
Street Address 1
shipTo.address1
Shipping Address
Street Address 2
shipTo_street2
Shipping Address Details
Flat, Suite, Floor, Building, etc.
—
Shipping Information
Street Address 2
shipTo.address2
Shipping Address
Legacy Recurring Billing
New Recurring Billing
Token Management Service
Business Center Section
Field Name
Simple Order API Field
Business Center Section
Field Name
REST API Field
Business Center Section
Field Name
REST API Field
Type
Installment
Title
subscription_title
Subscription Details
Subscription Name
subscriptionInformation.name
—
—
—
—
—
paySubscriptionCreateService_disableAutoAuth
—
—
—
—
—
—
—
—
paySubscriptionCreateService_paymentRequestID
—
—
subscriptionInformation.originalTransactionId
—
—
—
—
Currency
purchaseTotals_currency
Subscription Details / Subscription Billing Plan
Currency
orderInformation.amountDetails.currency
—
—
—
—
Recurring Amount
purchaseTotals_grandTotalAmount
Subscription Details / Subscription Billing Plan
Billing Amount
orderInformation.amountDetails.billingAmount
—
—
—
—
Set-up Fee
recurringSubscriptionInfo_amount
Subscription Details / Subscription Billing Plan
Set-up fee
orderInformation.amountDetails.setupFee
—
—
—
—
Automatically renew this subscription
recurringSubscriptionInfo_automaticRenew
—
—
—
—
—
—
—
Billing Frequency
recurringSubscriptionInfo_frequency
Subscription Details / Subscription Billing Plan
Billing Frequency
planInformation.billingPeriod.length
 +
planInformation.billingPeriod.unit
 If you want to create a token for on-demand payments you need to use TMS API or Payments API with Token Creation.
—
—
—
—
Number of Payments
recurringSubscriptionInfo_numberOfPayments
Subscription Details / Subscription Billing Plan
Billing Cycles
planInformation.billingCycles.total
—
—
—
—
Start Date
recurringSubscriptionInfo_startDate
Subscription Details
Start Date
subscriptionInformation.startDate
—
—
—
—
Ignore Fraud Checks
decisionManager_enabled
Decision Manager
 is not supported when creating a subscription with automatic processing of the initial transaction. If you want to use
Decision Manager
, process the initial transaction yourself and then include its Network Transaction ID in your request in the
subscriptionInformation.originalTransactionId
 field.
—
ccAuthService_commerceIndicator
If you are using the Recurring Billing REST API to create a subscription and you do not process the initial transaction yourself, include the
processingInformation.commerceIndicator
 field. To ensure SCA/3DS compliance, process the initial transaction yourself and then include its Network Transaction ID in your request in the
subscriptionInformation.originalTransactionId
 field.
recurringSubscriptionInfo_subscriptionID
The new Recurring Billing and subscriptions service uses a REST API. Each available action on a subscription has its own dedicated endpoint. To perform an action, specify the subscription ID as a path parameter.
For specific information, see the
Recurring Billing Developer Guide
.
paySubscriptionEventUpdateService_action
paySubscriptionEventUpdateService_event_amount
paySubscriptionEventUpdateService_event_approvedBy
paySubscriptionEventUpdateService_event_number
recurringSubscriptionInfo_numberOfPaymentsToAdd
recurringSubscriptionInfo_status

Upgraded Report Fields

The new Recurring Billing introduces a report that contains information pertinent to the new features and functions. This table compares fields in the legacy Subscription Detail Reports to corresponding fields in the new Recurring Billing Detail Report. Both the legacy report and the new report are accessed through the
Business Center
 UI.
Comparison of Recurring Billing Report Fields
Fields in the Legacy Subscription Detail Reports
Fields in the New Recurring Billing Detail Report
Comment
CustomerAccountID
—
RecurringPaymentEventAmount
—
RecurringPaymentAmount
SubscriptionPaymentAmount
SubscriptionTitle
SubscriptionName
SubscriptionStatus
SubscriptionStatus
SubscriptionPaymentMethod
—
RecurringStartDate
SubscriptionStartDate
RecurringNumberOfPayments
BillingCycles
RecurringFrequency
BillingPeriodUnit , BillingPeriodLength
RecurringApprovalRequired
—
RecurringPaymentEventApprovedBy
—
RecurringAutomaticRenew
—
SetupFee
SetupFee
SetupFeeCurrency
—
SubscriptionType
—
LastSubscriptionStatus
—
NextScheduledDate
SubscriptionNextPaymentDate
EventRetryCount
SubscriptionRetryCount
PaymentsSuccess
—
PaymentSuccessAmount
—
InstallmentSequence
—
InstallmentTotalCount
—
RequestID
RequestID
SubscriptionID
TMSCustomerID
TransactionDate
RequestDate
MerchantRefNo
—
TransRefNo
TransactionReferenceNumber
EcommerceIndicator
ApplicationName
BillToFirstName
BillTo_FirstName
BillToLastName
BillTo_LastName
BillToAddress1
BillTo_Address1
BillToAddress2
BillTo_Address2
BillToCity
BillTo_City
BillToState
BillTo_State
BillToZip
BillTo_Zip
BillToCountry
BillTo_Country
BillToCompanyName
—
BillToEmail
BillTo_Email
ConsumerPhone
BillTo_Phone
IPAddress
—
ShipToFirstName
—
ShipToLastName
—
ShipToAddress1
—
ShipToAddress2
—
ShipToCity
—
ShipToState
—
ShipToZip
—
ShipToCountry
—
ShipToCompanyName
—
CardType
CardType
CustomerCCExpiryMonth
ExpirationMonth
CustomerCCExpiryYear
ExpirationYear
CustomerCCStartMonth
—
CustomerCCStartYear
—
CustomerCCIssueNo
—
CustomerCCAccountSuffix
—
CustomerCCSubTypeDescription
—
CustomerCCRoutingNumber
—
Applications
—
PaymentProcessor
—
CurrencyCode
CurrencyCode
ReasonCode
—
AuthRCode
—
AuthCode
AuthorizationCode
AuthType
—
AuthAVSResults
—
AuthResponseCode
—
AuthCardVerificationResult
—
RCode
—
RFlag
—
RMsg
—
RequestToken
—
MerchantDefinedData1
—
MerchantDefinedData2
—
MerchantDefinedData3
—
MerchantDefinedData4
—
TaxAmount
—
Comments
—
MerchantSecureData1
—
MerchantSecureData2
—
MerchantSecureData3
—
MerchantSecureData4
—
MerchantID
MerchantID
—
PlanCurrency
New field
—
PlanCode
New field
—
PlanName
New field
—
SurchargeAmount
New field
—
SurchargeDescription
New field
—
TMSPaymentInstrumentID
New field
—
TMSShippingID
New field
—
SubscriptionID
New report information
—
SubscriptionCode
New report information
—
AccountSuffix
New report information

Migration Activities

Cybersource
 will prepare you and your data for the migration, and you will update your processes and order management system.
In some cases, the integration method you currently use to create subscriptions cannot be determined. Review all of the action cohorts to decide which one matches your needs and follow that upgrade path.

Preparation

Cybersource
 will inform you about migration timelines and expectations.
Cybersource
 will migrate all legacy Recurring Billing tokens to
TMS
.
Only active subscriptions will migrate to the upgraded Recurring Billing service. Canceled, On hold, and Completed subscriptions will not migrate.
Cybersource
 will provide access to those subscriptions through the
Business Center
, the REST API, and
TMS
.
Cybersource
 offers training for the migration to the upgraded Recurring Billing.
After migrating to the new Recurring Billing platform, you cannot access historical data about the legacy subscriptions.
When migration begins, your current integration will fail. Prepare changes on your site in advance. Before migration, create customer tokens. After migration, create subscriptions associated with the tokens.

Prerequisites

Before you begin using the upgraded Recurring Billing service, make sure that the prerequisites are completed:
  1. Understand how you currently use the legacy Recurring Billing service.
  2. Understand the actions required by
    Cybersource
     and, if relevant, your reseller.
  3. Integrate to the upgraded Recurring Billing using the REST API.
  4. Integrate to Payments using the REST API.
  5. Become familiar with the
    Business Center
     interface for the upgraded Recurring Billing service.
  6. Contact
    Cybersource
     customer support to begin migrating your legacy Recurring Billing data (tokens and subscriptions) to the new Recurring Billing service.
Cybersource
 migrates all active legacy Recurring Billing tokens to
TMS
. Canceled, On Hold, or Completed subscriptions are not included in the migration. After the migration to the new Recurring Billing platform, historical data about the subscriptions is no longer available.
Be sure to look at the migration TEST checklist to ensure that all your pre/post payment processing processes work with the new system

Timeline

Migrating from the legacy Recurring Billing to the new Recurring Billing service takes a few weeks.

Figure:

Recurring Billing Migration Timeline
Sample timeline that lists the Recurring Billing upgrade activities and estimated time for each action.

Test Checklist Recommendations

After
Cybersource
 notifies you that your upgrade and migration is complete in the TEST or preproduction environment, verify that your processes outside of
Cybersource
 systems remain unaffected.
Your subscriptions transitioned from the legacy system to the new system
  • Spot check that subscription states transitioned correctly.
  • Spot check that the subscription amounts transitioned correctly.
  • Confirm that the Next Billing dates of subscriptions transitioned correctly.
Subscription creation and management
  • Create a test subscription from a token. Additional information is available in Stabilization Period.
  • Update details of an existing test subscription.
  • Cancel a subscription.
You have a thorough understanding of your systems
  • Existing configuration in the legacy system
  • Integration between your
    Cybersource
     systems and external systems
  • Connections to other systems
  • Data flow between systems

Updating Your Processes and Order Management System

You must update your processes and order management system in order to upgrade to the new Recurring Billing service.
Merchants are divided into six groups (action cohorts) according to the legacy Recurring Billing integration method. Each of the six groups has its own set of upgrade steps:

Business Center
 User Interface

If you use the
Business Center
 Recurring Billing service to create and maintain subscriptions, you can continue to do so after your existing subscription tokens are migrated to the upgraded Recurring Billing and
TMS
 in the
Business Center
. No API integration updates are required.
To prepare for your upgrade:
  1. Become familiar with the new Recurring Billing service user interface in the
    Business Center
    .
  2. Contact
    Cybersource
     client services to start the migration.

Figure:

Upgraded Recurring Billing User Interface
Upgraded Recurring Billing user interface for creating a new subscription or maintaining an existing subscription

Related Information

Business Center
 Virtual Terminal

If you use the Virtual Terminal to create tokens during one-time payments and to create and maintain subscriptions, you can continue to do so after your existing subscription tokens are migrated to the upgraded Recurring Billing service and
TMS
 in the
Business Center
. No API integration updates are required.
To prepare for the migration:
  1. Become familiar with the new Recurring Billing service user interface in the
    Business Center
    .
  2. Become familiar with the new Recurring Billing two-step process for creating subscriptions.
  3. Contact
    Cybersource
     client services to start the migration.

Related Information

Business Center
 Transaction Management

If you use
Business Center
 Transaction Management to create subscriptions, select Action and then Create Subscription on the Transaction Details screen. The system will direct you to the new Recurring Billing service user interface in the
Business Center
.
Follow these steps to prepare for the migration:
  1. Become familiar with the new Recurring Billing service user interface in the
    Business Center
    .
  2. Contact
    Cybersource
     client services to start the migration.
This image shows the upgraded Recurring Billing user interface for creating a new subscription or maintaining an existing subscription.

Figure:

Example Upgraded Manage Subscription User Interface
Upgraded Recurring Billing user interface

Related Information

SCMP API and Simple Order API

If you use the SCMP API or Simple Order API to create and manage subscriptions, you must migrate to the Recurring Billing service that uses the REST API.
After your existing subscription tokens are migrated to the upgraded Recurring Billing and
TMS
 in the
Business Center
, you can create and manage subscriptions there.
To prepare for the migration:
  1. Integrate to the new Recurring Billing service that uses the REST API.
  2. Become familiar with the new Recurring Billing service user interface in the
    Business Center
    .
  3. Contact
    Cybersource
     client services to start the migration.

Related Information

Secure Acceptance
Hosted Checkout Integration
 and
Checkout API

After migration, you can no longer create subscriptions using
Hosted Checkout Integration
 or
Checkout API
. You must migrate to these services in this order:
  1. Unified Checkout, to collect customer information.
  2. TMS
     that uses the REST API, to create customer tokens from transient tokens.
  3. Recurring Billing service that uses the REST API.
During the transitional phase, you can still use the system to validate and create a payment token. This process will replace the previous steps 1 and 2. To create a token in this way, change the
recurring_frequency
 request field value to
on-demand
. Also, remove any other subscription-related fields (
recurring_*
) from the request.
After your existing subscription tokens are migrated to the upgraded Recurring Billing service and
TMS
 in the
Business Center
, you can create and manage subscriptions there.
To prepare for the migration:
  1. Integrate to Unified Checkout to collect the payment instrument.
  2. Integrate to Payments REST API to create the Customer Token from the Transient Token.
  3. Integrate to the new Recurring Billing service that uses the REST API.
  4. Become familiar with the new Recurring Billing service user interface in the
    Business Center
    .
  5. Contact
    Cybersource
     client services to start the migration.

Related Information

Aura and Cold Fusion

If you use the Aura process or Cold Fusion to create and manage subscriptions, you must migrate to Recurring Billing service that uses the REST API.
After your existing subscription tokens are migrated to the upgraded Recurring Billing and
TMS
 in the
Business Center
, you can create and manage subscriptions there.
Follow these steps to prepare for the migration:
  1. Integrate to the new Recurring Billing service that uses the REST API.
  2. Become familiar with the new Recurring Billing service user interface in the
    Business Center
    .
  3. Contact
    Cybersource
     client services to start the migration.

Post-Migration Information

This section describes changes to how you use the new Recurring Billing service compared to how you used the legacy system.

Creating a Subscription Using the API

To create a subscription, you need a customer token. Use the Create a Subscription in the
Cybersource
 Developer Center to create a test REST API request message.
After migration, a customer token is created in
TMS
 for each active subscription in the legacy system. This token has the same ID as the subscription. Use this token to create another subscription for the same customer.
To create a subscription for a new customer, you must generate a new customer token. To capture payment card data for future use, validate the payment card account by one of these methods:
  • Use a payment for a zero amount.
  • If your processor does not support zero amount, use a minimal amount.
Enable the Data Enrichment for Card Verification feature to automatically choose the minimal auth amount. Contact Customer Support for more details.
The best way to perform this transaction is with the REST API. For more information, see the Create a Customer Token with Validated Payment Details in the
Token Management Service Developer Guide
.
To create tokens using Secure Acceptance Checkout or the SCMP or Simple Order API:
  1. Set the value of the
    recurring_frequency
     request field to
    on-demand
  2. Remove any other subscription-related fields (field names that begin with
    recurring_*
    ) from the request message.
Your current integration will fail after migration begins. Prepare changes on your site in advance. Before migration, create tokens as described above. After migration, create subscriptions for them.
To create a subscription, use this data from the payment response:
Customer ID:
  • Payments REST API:
    tokenInformation.customer.id
  • Secure Acceptance Checkout:
    payment_token
  • SCMP API:
    pay_subscription_create_subscription_id
  • Simple Order API:
    paySubscriptionCreateReply_subscriptionID
Original Transaction ID:
  • Payments REST API:
    processorInformation.networkTransactionId
  • Secure Acceptance Checkout:
    payment_network_transaction_id
  • SCMP API:
    auth_payment_network_transaction_id
  • Simple Order API:
    ccAuthReply_paymentNetworkTransactionID
Original Transaction Authorized Amount
 ()Required only for Diners and Discover cards)
  • Payments REST API:
    orderInformation.amountDetails.authorizedAmount
  • Secure Acceptance Checkout:
    auth_amount
  • SCMP API:
    auth_auth_amount
  • Simple Order API:
    ccAuthReply_amount
For more information about creating a subscription, see the Create a Subscription section in the
Recurring Billing User Guide
.

Customer Notifications

The new Recurring Billing supports two customer notification methods: email and webhooks. You can configure one method or you can confiture both notification methods.

Email Notifications

Legacy Recurring Billing does not send customer notifications by email. The new Recurring Billing automatically sends email notifications to customers.

Webhook Notifications

Cybersource
 offers the Webhooks REST API. You can use it to subscribe to a webhook for a supported system event type. Designate a URL to receive notifications for that event. Webhooks let you to respond to events with code.
Create and manage webhook subscriptions for the Recurring Billing event types listed in the table. In the webhooks request message, set the
productId
 API field to
recurringBilling
 and set the
eventTypes
 API field to one of the values listed in the Event Type column of the table.
Recurring Billing Event Notifications
Product ID
Event Type
Description
recurringBilling
rbs.subscriptions.charge.failed
Notifies the customer of a recurring payment failure.
rbs.subscriptions.charge.pre-notified
Notifies the customer of an upcoming recurring payment.
rbs.subscriptions.charge.created
Notifies the customer of a successful recurring payment.
To customize your notifications, use webhooks. For details, go to the
Cybersource
 API Developer Center. In the left navigation pane, select
Platform Services
 >
Webhooks
 >
Create Webhook Security Keys
. Use the webhook request builder and live console to test example REST API requests.

Migrated Subscription Payment History

In the new Recurring Billing system, the Subscription Details section of the
Business Center
 shows the payment history associated with the subscription and the original start date and the billing cycles completed on the legacy Recurring Billing system.
Example subscription payment history in the
Business Center
:
Screen capture example of business center payment history
Example subscription details in the
Business Center
:
Screen capture example of business center subscription details

Subscription Details

These values in the Subscription Details screen identify the subscription:
Subscription Code
A unique code generated by the system if there is no input incremented by a number for every new subscription created. The code is a string of up to 10 numeric or alphanumeric characters and can include dash (-) and dot (.) characters.
Subscription Name
Any name to uniquely identify a subscription.
Subscription ID
A system-generated identifier associated with the customer token.
A subscription ID in the new system is not the the same as subscription ID in the legacy system. In the new system, the legacy Subscription ID is the Token ID.
Merchant Reference Number
A merchant-specified text string that uniquely identifies the merchant. This identifier is used in the new system in the same way as it was used in the legacy system.

Stabilization Period

During the first two weeks after you migrate from legacy Recurring Billing to the new Recurring Billing, these Recurring Billing functions are limited:
Creating a Subscription with a New Customer Flow Using the Business Center
During the payment synchronization period, you cannot use the new customer flow.
This image is an example of the Select Customer Type dialog:

Figure:

Select Customer Type Dialog
Screen capture of the Select Customer Type dialog in Manage Subsvcriptions

Creating a Subscription with a New Customer Flow Using the
Business Center

During the payment synchronization period, you cannot use the new customer flow.
Example subscription payment history in the
Business Center
:
Screen capture example of business center manage subscriptions
To create a subscription for a new customer without saved payment information, use the
TMS
 interface in the
Cybersource
Business Center
:
  1. On the left navigation panel, click
    Token Management
     and
    Tokens
    . The Tokens screen appears. Screen capture example of business center tms tokens
  2. Click
    New Profile
    . Screen capture example of business center tms tokens add profile
  3. In the Add Profile section, enter the merchant reference number, payment information, and shipping address details.
  4. If you want the system to perform a zero authorization, either leave the Profile Information field empty or enter your own Amount and Set Up Fee.
  5. Click
    Save
    . A message at the top of the screen confirms that the profile is created and that migration is in progress. Screen capture example of business center tms tokens add profile success
  6. Wait for the token to be being added to
    TMS
    . When the token is added, the screen refreshes and shows detailed information about the new token. Screen capture example of business center tms tokens profile success details
Use the existing customer flow with the token you just created. For more information, see the Creating a Subscription with an Existing Customer Token section in the
Recurring Billing Developer Guide
.
To apply the token to an existing customer in the Business Center:
  1. On the left navigation panel, click
    Recurring Billing
     and
    Create Subscription
    .
  2. In the Manage Subscriptions screen, click
    Create Subscription
    . Screen capture example of business center rb cre subs
  3. Select
    Existing Customer
    , and click
    Continue
    . Screen capture example of business center rb cre subs existing cust
  4. To find the customer token you just created, enter the customer's first and last name,
Two weeks after your migration is complete, you can use all features in the
Business Center
 to create subscriptions. For more information, see the Creating a Subscription with a New Customer Token section in the
Recurring Billing User Guide
.

Subscription Name Changes

For improved security, the migration process might apply additional restrictions or validations to legacy subscription names. If a legacy subscription name contains special characters not permitted by the new service, the migration process replaces those characters with a dash ('-'), which is allowed.
For example, any underscore ('_') in a legacy subscription name is replaced with a dash ('-').
When filtering and searching for subscription names, remember that legacy subscriiption names may have been modified during the migration to the new Recurring Billing service.
These characters are allowed:
  • Lowercase letters: a-z
  • Uppercase letters: A-Z
  • Digits: 0-9
  • Special characters: ? . , $ / @ & ! : -
  • Space
These special characters are not allowed:
  • # (hash)
  • % (percent)
  • ^ (caret)
  • * (asterisk)
  • ( (left parenthesis)
  • ) (right parenthesis)
  • _ (underscore)
  • + (plus)
  • = (equals)
  • { (left curly brace)
  • } (right curly brace)
  • [ (left square bracket)
  • ] (right square bracket)
  • | (vertical bar)
  • \ (backslash)
  • ; (semicolon)
  • ' (single quote)
  • " (double quote)
  • < (less than)
  • > (greater than)
  • ~ (tilde)
  • ` (backtick)
These non-ASCII characters are not allowed:
  • é (accented e)
  • ç (cedilla)
  • ü (umlaut u)
  • ñ (tilde n)
  • Ω (Greek Omega)
Emojis are not allowed. Examples:
  • smiling face
  • rocket
  • light bulb
Control characters are not allowed:
  • \t
     (tab)
  • \n
     (newline)
  • \r
     (carriage return)

Business Center
 Permissions

The upgraded Recurring Billing service requires you to configure role permissions.
  1. To configure role permissions
  2. In the
    Business Center
     left navigation panel, click the
    Account Management
     icon and
    Roles
    .
  3. Expand the Token Management Permissions list.

    ADDITIONAL INFORMATION

    Screen capture example of business center acct mgmt roles tms perms
  4. Select the name of each role that you want to add.
  5. Expand the Subscriptions and Recurring Billing Permissions list.

    ADDITIONAL INFORMATION

    Screen capture example of business center acct mgmt roles rbs perms
  6. Select the name of each role that you want to add.
  7. Click
    Save
    .

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

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.