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/json" \
    -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