v1

latestOpenAPI 3.0.22026-08-061303782.1 MB

Payment Instruments

Verify CVV, AVS, and Name

Verify a Payment Instrument to determine CVV, AVS, and name verification results.

{% admonition type="warning" name="PCI Scope Restriction" %} CVV submission is only available to PCI-compliant merchants. Non-PCI customers should not collect and pass CVV in this request. {% /admonition %}

put/payment_instruments/{payment_instrument_id_verify}

Request body

Response

A single Payment Instrument.

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

created_via'API'

The method by which the resource was created.

account_updater_enabledboolean

When enabled, Finix automatically checks for updates with card networks. This Account Updater functionality:

Automatically updates card details (e.g., number or expiration date) to maintain continuity of charges, increasing authorization rates.
Saves the cardholder the hassle of updating card details across Merchants for each of their Subscriptions.

Note: Cards created before the feature is enabled are unaffected by default. To include these cards, you can manually enable the Account Updater functionality for each card individually using a PUT request. Once enabled, you can link the card to this API call to trigger updates with card networks.

Details the results of verifying address with the issuing bank.
Set to UNKNOWN when address gets updated.

applicationstring

ID of the Application the resource was created under.

binstring

Bank Identification number for the Payment Instrument.

The brand of the card saved in the Payment Instrument.

The type of payment card saved in the Payment Instrument.

country'ABW' | 'AFG' | 'AGO' | 'AIA' | 'ALA' | 'ALB' | 'AND' | 'ARE' | 'ARG' | 'ARM' | 'ASM' | 'ATA' | 'ATF' | 'ATG' | 'AUS' | 'AUT' | 'AZE' | 'BDI' | 'BEL' | 'BEN' | 'BES' | 'BFA' | 'BGD' | 'BGR' | 'BHR' | 'BHS' | 'BIH' | 'BLM' | 'BLR' | 'BLZ' | 'BMU' | 'BOL' | 'BRA' | 'BRB' | 'BRN' | 'BTN' | 'BVT' | 'BWA' | 'CAF' | 'CAN' | 'CCK' | 'CHE' | 'CHL' | 'CHN' | 'CIV' | 'CMR' | 'COD' | 'COG' | 'COK' | 'COL' | 'COM' | 'CPV' | 'CRI' | 'CUB' | 'CUW' | 'CXR' | 'CYM' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DMA' | 'DNK' | 'DOM' | 'DZA' | 'ECU' | 'EGY' | 'ERI' | 'ESH' | 'ESP' | 'EST' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FRA' | 'FRO' | 'FSM' | 'GAB' | 'GBR' | 'GEO' | 'GGY' | 'GHA' | 'GIB' | 'GIN' | 'GLP' | 'GMB' | 'GNB' | 'GNQ' | 'GRC' | 'GRD' | 'GRL' | 'GTM' | 'GUF' | 'GUM' | 'GUY' | 'HKG' | 'HMD' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IMN' | 'IND' | 'IOT' | 'IRL' | 'IRN' | 'IRQ' | 'ISL' | 'ISR' | 'ITA' | 'JAM' | 'JEY' | 'JOR' | 'JPN' | 'KAZ' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'KNA' | 'KOR' | 'KWT' | 'LAO' | 'LBN' | 'LBR' | 'LBY' | 'LCA' | 'LIE' | 'LKA' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'MAC' | 'MAF' | 'MAR' | 'MCO' | 'MDA' | 'MDG' | 'MDV' | 'MEX' | 'MHL' | 'MKD' | 'MLI' | 'MLT' | 'MMR' | 'MNE' | 'MNG' | 'MNP' | 'MRT' | 'MSR' | 'MTQ' | 'MUS' | 'MWI' | 'MYS' | 'MYT' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NIU' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NZL' | 'OMN' | 'PAK' | 'PAN' | 'PCN' | 'PER' | 'PHL' | 'PLW' | 'PNG' | 'POL' | 'PRI' | 'PRK' | 'PRT' | 'PRY' | 'PSE' | 'PYF' | 'QAT' | 'REU' | 'ROU' | 'RUS' | 'RWA' | 'SAU' | 'SDN' | 'SEN' | 'SGP' | 'SGS' | 'SHN' | 'SJM' | 'SLB' | 'SLE' | 'SLV' | 'SMR' | 'SOM' | 'SPM' | 'SRB' | 'SSD' | 'STP' | 'SUR' | 'SVK' | 'SVN' | 'SWE' | 'SWZ' | 'SXM' | 'SYC' | 'SYR' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TKM' | 'TLS' | 'TON' | 'TTO' | 'TUN' | 'TUR' | 'TUV' | 'TWN' | 'TZA' | 'UGA' | 'UKR' | 'UMI' | 'URY' | 'USA' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'ZAF' | 'ZMB' | 'ZWE' nullable

