Deprecated API Reference

This API Reference is being deprecated. Please use the New API Reference.

Associate a Token

Associate the newly tokenized payment card or bank account with the Payment Instrument owner's Identity.

warning

Tokens should be associated immediately. Tokens that fail to associate with a Payment Instrument within 30 minutes of creation get invalidated.

Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "identity": "IDpYDM7J9n57q849o9E9yNrG",
      "token": "TKiMxe323RE5Dq3wLVtG8kSW",
	    "type": "TOKEN"
	}'

Example Response:

Copy
Copied
{
  "id" : "PImmCg3Po7oNi7jaZcXhfkEu",
  "created_at" : "2022-10-10T05:32:17.78Z",
  "updated_at" : "2022-10-10T05:32:17.78Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "created_via" : "API",
  "currency" : "USD",
  "enabled" : true,
  "fingerprint" : "FPRiCenDk2SoRng7WjQTr7RJY",
  "identity" : "IDgWxBhfGYLLdkhxx2ddYf9K",
  "instrument_type" : "PAYMENT_CARD",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "bin" : "520082",
  "brand" : "MASTERCARD",
  "card_type" : "DEBIT",
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "issuer_country" : "NON_USA",
  "last_four" : "8210",
  "name" : "Amy White",
  "security_code_verification" : "UNKNOWN",
  "tags" : {
    "card_name" : "Business Card"
  },
  "type" : "PAYMENT_CARD",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K"
    },
    "updates" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PImmCg3Po7oNi7jaZcXhfkEu/updates"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/payment_instruments

Request Arguments

Field Type Description
identity string, required ID for the Identity resource which the account is to be associated
token string, required ID for the Token that was returned via the tokenization client or hosted fields
type string, required Must pass TOKEN as the value

Response

Field Type Description
id string The ID of the Payment Instrument.
created_at string Timestamp of when the Payment Instrument was created.
updated_at string Timestamp of when the Payment Instrument was last updated.
address object The Payment Instrument owner's personal home address. This field is used for Identity verification purposes.
address_verification string Additional address information that’s required to verify the identity of the Payment Instrument owner`.
application string The ID of the Application resource used to create the Payment Instrument.
bin string Bank Identification number for the Payment Instrument.
brand string The brand of the card saved in the Payment Instrument.
type string
  • Type of Payment Instrument.
  • Available values include:
    • PAYMENT_CARD
    • APPLE_PAY
    • GOOGLE_PAY
currency string 3-letter ISO code designating the currency of the Payment Instrument (e.g. USD).
expiration_month integer Expiration month (e.g. 12 for December).
expiration_year integer 4-digit expiration year.
fingerprint string Unique ID that represents the tokenized card data.
identity string The ID of the Identity connected to the Payment Instrument.
instrument_type *string** The type of Payment Instrument.
last_four string Last four digits of the card or bank account number.
name string The name of the bank account or card owner.
security_code_verification string Details the results of the Card Verification Code check.
tags object Key value pair for annotating custom meta data (e.g. order numbers).
type string Type of Payment Instrument.
_link object For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

Address-object Response

Field Type Description
line1 string First line of the address (max 35 characters)
line2 string Second line of the address (max 35 characters)
city string City (max 20 characters)
region string 2-letter State code
postal_code string Zip or Postal code (max 7 characters)
country string 3-Letter Country code

The type of card that gets saved is detailed in card_type. Available values for Payment Instruments with type PAYMENT_CARD include:

  • CREDIT
  • DEBIT
  • HSA_FSA
  • NON_RELOADABLE_PREPAID
  • RELOADABLE_PREPAID
  • UNKNOWN