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
header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/json
Any of:
object

The address of the card owner.

Note: Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions.

expiration_month
required
integer

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

expiration_year
required
integer

The 4-digit expiration year of the card.

identity
required
string

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

name
required
string

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

number
required
string

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

security_code
required
string

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

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. (For example, order_number: 25, item_type: produce, department: sales)
type
required
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

422

Invalid field

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


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


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


 
 Example:  account_last4=4242
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.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
application
string
Filter by Application ID.


 
 Example:  application=APgPDQrLD52TYvqazjHJJchM
before_cursor
string
Return every resource created before the cursor value.


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


 
 Example:  bin=411111
created_at.gte
string <date-time> 
Filter where created_at is after the given date.


 
 Example:  created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time> 
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=9
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=2029
last4
string
Filter by the last 4 digits of the Payment Instrument card. This filter only applies to payment cards.


 
 Example:  last4=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
tags.key
string
Filter by the tag's key. For more information, see Tags.


 
 Example:  tags.key=card_type
tags.value
string
Filter by the tag's value. For more information, see Tags.


 
 Example:  tags.value=business_card
header Parameters
Accept
string
 Default:  application/hal+json
Body Header


 
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

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


Request 
path Parameters
payment_instrument_id
required
string
ID of object


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Responses 
200
Response schema and example when fetching a Payment Instrument.


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/PI8uU6wfi6hqBoWmzm9L4F2b" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/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).
    • 

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

  • Update the name on the Payment Instrument.
    • 

  • Change the tags.
    • 



Request 
path Parameters
payment_instrument_id
required
string
ID of object


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Request Body schema: application/json
Any of:
required
object or null
Address of the account owner.


 
merchant
required
string
 Default:  false
The ID of the Merchant that the Payment Instrument will be created under.


 
verify_payment_card
required
boolean
 Default:  false
    

  • 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.
    • 

  • When set to true, merchant must also be included with your request.
    • 



 
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.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
Responses 
200
Example responses when updating a Payment Instrument.


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/json
{}
Verify a Payment Instrument
Verify a Payment Instrument to determine CVV and AVS results.


You can also determine Push To Card eligibility for Push To Card customers.


Request 
path Parameters
payment_instrument_id_verify
required
string
 
header Parameters
Accept
string
 Default:  application/hal+json
 
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Request Body schema: application/json
Any of:
merchant
required
string
    

  • The ID of the Merchant.
    • 

  • Must be included when verify_payment_card is set to true.
    • 



 
processor
string
 Default:  "DUMMY_V1"
Set the acquiring processor. Available values include: 
  • DUMMY_V1
  • FINIX_V1
  • MASTERCARD_V1
  • VISA_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


 Enum: "DUMMY_V1" "MASTERCARD_V1" "VISA_V1"  
security_code
required
string
The ID of the Merchant.


 
verify_payment_card
required
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.
    • 

  • When set to true, merchant must also be included with your request.
    • 



 
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.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
Responses 
201
Single Verification object


400
Error


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


put/payment_instruments/{payment_instrument_id_verify}
Request samples 
Response samples 
application/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/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/json" \
  -H "Finix-Version: 2022-02-01" \
  -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/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": {}
}