Overview

Bring secure Telr payments to your React Native app fast. Our plug-in launches the checkout flow, manages the payment steps behind the scenes, and returns a clear success or failure result, so your team ships quicker and supports less.

Requirements

React Native ≥ 0.75
iOS: iOS 14+, Xcode 15+, Swift 5.9+
Android: minSdk 24+, targetSdk 34, Kotlin 1.9+
Your backend must return two URLs taken directly from the createOrder API response:
- tokenUrl — value of _links.auth.href
- orderUrl — value of _links.self.href

Installation

Install the package in your React Native app:

npm install @telrsdk/rn-telr-sdk
# or
yarn add @telrsdk/rn-telr-sdk

Platform Setup

iOS

Ensure your ios/Podfile targets iOS 15.1 or newer and has New Architecture enabled for the best performance.

Minimal example:

platform :ios, '15.1'

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

target 'YourApp' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath],
    :new_arch_enabled => true
  )

  use_frameworks! :linkage => :static
end

Install pods with New Architecture enabled:

cd ios && RCT_NEW_ARCH_ENABLED=1 pod install

If CocoaPods cannot find the TelrSDK pod, make sure you have access to Telr's podspec source as provided by Telr and that your Podfile declares the appropriate source entries. Then run pod repo update and re-install.

Android

No additional setup required

Usage

import TelrPayments, {
  TelrInitResult,
  TelrResult,
  TelrStatus,
  ConfigureOptions,
} from '@telr/react-native-payments';

async function checkout() {
  // 1) Initialize
  const init: TelrInitResult = await TelrPayments.initialize();
  if (!init.success) {
    // Show a friendly message; you may allow retry
    console.warn('Telr SDK initialization failed', init.error);
    return;
  }

  // 2) Fetch tokenUrl/orderUrl from your backend
  const { tokenUrl, orderUrl } = await fetch('/api/checkout')
    .then(r => r.json());

  // 3) Present native payment UI
  const result: TelrResult = await TelrPayments.presentPayment({
    tokenUrl,
    orderUrl,
  });

  // 4) Handle result
  switch (result.status) {
    case TelrStatus.Succeeded:
      // Optional: submit transactionId or metadata to your backend
      console.log('Payment successful');
      break;
    case TelrStatus.Canceled:
      console.log('Payment canceled by user');
      break;
    case TelrStatus.Failed:
      console.log('Payment failed', result.errorCode, result.message);
      break;
  }
}

API Reference

presentPayment(tokenURL: string, orderURL: string): Promise<PaymentResponse>
- Presents the Telr payment UI modally (full screen) on iOS.
- Resolves with { success: boolean; message: string } when the flow completes.

Types

type PaymentResponse = { success: boolean; message: string };

Notes

The payment view is presented full-screen using UIKit/SwiftUI under the hood and dismissed automatically when a result is available.
Make sure your tokenURL and orderURL are accessible from the device/simulator and use HTTPS.

Troubleshooting

TurboModule 'TelrSDK' is null or undefined
- Ensure New Architecture is enabled (:new_arch_enabled => true in Podfile, or RCT_NEW_ARCH_ENABLED=1 when installing pods) and re-run pod install.
CocoaPods cannot find TelrSDK
- Ensure your Podfile includes Telr's private spec repo or the correct pod source as provided by Telr, then run pod repo update and pod install.
Build fails due to iOS version
- Ensure your app targets platform :ios, '15.1' or newer.