Customer-Initiated Installment Payment with
TMS

An installment payment is a single purchase of goods or services billed to a customer in multiple transactions over a period of time agreed to by you and the customer, and sometimes, the issuing bank. The agreement enables you to charge a specific amount at specified intervals. For customers, installment payments provide greater purchasing power and lower impact on their monthly budget. For you, offering installment payments at checkout can help increase the number of successfully completed purchases.
Before you can accept installment payments, you and your acquirer must agree on the maximum number of installments you can accept, which can be different for each card type.
IMPORTANT
Do not use this document if you are using the Installments service. When using the Installments service,
Cybersource
 saves and stores payment credentials for installment transactions, ensuring compliance with COF best practices.

Supported Card Types

These are the supported card types for processing credentialed transactions:
  • Discover
  • Mastercard
  • Visa

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"
]

Endpoint

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

Required Fields for CIT Installment Payments with TMS

Card-Specific Fields for Authorizing Initial Installment Payments

Use this required field if you are authorizing an initial installment payment using the card type referenced below.
Mastercard
processingInformation. authorizationOptions. initiator. merchantInitiatedTransaction. reason
Set the value to
9
.

REST Example: CIT Installment Payment with TMS

Light Dark
Request
1234567891011121314151617181920212223242526272829303132333435
{
  "processingInformation": {
    "actionList": [
      "TOKEN_CREATE"
    ],
    "actionTokenTypes": [
      "instrumentIdentifier"
    ],
    "commerceIndicator": "internet"
  },
  "paymentInformation": {
    "card": {
      "number": "411111111111XXXX",
      "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": "4158880000"
    }
  }
}
Response to a Successful Request
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/6972267090226779103955/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/6972267090226779103955"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/6972267090226779103955/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "6972267090226779103955",
  "orderInformation": {
    "amountDetails": {
      "authorizedAmount": "102.21",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "001"
    }
  },
  "paymentInformation": {
    "tokenizedCard": {
      "type": "001"
    },
    "card": {
      "type": "001"
    }
  },
  "pointOfSaleInformation": {
    "terminalId": "111111"
  },
  "processorInformation": {
    "paymentAccountReferenceNumber": "V0010013022298169667504231315",
    "approvalCode": "888888",
    "networkTransactionId": "123456789619999",
    "transactionId": "123456789619999",
    "responseCode": "100",
    "avs": {
      "code": "X",
      "codeRaw": "I1"
    }
  },
  "reconciliationId": "62506622XNMR6Q1Y",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2023-10-13T19:51:49Z",
  "tokenInformation": {
    "instrumentidentifierNew": false,
    "instrumentIdentifier": {
      "state": "ACTIVE",
      "id": "7010000000016241111"
    }
  }
}