React Native

Overview

The Telr React Native Payments SDK provides:

• Unified API to present the native Telr payment UI (card payments, wallets, and 3DS handled internally).
• Cross-platform result model for success, failure, and cancellation.

Requirements

• React Native: 0.71+
• iOS: iOS 14+, Xcode 15+, Swift 5.9+
• Android: minSdk 24+, targetSdk 34, Kotlin 1.9+
• Your backend must provide:
  • tokenUrl from the createOrder response
  • orderUrl from the createOrder response

Installation

npm install @telrsdk/react-native-payments
# or
yarn add @telrsdk/react-native-payments

Auto-linking is supported for React Native 0.60 or later. No manual linking is required.

Platform Setup

iOS

• No additional setup required for card payments.
• Apple Pay (optional):
  • Enable the Apple Pay capability.
  • Add your merchantIdentifier in app entitlements.
  • Ensure the app targets iOS 14 or later.

Android

• No extra setup required.

Quick Start

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

async function checkout() {
  // 1) Initialize
  const init: TelrInitResult = await TelrPayments.initialize();
  if (!init.success) {
    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:
      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

initialize()

Promise<{ success: boolean; error?: TelrError }>

Registers internal launchers and prepares the SDK.

presentPayment({ tokenUrl, orderUrl })

Promise<TelrResult>

Presents the native Telr UI, runs token/order fetch, card entry, and 3DS if required.

• Arguments

  • tokenUrl: string
  • orderUrl: string

• Resolves with:

{
  status: 'succeeded' | 'failed' | 'canceled',
  message?: string,
  errorCode?: string
}

Result and Error Models

TelrResult

• succeeded — payment completed
• canceled — user explicitly canceled
• failed — payment failed
• message?: string — human-readable summary
• errorCode?: string — Telr/native error code for support

TelrError

• code: string — standardized short code
• message: string — human-readable
• details?: object — native error metadata (platform codes, HTTP status, etc.)

UX Behavior

The SDK presents a full-screen native flow that:

1. Fetches a token and order using the URLs you provide
2. Shows payment options and card entry (with BIN lookups)
3. Performs 3DS automatically when required
4. Returns a unified result to JavaScript when finished

Apple Pay (iOS) is surfaced within the SDK’s native UI when available.

Testing

• Use your sandbox backend to generate test tokenUrl and orderUrl.
• Use test cards and orders; the SDK will show 3DS challenge flows automatically when configured.

Best Practices

• Call initialize() once per app launch (for example, at startup or when first showing checkout).
• Pre-create the order on your backend to generate orderUrl and tokenUrl.

FAQ

Do I need to implement a 3DS UI? No. The SDK handles 3DS natively and returns the final result to JavaScript.

Do I need Apple Pay entitlements? Only if you intend to surface Apple Pay within the SDK flow on iOS. Card payments do not require it.