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

Import the PaymentsSDK library by running import FinixPaymentSheet.

 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

  • AppDelegate: used to react to new or ended session activity
  • ResultViewController: used to react to the result of the payment sheet
  • SceneDelegate: used to allow additional configuration and actions depending on the status of the sheet
  • ViewController: used to initialize and configure the payment sheet 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/vnd.json+api" \
    -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" : ""