CyberSource Instrument Identifier API
An Instrument Identifier represents a unique card number(PAN) or bank account (echeck). It can also be associated with a Network Token that can be used for payment transactions.
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 Instrument Identifier API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Instrument Identifier
description: 'An Instrument Identifier represents a unique card number(PAN) or bank account (echeck).
It can also be associated with a Network Token that can be used for payment transactions.
'
paths:
/tms/v1/instrumentidentifiers:
post:
summary: Create an Instrument Identifier
description: '| | | |
| --- | --- | --- |
|**Instrument Identifiers**<br>An Instrument Identifier represents either a card number, or in the case of an ACH bank account, the routing and account number.<br>The same token Id is returned for a specific card number or bank account & routing number allowing the Instrument Identifier Id to be used for cross-channel payment tracking.<br>An Instrument Identifier can exist independently but also be associated with a [Customer Payment Instrument](#token-management_customer-payment-instrument_create-a-customer-payment-instrument) or [Standalone Payment Instrument](#token-management_payment-instrument_create-a-payment-instrument).<br><br>**Creating an Instrument Identifier**<br>It is recommended you [create an Instrument Identifier via a Payment Authorization](#payments_payments_process-a-payment_samplerequests-dropdown_authorization-with-token-create_authorization-with-instrument-identifier-token-creation_liveconsole-tab-request-body), this can be for a zero amount.<br>An Instrument Identifier will also be created if you [create a Customer via a Payment Authorization](#payments_payments_process-a-payment_samplerequests-dropdown_authorization-with-token-create_authorization-with-customer-token-creation_liveconsole-tab-request-body)<br>In Europe: You should perform Payer Authentication alongside the Authorization.| |**Payment Network Tokens**<br>Network tokens perform better than regular card numbers and they are not necessarily invalidated when a cardholder loses their card, or it expires.<br>A Payment Network Token will be automatically created and used in future payments if you are enabled for the service.<br>A Payment Network Token can also be [provisioned for an existing Instrument Identifier](#token-management_instrument-identifier_enroll-an-instrument-identifier-for-payment-network-token).<br>For more information about Payment Network Tokens see the Developer Guide.<br><br>**Payments with Instrument Identifiers**<br>To perform a payment with an Instrument Identifier simply specify the [Instrument Identifier Id in the payments request along with the expiration date, card type, & billing address](#payments_payments_process-a-payment_samplerequests-dropdown_authorization-using-tokens_authorization-with-instrument-identifier-token-id_liveconsole-tab-request-body).<br>When an Instrument Identifier is used in a payment the **_previousTransactionId_** and **_originalAuthorizedAmount_** values are automatically recorded.<br>These values will be added for you to future Merchant Initiated Transaction payments.
'
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: retrieveBinDetails
in: query
description: Retrieve the Bin Details of PAN or network token
required: false
type: boolean
- name: postInstrumentIdentifierRequest
in: body
description: Specify either a Card, Bank Account or Enrollable Card
required: true
schema:
type: object
properties:
_links:
type: object
readOnly: true
properties:
self:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the Instrument Identifier.
'
example: tms/v1/instrumentidentifiers/7010000000016241111
paymentInstruments:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the Instrument Identifiers Payment Instruments.
'
example: tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments
tokenized-cards:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the Tokenized Card if network token is present.
'
example: tms/v2/tokenized-cards/352DAB7D2F3A9511E063AF598E0A2FE3
id:
type: string
description: 'The Id of the Instrument Identifier Token.
'
object:
type: string
readOnly: true
example: instrumentIdentifier
description: 'The type.
Possible Values:
- instrumentIdentifier
'
state:
type: string
readOnly: true
example: ACTIVE
description: 'Issuers state for the card number.
Possible Values:
- ACTIVE
- CLOSED : The account has been closed.
'
type:
type: string
description: 'The type of Instrument Identifier.
Possible Values:
- enrollable card
- enrollable token
'
source:
type: string
description: 'Source of the card details.
Possible Values:
- CONTACTLESS_TAP
'
tokenProvisioningInformation:
type: object
properties:
consumerConsentObtained:
type: boolean
description: 'Flag that indicates whether the user consented to the tokenization of their credentials. Required for card network tokenization in certain markets, such as India.
Possible Values:
- `true`: Consumer has consented to tokenization of their credentials.
- `false`: Consumer has not consented to tokenization of their credentials.
'
multiFactorAuthenticated:
type: boolean
description: 'Flag that indicates whether AFA (Additional Factor of Authentication) for the PAN was completed. Required for card network tokenization in certain markets, such as India.
Possible Values:
- `true`: Consumer has been authenticated by the issuer.
- `false`: Consumer has not been authenticated by the issuer.
'
card:
type: object
description: 'The expirationMonth, expirationYear and securityCode is sent to the issuer as part of network token enrollment and is not stored under the Instrument Identifier.
'
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`.
'
securityCode:
type: string
maxLength: 4
description: "Card Verification Code. \nThis value is sent to the issuer to support the approval of a network token provision.\nIt is not persisted against the Instrument Identifier.\n"
pointOfSaleInformation:
type: object
required:
- emvTags
properties:
emvTags:
type: array
minItems: 1
maxItems: 50
items:
type: object
required:
- tag
- value
- source
properties:
tag:
type: string
minLength: 1
maxLength: 10
pattern: ^[0-9A-Fa-f]{1,10}$
description: EMV tag, 1-10 hex characters.
value:
type: string
minLength: 1
maxLength: 64
description: EMV tag value, 1-64 characters.
source:
type: string
description: "Source of the tag.\n\nPossible Values:\n - CARD\n - TERMINAL\n"
example:
tag: 5A
value: '4111111111111111'
source: CARD
bankAccount:
type: object
properties:
number:
type: string
maxLength: 17
description: 'Account number.
When processing encoded account numbers, use this field for the encoded account number.
'
routingNumber:
type: string
description: 'Bank routing number. This is also called the transit number.
# For details, see `ecp_rdfi` field description in the [Electronic Check Services Using the SCMP API Guide.](https://apps.cybersource.com/library/documentation/dev_guides/EChecks_SCMP_API/html/)
'
tokenizedCard:
title: tmsv2TokenizedCard
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:
# --- truncated at 32 KB (610 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-instrument-identifier-api-openapi.yml