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.

Related Guides: Using Hosted Fields, Getting Started

Create a Payment Instrument

Create a Payment Instrument resource using a card or bank account.

  • 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.
Request
Request Body schema: application/hal+json
Any of:
object

The address of the card owner.

expiration_month
integer

The expiration month of the card (e.g. 12 for December).

expiration_year
integer

The 4-digit expiration year of the card.

identity
string

The ID of the Identity used to create the Payment Instrument resource.

name
string

The name of the bank account or card owner. This value can get truncated to comply with processor requirements.

number
string

The card or bank account number (no dashes in between numbers).

security_code
string

The 3-4 digit security code of the card (i.e. CVV code).

tags
object or null

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.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

type
string

Type of Payment Instrument.

Value: "PAYMENT_CARD"
third_party_token
string

Stringified token provided by Apple or Google. Required if using Apple or Google Pay.

Responses
201

Single Payment Instrument object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/payment_instruments
Request samples 
Response samples 
application/hal+json
{}
List Payment Instruments
Retrieve a list of Payment Instruments.


Request 
query Parameters
account_last4
string
Filter by the last 4 digits of the account if available.


 
 Example:  account_last4=9444
account_routing_number
string
Filter by the account routing number if available.


 
 Example:  account_routing_number=9444
after_cursor
string
Return every resource created after the cursor value.


 
application
string
Filter by Application ID.


 
before_cursor
string
Return every resource created before the cursor value.


 
bin
string
Filter by Bank Identification Number (BIN). The BIN is the first 6 digits of the masked number.


 
 Example:  bin=489514
created_at.gte
string
Filter where created_at is after the given date.


 
 Example:  created_at.gte=2022-09-27T11:21:23
created_at.lte
string
Filter where created_at is before the given date.


 
 Example:  created_at.lte=2022-09-27T11:21:23
expiration_month
string
Filter by the expiration month associated with the Payment Instrument if applicable. This filter only applies to payment cards.


 
 Example:  expiration_month=1
expiration_year
string
Filter by the 4 digit expiration year associated with the Payment Instrument if applicable. This filter only applies to payment cards.


 
 Example:  expiration_year=2022
last_four
string
Filter by the last 4 digits of the Payment Instrument card. This filter only applies to payment cards.


 
 Example:  last_four=0454
limit
integer
The numbers of items to return.


 
 Example:  limit=10
name
string
Filter by the name.


 
 Example:  name=john%20smith
owner_identity_id
string
Filter by the owner id of the associated Identity.


 
 Example:  owner_identity_id=IDcWwprrKrD6cSh225JWPri3
type
string
Filter by the Payment Instrument type.


 Enum: "ALL" "BANK_ACCOUNT" "PAYMENT_CARD"  
 Example:  type=BANK_ACCOUNT
Responses 
200
List of Payment Instrument objects


401
Authentication information is missing or invalid


403
Forbidden


406
Not Acceptable


get/payment_instruments
Request samples 
curl https://finix.sandbox-payments-api.com/payment_instruments \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}
Fetch a Payment Instrument
Retrieve the details of a Payment Instrument.


Request 
path Parameters
payment_instrument_id
required
string
ID of object


 
Responses 
200
Single Payment Instrument object


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


422
Invalid field


get/payment_instruments/{payment_instrument_id}
Request samples 
curl https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}
Update a Payment Instrument
Update a Payment Instrument to:


    

  • Change the billing address in case the account holder moved (instrument_type:PAYMENT_CARD only).
    • 

  • Change the CVV and reverify the instrument in case the account holder was issued a new card (instrument_type:PAYMENT_CARD only).
    • 

  • Disable the Payment Instrument resource so it can't be used in requests.
    • 

  • Change the tags.
    • 



Request 
path Parameters
payment_instrument_id
required
string
ID of object


 
Request Body schema: application/hal+json
object or null
Address of the account owner.


 
enabled
boolean
Details if the Payment Instrument resource is enabled. Default value is true; set to false to disable the Payment Instrument.


 
merchant
string
ID of the Merchant processing the transaction.


 
security_code
string
The new 3-4 digit security code for the card (i.e. CVV code).


 
tags
object or null
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.
    • 



(e.g., order number: 25, item_type: produce, department: sales, etc.)


 
verify_payment_card
boolean
    

  • Set to true to verify card details with the card issuer.
    • 

  • Must be set to true to update the CVV or security code of a card.
    • 



 
Responses 
200
Single Payment Instrument object


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


put/payment_instruments/{payment_instrument_id}
Request samples 
Response samples 
application/hal+json
{}
Verify a Payment Instrument
Verify a Payment Instrument to determine if it's eligible for Push To Card transactions. 


    

  • Only verify Payment Instruments for Push To Card customers.
    • 



Request 
path Parameters
payment_instrument_id
required
string
ID of Payment Instrument object.


 
Request Body schema: application/hal+json
identity
string
ID of the Identity resource associated with the Merchant.


 
merchant
string
The ID of the Merchant.


 
tags
object or null
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.
    • 



(e.g., order number: 25, item_type: produce, department: sales, etc.)


 
processor
string or null
Set the acquiring processor. Avalible values include: 
  • DUMMY_V1
  • LITLE_V1
  • MASTERCARD_V1
  • VISA_V1
  • NMI_V1
  • VANTIV_V1
Use DUMMY_V1 or  null to use your sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.


 
Responses 
201
Single Verification object


400
Error


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


post/payment_instruments/{payment_instrument_id}/verifications
Request samples 
curl https://finix.sandbox-payments-api.com/payment_instruments/PIwWisLuZNwPBoLbCgQVTCoY/verifications \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '
  {
    "identity": "ID2CGJmjqyYaQAu6qyuvGeWK",
    "merchant": "MUgWbPVvtKbzjKNNGKqdQYV7",
    "tags": {
      "card_name": "Business_Card"
    }
  }'
Response samples 
application/hal+json
{}
Create an Apple Pay Session
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.


Request 
Request Body schema: application/hal+json
display_name
string
This will be the merchant name shown to users when making a purchase via Apple Pay.


 
domain
string
The domain (or website) where the buyer is initiating the payment.


 
merchant_identity
string
The merchant_identity_id used when registering the business with Apple Pay through our registration API.


 
validation_url
string
A unique validation URL that will be provided by the Apple SDK front-end for every payment.


 
Responses 
200
Single apple_pay_session object


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


post/apple_pay_sessions
Request samples 
curl https://finix.sandbox-payments-api.com/apple_pay_sessions \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '
  {
    "display_name": "Finix Test Merchant",
    "domain": "www.finixtestmerchant.com",
    "merchant_identity": "IDmULj61C8ke6Y7qQiKENJ7",
    "validation_url": "https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession"
  }'
Response samples 
application/hal+json
{
  • "id": "APPLEPAYSESSION_xxx",
  • "created_at": "2021-11-22T23:58:19.50Z",
  • "updated_at": "2021-11-22T23:58:19.50Z",
  • "session_details": "{\"epochTimestamp\":1640213041060,\"expiresAt\":1640216641060,\"merchantSessionIdentifier\":\"SSH1524BA9006A944B8B9B8FB60227D9990_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\"nonce\":\"a5ee8554\",\"merchantIdentifier\":\"23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"domainName\":\"tj.ngrok.io\",\"displayName\":\"Christmas Shopping\",\"signature\":\"...\",\"operationalAnalyticsIdentifier\":\"Christmas Shopping:23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"retries\":0}",
  • "_links": {}
}