Mobile 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: \(instrument.id)
fingerprint: \(instrument.fingerprint)
created: \(instrument.created)
updated: \(instrument.updated)
instrument: \(instrument.instrument)
expires: \(instrument.expires)
isoCurrency: \(instrument.isoCurrency)

Token invalidation

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

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 '{
    "token": "TKghUufLdh4QQ96CBi928HP3",
    "type": "TOKEN",
    "identity": "IDgWxBhfGYLLdkhxx2ddYf9K"
  }'

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 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": "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"
        }
    }
}