Mobile SDKsImprove this page

The native mobile SDKs allow you to integrate card linking technology in your mobile apps in minutes. Card details are collected securely, removing any PCI compliance requirements from your side. See below code examples on how to integrate the SDKs in your apps.

For more detailed documentation about any class in the SDKs and available customization options, check the Github repositories for iOS and Android.

iOS

Install

We recommend using CocoaPods to integrate Fidel iOS SDK with your project. Add a Podfile (if you don't have one already), by running the following command: pod init.

Add Fidel pod:

12
pod 'Fidel'

Camera

In order to allow scanning cards with the camera, make sure to add the key NSCameraUsageDescription to your app’s Info.plist and set the value to a string describing why your app needs to use the camera (e.g. “Used for scanning credit cards.”)

Objective-C (skip for Swift projects)

If you have an Objective-C project and did not add any Swift code yet, please set the Always Embed Swift Standard Libraries flag in Build Settings to YES.

Troubleshooting

In case Cocoapods doesn't find the Fidel specs or it finds older specs, try updating with pod update. After updating, run pod install.

Usage

Import the SDK:

12
import Fidel

Set your public SDK key (pk_test or pk_live) and the programId you want to link cards to:

123
Fidel.apiKey    = "pk_test_6e94da6f-145a-47db-b56b-f1314e74aa2e"
Fidel.programId = "f8d6890e-145d-46ea-b66f-afacfd954580"

Set cardholder consent variables:

1234
Fidel.companyName = "Your Company Name" // default: "Company Name".
Fidel.privacyURL = "https://yourcompany.com/privacyURL"
Fidel.deleteInstructions = "Your delete instructions" // Maximum 60 characters, default: "going to your account settings."

Set a default card country (if set, country picker will be hidden):

12
Fidel.country = .unitedKingdom

Present the SDK view:

123456
Fidel.present(self, onCardLinkedCallback: { (card: LinkResult) in
  print(card.id)
}, onCardLinkFailedCallback: { (err: LinkError) in
  print(err.message)
})

If you run into a problem, check the issues section of the SDK repository.

Android

Install

Add jitpack.io to your root build.gradle at the end of repositories:

1234567
allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

Add Fidel SDK as a dependency:

1234
dependencies {
  implementation 'com.github.FidelLimited:android-sdk:1.3.1'
}

Usage

Set your public SDK key (pk_test or pk_live) and the programId you want to link cards to:

123
Fidel.apiKey = "pk_test_6e94da6f-145a-47db-b56b-f1314e74aa2e"
Fidel.programId = "f8d6890e-145d-46ea-b66f-afacfd954580"

Set cardholder consent variables:

1234
Fidel.companyName = "Your Company Name" // default: "Company Name".
Fidel.privacyURL = "https://yourcompany.com/privacyURL"
Fidel.deleteInstructions = "Your delete instructions" // Maximum 60 characters, default: "going to your account settings."

Set a default card country (if set, country picker will be hidden):

12
Fidel.country = Fidel.Country.UNITED_KINGDOM;

You can pass additional data with org.json.JSONObject:

12345678910111213
JSONObject jsonMeta = new JSONObject();

try {
  jsonMeta.put("id", "this-is-the-metadata-id");
  jsonMeta.put("customKey1", "customValue1");
  jsonMeta.put("customKey2", "customValue2");
}
  catch(JSONException e) {
  Log.e(Fidel.FIDEL_DEBUG_TAG, e.getLocalizedMessage());
}

Fidel.metaData = jsonMeta;

Present the activity:

12
Fidel.present(YourActivityClass.this);

Get the resulting card object:

123456789101112
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);

  if(requestCode == Fidel.FIDEL_LINK_CARD_REQUEST_CODE) {
    if(data != null && data.hasExtra(Fidel.FIDEL_LINK_CARD_RESULT_CARD)) {
      LinkResult card = (LinkResult)data.getParcelableExtra(Fidel.FIDEL_LINK_CARD_RESULT_CARD);
      Log.d("d", "CARD ID = " + card.id);
    }
  }
}

If you run into a problem, check the issues section of the SDK repository.

React Native

Getting started

$ npm install fidel-react-native --save

(Almost) Automatic linking (for RN >= 0.60)

$ react-native link fidel-react-native

iOS

Go to the ios folder. Please check that in your Podfile you have the following line:
pod 'fidel-react-native', :path => '../node_modules/fidel-react-native'
Make sure that the minimum platform is set to 9.1 in your Podfile: platform :ios, '9.1'.
Run pod install.

Android

Append Jitpack to android/build.gradle:

