Recurring Payments

A recurring payment is a credentials-on-file (COF) transaction in a series of payments that you bill to a customer for a fixed amount at regular intervals that do not exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Recurring payments are also known as
subscriptions
.
Mastercard uses standing order and subscription payments instead of recurring payments. See Mastercard Standing Order Payments and Mastercard Subscription Payments.

Recurring Billing Service for Recurring Payments

IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer Guide
. When you use the Recurring Billing service,
Cybersource
 saves and stores payment credentials for recurring transactions, ensuring compliance with COF best practices.

Customer-Initiated Recurring Payment with PAN

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 between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals.

Supported Card Types

These are the supported card types for processing credentialed transactions:
  • American Express
  • Visa
Mastercard uses standing order and subscription payments instead of recurring payments. See Mastercard Standing Order Payments and Mastercard Subscription Payments.

Recurring Billing Service for Recurring Payments

IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer Guide
. When you use the Recurring Billing service,
Cybersource
saves and stores payment credentials for recurring transactions, ensuring compliance with COF best practices.

Address Verification Service for Recurring Payments

If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request.
Cybersource
recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud.
You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Successful Response

You must store the
network transaction ID
from the successful response message to include in subsequent MIT authorization requests in order to associate the CIT to the MIT. The network transaction ID is the
processorInformation.networkTransactionId
field value.
Store the
network transaction ID
, which is the
processorInformation.networkTransactionId
field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT.

Customer-Initiated Recurring Payment with
TMS

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 between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals.

Supported Card Types

These are the supported card types for processing credentialed transactions:
  • American Express
  • Visa
Mastercard uses standing order and subscription payments instead of recurring payments. See Mastercard Standing Order Payments and Mastercard Subscription Payments.

Recurring Billing Service for Recurring Payments

IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer Guide
. When you use the Recurring Billing service,
Cybersource
saves and stores payment credentials for recurring transactions, ensuring compliance with COF best practices.

Creating a
TMS
Token

When sending the initial CIT, you can create a
TMS
token to store the customer's credentials for the subsequent MITs. To create a
TMS
token, include the
processingInformation.actionTokenTypes
field in the authorization request. Set the field to one of these values based on the
TMS
token type you want to create:
Customer
Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. 
        
