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}",
}