CyberSource Customer Payment Instrument API
A Customer Payment Instrument is linked to a Customer and an Instrument Identifier. It stores additional information in relation to a card number(PAN) or bank account (echeck).
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 Customer Payment Instrument API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Customer Payment Instrument
description: 'A Customer Payment Instrument is linked to a Customer and an Instrument Identifier.
It stores additional information in relation to a card number(PAN) or bank account (echeck).
'
paths:
/tms/v2/customers/{customerId}/payment-instruments:
post:
summary: Create a Customer Payment Instrument
description: '| | | |
| --- | --- | --- |
|**Customer Payment Instrument**<br>A Customer Payment Instrument represents tokenized customer payment information such as expiration date, billing address & card type.<br>A [Customer](#token-management_customer_create-a-customer) can have [one or more Payment Instruments](#token-management_customer-payment-instrument_retrieve-a-customer-payment-instrument), with one allocated as the Customers default for use in payments.<br>A Payment Instrument token does not store the card number. A Payment Instrument is associated with an [Instrument Identifier](#token-management_instrument-identifier_create-an-instrument-identifier) that represents either a payment card number, or in the case of an ACH bank account, the routing and account number.<br><br>**Creating a Customer Payment Instrument**<br>It is recommended you [create a Customer Payment Instrument via a Payment Authorization](#payments_payments_process-a-payment_samplerequests-dropdown_authorization-with-token-create_authorization-create-default-payment-instrument-shipping-address-for-existing-customer_liveconsole-tab-request-body), this can be for a zero amount.<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 Customers Payment Instrument**<br>To perform a payment with a particular Payment Instrument or Shipping Address specify the [Payment Instrument in the payment request](#payments_payments_process-a-payment_samplerequests-dropdown_authorization-using-tokens_authorization-with-customer-payment-instrument-and-shipping-address-token-id_liveconsole-tab-request-body).
'
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: customerId
in: path
description: The Id of a Customer.
required: true
type: string
minLength: 1
maxLength: 32
- name: postCustomerPaymentInstrumentRequest
in: body
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 Payment Instrument.
'
example: /tms/v2/customers/D9F340DD3DB9C276E053A2598D0A41A3/payment-instruments
customer:
type: object
readOnly: true
properties:
href:
type: string
readOnly: true
description: 'Link to the Customer.
'
example: /tms/v2/customers/D9F340DD3DB9C276E053A2598D0A41A3
id:
type: string
minLength: 1
maxLength: 32
description: The Id of the Payment Instrument Token.
object:
type: string
readOnly: true
example: paymentInstrument
description: 'The type.
Possible Values:
- paymentInstrument
'
default:
type: boolean
description: "Flag that indicates whether customer payment instrument is the dafault.\nPossible Values:\n - `true`: Payment instrument is customer's default.\n - `false`: Payment instrument is not customer's default.\n"
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
readOnly: true
description: 'The type of Payment Instrument.
Possible Values:
- cardHash
'
bankAccount:
type: object
properties:
type:
type: string
maxLength: 18
description: "Account type.\n\nPossible Values:\n - checking : C\n - general ledger : G This value is supported only on Wells Fargo ACH\n - savings : S (U.S. dollars only)\n - corporate checking : X (U.S. dollars only)\n"
card:
type: object
properties:
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: "Value that indicates the card type. Possible Values v2 : v1:\n * 001 : visa\n * 002 : mastercard - Eurocard—European regional brand of Mastercard\n * 003 : american express\n * 004 : discover\n * 005 : diners club\n * 006 : carte blanche\n * 007 : jcb\n * 008 : optima\n * 011 : twinpay credit\n * 012 : twinpay debit\n * 013 : walmart\n * 014 : enRoute\n * 015 : lowes consumer\n * 016 : home depot consumer\n * 017 : mbna\n * 018 : dicks sportswear\n * 019 : casual corner\n * 020 : sears\n * 021 : jal\n * 023 : disney\n * 024 : maestro uk domestic\n * 025 : sams club consumer\n * 026 : sams club business\n * 028 : bill me later\n * 029 : bebe\n * 030 : restoration hardware\n * 031 : delta online — use this value only for Ingenico ePayments. For other processors, use 001 for all Visa card types.\n * 032 : solo\n * 033 : visa electron\n * 034 : dankort\n * 035 : laser\n * 036 : carte bleue — formerly Cartes Bancaires\n * 037 : carta si\n * 038 : pinless debit\n * 039 : encoded account\n * 040 : uatp\n * 041 : household\n * 042 : maestro international\n * 043 : ge money uk\n * 044 : korean cards\n * 045 : style\n * 046 : jcrew\n * 047 : payease china processing ewallet\n * 048 : payease china processing bank transfer\n * 049 : meijer private label\n * 050 : hipercard — supported only by the Comercio Latino processor.\n * 051 : aura — supported only by the Comercio Latino processor.\n * 052 : redecard\n * 054 : elo — supported only by the Comercio Latino processor.\n * 055 : capital one private label\n * 056 : synchrony private label\n * 057 : costco private label\n * 060 : mada\n * 062 : china union pay\n * 063 : falabella private label\n"
issueNumber:
type: string
maxLength: 2
description: 'Number of times a Maestro (UK Domestic) card has been issued to the account holder. The card might or might not have an issue number. The number can consist of one or two digits, and the first digit might be a zero. When you include this value in your request, include exactly what is printed on the card. A value of 2 is different than a value of 02. Do not include the field, even with a blank value, if the card is not a Maestro (UK Domestic) card.
**Note** The issue number is not required for Maestro (UK Domestic) transactions.
'
startMonth:
type: string
maxLength: 2
description: 'Month of the start of the Maestro (UK Domestic) card validity period. Do not include the field, even with a blank value, if the card is not a Maestro (UK Domestic) card. `Format: MM`.
Possible Values: 01 through 12.
**Note** The start date is not required for Maestro (UK Domestic) transactions.
'
startYear:
type: string
maxLength: 4
description: 'Year of the start of the Maestro (UK Domestic) card validity period. Do not include the field, even with a blank value, if the card is not a Maestro (UK Domestic) card. `Format: YYYY`.
**Note** The start date is not required for Maestro (UK Domestic) transactions.
'
useAs:
type: string
example: pinless debit
description: '''Payment Instrument was created / updated as part of a pinless debit transaction.''
'
hash:
type: string
minLength: 32
maxLength: 34
readOnly: true
description: 'Hash value representing the card.
'
tokenizedInformation:
type: object
properties:
requestorID:
type: string
maxLength: 11
description: 'Value that identifies your business and indicates that the cardholder''s account number is tokenized. This value
is assigned by the token service provider and is unique within the token service provider''s database.
**Note** This field is supported only through **VisaNet** and **FDC Nashville Global**.
'
transactionType:
type: string
maxLength: 1
description: 'Type of transaction that provided the token data. This value does not specify the token service provider; it
specifies the entity that provided you with information about the token.
Set the value for this field to 1. An application on the customer''s mobile device provided the token data.
'
buyerInformation:
type: object
properties:
companyTaxID:
type: string
maxLength: 9
description: 'Company''s tax identifier. This is only used for eCheck service.
'
currency:
type: string
maxLength: 3
description: 'Currency used for the order. Use the three-character I[ISO Standard Currency Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf)
For an authorization reversal (`reversalInformation`) or a capture (`processingOptions.capture` is set to `true`), you must use the same currency that you used in your payment authorization request.
#### DCC for First Data
Your local currency. For details, see the `currency` field description in [Dynamic Currency Conversion For First Data Using the SCMP API](http://apps.cybersource.com/library/documentation/dev_guides/DCC_FirstData_SCMP/DCC_FirstData_SCMP_API.pdf).
# For details about currency as used in partial authorizations, see "Features for Debit Cards and Prepaid Cards" in the [Credit Card Services Using the SCMP API Guide](https://apps.cybersource.com/library/documentation/dev_guides/CC_Svcs_SCMP_API/html/)
'
dateOfBirth:
type: string
format: date
example: '1960-12-30'
description: 'Date of birth of the customer. Format: YYYY-MM-DD
'
personalIdentification:
type: array
items:
type: object
properties:
id:
type: string
maxLength: 26
description: 'The value of the identification type.
'
type:
type: string
description: "The type of the identification.\n\nPossible Values:\n - driver license\n"
issuedBy:
type: object
properties:
administrativeArea:
type: string
description: 'The State or province where the customer''s driver''s license was issued.
Use the two-character State, Province, and Territory Codes for the United States and Canada.
'
maxLength: 20
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.
'
lastName:
type: string
maxLength: 60
description: 'Customer''s last name. This name must be the same as the name on the card.
'
company:
type: string
maxLength: 60
description: 'Name of the customer''s company.
'
address1:
type: string
maxLength: 60
description: 'Payment card billing street address as it appears on the credit card issuer''s records.
'
address2:
type: string
maxLength: 60
description: 'Additional address information.
'
locality:
type: string
maxLength: 50
description: 'Payment card billing city.
'
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.
'
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`
'
country:
type: string
maxLength: 2
description: 'Payment card billing country. Use the two-character ISO Standard Country Codes.
'
email:
type: string
maxLength: 255
description: 'Customer''s email address, including the full domain name.
'
phoneNumber:
type: string
maxLength: 15
description: 'Customer''s phone number.
'
processingInformation:
type: object
title: tmsPaymentInstrumentProcessingInfo
properties:
billPaymentProgramEnabled:
type: boolean
description: 'Flag that indicates that this is a payment for a bill or for an existing contractual loan.
Possible Values:
- `true`: Bill payment or loan payment.
- `false` (default): Not a bill payment or loan payment.
# For processor-specific details, see the `bill_payment` field description in [Credit Card Services Using the SCMP API.](https://apps.cybersource.com/library/documentation/dev_guides/CC_Svcs_SCMP_API/html/)
'
bankTransferOptions:
type: object
properties:
SECCode:
type: string
maxLength: 3
description: 'Specifies the authorization method for the transaction.
#### TeleCheck
Possible Values:
- `ARC`: account receivable conversion
- `CCD`: corporate cash disbursement
- `POP`: point of purchase conversion
- `PPD`: prearranged payment and deposit entry
- `TEL`: telephone-initiated entry
- `WEB`: internet-initiated entry
# For details, see `ecp_sec_code` field description in the [Electronic Check Services Using the SCMP API Guide.](https://apps.cybersource.com/library/documentation/dev_guides/EChecks_SCMP_API/html/)
'
merchantInformation:
type: object
title: TmsMerchantInformation
properties:
merchantDescriptor:
type: object
properties:
alternateName:
type: string
description: 'Alternate contact information for your business,such as an email address or URL.
This value might be displayed on the cardholder''s statement.
When you do not include this value in your capture or credit request, the merchant URL from your CyberSource account is used.
Important This value must consist of English characters
'
maxLength: 13
instrumentIdentifier:
type: object
properties:
id:
type: string
minLength: 12
maxLength: 32
description: 'The Id of the Instrument Identifier linked to the Payment Instrument.
'
metadata:
type: object
readOnly: true
properties:
creator:
type: string
readOnly: true
description: 'The creator of the Payment Instrument.
'
_embedded:
type: object
readOnly: true
description: 'Additional resources for the Payment Instrument.
'
properties:
instrumentIdentifier:
readOnly: true
title: tmsEmbeddedInstrumentIdentifier
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.
Possibl
# --- truncated at 32 KB (608 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-customer-payment-instrument-api-openapi.yml