Tokenization - iOS

Learn how to accept and secure payment details cards in your iOS app.

This article details how to accept the payments details of your buyer and secure their information in your iOS app. Payment details get secured via tokenization and stored in Finix's vault, so payment information is never exposed and minimizes your PCI scope.

If you have any questions about using Finix, reach out to your Finix point of contact or email the Finix Support team at anytime!

Step 1: Add the FinixPaymentSheet Framework

Ask your Finix point of contact for the FinixPaymentSheet SDK and Test App. Add the SDK to your application.

Step 2: Import Library

You can access PaymentsSDK by importing the library.

 import FinixPaymentSheet

Step 3: Initialize Tokenizer Class

The PaymentsSDK provides a Test app that you can utilize to build your own application.

It's composed of 2 delegates and 2 ViewControllers

  • ResultViewController: used to react to the result of the tokenization form
  • ViewController: used to initialize and configure the tokenization form to your specifications

Step 4: Create a Payment Instrument

Before you can use the newly tokenized card or bank account you will need to associate it with an Identity.

To do this, make an authenticated POST request to the /payment_instrument and create a Payment Instrument with the relevant token and Identity information. You can access the Token from the TokenResponse. TokenResponse is of the following structure:

id: \(
fingerprint: \(instrument.fingerprint)
created: \(instrument.created)
updated: \(instrument.updated)
instrument: \(instrument.instrument)
expires: \(instrument.expires)
isoCurrency: \(instrument.isoCurrency)

Tokens should be associated right away. Tokens that don't get associated within 30 mins of creation get invalidated.

curl \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
            "token": "TKghUufLdh4QQ96CBi928HP3",
            "type": "TOKEN",
            "identity": "IDgWxBhfGYLLdkhxx2ddYf9K"

HTTP Request


Request Arguments

Field Type Description
address object, required Billing address (Full description of child attributes below)
Note: Including a postal or zip code when creating a Payment Instrument can lower the interchange on credit card transactions
identity string, required ID for the Identity resource which the account is to be associated
name string, required Full name of the registered card holder
token string, required ID for the Token that was returned via the tokenization client
type string, required Must pass TOKEN as the value

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:

  "id" : "PImmCg3Po7oNi7jaZcXhfkEu",
  "created_at" : "2022-10-10T05:32:17.78Z",
  "updated_at" : "2022-10-10T05:35:04.55Z",
  "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" : "POSTAL_CODE_AND_STREET_MATCH",
  "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" : "MATCHED",
  "tags" : {
    "card_name" : "Business Card"
  "type" : "PAYMENT_CARD",
  "_links" : {
    "self" : {
      "href" : ""
    "authorizations" : {
      "href" : ""
    "transfers" : {
      "href" : ""
    "verifications" : {
      "href" : ""
    "application" : {
      "href" : ""
    "identity" : {
      "href" : ""
    "updates" : {
      "href" : ""