CyberSource Plans API
Create and manage Plans for 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 Plans API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Plans
description: 'Create and manage Plans for subscriptions.
'
paths:
/rbs/v1/plans:
post:
summary: Create a Plan
description: 'The recurring billing service enables you to manage payment plans and subscriptions for recurring payment schedules. It securely stores your customer''s payment information and personal data within secure Visa data centers, reducing storage risks and PCI DSS scope through the use of *Token Management* (*TMS*).
The three key elements of *Cybersource* Recurring Billing are:
- **Token**: stores customer billing, shipping, and payment details.
- **Plan**: stores the billing schedule.
- **Subscription**: combines the token and plan, and defines the subscription start date, name, and description.
The APIs in this section demonstrate the management of the Plans and Subscriptions. For Tokens please refer to [Token Management](#token-management)
The availability of API features for a merchant can depend on the portfolio configuration and may need to be enabled at the portfolio level before they can be added to merchant accounts.
'
tags:
- Plans
operationId: createPlan
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
parameters:
- name: createPlanRequest
in: body
required: true
schema:
type: object
properties:
planInformation:
type: object
required:
- name
- billingPeriod
properties:
code:
type: string
maxLength: 10
description: 'Plan code is an optional field, If not provided system generates and assign one
'
name:
type: string
maxLength: 100
description: 'Plan name
'
description:
type: string
maxLength: 255
description: 'Plan description
'
status:
type: string
description: "Plan Status:\n - `DRAFT`\n - `ACTIVE` (default)\n"
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
'
orderInformation:
type: object
properties:
amountDetails:
type: object
required:
- currency
- billingAmount
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
'
example:
planInformation:
name: Gold Plan
description: New Gold Plan
billingPeriod:
length: '1'
unit: M
billingCycles:
total: '12'
orderInformation:
amountDetails:
currency: USD
billingAmount: '10'
setupFee: '2'
responses:
'201':
description: Successful response.
schema:
title: createPlanResponse
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.'
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"
planInformation:
type: object
properties:
code:
type: string
maxLength: 10
description: 'Plan code
'
status:
type: string
description: "Plan Status:\n - `DRAFT`\n - `ACTIVE`\n"
example:
_links:
self:
href: rbs/v1/plans/4963015972176007901546
method: GET
id: '4963015972176007901546'
submitTimeUtc: '2020-06-28T19:48:06Z'
status: COMPLETED
planInformation:
code: PLN1
status: DRAFT
'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_MERCHANT_CONFIGURATION\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 Plan
sample-name: Create Plan
value:
planInformation:
name: Gold Plan
description: New Gold Plan
billingPeriod:
length: '1'
unit: M
billingCycles:
total: '12'
orderInformation:
amountDetails:
currency: USD
billingAmount: '10'
setupFee: '2'
get:
summary: Get a List of Plans
description: 'Retrieve Plans by Plan Code & Plan Status.
'
tags:
- Plans
operationId: getPlans
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
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 Plan Code
- name: status
in: query
type: string
required: false
description: Filter by Plan Status
- name: name
in: query
type: string
required: false
description: 'Filter by Plan Name. (First sub string or full string) **[Not Recommended]**
'
responses:
'200':
description: Successful response.
schema:
title: getAllPlansResponse
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 plans created
plans:
type: array
items:
type: object
description: Plan 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.'
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
'
status:
type: string
description: "Plan Status:\n - `DRAFT`\n - `ACTIVE`\n - `INACTIVE`\n"
name:
type: string
maxLength: 100
description: 'Plan name
'
description:
type: string
maxLength: 255
description: 'Plan description
'
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
'
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
'
'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_MERCHANT_CONFIGURATION\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.
/rbs/v1/plans/{id}:
get:
summary: Get a Plan
description: Retrieve a Plan details by Plan Id.
tags:
- Plans
operationId: getPlan
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
parameters:
- name: id
in: path
required: true
type: string
description: Plan Id
responses:
'200':
description: Successful response.
schema:
title: getPlanResponse
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.'
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.
'
planInformation:
type: object
properties:
code:
type: string
maxLength: 10
description: 'Plan code
'
status:
type: string
description: "Plan Status:\n - `DRAFT`\n - `ACTIVE`\n - `INACTIVE`\n"
name:
type: string
maxLength: 100
description: 'Plan name
'
description:
type: string
maxLength: 255
description: 'Plan description
'
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
'
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
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-plans-api-openapi.yml