Payment Instruments

A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument.

A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.

Including an address when creating a Payment Instrument can lower interchange on credit card transactions.

Create a Payment Instrument

• POST /payment_instruments: Create a Payment Instrument resource using a card or bank account.

{% admonition type="warning" name="Payment Instruments PCI Scope" %} The creation of Payment Instruments directly via Finix's API should only be done for testing purposes. You must use our hosted fields or the javascript client to remain out of PCI scope. {% /admonition %}

List Payment Instruments

• GET /payment_instruments: Retrieve a list of Payment Instrument resources.

For details on how to query endpoints using the available parameters, see Query Parameters.

{% admonition type="info" %} If no query parameters are specified in the request the API automatically limits the response to records from the last 30 days. You can request older data by passing an explicit created_at.lte filter. {% /admonition %}

Fetch a Payment Instrument

• GET /payment_instruments/{payment_instrument_id}: Retrieve the details of an existing Payment Instrument.

Update a Payment Instrument

• PUT /payment_instruments/{payment_instrument_id}: Update a Payment Instrument to:
  • Change the billing address in case the account holder moved (instrument_type:PAYMENT_CARD only).
  • Disable the Payment Instrument resource so it can't be used in requests.
  • Update the name on the Payment Instrument.
  • Change the tags.
  • Enable or disable Account Updater.
  • Enable or disable Network Tokens.
  • Update the expiration date (instrument_type:PAYMENT_CARD only).

List Instrument History Entries

• GET /payment_instruments/{payment_instrument_id}/instrument_history: Whenever a stored payment card's details are updated, an Instrument History Entry is created. Use this endpoint to retrieve a list of Instrument History Entries for a specific Payment Instrument.

Verify CVV, AVS, and Name

• PUT /payment_instruments/{payment_instrument_id_verify}: 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 %}

Verify Push-to-Card Eligibility

• POST /payment_instruments/{payment_instrument_id_verify}/verifications: Determine Push To Card eligibility for Push To Card customers.

Additionally, the cardholder's name is verified with the issuing bank, and the result is shown in name_verification_results. This applies to Visa and Mastercard.

Create an Apple Pay Session

• POST /apple_pay_sessions: Create an apple_pay_session to process Apple Pay transactions on the web.

To create an Apple Pay Session, pass the unique validation_url (provided by Apple) while creating an apple_pay_sessions resource. Finix returns a merchantSession object that you can use to create a payment. For more information, see Apple Pay.