REST API

Creating a COF Network Token

Creating a credential-on-file (COF) network token requires that a cardholder, who has created an account, consents to the merchant storing their credential. After the cardholder provides the merchant their payment credential, the merchant uses it to create a COF network token. 
Get Cardholder Consent
Through the TMS REST API, merchants can control when to request a COF network token. Merchants can create tokens during checkout or COF account setup. It is important that merchants capture cardholder consent in their standard Terms of Service agreement. Capture consent during the consumer interaction to set up an account for the cardholder prior to requesting COF network token.
Request the Token
Once you capture the cardholder's consent, request a network token using the TMS API create token operation. Provide the required fields to provision a COF network token, which are the card PAN or instrument identifier token and the PAN expiration date. The more data fields you submit during token provisioning gives card issuers more information on whether to provision a network token or not.
Example:
The minimum information required to request a network token is to include:
  • type: enrollable card
  • expirationMonth
  • expirationYear
Request
POST https://api.cybersource.com/tms/v1/instrumentidentifiers { "type": "enrollable card", "card": { "number": "4622943127013705", "expirationMonth": "12", "expirationYear": "2022", "securityCode": "838" }, "billTo": { "address1": "8310 Capital of Texas Highway North", "address2": "Bluffstone Drive", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78731", "country": "US" } }
Response
{ "_links": { "self": { "href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/7020000000016623705" }, "paymentInstruments": { "href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/7020000000016623705/paymentinstruments" } }, "id": "7020000000016623705", "object": "instrumentIdentifier", "state": "ACTIVE", "card": { "number": "462294XXXXXX3705" }, "metadata": { "creator": "mid" } }
Set Up a Listener
After you make the API request, we send the COF network token provisioning request to the appropriate network. When successfully provisioned, TMS notifies you in real-time via a POST API response message. Setup a listener to receive the enrollment post notifications for successfully provisioned COF network token. When you receive these notifications, record in your database that a network token has been provisioned for your TMS token. If you're interested in customer tracking, get the Payment Account Reference (PAR) value for the cardholder after successful provisioning.
Please consider the following when requesting COF network tokens:
  • For onboarding existing COF PANs or retroactively provisioning COF network tokens to existing TMS Cybersource tokens, contact your Cybersource representative to understand the current performance limitations for issuers when migrating large portfolios of COF.
  • Cybersource recommends the proper throttling of transactions to stay within issuer processing limitations to ensure best provisioning rate.
  • You can resubmit requests for TMS tokens that were unsuccessful in receiving a provisioned COF network token during the initial token creation request based on the cardholder’s account activity (i.e. payment request).
  • Issuer adoption rate of COF network tokens is dynamic and will continue to see improvements globally for all card products over time.