This section describes how to use this guide and where to find further 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.
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 PCI DSS compliance scope.
The upgraded Recurring Billing product benefits merchants and customers in these ways:
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 your costs and reducing waste with streamlined payment processes.
Keeps payment information secure by using tokens.
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.
This figure illustrates the components of automatic recurring payments.
Figure:
Automating Recurring Payments
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.
You can still create ad-hoc subscriptions if preferred, but these need 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 re-use. You can assign these plans to multiple
subscriptions.
One-time plans
: created specifically for a single subscription and
not stored for re-use nor 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 set-up 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, you can take these actions:
Quickly create a subscription defining the billing schedule with an existing
plan, or you can 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.
Upgraded Report Fields
The new Recurring Billing report contains the fields in this table:
Recurring Billing Report Fields
AccountSuffix
BillTo_State
SubscriptionID
ApplicationName
BillTo_Zip
SubscriptionName
AuthorizationCode
CardType
SubscriptionNextPaymentDate
BillingCycles
CurrencyCode
SubscriptionPaymentAmount
BillingPeriodLength
ExpirationMonth
SubscriptionRetryCount
BillingPeriodUnit
ExpirationYear
SubscriptionStartDate
BillTo_Address1
MerchantID
SubscriptionStatus
BillTo_Address2
PlanCode
SurchargeAmount
BillTo_City
PlanCurrency
SurchargeDescription
BillTo_Country
PlanName
TMSCustomerID
BillTo_Email
RequestDate
TMSPaymentInstrumentID
BillTo_FirstName
RequestID
TMSShippingID
BillTo_LastName
SetupFee
TransactionReferenceNumber
BillTo_Phone
SubscriptionCode
—
Business Center Permissions
The upgraded Recurring Billing service requires you to configure role permissions.
Follow these steps to configure role permissions:
In the
Business Center
left navigation panel,
click the
Account Management
icon
(
).
Click
Roles
. The Roles page appears.
Expand the Token Management Permissions list.
Check the box next to the name of each role that you want to add.
Expand the Subscriptions and Recurring Billing Permissions list.
Check the box next to the name of each role that you want to add.
Click
Save
.
Customer Notifications
The new Recurring Billing supports two customer notification methods: email and
webhooks.
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 respond to events with code.
Create and manage webhook subscriptions for Recurring Billing event types listed in
the table. In the webhooks request message, set the
productId
API
field to
recurringBilling
. Then, set the
eventTypes
API field to one of the values in the Event Type
column of the table.
Recurring Billing Event Notifications
Product ID
Event Types
Description
recurringBilling
rbs.subscriptions.charge.failed
Notifies you of a recurring payment failure.
rbs.subscriptions.charge.pre-notified
Notifies you of an upcoming recurring payment.
rbs.subscriptions.charge.created
Notifies you of successful recurring payment.
To customize your notifications, use webhooks. For more details, see the
Cybersource
API Developer Center Create Webhook Security Keys to create a
webhook test API request in the live, test console. You can test example requests
for different payment processors.
Post-Migration Information
This section describes changes to how you use the new Recurring Billing service as
compared to how you used the legacy system.
Creating a Subscription using the API
To create a subscription, you need a customer token. For more details, see to the
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. You can 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.
When capturing payment card data for future use, validate the payment card account
by:
Using a payment for a zero amount, or
If your processor does not support zero amount, using a minimal amount.
Enable the Data Enrichment for Card Verification feature to automatically choose the
minimal auth amount. Contact Customer Support for more details.
If using Secure Acceptance Checkout or SCMP/SOAP API to create tokens, follow these
steps:
Change the request field
recurring_frequency
value to
on-demand
.
Remove any other subscription-related fields (
recurring_*
) from
the request.
Your current integration will fail once migration starts. 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
SOAP 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
SOAP 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
SOAP API:
ccAuthReply_amount
For more details on creating a subscription, see to the Create a Subscription section in the
Recurring Billing User Guide
.
Stabilization Period
For 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.
To create a subscription for a new customer (without saved payment information), use
the
Token Management Service
interface in the
Cybersource
Business Center
.
Follow these steps to create a customer token in the
Business Center
:
On the left navigation panel, click
Token
Management
.
Click
Tokens
. The Tokens page appears.
Click
New Profile
.
Enter the
Merchant Reference Number
,
Payment
, and
Shipping Address
details.
You can leave the
Profile Information
field blank for the
system to perform a zero authorization. Alternatively, enter your own
Amount and Set Up Fee
.
Click
Save
.
A message at the top of the screen confirms that the profile is created and
migration is in progress. The token is being added to TMS, so wait a
moment.
The screen refreshes, and you see the details of the new token you just created.
For improved security, additional restrictions or validations may be applied 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 subscription names may have been modified during the
migration to the new Recurring Billing.
These characters are allowed:
Lowercase letters: a-z
Uppercase letters: A-Z
Digits: 0-9
Special characters: ? . , $ / @ & ! : -
Space
These characters are restricted:
Special Characters:
#
(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)
Non-ASCII Characters:
é
(accented e)
ç
(cedilla)
ü
(umlaut u)
ñ
(tilde n)
Ω
(Greek Omega)
Emojis:
😊 (smiling face)
🚀 (rocket)
💡 (light bulb)
Control Characters:
\t
(tab)
\n
(newline)
\r
(carriage return)
Prerequisites
Before you begin using the upgraded Recurring Billing service, make sure that the
prerequisites are completed:
Understand how you currently use the legacy Recurring Billing service.
Understand the actions required by
Cybersource
and, if relevant,
your reseller.
Integrate to the upgraded Recurring Billing using the REST API.
Integrate to Payments using the REST API.
Become familiar with the
Business Center
interface for the upgraded
Recurring Billing service.
Contact
Cybersource
customer support to begin migrating your
legacy Recurring Billing data (tokens and subscriptions) to the new Recurring
Billing service.
Here is the revised text for clarity:
Cybersource
will migrate all legacy Recurring Billing tokens to
TMS. Only active subscriptions will be migrated. Canceled, On Hold, or Completed
subscriptions will not be included. After the migration to the new Recurring Billing
Platform, historical data about the subscriptions will not be available.
Timeline
Migrating from the legacy Recurring Billing to the new
Recurring Billing service takes a few weeks. This timeline example shows activities and
the estimated amount of time for completion.
Figure:
Timeline Example
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.
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 set-up fee.
Use the create subscription service to create a subscription ID
and use the authorization and capture services to charge the set-up
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.
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, we cannot decide the integration method you currently
use to create subscriptions. 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 these through the
Business Center
, the REST API, and
TMS
.
Cybersource
will offer training for the migration to the upgraded
Recurring Billing.
No historical data about
the subscriptions will be available after the migration to the new Recurring Billing
Platform.
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:
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.
Follow these steps to prepare for your upgrade:
Become familiar with the new Recurring Billing service user interface in the
Business Center
.
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.
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.
Follow these steps to prepare for the migration:
Become familiar with the new Recurring Billing service user interface in the
Business Center
.
Become familiar with the new Recurring Billing two-step process for creating
subscriptions.
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:
Become familiar with the new Recurring Billing service user interface in the
Business Center
.
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
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.
Follow these steps to prepare for the migration:
Integrate to the new Recurring Billing service that uses the REST API.
Become familiar with the new Recurring Billing service user interface in the
After migration, you can no longer create subscriptions
using
Hosted Checkout Integration
or
Checkout API
. You must migrate
to these services in this order:
Unified Checkout, to collect customer information.
TMS
that uses the REST API, to create customer tokens
from transient tokens.
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.
Follow these steps to prepare for the migration:
Integrate to Unified Checkout to collect the payment instrument.
Integrate to Payments REST API to create the Customer Token from the Transient
Token.
Integrate to the new Recurring Billing service that uses the REST API.
Become familiar with the new Recurring Billing service user interface in the
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.
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.
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.
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.
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.
).