"processingInformation": {
    "actionTokenTypes": [
      "customer"
]
For more information about this
TMS
token type, see Customer Tokens in the
Token Management Service
Developer Guide
.
Payment Instrument
Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. 
        
"processingInformation": {
    "actionTokenTypes": [
      "paymentInstrument"
]
For more information about this
TMS
token type, see Payment Instrument Token in the
Token Management Service
Developer Guide
.
Instrument Identifier
Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. 
        
"processingInformation": {
    "actionTokenTypes": [
      "instrumentIdentifier"
]
For more information about this TMS token type, see Instrument Identifier Token in the
Token Management Service
Developer Guide
.
Instrument Identifier, Payment Instrument, and Customer Identifier
You can also create multiple
TMS
token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: 
        
 "processingInformation": {
    "actionTokenTypes": [
        "instrumentIdentifier",
        "paymentInstrument",
        "customer"
]

Address Verification Service for Recurring Payments

If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request.
Cybersource
recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud.
You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Customer-Initiated Recurring Payment with Enrollable Network Tokens

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 between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals.
Mastercard uses standing order and subscription payments instead of recurring payments. See Mastercard Standing Order Payments and Mastercard Subscription Payments.

Recurring Billing Service for Recurring Payments

IMPORTANT
Do not use this document for the Recurring Billing service.
Use the
Recurring Billing Developer Guide
. When you use the Recurring Billing service,
Cybersource
saves and stores payment credentials for recurring transactions, ensuring compliance with COF best practices.

Using Enrollable Network Tokens

The
Token Management Service
can enroll certain
network tokens
, known as device tokens, into an instrument identifier token for future payments.
Device tokens
store and encrypt card-on-file information which enables customers to make quick and easy purchases using their mobile device. When authorizing a credentialed payment with a device token, you must create and store the device token in a
TMS
instrument identifier token. To do this, include the device token information in the
paymentInformation.tokenizedCard
fields and set the token creation fields to create an instrument identifier token.
Follow-on merchant-initiated transactions are performed using the created instrument identifier as the payment information. For more information about how to request a merchant-initiated transaction, see Merchant-Initiated Recurring Payments with TMS.
Device tokens are also known as
digital payments
,
digital wallets
, and
tokenized cards
.

Network Token Types

In your request, include the
processingInformation.paymentSolution
field to identify the device token type you are using, and set it to one of these possible values:
  • 001
    : Apple Pay
  • 004
    :
    Cybersource
    In-App Solution
  • 005
    : Masterpass
  • 006
    : Android Pay
  • 007
    : Chase Pay
  • 008
    : Samsung Pay
  • 012
    : Google Pay
  • 014
    : Mastercard credential-on-file (COF) payment network token
  • 015
    : Visa credential-on-file (COF) payment network token
  • 027
    : Click to Pay
  • visacheckout
    :
    Visa Click to Pay
    .

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Merchant-Initiated Recurring Payments with PAN

After the initial recurring payment (CIT), subsequent recurring payments are merchant-initiated transactions (MITs).

Prerequisites

The first transaction in a recurring payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the customer's credentials, you must get their consent to store their private information. This is also known as establishing a relationship with the customer.

Supported Card Types

These are the supported card types for processing credentialed transactions:
  • American Express
  • Visa
Mastercard uses standing order and subscription payments instead of recurring payments. See Mastercard Standing Order Payments and Mastercard Subscription Payments.

Address Verification Service for Recurring Payments

If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request.
Cybersource
recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud.
You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment.

Replacing Expiration Dates

If the customer's card-on-file is going to expire before a scheduled subsequent recurring payment, your processor may allow you to replace the expiration date with the date 12/2099.
IMPORTANT
Do not replace a card's expiration date if the card is not expired.
Using this replacement expiration date does not guarantee a successful authorization request. It is your responsibility to know if your processor supports this feature. Not all issuing banks support the 12/2099 expiration date and may decline the authorization request.
To include this date in the authorization request, use these fields and values.
paymentInformation.card.expirationMonth
Set to
12
.
paymentInformation.card.expirationYear
Set to
99
.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Merchant-Initiated Recurring Payments with
TMS

After the customer-initiated recurring payment, you can send merchant-initiated recurring payments using one or more
TMS
token types:
Customer
Customer tokens store one or more customer payment instrument tokens and shipping address tokens.
Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID. 
        
"paymentInformation": {
  "customer": {
    "id": "07C9CA98022DA498E063A2598D0AA400"
  }
}
For more information about this
TMS
token type, see Customer Tokens in the
Token Management Service
Developer Guide
.
Payment Instrument
Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token.
Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID. 
        
"paymentInformation": {
  "paymentInstrument": {
    "id": "07CA24EF20F9E2C9E063A2598D0A8565"
  }
}
For more information about this
TMS
token type, see Payment Instrument Token in the
Token Management Service
Developer Guide
.
Instrument Identifier
Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID. 
        
"paymentInformation": {
  "instrumentIdentifier": {
    "id": "7010000000016241111"
  }
}
For more information about this
TMS
token type, see Instrument Identifier Token in the
Token Management Service
Developer Guide
.

Prerequisites

The first transaction in a recurring payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the customer's credentials, you must get their consent to store their private information. This is also known as establishing a relationship with the customer.

Supported Card Types

These are the supported card types for processing credentialed transactions:
  • American Express
  • Mastercard
  • Visa
Mastercard uses standing order and subscription payments instead of recurring payments. See Mastercard Standing Order Payments and Mastercard Subscription Payments.

Address Verification Service for Recurring Payments

If your processor supports the Address Verification Service (AVS), then the AVS should verify every authorization request.
Cybersource
recommends checking the AVS's results for the first recurring payment to ensure that the payment information is accurate and to reduce the risk of fraud.
You must determine how to handle the AVS results for any subsequent recurring payments that are not the same as the already-verified billing address information from the first recurring payment.

Replacing Expiration Dates

If the customer's card-on-file is going to expire before a scheduled subsequent recurring payment, your processor may allow you to replace the expiration date with the date 12/2099.
IMPORTANT
Do not replace a card's expiration date if the card is not expired.
Using this replacement expiration date does not guarantee a successful authorization request. It is your responsibility to know if your processor supports this feature. Not all issuing banks support the 12/2099 expiration date and may decline the authorization request.
To include this date in the authorization request, use these fields and values.
paymentInformation.card.expirationMonth
Set to
12
.
paymentInformation.card.expirationYear
Set to
99
.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments