This revision contains only editorial changes and no technical updates.
Introduction to Recurring Billing
This guide explains how to integrate to the Recurring Billing REST API.
The Recurring Billing service enables you to create and manage payment plans
and subscriptions for recurring payment schedules. It automates the storage and handling of
your customer’s payment information and personal data within secure Visa data centers in
compliance with credentials-on-file (COF) best practices. Storage risks and the PCI DSS scope
are reduced through the use of
the
Token Management Service
(
TMS
)
.
Cybersource
Recurring Billing consists of these three
elements:
Plan:
Stores the billing schedule.
Subscription:
Combines the token and plan and defines the subscription start
date, name, and description.
Token:
Stores customer billing, shipping, and payment details.
Recurring payments can also be handled with the payments API.
Merchant-initiated transactions (MITs) are part of the payments API.
For more information on recurring payments using MITs,
see the Recurring Payments section in the
Do not use this document if you are using the payments API to process
recurring payments. When using payments API for MITs, you must capture and store the
customer's payment credentials manually. Also, you send the payments API MIT requests to
different endpoints than you send the recurring billing requests.
The Recurring Billing service is available for the
When your system is REST compliant, you can test your Recurring Billing integration by
sending requests to the
Cybersource
test server.
Account Validation (Pre-Authorization)
When you capture payment card data for future use,
Cybersource
recommends
that you validate the payment card account to ensure that the account number entered is
an active, valid account. You can also use the Address Verification Service (AVS), the
Card Verification Number (CVN), and expiration date validation. To validate the account,
initiate a zero-amount authorization transaction.
To verify that
your processor supports zero-amount authorization, see the zero-amount authorization
information in the
A plan defines the payment amount and billing schedule for recurring or subscription
payments.
After you create a plan, you can assign it to multiple subscriptions and manage changes for
multiple subscriptions.
IMPORTANT
Installment based plans are currently not supported.
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.
Both plan types have two billing cycle options. Choose one of these billing cycles when
defining the number of recurring payments to be made:
Bill indefinitely
Fixed number of payments
Bill Indefinitely
This option has a fixed payment amount and a payment schedule with no end date. This option
comprises these elements:
Plan code
Plan name
Plan description (optional)
Billing frequency
Currency
Payment amount
Set-up fee (optional)
IMPORTANT
One-time plans do not include a plan code, plan name, or plan
description.
Fixed Number of Payments
This option has a fixed payment amount, a payment schedule, and a fixed number of
payments. This option comprises these elements:
Plan code
Plan name
Plan description (optional)
Billing frequency
Currency
Payment amount
Number of billing cycles
Set-up fee (optional)
IMPORTANT
One-time plans do not include a plan code, plan name, or plan
description.
Plan Statuses
A plan has one of these statuses:
Figure:
Plan Status Flow
Draft
: a draft plan cannot be assigned to new or existing subscriptions.
Draft plans can be changed to active or deleted.
Active
: an active plan can be used when you create a new subscription or
assigned to an existing subscription. Active plans can be changed to inactive or
deleted.
Inactive
: subscriptions that are assigned to an inactive plan are billed
until the subscription is completed or canceled. You cannot use inactive plans to
create new subscriptions, nor switch subscriptions to an inactive plan. Inactive
plans can be changed to active.
Deleted
: a deleted plan is removed from the system.
IMPORTANT
You cannot amend an inactive plan. To make changes, move the plan
to active or draft status.
IMPORTANT
You can delete a standard plan that has a draft status or
has an active or inactive status and has never been assigned to any subscriptions.
Assigning a Plan Code
When you create a standard plan, you can choose to supply a plan code that relates to your business and is used for reference to the plan. This code can be numeric or alphanumeric with dash (-) and dot (.) characters, and up to 10 characters long.
If no plan code is assigned, the system automatically assigns a system-generated value.
Creating a Plan
Create a plan to define the billing schedule, which includes the amount, frequency,
and billing cycles for a subscription. The interval between subscription payments cannot
exceed 12 months.
IMPORTANT
If a subscription is to use a one-time plan
instead of a standard plan, you create the one-time plan when you create the
subscription. The plan details are embedded in the subscription
request.
When you create a plan, the system assigns an ID to the plan. Use
the plan ID to request these actions:
Creating a subscription
Retrieving a plan
Amending a plan
Activating a plan
Deactivating a plan
Deleting a plan
Follow these steps to create a plan:
Send the request to the recurring billing endpoint:
Production:
POST https://api.cybersource.com/rbs/v1/plans
Test:
POST https://apitest.cybersource.test.com/rbs/v1/plans
Check the response message to make sure that the request was
successful. A 200-level HTTP response code indicates success.
When you specify your own plan codes, you can request the next consecutive alphabetical or numeric plan code based on the last plan code that you specified. For example, if the last plan code that you specified was
Plan104
, the system returns the code
Plan105
.
Follow these steps to retrieve a plan code:
Send the request to the Recurring Billing endpoint:
Production:
GET
https://api.cybersource.com/rbs/v1/plans/code
Test:
GET
https://apitest.cybersource.test.com/rbs/v1/plans/code
Check the response message to make sure that the request was
successful. A 200-level HTTP response code indicates success.
{
"status": "INVALID_REQUEST",
"reason": "INVALID_DATA",
"message": "One or more fields in the request contains invalid data.",
"details": [
{
"field": "planInformation.status",
"reason": "INVALID_DATA"
}
]
}
Deleting a Plan
You can delete a standard plan that has a draft status. You can also delete a plan
that has an active or inactive status and has never been assigned to any subscriptions.
Follow these steps to delete a plan:
In the endpoint path, include the plan ID that you received when you retrieved a
list of plans.
Send the request to the Recurring Billing endpoint:
{
"status": "NOT_FOUND",
"reason": "NOT_FOUND",
"message": "One or more fields in the request contains invalid data.",
"details": [
{
"field": "subscriptionInformation.planId",
"reason": "INVALID_DATA"
}
]
}
Subscriptions
Subscriptions store customer details by using a Token Management Service (TMS) token. You
must have an assigned payment plan. Subscriptions consist of this information:
Subscription code
Subscription name
Start date
Token Management Service (TMS) token
Plan: standard or one-time
Subscriptions can be updated, activated, suspended, or canceled.
Subscription Prerequisites
Before creating a subscription, you must create a customer token.
Authorized amount for the transaction initializing the subscription. Required only for Diners or Discover cards.
Subscription Statuses
This diagram illustrates the statuses of a subscription from creation to completion.
Figure:
Subscription Flow
A subscription has one of these statuses:
Pending
The first payment is scheduled, or the subscription is in transition to another
state.
Active
The subscription is currently in use. It is set with a payment instrument, and a
payment is scheduled at a pre-determined frequency that you agreed upon with
your customer.
Delinquent
A scheduled payment was declined.
The system automatically retries the payment a number of times. If the payment
succeeds, the system automatically moves the subscription back to the
active
state. Otherwise, if the automated retry logic fails to obtain
a successful payment, the system automatically moves the subscription to the
suspended
state.
Suspended
The automated retry logic failed to obtain successful payment,
or you have explicitly suspended the subscription.
In order to resume a suspended subscription for the next billing cycle, choose one of these options:
Collect a different payment method from your customer and then
reactivate the subscription.
Cancel the subscription and create a new subscription for your customer.
Cancelled
You have explicitly cancelled the subscription and it cannot be reactivated.
You might cancel an active or pending subscription when you and the customer agree to end the subscription.
You might choose to cancel a delinquent subscription rather than wait for the automatic retry logic to proceed.
You might cancel a suspended subscription if the customer does not have an acceptable alternate payment method.
IMPORTANT
You cannot cancel a subscription within 10 minutes before or after a payment begins processing.
Completed
All scheduled payments were made.
This is the state of a subscription that ends with all scheduled payments successfully completed.
This state applies to subscriptions set up with a scheduled end date.
IMPORTANT
You cannot reactivate a completed subscription.
Zero-Amount Authorizations
When you create a subscription before the subscription start date,
Cybersource
verifies the account with a zero-amount authorization to ensure
that the stored card details are valid.
When you create a subscription on the subscription start date,
Cybersource
does not perform a zero-amount authorization because the first recurring payment is
processed immediately.
IMPORTANT
Deprecated flow:
This behavior occurs only when you do not provide the value for
subscriptionInformation.originalTransactionId
and application performs the initial
authorization. This flow does not ensure Strong Customer Authentication (SCA)
compliance.
Assigning a Subscription Code
When you create a subscription, you can supply a subscription code that relates to your business and that is used for reference to the subscription. This code can be numeric or alphanumeric with dash (-) and dot (.) characters and can be up to 10 characters long.
If you do not supply a subscription code, the recurring billing system automatically
assigns a code.
Subscription ID
When you create a subscription, the system assigns an ID to the subscription that you can
use for these actions:
Retrieving a subscription
Amending a subscription
Canceling a subscription
Re-activating a subscription
Suspending a subscription
IMPORTANT
The interval between subscription payments cannot exceed 12
months.
Overriding a Plan
When assigning a plan to a subscription or amending a subscription, you can amend
standard plan details for individual subscriptions. For example, such changes might
include an amendment to the billing amount, plan duration (billing cycles)
amendment.
IMPORTANT
Plan overrides apply only to the individual
subscription and do not amend the standard plan details used for other subscriptions.
Creating a Subscription with an Existing Plan
You can shows how to create a subscription with a standard plan.
The start date must be in coordinated universal time (UTC) in this format:
YYYY-MM-DDThh:mm:ssZ. The T separates the date and the time. The Z indicates UTC. For example,
2023-08-11T22:47:57Z
indicates August 11, 2023, at 22:47:57 (10:47:57PM).
For subscriptions created on the start date, set the time to the current
time and day in your time zone.
Basic Steps
Follow these steps to create a subscription:
Create the request with the required API fields.
Send the request to one of these endpoints:
Production:
POST
https://api.cybersource.com/rbs/v1/subscriptions
Test:
POST
https://apitest.cybersource.test.com/rbs/v1/subscriptions
Verify the response messages to make sure that the request was successful. A
200-level HTTP response code indicates success.
{
"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
You can create a subscription with a plan overrides.
The start date must be in coordinated universal time (UTC) in this format:
YYYY-MM-DDThh:mm:ssZ. The T separates the date and the time. The Z indicates UTC. For example,
2023-08-11T22:47:57Z
indicates August 11, 2023, at 22:47:57 (10:47:57PM).
For subscriptions created on the start date, set the time to the current
time and day in your time zone.
Fields Specific to This Use Case
These REST API request fields and values are specific to this use case:
subscriptionInformation.name
subscriptionInformation.planId
subscriptionInformation.startDate
subscriptionInformation.originalTransactionId
These REST API request fields are optional:
orderInformation.amountDetails.billingAmount
orderInformation.amountDetails.currency
orderInformation.amountDetails.setupFee
planInformation.billingPeriod.length
planInformation.billingPeriod.unit
planInformation.billingCycles.total
Basic Steps
Follow these steps to create a subscription:
Create the request with the required API fields.
Send the request to one of these endpoints:
Production:
POST
https://api.cybersource.com/rbs/v1/subscriptions
Test:
POST
https://apitest.cybersource.test.com/rbs/v1/subscriptions
Verify the response messages to make sure that the request was successful. A
200-level HTTP response code indicates success.
{
"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"
}
]
}
Creating a Fully Customized Subscription with a One-Time Plan
You can create a subscription with a one-time plan.
The start date must be in coordinated universal time (UTC) in
this format:
YYYY-MM-DDThh:mm:ssZ
. The T separates the date and the
time. The
Z
indicates UTC. For example,
2023-08-11T22:47:57Z
indicates August 11, 2023, at 22:47:57
(10:47:57PM).
For subscriptions created on the start date, set the time to
the current time and day in your time zone.
Fields Specific to This Use Case
These REST API request fields and values are specific to this use case:
orderInformation.amountDetails.billingAmount
orderInformation.amountDetails.currency
orderInformation.amountDetails.setupFee
planInformation.billingCycles.total
planInformation.billingPeriod.length
planInformation.billingPeriod.unit
subscriptionInformation.startDate
Basic Steps
Follow these steps to create a subscription:
Create the request with the required API fields.
Send the request to one of these endpoints:
Production:
POST
https://api.cybersource.com/rbs/v1/subscriptions
Test:
POST
https://apitest.cybersource.test.com/rbs/v1/subscriptions
Verify the response messages to make sure that the request was successful. A
200-level HTTP response code indicates success.
{
"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 Follow on Subscription from an Existing Transaction
You can create a subscription using an existing successful transaction by specifying its
request ID in the path. This method eliminates the need to provide a customer
token.
You can use an existing or one-time plan.
The start date must be in coordinated universal time (UTC) in this format:
YYYY-MM-DDThh:mm:ssZ. The T separates the date and the time. The Z indicates UTC.
For example,
2023-08-11T22:47:57Z
indicates August 11, 2023, at
22:47:57 (10:47:57 p.m.).
For subscriptions created on the start date, set the
time to the current time and day in your time zone.
Follow these steps to create a subscription:
Create the request with the required API fields.
Send the request to one of these endpoints:
Production:
POST
https://api.cybersource.com/rbs/v1/subscriptions/follow-ons/{requestId}
Test:
POST
https://apitest.cybersource.test.com/rbs/v1/subscriptions/follow-ons/{requestId}
Verify the responses to make sure that the request was successful. A 200-level
HTTP response code indicates success.
Retrieving Details for Follow on Subscription Creation Based on Existing
Transaction
You can retrieve details from the specified transaction request ID that you can
include to create a new subscription. You will be able to verify the payment
instrument, billing, and shipping address information from an existing transaction
before creating a new subscription.
Follow these steps to retrieve details on a subscription:
In the endpoint path, include the request ID of an existing transaction.
Send the request message to one of these endpoints:
Production:
POST
https://api.cybersource.com/rbs/v1/subscriptions/follow-ons/{requestId}
Test:
POST
https://apitest.cybersource.test.com/rbs/v1/subscriptions/follow-ons/{requestId}
Verify the response messages to make sure that the request was successful. A
200-level HTTP response code indicates success.
When you specify your subscription code, you can request the next consecutive
alphabetical or numeric subscription code based on the last subscription code you
specified. For example, if the last subscription code that you specified was
24B
, the system returns the code
24C
.
Follow
these steps to retrieve the next subscription code:
Send the request to the recurring billing endpoint:
Production:
GET
https://api.cybersource.com/rbs/v1/subscriptions/code
Test:
GET
https://apitest.cybersource.test.com/rbs/v1/subscriptions/code
Check the response message to make sure that the request was
successful. A 200-level HTTP response code indicates success.
Subscriptions store customer details using a Token Management Service (TMS) token and
have an assigned payment plan. Subscriptions consist of this information:
Subscription code
Use the
subscriptionInformation.code
REST API field
to specify an amended value.
Subscription name
Use the
subscriptionInformation.name
REST API field
to specify an amended value.
Start date
Use the
subscriptionInformation.startDate
REST API field
to specify an amended value.
Token Management Service (TMS) token
You cannot change this information.
Plan: standard or one-time
A
standard plan
is created and stored within the recurring billing service for re-use.
You can assign these plans to multiple subscriptions.
A
one-time plan
is created specifically for a single subscription,
and you create the plan when you create the subscription.
A one-time plan does not include a plan code, plan name, or plan description.
IMPORTANT
The subscription information that you can amend
depends on the status of the subscription. Note the limitations described in in the paragraphs that follow.
IMPORTANT
When you change the plan ID (
subscriptionInformation.planId
field) assigned to a subscription,
the first payment is processed immediately.
If proration is required after the change, it must be managed
outside of the recurring billing service.
Basic Steps
Follow these steps to amend a subscription.
Create the request message with the API fields that contain new values.
Send the request message to one of these endpoints. In the endpoint path,
replace the
{id}
portion of the URL with the subscription
ID (
id
) that you received when you retrieved a list of
subscriptions:
{
"status": "INVALID_REQUEST",
"reason": "INVALID_DATA",
"message": "The subscription cannot be reactivated at this time.",
"details": [
{
"field": "subscriptionInformation.status",
"reason": "INVALID_FOR_ACTIVATION"
}
]
}
Suspending a Subscription
You can suspend a pending, active, or delinquent subscription. Subscriptions cannot
be suspended 10 minutes before or after a payment begins processing.
Follow these
steps to suspend a subscription:
In the endpoint path, include the subscription ID that you received when you retrieved a list of subscriptions.
Send the request to the recurring billing endpoint:
Production:
POST
https://api.cybersource.com/rbs/v1/subscriptions/{id}/suspend
Test:
POST
https://apitest.cybersource.test.com/rbs/v1/subscriptions/{id}/suspend
Check the response message to make sure that the request was
successful. A 200-level HTTP response code indicates success.
You can cancel a pending, active, suspended, or delinquent subscription. Subscriptions cannot be canceled within 10 minutes before or after a payment begins processing.
Follow these steps to cancel a subscription:
In the endpoint path, include the subscription ID that you received when you retrieved a list of subscriptions.
Send the request to the recurring billing endpoint:
Production:
POST
https://api.cybersource.com/rbs/v1/subscriptions/{id}/cancel
Test:
POST
https://apitest.cybersource.test.com/rbs/v1/subscriptions/{id}/cancel
Check the response message to make sure that the request was
successful. A 200-level HTTP response code indicates success.
Recurring Billing includes these additional features.
System Retry Logic
Cybersource
automatically retries failed recurring payments based on the
type of decline received from the service. The service retries the internal and external
payment declines.
If the Recurring Billing service encounters an internal processing error without sending
the request out to the banking network, the service retries the payment until the error
is resolved.
If the recurring billing service encounters an external processing error when the request
is sent out to the banking network,
Cybersource
retries the payment
before changing the subscription status to suspended.
If the issuer provides a reason code like "Do Not Retry",
Cybersource
stops all retry attempts.
Cybersource
immediately updates the
subscription status to suspended.
The maximum number of retries is five times and is based on the billing frequency. During
the retry period,
Cybersource
changes the subscription status to
delinquent.
This example shows the system retry logic based on the billing frequency:
Daily
: retry 1 hour later, 1 time
Monthly
: retry every 2 days, 5 times
Weekly
: retry every 1 day, 3 times
Yearly
: retry every 15 days, 3 times
For a recurring payment that has a custom billing frequency, the Recurring Billing
service retries a failed payment based on the billing frequency. As an example, suppose
a payment fails for a recurring billing on a 14-day cycle. The recurring billing service
uses the Daily retry logic and every 2 weeks uses the Weekly retry logic, even if the
duration is the same.
The Recurring Billing service sends email notifications to customers using the email
address stored on the customer token. The system sends notifications for three defined
payment events:
Prepayment notification: notification of an upcoming recurring payment.
Successful payment notification: notification of a successful recurring
payment.
Failed payment notification: notification of recurring payment failure.
Cybersource
sends email notifications from a
Cybersource
email address.
Example: Notification of Upcoming Subscription Payment
Hello,
Your recurring subscription will be charged to your payment card on file on
${paymentDate}
.
Subscription ID
:
${subscriptionId}
Subscription Name
:
${subscriptionName}
Billing Amount
:
${billingAmount} ${currency}
Set-up Fee
:
${setupFee} ${currency}
Thank you,
${merchantName}
Example: Notification of Successful Subscription Payment
Hello,
Your recurring subscription has been successfully charged to your payment card on file.
Subscription ID
:
${subscriptionId}
Subscription Name
:
${subscriptionName}
Billing Amount
:
${billingAmount} ${currency}
Set-up Fee
:
${setupFee} ${currency}
Transaction ID
:
${transactionId}
Transaction Date
:
${paymentDate}
Thank you,
${merchantName}
Example: Notification of Failed Subscription Payment
Hello,
Your recurring subscription has failed to charge to your payment card on file.
Subscription ID
:
${subscriptionId}
Subscription Name
:
${subscriptionName}
Billing Amount
:
${billingAmount} ${currency}
Setup Fee
:
${setupFee} ${currency}
Transaction ID
:
${transactionId}
Transaction Date
:
${paymentDate}
Thank you,
${merchantName}
Decision Manager
Integration
A recurring payment is a credentials-on-file (COF) transaction in a series of payments
that you bill to a customer at a fixed amount at regular intervals that do not exceed
one year.
Cybersource
saves and stores payment
credentials for recurring transactions, ensuring compliance with COF best practices.
Recurring transactions are considered low risk compared to unscheduled payments.
Therefore, when the
Decision Manager
fraud detection system is enabled on your
account,
Cybersource
does not submit recurring billing transactions to
Decision Manager
for fraud screening.
For more information about the
Decision Manager
,
you can access the documentation by logging in to the
Business Center
.
Account Updater Integration
Account Updater is integrated with the Recurring Billing functionality so that your
customer subscriptions can be kept current with credit card data changes. These changes
can include a new expiration date, a new credit card number, or a brand change such as a
change from Visa to Mastercard.
For more information relating to Account Updater, contact your
Cybersource
representative.
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
