Deprecated API Reference

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

Create a Payment Card

attention

Creating cards directly using the Finix API should only be done for testing purposes. You must use the Tokenization Hosted Fields or JavaScript client to remain out of PCI scope.

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 '
	{
	    "address": {
	        "city": "San Francisco",
	        "country": "USA",
	        "line1": "900 Metro Center Blv",
	        "postal_code": "94404",
	        "region": "CA"
	    },
	    "expiration_month": 12,
	    "expiration_year": 2029,
	    "identity": "IDgWxBhfGYLLdkhxx2ddYf9K",
	    "name": "John Smith",
	    "number": "5200828282828210",
	    "security_code": "022",
	    "tags": {
	        "card_name": "Business Card"
	    },
	    "type": "PAYMENT_CARD"
	}'

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).
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.
type string, required
  • Type of Payment Instrument.
  • Available values include:
    • PAYMENT_CARD
    • APPLE_PAY
    • 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

Example Response:

Copy
Copied
{
  "id" : "PInbUSypj2c1sKXh17ioakyx",
  "created_at" : "2022-10-10T01:36:28.15Z",
  "updated_at" : "2022-10-10T01:36:28.15Z",
  "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" : "John Smith",
  "security_code_verification" : "UNKNOWN",
  "tags" : {
    "card_name" : "Business Card"
  },
  "type" : "PAYMENT_CARD",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PInbUSypj2c1sKXh17ioakyx"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PInbUSypj2c1sKXh17ioakyx/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PInbUSypj2c1sKXh17ioakyx/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PInbUSypj2c1sKXh17ioakyx/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/PInbUSypj2c1sKXh17ioakyx/updates"
    }
  }
}

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