CyberSource Network Tokens API
A Network Token represents a tokenized version of a card number (PAN) that can be used for payment transactions and, it's represented by a Tokenized Card in TMS.
OpenAPI Specification
swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation Network Tokens API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Network Tokens
description: 'A Network Token represents a tokenized version of a card number (PAN) that can be used for payment transactions and, it''s represented by a Tokenized Card in TMS.
'
paths:
/tms/v2/tokenized-cards:
post:
summary: Create a Tokenized Card
description: '**Tokenized cards**<br>A Tokenized card represents a network token.
Network tokens perform better than regular card numbers and they are not necessarily invalidated when a cardholder loses their card, or it expires.
This API submits a request to the card association to create a network token. If successful, a tokenized card will be created in TMS to represent the network token.
'
parameters:
- name: profile-id
in: header
description: The Id of a profile containing user specific TMS configuration.
required: false
type: string
minLength: 36
maxLength: 36
x-hide-field: true
- name: postTokenizedCardRequest
in: body
required: true
schema:
type: object
required:
- source
properties:
accountReferenceId:
type: string
description: 'An identifier provided by the issuer for the account.
**Required when source is ISSUER.**
'
consumerId:
type: string
maxLength: 36
description: Identifier of the consumer within the wallet. Maximum 24 characters for VTS.
createPanInstrumentIdentifier:
type: boolean
description: 'Specifies whether the Instrument Identifier should be created (true) or not (false) with the PAN provided for the Network Token Provision request.
Possible Values:
- `true`: The InstrumentIdentifier should be created.
- `false`: The InstrumentIdentifier should not be created.
'
source:
type: string
description: 'Source of the card details.
Possible Values:
- ONFILE
- TOKEN
- ISSUER
'
card:
type: object
properties:
number:
type: string
minLength: 12
maxLength: 19
description: 'The customer''s payment card number, also known as the Primary Account Number (PAN). You
can also use this field for encoded account numbers.
'
expirationMonth:
type: string
maxLength: 2
description: 'Two-digit month in which the payment card expires.
Format: `MM`.
Possible Values: `01` through `12`.
'
expirationYear:
type: string
maxLength: 4
description: 'Four-digit year in which the credit card expires.
Format: `YYYY`.
'
type:
type: string
description: 'The type of card (Card Network).
Possible Values:
- 001: visa
**Required when source is ISSUER.**
'
passcode:
type: object
description: 'Passcode by issuer for ID&V.
'
properties:
value:
type: string
description: 'OTP generated at issuer.
'
billTo:
type: object
properties:
firstName:
type: string
maxLength: 60
description: 'Customer''s first name. This name must be the same as the name on the card.
'
example: John
lastName:
type: string
maxLength: 60
description: 'Customer''s last name. This name must be the same as the name on the card.
'
example: Doe
address1:
type: string
maxLength: 60
description: 'Payment card billing street address as it appears on the credit card issuer''s records.
'
example: 1 Market St
locality:
type: string
maxLength: 50
description: 'Payment card billing city.
'
example: San Francisco
administrativeArea:
type: string
maxLength: 20
description: 'State or province of the billing address. Use the State, Province, and Territory Codes for the United States
and Canada.
'
example: CA
postalCode:
type: string
maxLength: 10
description: 'Postal code for the billing address. The postal code must consist of 5 to 9 digits.
When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
**Example** `12345-6789`
When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha][numeric]
**Example** `A1B 2C3`
'
example: '94105'
country:
type: string
maxLength: 2
description: 'Payment card billing country. Use the two-character ISO Standard Country Codes.
'
example: US
email:
type: string
maxLength: 255
description: 'Customer''s email address, including the full domain name.
'
example: test@cybs.com
tags:
- Network Tokens
operationId: postTokenizedCard
x-devcenter-metaData:
categoryTag: Token_Management
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/tms/developer/all/rest/tms/tms-net-tkn-intro/tms-net-tkn-card-create-cof-intro.html
mleForRequest: optional
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
responses:
'200':
description: Returns an existing tokenized card associated with the supplied Id.
headers:
v-c-correlation-id:
description: The mandatory correlation Id passed by upstream (calling) system.
type: string
uniqueTransactionID:
description: A globally-unique Id associated with your request.
type: string
schema:
type: object
readOnly: true
properties:
_links:
type: object
readOnly: true
properties:
self:
type: object
properties:
href:
type: string
tokenizedCard:
type: object
properties:
id:
type: string
readOnly: true
description: 'The Id of the Tokenized Card.
'
object:
type: string
readOnly: true
example: tokenizedCard
description: 'The type.
Possible Values:
- tokenizedCard
'
source:
type: string
description: 'Source of the card details.
Possible Values:
- ONFILE
- TOKEN
- ISSUER
'
state:
type: string
readOnly: true
example: ACTIVE
description: "State of the network token or network token provision.\nPossible Values:\n - ACTIVE : Network token is active.\n - SUSPENDED : Network token is suspended. This state can change back to ACTIVE.\n - DELETED : This is a final state for a network token instance.\n - UNPROVISIONED : A previous network token.\n"
enrollmentId:
type: string
readOnly: true
description: 'Unique id to identify this PAN/ enrollment.
'
tokenReferenceId:
type: string
readOnly: true
description: 'Unique ID for netwrok token.
'
number:
type: string
readOnly: true
description: 'The token requestor''s network token for the provided PAN and consumer Id, if available.
'
expirationMonth:
type: string
readOnly: true
description: 'Two-digit month in which the network token expires.
Format: `MM`.
Possible Values: `01` through `12`.
'
expirationYear:
type: string
readOnly: true
description: 'Four-digit year in which the network token expires.
Format: `YYYY`.
'
type:
type: string
description: 'The type of card (Card Network).
Possible Values:
- visa
- mastercard
- americanexpress
'
reason:
type: string
readOnly: true
example: ACTIVE
description: 'Indicates the reason why the network token provision request failed.
Possible Values:
- INVALID_REQUEST : The network token provision request contained invalid data.
- CARD_VERIFICATION_FAILED : The network token provision request contained data that could not be verified.
- CARD_NOT_ELIGIBLE : Card can currently not be used with issuer for tokenization.
- CARD_NOT_ALLOWED : Card can currently not be used with card association for tokenization.
- DECLINED : Card can currently not be used with issuer for tokenization.
- SERVICE_UNAVAILABLE : The network token service was unavailable or timed out.
- SYSTEM_ERROR : An unexpected error occurred with network token service, check configuration.
'
cryptogram:
type: string
readOnly: true
description: 'Value generated by the card association to be used alongside the network token for processing a payment.
This field is returned by default for Visa and Mastercard network tokens.
It can also be explicitly requested using paymentCredentialType: CRYPTOGRAM.
'
example: CgAFRFYFPTFOfg5rj2ais9wQAAAAAM=
securityCode:
type: string
readOnly: true
description: 'Dynamic number generated by the card association to be used alongside the network token for processing a payment.
- For American Express: Dynamic Card Secure Code (DCSC) returned by default.
- For Visa: DTVV cryptogram when explicitly requested using paymentCredentialType: SECURITY_CODE.
It can also be explicitly requested using paymentCredentialType: SECURITY_CODE.
'
example: '4523'
eci:
type: string
readOnly: true
description: 'Raw Electronic Commerce Indicator provided by the card association with the result of the cardholder authentication.
'
requestorId:
type: string
readOnly: true
maxLength: 11
description: '11-digit identifier that uniquely identifies the Token Requestor.
'
paymentAccountReference:
type: string
readOnly: true
description: 'Payment account reference.
'
applicationTransactionCounter:
type: string
readOnly: true
description: 'A sequence counter used as part of the input to the TAVV cryptogram and it is incremented for each cryptogram generation.
This field is only returned for Visa network tokens.
'
card:
type: object
properties:
number:
type: string
minLength: 12
maxLength: 19
description: 'The latest customer''s payment card number associated to the network token.
'
expirationMonth:
type: string
maxLength: 2
description: 'Two-digit month in which the payment card expires.
Format: `MM`.
Possible Values: `01` through `12`.
'
expirationYear:
type: string
maxLength: 4
description: 'Four-digit year in which the credit card expires.
Format: `YYYY`.
'
type:
type: string
description: 'The type of card (Card Network).
Possible Values:
- 001: visa
- 002: mastercard
- 003: american express
- 007: jcb
'
suffix:
type: string
readOnly: true
description: 'The customer''s latest payment card number suffix.
'
issueDate:
type: string
readOnly: true
format: date
description: 'Card issuance date. XML date format: YYYY-MM-DD.'
example: '2030-12-15'
activationDate:
type: string
readOnly: true
format: date
description: 'Card activation date. XML date format: YYYY-MM-DD'
example: '2030-12-20'
expirationPrinted:
type: boolean
readOnly: true
description: Indicates if the expiration date is printed on the card.
example: true
securityCodePrinted:
type: boolean
readOnly: true
description: Indicates if the Card Verification Number is printed on the card.
example: true
termsAndConditions:
type: object
readOnly: true
properties:
url:
type: string
readOnly: true
description: Issuer Card Terms and Conditions url.
verificationResults:
type: object
description: 'Verification results returned by the issuer during the provisioning when Security Code or Billing Address data is provided on the request.
Supported only for VTS tokens.
'
readOnly: true
properties:
securityCode:
type: string
readOnly: true
description: 'Indicates whether the security code (CVV/CVC) was verified by the issuer during the provisioning request.
Supported only for VTS tokens.
Possible Values:
- MATCH: Verified, CVV2 data matched.
- NO_MATCH: Verified, CVV2 data did not match.
- NOT_SUPPORTED: Verification not supported by card issuer.
- SKIPPED: Verification was not performed.
'
address:
type: string
readOnly: true
description: 'Indicates whether the billing address was verified by the issuer during the provisioning request.
Supported only for VTS tokens.
Possible Values:
- MATCH: Verified, address and postal code data matched.
- PARTIAL_MATCH: Verified, either address data matched or postal code data matched.
- PARTIAL_MATCH_FORMAT_UNSUPPORTED: Verified, either address data matched or postal code data matched, but the other could not be verified due to format issues.
- NO_MATCH: Verified, address and postal code data did not match.
- NOT_SUPPORTED: Verification not supported by card issuer.
- SKIPPED: Verification was not performed.
'
metadata:
type: object
properties:
cardArt:
title: TmsCardArt
description: 'Card art associated with the tokenized card.
'
type: object
readOnly: true
properties:
foregroundColor:
description: 'Card foreground color.
'
type: string
readOnly: true
backgroundColor:
description: 'Card background color.
'
type: string
readOnly: true
labelColor:
description: 'Card label color.
'
type: string
readOnly: true
combinedAsset:
description: 'Combined card art asset associated with the tokenized card.
'
type: object
readOnly: true
properties:
id:
type: string
description: 'Unique identifier for the asset
'
_links:
type: object
readOnly: true
properties:
self:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the card art asset.
example: ''tms/v2/tokens/7020000000010603216/visa/assets/card-art-combined''
'
brandLogoAsset:
description: 'Brand logo card art asset associated with the tokenized card.
'
type: object
readOnly: true
properties:
id:
type: string
description: 'Unique identifier for the asset
'
_links:
type: object
readOnly: true
properties:
self:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the card art asset.
example: ''tms/v2/tokens/7020000000010603216/visa/assets/brand-logo''
'
issuerLogoAsset:
description: 'Issuer logo card art asset associated with the tokenized card.
'
type: object
readOnly: true
properties:
id:
type: string
description: 'Unique identifier for the asset
'
_links:
type: object
readOnly: true
properties:
self:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the card art asset.
example: ''tms/v2/tokens/7020000000010603216/visa/assets/issuer-logo''
'
iconAsset:
description: 'Icon card art asset associated with the tokenized card.
'
type: object
readOnly: true
properties:
id:
type: string
description: 'Unique identifier for the asset
'
_links:
type: object
readOnly: true
properties:
self:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the card art asset.
example: ''tms/v2/tokens/7020000000010603216/visa/assets/icon''
'
issuer:
description: 'Issuer associated with the tokenized card.
'
type: object
readOnly: true
properties:
name:
description: 'Issuer name.
'
type: string
readOnly: true
shortDescription:
description: 'Short description of the card.
'
type: string
readOnly: true
longDescription:
description: 'Long description of the card.
'
type: string
readOnly: true
email:
type: string
readOnly: true
description: 'Issuer customer service email address.
'
phoneNumber:
type: string
readOnly: true
description: 'Issuer customer service phone number.
'
url:
type: string
readOnly: true
description: 'Issuer customer service url.
'
privacyPolicyUrl:
type: string
readOnly: true
description: 'Issuer privacy policy url.
'
capabilities:
type: object
readOnly: true
description: 'Flags indicating what authentication, binding, and trusted-beneficiary enrollment capabilities the issuer supports.
Supported only for VTS Tokens.
'
properties:
deviceBindingSupported:
type: boolean
readOnly: true
description: 'Indicates if the issuer supports device binding.
'
cardholderVerificationSupported:
type: boolean
readOnly: true
description: 'Indicates if the issuer participates in step-up authentication that requires cardholder verification.
'
trustedBeneficiaryEnrollmentSupported:
type: boolean
readOnly: true
description: 'Indicates if the issuer supports trusted beneficiary enrollment.
e.g allowing cardholders to designate trusted merchants or payment recipients that can be exempt from step-up authentication.
'
delegatedAuthenticationSupported:
type: boolean
readOnly: true
description: 'Indicates if the issuer supports delegated authentication.
e.g allowing approved thrird parties to perform authentication on behalf of the issuer.
'
oboDeviceBindingSupported:
type: boolean
readOnly: true
description: 'Indicates if the issuer supports on-behalf-of device binding.
e.g allowing approved third parties to perform device binding on behalf of the issuer.
'
tokenLcmNotificationsSupported:
type: boolean
readOnly: true
description: 'Indicates if the issuer supports receiving token lifecycle management notifications.
e.g receiving updates on changes to the token''s status or attributes.
'
fpanLcmNotificationsSupported:
type: boolean
readOnly: true
description: 'Indicates if the issuer supports receiving PAN lifecycle management notifications.
e.g receiving updates on changes to the underlying card''s status or attributes.
'
bankApplications:
type: array
readOnly: true
items:
type: object
readOnly: true
properties:
name:
type: string
readOnly: true
description: 'Bank application name.
'
address:
type: string
readOnly: true
description: 'Bank application address. (e.g. com.mybank.app)
'
creator:
type: string
readOnly: true
description: The creator of the Tokenized Card.
'201':
description: A new tokenized card has been created.
headers:
Location:
description: Location of the Tokenized Card.
type: string
v-c-correlation-id:
description: The mandatory correlation Id passed by upstream (calling) system.
type: string
uniqueTransactionID:
description: A globally-unique Id associated with your request.
type: string
schema:
type: object
readOnly: true
properties:
_links:
type: object
readOnly: true
properties:
self:
type: object
properties:
href:
type: string
tokenizedCard:
type: object
properties:
id:
type: string
readOnly: true
description: 'The Id of the Tokenized Card.
'
object:
type: string
readOnly: true
example: tokenizedCard
description: 'The type.
Possible Values:
- tokenizedCard
'
source:
type: string
description: 'Source of the car
# --- truncated at 32 KB (205 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-network-tokens-api-openapi.yml