CyberSource Subscriptions Follow-Ons API
Create a Follow-On Subscription from an already existing successful Transaction. 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 Follow-Ons API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Subscriptions Follow-Ons
description: 'Create a Follow-On Subscription from an already existing successful Transaction.
You have option to link subscription to plan or create independent subscriptions.
'
paths:
/rbs/v1/subscriptions/follow-ons/{requestId}:
get:
summary: Get a Follow-On Subscription
description: 'Get details of the Subscription being created based on the Request Id of an existing successful Transaction.
'
tags:
- Subscriptions Follow-Ons
x-devcenter-metaData:
categoryTag: Recurring_Billing_Subscriptions
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing/recur-bill-dev-intro.html
disableProcessorDropDown: true
mleForRequest: optional
mleForResponse: optional
produces:
- application/json
- application/hal+json
- application/json;charset=utf-8
- application/hal+json;charset=utf-8
operationId: getFollowOnSubscription
parameters:
- name: requestId
in: path
type: string
required: true
description: Request Id of an existing successful Transaction
responses:
'200':
description: Successful response.
schema:
title: getSubscriptionResponse
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.'
create:
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.'
buyerInformation:
type: object
description: Customer information used during Follow-On Transaction.
properties:
merchantCustomerID:
type: string
description: 'Merchant identifier for the customer.
'
maxLength: 100
email:
type: string
maxLength: 255
description: 'Customer''s primary email address, including the full domain name.
'
paymentInstrument:
type: object
description: Payment instrument used during Follow-On Transaction.
properties:
id:
type: string
minLength: 1
maxLength: 32
description: The Id of the Payment Instrument Token.
bankAccount:
type: object
properties:
type:
type: string
maxLength: 18
description: "Account type.\n\nPossible Values:\n - checking : C\n - general ledger : G This value is supported only on Wells Fargo ACH\n - savings : S (U.S. dollars only)\n - corporate checking : X (U.S. dollars only)\n"
number:
type: string
maxLength: 17
description: 'Account number.
When processing encoded account numbers, use this field for the encoded account number.
'
routingNumber:
type: string
description: 'Bank routing number. This is also called the transit number
'
card:
type: object
description: 'The masked number (PAN), expirationMonth, expirationYear and type of the card used during transaction.
'
properties:
number:
type: string
minLength: 12
maxLength: 19
description: 'The masked customer''s payment card number, also known as the Primary Account Number (PAN).
'
expirationMonth:
type: string
maxLength: 2
description: 'Two-digit month in which the payment card expires.
Format: `MM`.
Possible Values: `01` through `12`.
'
expirationYear:
type: string
maxLength: 4
description: 'Four-digit year in which the credit card expires.
Format: `YYYY`.
'
type:
type: string
description: "Value that indicates the card type. Possible Values v2 : v1:\n * 001 : visa\n * 002 : mastercard - Eurocard—European regional brand of Mastercard\n * 003 : american express\n * 004 : discover\n * 005 : diners club\n * 006 : carte blanche\n * 007 : jcb\n * 008 : optima\n * 011 : twinpay credit\n * 012 : twinpay debit\n * 013 : walmart\n * 014 : enRoute\n * 015 : lowes consumer\n * 016 : home depot consumer\n * 017 : mbna\n * 018 : dicks sportswear\n * 019 : casual corner\n * 020 : sears\n * 021 : jal\n * 023 : disney\n * 024 : maestro uk domestic\n * 025 : sams club consumer\n * 026 : sams club business\n * 028 : bill me later\n * 029 : bebe\n * 030 : restoration hardware\n * 031 : delta online — use this value only for Ingenico ePayments. For other processors, use 001 for all Visa card types.\n * 032 : solo\n * 033 : visa electron\n * 034 : dankort\n * 035 : laser\n * 036 : carte bleue — formerly Cartes Bancaires\n * 037 : carta si\n * 038 : pinless debit\n * 039 : encoded account\n * 040 : uatp\n * 041 : household\n * 042 : maestro international\n * 043 : ge money uk\n * 044 : korean cards\n * 045 : style\n * 046 : jcrew\n * 047 : payease china processing ewallet\n * 048 : payease china processing bank transfer\n * 049 : meijer private label\n * 050 : hipercard — supported only by the Comercio Latino processor.\n * 051 : aura — supported only by the Comercio Latino processor.\n * 052 : redecard\n * 054 : elo — supported only by the Comercio Latino processor.\n * 055 : capital one private label\n * 056 : synchrony private label\n * 057 : costco private label\n * 060 : mada\n * 062 : china union pay\n * 063 : falabella private label\n"
billTo:
type: object
properties:
firstName:
type: string
maxLength: 60
description: 'Customer''s first name. This name must be the same as the name on the card.
'
lastName:
type: string
maxLength: 60
description: 'Customer''s last name. This name must be the same as the name on the card.
'
company:
type: string
maxLength: 60
description: 'Name of the customer''s company.
'
address1:
type: string
maxLength: 60
description: 'Payment card billing street address as it appears on the credit card issuer''s records.
'
address2:
type: string
maxLength: 60
description: 'Additional address information.
'
locality:
type: string
maxLength: 50
description: 'Payment card billing city.
'
administrativeArea:
type: string
maxLength: 20
description: 'State or province of the billing address. Use the State, Province, and Territory Codes for the United States
and Canada.
'
postalCode:
type: string
maxLength: 10
description: 'Postal code for the billing address. The postal code must consist of 5 to 9 digits.
When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
**Example** `12345-6789`
When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha][numeric]
**Example** `A1B 2C3`
'
country:
type: string
maxLength: 2
description: 'Payment card billing country. Use the two-character ISO Standard Country Codes.
'
email:
type: string
maxLength: 255
description: 'Customer''s email address, including the full domain name.
'
phoneNumber:
type: string
maxLength: 15
description: 'Customer''s phone number.
'
buyerInformation:
type: object
properties:
companyTaxID:
type: string
maxLength: 9
description: 'Company''s tax identifier. This is only used for eCheck service.
'
currency:
type: string
maxLength: 3
description: 'Currency used for the order. Use the three-character I[ISO Standard Currency Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf)
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.
#### DCC for First Data
Your local currency. For details, see the `currency` field description in [Dynamic Currency Conversion For First Data Using the SCMP API](http://apps.cybersource.com/library/documentation/dev_guides/DCC_FirstData_SCMP/DCC_FirstData_SCMP_API.pdf).
'
dateOfBirth:
type: string
format: date
example: '1960-12-30'
description: 'Date of birth of the customer. Format: YYYY-MM-DD
'
personalIdentification:
type: array
items:
type: object
properties:
id:
type: string
maxLength: 26
description: 'The value of the identification type.
'
type:
type: string
description: "The type of the identification.\n\nPossible Values:\n - driver license\n"
issuedBy:
type: object
properties:
administrativeArea:
type: string
description: 'The State or province where the customer''s driver''s license was issued.
Use the two-character State, Province, and Territory Codes for the United States and Canada.
'
maxLength: 20
shippingAddress:
type: object
description: Shipping address used during Follow-On Transaction.
properties:
id:
type: string
minLength: 1
maxLength: 32
description: The Id of the Shipping Address Token.
shipTo:
type: object
properties:
firstName:
type: string
maxLength: 60
description: 'First name of the recipient.
'
lastName:
type: string
maxLength: 60
description: 'Last name of the recipient.
'
company:
type: string
maxLength: 60
description: 'Company associated with the shipping address.
'
address1:
type: string
maxLength: 60
description: 'First line of the shipping address.
'
address2:
type: string
maxLength: 60
description: 'Second line of the shipping address.
'
locality:
type: string
maxLength: 50
description: 'City of the shipping address.
'
administrativeArea:
type: string
maxLength: 20
description: 'State or province of the shipping address. Use 2 character the State,
Province, and Territory Codes for the United States and Canada.
'
postalCode:
type: string
maxLength: 10
description: 'Postal code for the shipping address. The postal code must consist of 5 to 9 digits.
When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha][numeric]
Example A1B 2C3
**American Express Direct**\
Before sending the postal code to the processor, all nonalphanumeric characters are removed and, if the
remaining value is longer than nine characters, truncates the value starting from the right side.
'
country:
type: string
description: 'Country of the shipping address. Use the two-character ISO Standard Country Codes.
'
maxLength: 2
email:
type: string
maxLength: 320
description: 'Email associated with the shipping address.
'
phoneNumber:
type: string
maxLength: 15
description: 'Phone number associated with the shipping address.
'
example:
_links:
self:
href: rbs/v1/subscriptions/follow-ons/7216512479796378604957
method: GET
create:
href: rbs/v1/subscriptions/follow-ons/7216512479796378604957
method: POST
buyerInformation:
merchantCustomerID: Merchant customer identifier
email: test@cybs.com
paymentInstrument:
id: 1F90575B08822A60E063AF598E0AB9BF
bankAccount:
type: checking
number: XXXXX4100
routingNumber: 071923284
card:
number: 411111XXXXXX1111
expirationMonth: '12'
expirationYear: '2024'
type: '001'
billTo:
firstName: John
lastName: Doe
company: CyberSource
address1: 1 Market St
locality: San Francisco
administrativeArea: CA
postalCode: '94105'
country: US
email: test@cybs.com
phoneNumber: '4158880000'
buyerInformation:
companyTaxID: '12345'
currency: USD
dateOfBirth: '2018-12-13'
personalIdentification:
id: '57684432111321'
type: driver license
issuedBy:
administrativeArea: CA
shippingAddress:
id: 1F90575B08822A60E063AF598E0AB9BF
shipTo:
firstName: John
lastName: Doe
company: CyberSource
address1: 1 Market St
locality: San Francisco
administrativeArea: CA
postalCode: '94105'
country: US
email: test@cybs.com
phoneNumber: '4158880000'
'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 - PROCESSOR_UNAVAILABLE\n - INVALID_FOLLOW_ON_TRANSACTION_STATUS\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"
'404':
description: Not found.
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 - NOT_FOUND\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.
post:
summary: Create a Follow-On Subscription
description: Create a new Subscription based on the Request Id of an existing successful Transaction.
tags:
- Subscriptions Follow-Ons
x-devcenter-metaData:
categoryTag: Recurring_Billing_Subscriptions
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing/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: createFollowOnSubscription
parameters:
- name: requestId
in: path
type: string
required: true
description: Request Id of an existing successful Transaction
- 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*.
'
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:
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-subscriptions-follow-ons-api-openapi.yml