On This Page

Create a Customer Payment Instrument

This section describes how to create a customer payment instrument. Customer tokens can contain instrument identifiers, payment instruments, and shipping address tokens.

For information about managing these token types, see these topics:

Manage Customer Tokens

Manage Instrument Identifier Tokens

Manage Shipping Address Tokens

Endpoint

Test:

POST https://apitest.cybersource.com/tms/v2/tokenize

Production:

POST https://api.cybersource.com/tms/v2/tokenize

Production in India:

POST https://api.in.cybersource.com/tms/v2/tokenize

Production in Saudi Arabia:

POST https://api.sa.cybersource.com/tms/v2/tokenize

Test in Saudi Arabia:

POST https://apitest.sa.cybersource.com/tms/v2/tokenize

Required Fields for Creating an Instrument Identifier and Provisioning a Network Token

processingInformation.actionList: Set to
TOKEN_CREATE
.
processingInformation.actionTokenTypes.customer: Required when you are creating a customer token.
processingInformation.actionTokenTypes.instrumentIdentifier: Required when you are creating an instrument identifier token.
processingInformation.actionTokenTypes.paymentInstrument: Required when you are creating a payment instrument.
tokenInformation.customer.buyerInformation.email
tokenInformation.customer.buyerInformation.merchantCustomerID
tokenInformation.customer.clientReferenceInformation.code
tokenInformation.customer.merchantDefinedInformation[].name
tokenInformation.customer.merchantDefinedInformation[].value
tokenInformation.instrumentIdentifier.card.expirationMonth
tokenInformation.instrumentIdentifier.card.expirationYear
tokenInformation.instrumentIdentifier.card.number
tokenInformation.instrumentIdentifier.type
tokenInformation.paymentInstrument.billTo.address1
tokenInformation.paymentInstrument.billTo.administrativeArea
tokenInformation.paymentInstrument.billTo.company
tokenInformation.paymentInstrument.billTo.country
tokenInformation.paymentInstrument.billTo.email
tokenInformation.paymentInstrument.billTo.firstName
tokenInformation.paymentInstrument.billTo.lastName
tokenInformation.paymentInstrument.billTo.locality
tokenInformation.paymentInstrument.billTo.phoneNumber
tokenInformation.paymentInstrument.billTo.postalCode
tokenInformation.paymentInstrument.card.expirationMonth
tokenInformation.paymentInstrument.card.expirationYear
tokenInformation.paymentInstrument.card.type
tokenInformation.paymentInstrument.default

Related Information

API Field Reference for the REST API

REST Example: Creating a Customer Payment Instrument

Request

{
  "processingInformation": {
    "actionList": [
      "TOKEN_CREATE"
    ],
    "actionTokenTypes": [
      "customer",
      "paymentInstrument",
      "instrumentIdentifier"
    ]
  },
  "tokenInformation": {
    "customer": {
      "buyerInformation": {
        "merchantCustomerID": "Your customer identifier",
        "email": "test@cybs.com"
      },
      "clientReferenceInformation": {
        "code": "TC50171_3"
      },
      "merchantDefinedInformation": [
        {
          "name": "data1",
          "value": "Your customer data"
        }
      ]
    },
    "paymentInstrument": {
      "default": "true",
      "card": {
        "expirationMonth": "12",
        "expirationYear": "2031",
        "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"
      }
    },
    "instrumentIdentifier": {
      "type": "enrollable card",
      "card": {
        "number": "X622943123116478",
        "expirationMonth": "12",
        "expirationYear": "2026"
      }
    }
  }
}

Response to a Successful Request

{
    "paymentInformation": {
        "card": {
            "type": "001"
        }
    },
    "tokenInformation": {
        "instrumentIdentifierNew": false,
        "customer": {
            "id": "4DC6BB4C7353F90CE063AF598E0AEBE8"
        },
        "instrumentIdentifier": {
            "id": "7034450000295211111",
            "state": "ACTIVE"
        },
        "paymentInstrument": {
            "id": "4DC6C33114B31665E063AF598E0A87FF"
        },
        "shippingAddress": {
            "id": "4DC6BF33FF03FB70E063AF598E0A1472"
        }
    }
}