Create a Payment Card

warning

The creation of cards directly via the API should only be done for testing purposes. You must use the Tokenization iframe or javascript client to remain out of PCI scope.

Review our guide on how to tokenize cards via the tokenization with hosted fields form

Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "name": "Amy White",
	    "expiration_year": 2029,
	    "tags": {
	        "card_name": "Business Card"
	    },
	    "number": "4895142232120006",
	    "expiration_month": 12,
	    "address": {
	        "city": "San Francisco",
	        "region": "CA",
	        "postal_code": "94404",
	        "line1": "900 Metro Center Blv",
	        "country": "USA"
	    },
	    "security_code": "022",
	    "type": "PAYMENT_CARD",
	    "identity": "IDgWxBhfGYLLdkhxx2ddYf9K"
	}'

Example Response:

Copy
Copied
{
  "id" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "fingerprint" : "FPRogKWsRQks2HGaau5eGR9AF",
  "tags" : {
    "card_name" : "Business Card"
  },
  "expiration_month" : 12,
  "expiration_year" : 2029,
  "bin" : "489514",
  "last_four" : "0006",
  "brand" : "VISA",
  "card_type" : "UNKNOWN",
  "name" : "Amy White",
  "address" : {
    "line1" : "900 Metro Center Blv",
    "line2" : null,
    "city" : "San Francisco",
    "region" : "CA",
    "postal_code" : "94404",
    "country" : "USA"
  },
  "address_verification" : "UNKNOWN",
  "security_code_verification" : "UNKNOWN",
  "created_at" : "2022-01-27T07:37:00.53Z",
  "updated_at" : "2022-01-27T07:37:00.53Z",
  "instrument_type" : "PAYMENT_CARD",
  "type" : "PAYMENT_CARD",
  "currency" : "USD",
  "identity" : "IDgWxBhfGYLLdkhxx2ddYf9K",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137/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/PIe2YvpcjvoVJ6PzoRPBK137/updates"
    }
  }
}

HTTP Request

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

Request Arguments

Field Type Description
address object, required Billing address (Full description of child attributes below).
Note: Including a postal or zip code when tokenizing a card can lower the interchange on credit card transactions.
expiration_month integer, required Expiration month (e.g. 12 for December).
expiration_year integer, required 4-digit expiration year.
identity string, required ID of the Identity that the card should be associated.
name string, required Full name of the registered card holder.
number string, required Primary account number (no dashes in between numbers).
type string, required Type of Payment Instrument (for cards input PAYMENT_CARD).
security_code string, required The 3-4 digit security code for the card (i.e. CVV code).
third_party_token string, optional Stringified token provided by Apple or Google. Required if using Apple or Google Pay.

Address-object Request Arguments

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