currency'CAD' | 'USD'

ISO 4217 3-letter currency code.

A code indicating why the Payment Instrument was disabled. This field is set when:

The system automatically disables the Payment Instrument.
A user manually disables it (returns USER_INITIATED).

See disabled_message for all possible codes and their descriptions.

disabled_messagestring nullable

A human-readable message explaining why the Payment Instrument was disabled. This field provides additional context for the disabled_code.

The possible error codes/messages are:

CARD_ACCOUNT_CLOSED: "The card account has been closed. The card has been disabled to prevent further use."
INVALID_ACCOUNT_NUMBER: "The card number is not valid. The card has been disabled to prevent further use."
LOST_OR_STOLEN_CARD: "The card is reported lost or stolen. The card has been disabled to prevent further use."
NON_RELOADABLE_INSUFFICIENT_FUNDS: "The card has insufficient funds for the transaction and is non-reloadable. The card has been disabled to prevent further use."
PICK_UP_CARD: "The card is reported lost or stolen. The card has been disabled to prevent further use."
RESTRICTED_CARD: "The card has a restriction preventing approval for this transaction. The card has been disabled to prevent further use."
USER_INITIATED: "The card has been disabled by a user."

enabledboolean

Indicates whether the Payment Instrument resource is enabled. The default value is true; set it to false to disable the Payment Instrument. The user or the system can update this field to enable or disable the payment instrument.

expiration_monthinteger

Expiration month (e.g. 12 for December).

expiration_yearinteger

4-digit expiration year.

fast_funds_indicatorstring

Details if Fast Funds is enabled for the card.

fingerprintstring

Unique ID that represents the tokenized card data.

identitystring

The ID of the Identity used to create the resource.

instrument_type'PAYMENT_CARD' | 'PAYMENT_CARD_PRESENT' | 'TOKEN'

The type of Payment Instrument.

