Link External Cards

Synctera allows external card tokenization and association with the customers on the platform. This guide walks you through the steps necessary to start using the external cards feature by integrating with the Finix Cards Tokenization widget. Card tokenization is the process of de-identifying sensitive cardholder data by converting it into a token. Similar to encryption, tokenization obfuscates the actual data to render it unreadable in the event of a data breach or other exposure. Since this widget communicates directly between the client, Finix, and Synctera, it removes the need for the integrator to be PCI certified.

Getting started


Refer to Finix’s documentation Tokenization With Hosted Fields for additional information on card tokenization.

Make sure you've got the necessary components in place before integrating Finix Card Tokenization widget:

  1. Ensure Synctera API keys are provisioned and working for your business;
  2. Ensure external cards have been enabled for your program with your Synctera implementation and onboarding contact;
  3. If integrating in a mobile application, you may need to use a web view such as a WKWebView in a iOS application, WebView in an android application, or a WebView in React Native;
  4. Content security policies should be set in the application using the following directives:
  "script-src": [
  "frame-src": [

Tokenize the card via finix.js iframe

The steps below describe how to display the iframe with the finix.js client library:

  1. The finix.js library must be loaded into the window object of the browser. For that, add the following script to the head tag of the html page:
<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8" />
    <script src=""></script>


  1. Next, make sure that the PaymentForm library is initialized and and hosted fields are defined. To see the instructions please refer to steps 2 and 3 of the Finix documentation:
  1. After, the above-mentioned steps are completed, you are ready to input your cards details and tokenize it’s sensitive data. When the form is submitted, you will get the following response:
  "status": 201,
  "statusText": "Created",
  "data": {
    "id": "TKiu6N8r5wN38J1xXdeNjzZY",
    "fingerprint": "FPR-2083311660",
    "created_at": "2017-08-29T06:25:54.29Z",
    "updated_at": "2017-08-29T06:25:54.29Z",
    "instrument_type": "PAYMENT_CARD",
    "expires_at": "2017-08-30T06:25:54.29Z",
    "currency": "USD"
  "cardBrand": "visa",
  "bin": "411111"


Associate token with the customer

The final step is to associate the created token with the customer identity. For that, use the following request:

curl -X POST "" -d "token={token}&customer_id={customerId}" -H "Content-Length: 0" -H "Authorization: Bearer {apiKey}"

    "created_time": "2022-06-16T20:47:49.08628Z",
    "currency": "USD",
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "expiration_month": "1",
    "expiration_year": "2023",
    "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "last_four": "1111",
    "last_modified_time": "2022-06-16T20:47:49.08628Z",
    "name": "Isaac Newton",
    "verifications": {}

Please refer to the following link for more information on external cards API:

Did this page help you?