Enroll a Card

Use the information in this section to securely tokenize a customer's payment credentials for future purchases. Your agents can enroll a customer's card for tokenization during the customer's account registration or when the customer begins a new purchase intent. Each customer must have at least one card enrolled in Intelligent Commerce to complete a purchase. Enrolling a card includes also tokenizing the customer's billing information, such as their name and address.

Intelligent Commerce uses the Token Management Service (TMS) to tokenize the customer's payment credentials. Your agents can tokenize any card type supported by TMS.

A successful response includes the

PENDING

status in the

status

field. After sending the request, the customer is immediately prompted to verify their identity in order to activate the enrolled card.

Endpoints

Send a POST request to one of these endpoints.

Production:

POST https://api.cybersource.com/acp/v1/tokens

Test:

POST https://apitest.cybersource.com/acp/v1/tokens

Required Fields for Enrolling a Card

billTo.country
billTo.countryCallingCode
billTo.phoneNumber
clientCorrelationId
consumerIdentity.identityType
consumerIdentity.identityValue
deviceInformation.applicationName
deviceInformation.deviceData.brand
deviceInformation.deviceData.type
deviceInformation.fingerprintSessionId
deviceInformation.ipAddress
paymentInformation.customer.id
paymentInformation.instrumentIdentifier.id
paymentInformation.paymentInstrument.id

Additional Information

For complete descriptions of the request fields, see the Enroll a card section in the Intelligent Commerce API Hub.

Optional Fields for Enrolling a Card

assuranceData[].additionalData
assuranceData[].authenticatedIdentities.data
assuranceData[].authenticatedIdentities.id
assuranceData[].authenticatedIdentities.provider
assuranceData[].authenticationContext.action
assuranceData[].verificationEntity
assuranceData[].verificationEvents
assuranceData[].verificationMethod
assuranceData[].verificationResults
assuranceData[].verificationTimestamp
assuranceData[].verificationType
billTo.email
billTo.firstName
billTo.fullName
billTo.lastName
billTo.numberIsVoiceOnly
buyerInformation.language
buyerInformation.merchantCustomerId
buyerInformation.personalIdentification[].id
buyerInformation.personalIdentification[].issuedBy
buyerInformation.personalIdentification[].type
consentData[].acceptedTime
consentData[].effectiveUntil
consentData[].id
consentData[].source
consentData[].type
consumerIdentity.identityProvider
consumerIdentity.identityProviderUrl
deviceInformation.clientDeviceId
deviceInformation.country
deviceInformation.deviceData.manufacturer
deviceInformation.deviceData.model
deviceInformation.userAgent
enrollmentReferenceData.enrollmentReferenceProvider
enrollmentReferenceData.enrollmentReferenceType
tokenizedCard.tokenReferenceId

Example: Enrolling a Card

Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "deviceInformation": {
    "userAgent": "SampleUserAgent",
    "applicationName": "My Magic App",
    "fingerprintSessionId": "finSessionId",
    "country": "US",
    "deviceData": {
      "type": "Mobile",
      "manufacturer": "Apple",
      "brand": "Apple",
      "model": "iPhone 16 Pro Max"
    },
    "ipAddress": "192.168.0.100",
    "clientDeviceId": "000b2767814e4416999f4ee2b099491d2087"
  },
  "buyerInformation": {
    "merchantCustomerId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
    "personalIdentification": [
      {
        "type": "The identification type",
        "id": "1",
        "issuedBy": "The government agency that issued the driver's license or passport"
      }
    ],
    "language": "en"
  },
  "billTo": {
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Michael Doe",
    "email": "[email protected]",
    "countryCallingCode": "1",
    "phoneNumber": "5551234567",
    "numberIsVoiceOnly": false,
    "country": "US"
  },
  "consumerIdentity": {
    "identityType": "EMAIL_ADDRESS",
    "identityValue": "[email protected]",
    "identityProvider": "PARTNER",
    "identityProviderUrl": "https://identity.partner.com"
  },
  "paymentInformation": {
    "customer": {
      "id": ""
    },
    "paymentInstrument": {
      "id": ""
    },
    "instrumentIdentifier": {
      "id": "3C189A435506B99AE0634136CF0AEB92"
    }
  },
  "tokenizedCard": {
    "tokenReferenceId": "15602cf86c70b8b63297134292ec5801"
  },
  "enrollmentReferenceData": {
    "enrollmentReferenceType": "TOKEN_REFERENCE_ID",
    "enrollmentReferenceProvider": "VTS"
  },
  "assuranceData": [
    {
      "verificationType": "DEVICE",
      "verificationEntity": "10",
      "verificationEvents": [
        "01"
      ],
      "verificationMethod": "02",
      "verificationResults": "01",
      "verificationTimestamp": "1735690745",
      "authenticationContext": {
        "action": "AUTHENTICATE"
      },
      "authenticatedIdentities": {
        "data": "authenticatedIdentities.data",
        "provider": "VISA_PAYMENT_PASSKEY",
        "id": "authenticatedIdentities.id"
      },
      "additionalData": "assuranceData.additionalData"
    }
  ],
  "consentData": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "PERSONALIZATION",
      "source": "CLIENT",
      "acceptedTime": "1719169800",
      "effectiveUntil": "1750705800"
    }
  ]
}

Response to a Successful Request

{
  "clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
  "status": "PENDING",
  "pendingEvents": [
    "PENDING_CARDHOLDER_AUTHENTICATION"
  ]
}

Response to a Successful Request

{
"clientCorrelationId": "3e1b7943-6567-4965-a32b-5aa93d057d35",
"status": "ACTIVE"
}