CyberSource Subscriptions API
Create and manage Recurring Subscriptions. You have option to link subscription to plan or create independent subscriptions.
OpenAPI Specification
swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation Subscriptions API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Subscriptions
description: 'Create and manage Recurring Subscriptions.
You have option to link subscription to plan or create independent subscriptions.
'
paths:
/rbs/v1/subscriptions:
post:
summary: Create a Subscription
description: Create a Recurring Billing Subscription
tags:
- Subscriptions
x-devcenter-metaData:
categoryTag: Recurring_Billing_Subscriptions
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-dev/recur-bill-dev-intro.html
disableProcessorDropDown: true
mleForRequest: optional
mleForResponse: optional
consumes:
- application/json;charset=utf-8
produces:
- application/json
- application/hal+json
- application/json;charset=utf-8
- application/hal+json;charset=utf-8
operationId: createSubscription
parameters:
- name: createSubscriptionRequest
in: body
required: true
schema:
type: object
properties:
clientReferenceInformation:
type: object
properties:
code:
description: '
Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
type: string
maxLength: 59
processingInformation:
type: object
properties:
commerceIndicator:
description: '> This field is ignored when you provide the `subscriptionInformation.originalTransactionId` or update the subscription.
Commerce Indicator is a way to identify the type of transaction. Some payment card companies use this information when determining discount rates.
Valid values:
- `MOTO`
- `RECURRING`
- `INTERNET`
Please add the ecommerce indicator based on the rules defined by your gateway/processor. Some gateways may not accept the Commerce Indicator `RECURRING` with a Zero Dollar Authorization, that is done for subscriptions starting at a future date.
'
type: string
maxLength: 20
authorizationOptions:
type: object
properties:
initiator:
type: object
properties:
type:
description: '> This field is ignored when you provide the `subscriptionInformation.originalTransactionId` or update the subscription.
This field indicates whether the transaction is a merchant-initiated transaction or customer-initiated transaction.
Valid values:
- **customer**
- **merchant**
'
type: string
planInformation:
type: object
properties:
billingPeriod:
type: object
description: 'Billing Frequency
'
properties:
length:
type: string
description: 'Example:
- If length=1 & unit=month then charge every month
- If length=7 & unit=day then charge every 7th day
'
unit:
type: string
description: "Calendar unit values.\n possible values:\n - `D` - day\n - `M` - month\n - `W` - week\n - `Y` - year\n"
billingCycles:
type: object
description: 'Number of times customer is going to be billed
'
properties:
total:
type: string
description: 'Describe total number of billing cycles
'
subscriptionInformation:
type: object
required:
- name
- startDate
properties:
code:
type: string
maxLength: 10
description: 'Subscription code is an optional field, If not provided system generates and assign one
'
planId:
type: string
maxLength: 26
description: 'Plan Id. Use Plan Id from Create Plan Service.
'
name:
type: string
maxLength: 100
description: 'Subscription Name
'
startDate:
type: string
description: 'Start date of the Subscription
Start date must be in UTC. Format: YYYY-MM-DDThh:mm:ssZ
The T separates the date and the time. The Z indicates UTC.
Note: Subscription starts on the day provided in UTC.
**Example** 2022-08-11T22:47:57Z equals August 11, 2022, at 22:47:57 (10:47:57 p.m.).
Subscription will start on August 11,2022.
'
originalTransactionId:
type: string
maxLength: 50
description: 'Network transaction identifier that was returned in the payment response field _processorInformation.transactionId_
in the reply message for the original subscription-initializing payment.
'
originalTransactionAuthorizedAmount:
type: string
maxLength: 19
description: 'Amount of the original subscription-initializing payment.
*Required when using a Diners or Discover card*.
'
paymentInformation:
type: object
properties:
customer:
type: object
required:
- id
properties:
id:
type: string
description: 'Unique identifier for the Customer token used in the transaction.
When you include this value in your request, many of the fields that are normally required for an authorization or credit
become optional.
'
minLength: 1
maxLength: 32
orderInformation:
type: object
properties:
amountDetails:
type: object
properties:
currency:
type: string
maxLength: 3
description: 'Currency used for the order. Use the three-character [ISO Standard Currency Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf)
#### Used by
**Authorization**
Required field.
**Authorization Reversal**
For an authorization reversal (`reversalInformation`) or a capture (`processingOptions.capture` is set to `true`), you must use the same currency that you used in your payment authorization request.
#### PIN Debit
Currency for the amount you requested for the PIN debit purchase. This value is returned for partial authorizations. The issuing bank can approve a partial amount if the balance on the debit card is less than the requested transaction amount. For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Returned by PIN debit purchase.
For PIN debit reversal requests, you must use the same currency that was used for the PIN debit purchase or PIN debit credit that you are reversing.
For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Required field for PIN Debit purchase and PIN Debit credit requests.
Optional field for PIN Debit reversal requests.
#### GPX
This field is optional for reversing an authorization or credit.
#### DCC for First Data
Your local currency.
#### Tax Calculation
Required for international tax and value added tax only.
Optional for U.S. and Canadian taxes.
Your local currency.
'
billingAmount:
type: string
maxLength: 19
description: 'Billing amount for the billing period.
'
setupFee:
type: string
maxLength: 19
description: 'Subscription setup fee
'
surcharge:
type: object
properties:
amount:
description: "Surcharge amount that you are charging the customer for this subscription. The surcharge amount will be added to the billing amount. \nThe issuer can provide information about the surcharge amount to the customer.\n\n**NOTE**: This field is supported only for CyberSource through VisaNet (CtV) for Payouts. For CtV, the maximum string length is 8.\n"
type: string
maxLength: 15
description:
maxLength: 255
description: 'Description of the surcharge.
'
type: string
example:
subscriptionInformation:
planId: '6868912495476705603955'
name: Subscription with PlanId
startDate: '2025-06-11'
originalTransactionId: 016153570198200
paymentInformation:
customer:
id: C24F5921EB870D99E053AF598E0A4105
clientReferenceInformation:
code: TC501713
responses:
'201':
description: Successful response.
schema:
title: createSubscriptionResponse
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
update:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
cancel:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
suspend:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
activate:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
status:
type: string
description: "The status of the submitted transaction.\n\nPossible values:\n - COMPLETED\n - DECLINED\n"
subscriptionInformation:
type: object
properties:
code:
type: string
maxLength: 10
description: 'Subscription code.
'
status:
type: string
description: "Subscription Status:\n - `PENDING`\n - `ACTIVE`\n - `FAILED`\n"
clientReferenceInformation:
type: object
properties:
code:
description: '
Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
#### Used by
**Authorization**
Required field.
#### PIN Debit
Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being
reversed.
Required field for all PIN Debit requests (purchase, credit, and reversal).
#### FDC Nashville Global
Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports.
'
type: string
maxLength: 59
example:
_links:
self:
href: /rbs/v1/subscriptions/4567000000000123456789
method: GET
update:
href: /rbs/v1/subscriptions/4567000000000123456789
method: PATCH
cancel:
href: /rbs/v1/subscriptions/4567000000000123456789/cancel
method: POST
suspend:
href: /rbs/v1/subscriptions/4567000000000123456789/suspend
method: POST
activate:
href: /rbs/v1/subscriptions/4567000000000123456789/activate
method: POST
id: '4567000000000123456789'
submitTimeUtc: 2020-11-01T071957Z
status: COMPLETED
subscriptionInformation:
code: SUB1
status: ACTIVE
'400':
description: Invalid request.
schema:
type: object
properties:
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
status:
type: string
description: "The status of the submitted transaction.\n\nPossible values:\n - INVALID_REQUEST\n"
reason:
type: string
description: "The reason of the status.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n - DUPLICATE_REQUEST\n - INVALID_CARD\n - CARD_TYPE_NOT_ACCEPTED\n - INVALID_MERCHANT_CONFIGURATION\n - PROCESSOR_UNAVAILABLE\n - INVALID_CARD_TYPE\n"
message:
type: string
description: The detail message related to the status and reason listed above.
details:
type: array
items:
type: object
properties:
field:
type: string
description: This is the flattened JSON object field name/path that is either missing or invalid.
reason:
type: string
description: "Possible reasons for the error.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n"
'502':
description: Unexpected system error or system timeout.
schema:
type: object
properties:
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
status:
type: string
description: "The status of the submitted transaction.\n\nPossible values:\n - SERVER_ERROR\n"
reason:
type: string
description: "The reason of the status.\n\nPossible values:\n - SYSTEM_ERROR\n - SERVER_TIMEOUT\n - SERVICE_TIMEOUT\n"
message:
type: string
description: The detail message related to the status and reason listed above.
x-example:
example0:
summary: Create Subscription
sample-name: Create Subscription
value:
clientReferenceInformation:
code: TC501713
subscriptionInformation:
planId: '6868912495476705603955'
name: Subscription with PlanId
startDate: '2025-06-11'
originalTransactionId: 016153570198200
paymentInformation:
customer:
id: C24F5921EB870D99E053AF598E0A4105
example1:
summary: (deprecated) Create Subscription with Authorization
sample-name: (deprecated) Create Subscription with Authorization
value:
clientReferenceInformation:
code: TC501713
processingInformation:
commerceIndicator: recurring
authorizationOptions:
initiator:
type: merchant
subscriptionInformation:
planId: '6868912495476705603955'
name: Subscription with PlanId
startDate: '2024-06-11'
paymentInformation:
customer:
id: C24F5921EB870D99E053AF598E0A4105
get:
summary: Get a List of Subscriptions
description: 'Retrieve Subscriptions by Subscription Code & Subscription Status.
'
tags:
- Subscriptions
x-devcenter-metaData:
categoryTag: Recurring_Billing_Subscriptions
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-dev/recur-bill-dev-intro.html
disableProcessorDropDown: true
consumes:
- application/json;charset=utf-8
produces:
- application/json
- application/hal+json
- application/json;charset=utf-8
- application/hal+json;charset=utf-8
operationId: getAllSubscriptions
parameters:
- name: offset
in: query
type: integer
required: false
description: Page offset number.
- name: limit
in: query
type: integer
required: false
description: 'Number of items to be returned. Default - `20`, Max - `100`
'
- name: code
in: query
type: string
required: false
description: Filter by Subscription Code
- name: status
in: query
type: string
required: false
description: Filter by Subscription Status
- name: customerId
in: query
type: string
required: false
description: Filter by Customer Id
- name: clientReferenceInformationCode
in: query
type: string
required: false
description: Filter by Client Reference Information Code / Merchant Reference Number
responses:
'200':
description: Successful response.
schema:
title: getAllSubscriptionsResponse
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
next:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
previous:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
**Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.).
The `T` separates the date and the time. The `Z` indicates UTC.
Returned by Cybersource for all services.
'
totalCount:
type: integer
description: total number of subscriptions created
subscriptions:
type: array
items:
type: object
description: Subscription list
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
cancel:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
suspend:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
activate:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
planInformation:
type: object
properties:
code:
type: string
maxLength: 10
description: 'Plan code
'
name:
type: string
maxLength: 100
description: 'Plan name
'
billingPeriod:
type: object
description: 'Billing Frequency
'
properties:
length:
type: string
description: 'Example:
- If length=1 & unit=month then charge every month
- If length=7 & unit=day then charge every 7th day
'
unit:
type: string
description: "Calendar unit values.\n possible values:\n - `D` - day\n - `M` - month\n - `W` - week\n - `Y` - year\n"
billingCycles:
type: object
properties:
total:
type: string
description: 'Describe total number of billing cycles
'
current:
type: string
description: 'Current billing cycle
'
subscriptionInformation:
type: object
properties:
code:
type: string
maxLength: 10
description: 'Subscription code.
'
planId:
type: string
maxLength: 26
description: 'Plan Id.
'
name:
type: string
maxLength: 100
description: 'Subscription Name
'
startDate:
type: string
description: 'Start date of the Subscription
Start date will be in UTC. Format: YYYY-MM-DDThh:mm:ssZ
The T separates the date and the time. The Z indicates UTC.
**Example** 2022-08-11T22:47:57Z equals August 11, 2022, at 22:47:57 (10:47:57 p.m.).
'
status:
type: string
description: 'Subscription Status:
- `PENDING`
- `ACTIVE`
- `FAILED`
- `COMPLETED`
- `DELINQUENT`
- `SUSPENDED`
- `CANCELLED`
'
clientRefe
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-subscriptions-api-openapi.yml