1234567
allprojects {
  repositories {
    ...
    maven { url "https://jitpack.io" }
  }
}

Make sure that the minSdkVersion is the same or higher than the minSdkVersion of our native Android SDK:

12345678
buildscript {
  ext {
    ...
    minSdkVersion = 19
    ...
  }
}

Manual linking on iOS

Step 1: Add the Fidel React Native iOS project as a dependency

In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
Go to node_modules ➜ fidel-react-native and add Fidel.xcodeproj
In XCode, in the project navigator, select your project. Add libFidel.a to your project's Build Phases ➜ Link Binary With Libraries
Under your target's Build Settings, make sure to set YES for Always Embed Swift Standard Libraries. That's because, by default, your project might not need it. It needs to be YES because otherwise the project will not find the Swift libraries to be able to run our native iOS SDK.

Step 2: Add the Native iOS SDK as a dependency

You can use Cocoapods or install the library as a dynamic library.

Add a Podfile in your ios/ folder of your React Native project. It should include the following dependency:
```
123
use_frameworks!
pod 'Fidel'
```
Here is the simplest Podfile you need to link with our native iOS SDK:
```
123456789
platform :ios, '9.1'

workspace 'example'

target 'example' do
  use_frameworks!
  pod 'Fidel'
end
```
If you use an older Swift version, you should install a different Fidel pod version. If your project uses Swift 4.2.1, for example, your Podfile should include pod Fidel, '~>1.4, not pod 'Fidel' (which installs the latest version of the latest Swift supported version). Please check our iOS SDK docs. You’ll find a suitable version you should set for our Fidel iOS SDK.
Run pod install in your terminal.
Make sure to use the new .xcworkspace created by Cocoapods when you run your iOS app. React Native should use it by default.

In order to allow scanning cards with the camera, make sure to add the key NSCameraUsageDescription to your iOS app Info.plist and set the value to a string describing why your app needs to use the camera (e.g. "To scan credit cards."). This string will be displayed when the app initially requests permission to access the camera.

Manual linking on Android

Append the following lines to android/settings.gradle:

123
include ':fidel-react-native'
project(':fidel-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/fidel-react-native/android')

Insert the following lines inside the dependencies block in android/app/build.gradle:

12
implementation project(':fidel-react-native')

Append Jitpack to android/build.gradle:

1234567
allprojects {
  repositories {
    ...
    maven { url "https://jitpack.io" }
  }
}

Make sure that the minSdkVersion is the same or higher than the minSdkVersion of our native Android SDK:

12345678
buildscript {
  ext {
    ...
    minSdkVersion = 19
    ...
  }
}

Only for projects initialized with RN <= 0.59: Open up android/app/src/main/java/[...]/MainApplication.java
Add import com.fidelreactlibrary.FidelPackage; to the imports at the top of the file
Add new FidelPackage() to the list returned by the getPackages() method:

12345678
protected List <ReactPackage> getPackages() {
  return Arrays.<ReactPackage>asList(
    new MainReactPackage(),
    new FidelPackage(),
    // you might have other Packages here as well.
  );
}

Ensure that you have Google Play Services installed. For a physical device you need to search on Google for Google Play Services. There will be a link that takes you to the Play Store and from there you will see a button to update it (do not search within the Play Store).

Usage

Import Fidel in your RN project:

12
import Fidel from 'fidel-react-native';

Set up Fidel with your API key and your programId.

12345
Fidel.setup({
  apiKey:'your api key',
  programId: 'your program id'
});

Set the options that create the experience of linking a card with Fidel:

1234567891011121314
const myImage = require('./images/fdl_test_banner.png');
const resolveAssetSource = require('react-native/Libraries/Image/resolveAssetSource');
const resolvedImage = resolveAssetSource(myImage);

Fidel.setOptions ({
  bannerImage: resolvedImage,
  country: Fidel.Country.sweden,
  autoScan: false,
  metaData: { 'id': 'yourCustomId', 'someOtherKey': 'someOtherValue' },
  companyName: 'My RN Company',
  deleteInstructions: 'My custom delete instructions',
  privacyUrl: 'https://example.com/privacy',
});

Open the card linking view by calling:

12345678
Fidel.openForm((error, result) => {
  if (error) {
    console.error(error);
  } else {
    console.info(result);
  }
});

Error and result look like the following:

Result

123456789101112131415161718
{
  accountId: "the-account-id",
  countryCode: "GBR",
  created: "2019-04-22T05:26:45.611Z",
  expDate: "2023-12-31T23:59:59.999Z",
  expMonth: 12,
  expYear: 2023,
  id: "card-id",
  lastNumbers: "4001",
  live: false,
  mapped: false,
  metaData: {key1: "value1"},
  programId: "your program ID, as specified for the Fidel SDK",
  scheme: "visa",
  type: "visa",
  updated: "2019-04-22T05:26:45.611Z"
}

Error

123456
{
  code: "item-save",
  date: "2019-04-22T05:34:04.621Z",
  message: "Item already exists"
}

SDK options

bannerImage

Use this option to customize the topmost banner image with the Fidel UI. Your custom asset needs to be resolved in order to be passed to our native module:

12345678
const myImage = require('./images/fdl_test_banner.png');
const resolveAssetSource = require('react-native/Libraries/Image/resolveAssetSource');
const resolvedImage = resolveAssetSource(myImage);

Fidel.setOptions({
  bannerImage: resolvedImage,
});

country

Set a default country the SDK should use with:

1234
Fidel.setOptions({
  country: Fidel.Country.unitedKingdom,
});

When you set a default country, the card linking screen will not show the country picker UI. The other options, for now, are: unitedStates, ireland, sweden, japan, canada.

supportedCardSchemes

We currently support Visa, Mastercard and AmericanExpress. You can choose to support only one, two or all three. By default the SDK is configured to support all three. (Geographical limitations exist, please see available countries or via email if you have questions).

If you set this option to an empty array or to null, of course, you will not be able to open the Fidel UI. You must support at least one of our supported card schemes.

12345678910
/* this is the default value for supported card schemes,
 * but you can remove the support for some of the card schemes if you want to */
const supportedCardSchemes = [
  Fidel.CardScheme.visa,
  Fidel.CardScheme.mastercard,
  Fidel.CardScheme.americanExpress,
];

Fidel.setOptions({ supportedCardSchemes });

autoScan

Set this property to true, if you want to open the card scanning UI immediately after executing Fidel.openForm. The default value is false.

1234
Fidel.setOptions({
  autoScan: true,
});

metaData

Use this option to pass any other data with the card data:

1234567
Fidel.setOptions({
  metaData: {
    id: 'your-custom-id',
    'meta-data-key-2': 'value2',
  },
});

companyName

Set your company name as it will appear in our consent checkbox text. Please set it to a maximum of 60 characters.

1234
Fidel.setOptions({
  companyName: 'Your Company Name',
});

deleteInstructions

Write your custom opt-out instructions for your users. They will be displayed in the consent checkbox text as well.

1234
Fidel.setOptions({
  deleteInstructions: 'by contacting our support team at support@example.com',
});

privacyUrl

This is the privacy policy URL that you can set for the consent checkbox text.

1234
Fidel.setOptions({
  privacyUrl: 'https://fidel.uk',
});

Test card numbers

In the test environment, you can use the following Visa, Mastercard or American Express test card numbers. You must use a test API Key for them to work.

Visa: 4444000000004*** (the last 3 numbers can be anything)

Mastercard: 5555000000005*** (the last 3 numbers can be anything)

Amex: 3400000000003** or 3700000000003** (the last 2 numbers can be anything)

Feedback

The React Native SDK is in active development, you are welcome to leave feedback!

GitHub Issues — For SDK issues and feedback.

The banner image will take the device's width, but it has a fixed height of 100 pts. The image view has an "Aspect Fill" content mode, which means that the banner image you set will fill its entire predefined area. The banner image will be cropped from the top and bottom sides on wider devices. This is because of the "Aspect Fill" content mode that we set for the image view. Depending on what you want to display in the banner image, you might need to experiment a bit to ensure that nothing important from the image is hidden. The most important information should be displayed in the centre of the banner image.

We suggest using the aspect ratio of the smallest devices that you support. If you support iPhone 5, the aspect ratio would be 320:100. If the smallest device you support is the iPhone 6, your banner image's aspect ratio would be 375:100.

The same logic works for the Android banner image. You can make the image as pixel-dense as you need to

On iOS, you would need to provide the image for all screen densities. We recommend 375 x 130 for non-retina, 750 x 260 @2x and 1050 x 390 @3x.

Mobile SDKsImprove this page

iOS

Install

Camera

Objective-C (skip for Swift projects)

Troubleshooting

Usage

Android

Install

Usage

React Native

Getting started

(Almost) Automatic linking (for RN >= 0.60)

iOS

Android

Manual linking on iOS

Step 1: Add the Fidel React Native iOS project as a dependency

Step 2: Add the Native iOS SDK as a dependency

Manual linking on Android

Usage

Result

Error

SDK options

bannerImage

country

supportedCardSchemes

autoScan

metaData

companyName

deleteInstructions

privacyUrl

Test card numbers

Feedback

Banner Images