issuer_country'ABW' | 'AFG' | 'AGO' | 'AIA' | 'ALA' | 'ALB' | 'AND' | 'ARE' | 'ARG' | 'ARM' | 'ASM' | 'ATA' | 'ATF' | 'ATG' | 'AUS' | 'AUT' | 'AZE' | 'BDI' | 'BEL' | 'BEN' | 'BES' | 'BFA' | 'BGD' | 'BGR' | 'BHR' | 'BHS' | 'BIH' | 'BLM' | 'BLR' | 'BLZ' | 'BMU' | 'BOL' | 'BRA' | 'BRB' | 'BRN' | 'BTN' | 'BVT' | 'BWA' | 'CAF' | 'CAN' | 'CCK' | 'CHE' | 'CHL' | 'CHN' | 'CIV' | 'CMR' | 'COD' | 'COG' | 'COK' | 'COL' | 'COM' | 'CPV' | 'CRI' | 'CUB' | 'CUW' | 'CXR' | 'CYM' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DMA' | 'DNK' | 'DOM' | 'DZA' | 'ECU' | 'EGY' | 'ERI' | 'ESH' | 'ESP' | 'EST' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FRA' | 'FRO' | 'FSM' | 'GAB' | 'GBR' | 'GEO' | 'GGY' | 'GHA' | 'GIB' | 'GIN' | 'GLP' | 'GMB' | 'GNB' | 'GNQ' | 'GRC' | 'GRD' | 'GRL' | 'GTM' | 'GUF' | 'GUM' | 'GUY' | 'HKG' | 'HMD' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IMN' | 'IND' | 'IOT' | 'IRL' | 'IRN' | 'IRQ' | 'ISL' | 'ISR' | 'ITA' | 'JAM' | 'JEY' | 'JOR' | 'JPN' | 'KAZ' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'KNA' | 'KOR' | 'KWT' | 'LAO' | 'LBN' | 'LBR' | 'LBY' | 'LCA' | 'LIE' | 'LKA' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'MAC' | 'MAF' | 'MAR' | 'MCO' | 'MDA' | 'MDG' | 'MDV' | 'MEX' | 'MHL' | 'MKD' | 'MLI' | 'MLT' | 'MMR' | 'MNE' | 'MNG' | 'MNP' | 'MOZ' | 'MRT' | 'MSR' | 'MTQ' | 'MUS' | 'MWI' | 'MYS' | 'MYT' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NIU' | 'NLD' | 'NON_USA' | 'NOR' | 'NPL' | 'NRU' | 'NZL' | 'OMN' | 'PAK' | 'PAN' | 'PCN' | 'PER' | 'PHL' | 'PLW' | 'PNG' | 'POL' | 'PRI' | 'PRK' | 'PRT' | 'PRY' | 'PSE' | 'PYF' | 'QAT' | 'REU' | 'ROU' | 'RUS' | 'RWA' | 'SAU' | 'SDN' | 'SEN' | 'SGP' | 'SGS' | 'SHN' | 'SJM' | 'SLB' | 'SLE' | 'SLV' | 'SMR' | 'SOM' | 'SPM' | 'SRB' | 'SSD' | 'STP' | 'SUR' | 'SVK' | 'SVN' | 'SWE' | 'SWZ' | 'SXM' | 'SYC' | 'SYR' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TKM' | 'TLS' | 'TON' | 'TTO' | 'TUN' | 'TUR' | 'TUV' | 'TWN' | 'TZA' | 'UGA' | 'UKR' | 'UMI' | 'UNKNOWN' | 'URY' | 'USA' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'YEM' | 'ZAF' | 'ZMB' | 'ZWE'

The Alpha-3 Code of the country the card was issued in.

In addition, the following values are possible:

NON_USA - The card was issued outside of the United States.
UNKNOWN - The processor did not return an issuer country for this particular BIN.

last_fourstring

Last four digits of the card.

namestring nullable

The name of the card owner.

network_token_enabledboolean

When enabled, a "network token" replaces raw card details (e.g., the 16-digit PAN and expiration date) for transactions. Network tokens have several benefits:

The token offers increased authorization rates, even for lost or stolen cards, as it remains valid while the physical card is replaced.
Visa reduces interchange fees when using network tokens.
Tokens enhance security by replacing card details with a non-sensitive string that is usable only within the Finix system.

Note: Cards created before the feature is enabled are unaffected. To include them, update the individual Payment Instrument to set network_token_enabled to true.

The state of the network token. The possible enum values are as follows:

NOT_ENABLED: The network_token_state is NOT_ENABLED when the value of network_token_enabled on the Payment Instrument is false.
PENDING: Immediately after Finix enables network tokens for a specific card, network_token_state is initially set to PENDING.
ACTIVE: After Finix receives the network token successfully from the card network, network_token_state updates to ACTIVE.
FAILED: In the event that there is an issue with the card network such as service becomes unavailable, FAILED is returned.
SUSPENDED: When the issuing bank does not allow the network token to be used in transactions, SUSPENDED is returned.
CLOSED: In the event that the issuing bank has closed the card permanently, CLOSED is returned.

payload_type'SOURCE' | 'DESTINATION'

push_funds_block_indicatorstring

Details if the card is enabled to receive push-to-card disbursements.

security_code_verification'MATCHED' | 'UNKNOWN' | 'UNMATCHED'

Details the results of the Card Verification Code check.

tagsTags nullable

Include up to 50 key: value pairs to annotate requests with custom metadata.

Maximum character length for individual keys is 40.
Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)

third_partystring nullable

This field is not applicable to payment cards.

third_party_tokenstring nullable

This field is not applicable to payment cards.

type'PAYMENT_CARD' | 'TOKEN' | 'GOOGLE_PAY' | 'APPLE_PAY'

Type of Payment Instrument.

Example response

{
  "fingerprint": "FPRxxxxxxxxxxxxxxxxx"
}