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.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cybersource-instrument-identifier-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.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
servers:
- url: https://apitest.cybersource.com/
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
x-hide-field: true
schema:
type: string
maxLength: 36
minLength: 36
- name: retrieveBinDetails
in: query
description: Retrieve the Bin Details of PAN or network token
required: false
schema:
type: boolean
tags:
- Instrument Identifier
operationId: postInstrumentIdentifier
x-devcenter-metaData:
categoryTag: Token_Management
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/tms/developer/all/rest/tms/tms-ii-tkn/tms-manage-ii-tkn/tms-ii-tkn-create-intro.html
mleForRequest: optional
responses:
'200':
description: Returns an existing Instrument Identifier associated with the supplied Id.
headers:
ETag:
description: An ETag is an identifier assigned to a specific version of a resource.
schema:
type: string
v-c-correlation-id:
description: The mandatory correlation Id passed by upstream (calling) system.
schema:
type: string
uniqueTransactionID:
description: A globally-unique Id associated with your request.
schema:
type: string
content:
application/json;charset=utf-8:
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 c
# --- truncated at 32 KB (647 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-instrument-identifier-api-openapi.yml