Customer-Initiated Recurring Payment with TMS
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
TMS
TokenWhen 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 thisTMStoken type, see Customer Tokens in the.Token Management ServiceDeveloper 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 thisTMStoken type, see Payment Instrument Token in the.Token Management ServiceDeveloper 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 ServiceDeveloper Guide
- Instrument Identifier, Payment Instrument, and Customer Identifier
- You can also create multipleTMStoken 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/paymentsTest:
POST
https://apitest.cybersource.com
/pts/v2/paymentsRequired Fields for Authorizing a Customer-Initiated
Recurring Payment with TMS
TMS
Use these required fields to request a customer-initiated recurring payment with
TMS
.- Set toTOKEN_CREATE.
- Set to one or more of these values:
- customer
- instrumentIdentifier
- paymentInstrument
- Set tointernetor a payer authentication value.
- processingInformation.recurringOptions.firstRecurringPayment
- Set totrue.
REST Example: Authorizing a Customer-Initiated Recurring Payment with TMS
TMS
Request
{ "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "customer" ], "commerceIndicator": "internet", "recurringOptions": { "firstRecurringPayment": true } }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Doe", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "test@cybs.com", "phoneNumber": "" } } }
Response to a Successful Request
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6976858134106105703954/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6976858134106105703954" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6976858134106105703954/captures" } }, "clientReferenceInformation": { "code": "1697685813462" }, "id": "6976858134106105703954", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "USD" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "62698397FNN143CC", "status": "AUTHORIZED", "submitTimeUtc": "2023-10-19T03:23:33Z", "tokenInformation": { "customer": { "id": "080A3A742BF87171E063A2598D0AEABE" } } }