Advanced Features

Advanced configuration and custom integrations for react-native.

Alternative mounting options

The basic flow uses automatic payment method display. For more control, use these alternatives:

Custom payment method selection (`startPaymentLite`)

Select which payment method to display:

// 1. Fetch available methods
const methods = await fetchPaymentMethods(sessionId);

// 2. Display in your UI
// 3. Start payment with selected method

await YunoSdk.startPaymentLite(
  {
    checkoutSession: session.checkoutSession,
    methodSelected: {
      paymentMethodType: selectedMethod, // 'CARD', 'PIX', etc.
      vaultedToken: null, // or saved token
    },
    showPaymentStatus: true,
  },
  'US' // Optional country code override
);

Simplified flow (`startPaymentSeamlessLite`)

Similar to Lite but with automatic payment creation:

await YunoSdk.startPaymentSeamlessLite({
  checkoutSession: session.checkoutSession,
  methodSelected: {
    paymentMethodType: 'CARD',
    vaultedToken: null, // or saved token
  },
  showPaymentStatus: true,
  countryCode: 'US',
});

Enrollment (save cards)

Save during payment

// When creating payment on backend, include vault_on_success flag
async function createPayment(token: string, checkoutSession: string) {
  await fetch('/api/payment/create', {
    method: 'POST',
    body: JSON.stringify({
      one_time_token: token,
      checkout_session: checkoutSession,
      vault_on_success: true, // Save after successful payment
    }),
  });
}

Separate enrollment

// Create customer session on backend
const customerSession = await createCustomerSession('cus_123');

// Set up listener
const enrollmentSubscription = YunoSdk.onEnrollmentStatus((state) => {
  if (state.status === 'SUCCEEDED') {
    console.log('Card saved successfully');
  }
});

// Start enrollment flow
await YunoSdk.enrollmentPayment({
  customerSession: customerSession.id,
  countryCode: 'US',
  showPaymentStatus: true,
});

// Clean up
enrollmentSubscription.remove();

Vaulted token payments

await YunoSdk.startPaymentLite({
  checkoutSession: session.checkoutSession,
  methodSelected: {
    paymentMethodType: 'CARD',
    vaultedToken: 'vtok_saved_card_123',
  },
  showPaymentStatus: true,
});

Custom UI (headless integration)

Build completely custom payment forms with full UI control when you need complete control over every UI element, highly custom checkout experiences, or have development resources for custom UI.

import { YunoSdk } from '@yuno-payments/yuno-sdk-react-native';

const CustomPaymentForm = () => {
  const [cardNumber, setCardNumber] = useState('');
  const [expiry, setExpiry] = useState('');
  const [cvv, setCvv] = useState('');
  
  const processPayment = async () => {
    try {
      // 1. Use headless API
      const result = await YunoSdk.generateToken({
        checkoutSession: 'session_id',
        paymentMethod: {
          type: 'CARD',
          card: {
            number: cardNumber,
            expirationMonth: parseInt(expiry.split('/')[0]),
            expirationYear: parseInt(expiry.split('/')[1]),
            securityCode: cvv,
            holderName: 'John Doe',
            type: 'CREDIT',
          },
        },
      }, 'session_id', 'US');
      
      
      // 2. Create payment with token
      await createPayment(result.token);
      
      // 3. Handle 3DS if needed - use getThreeDSecureChallenge
      const challengeResult = await YunoSdk.getThreeDSecureChallenge('session_id', 'US');
      if (challengeResult.type === 'URL') {
        // Open 3DS URL in WebView, then continue payment
        await YunoSdk.continuePayment('session_id', 'US', true);
      }
      
    } catch (error) {
      console.error('Payment error:', error);
    }
  };
  
  return (
    <View>
      <TextInput
        placeholder="Card Number"
        value={cardNumber}
        onChangeText={setCardNumber}
      />
      <TextInput
        placeholder="MM/YY"
        value={expiry}
        onChangeText={setExpiry}
      />
      <TextInput
        placeholder="CVV"
        value={cvv}
        onChangeText={setCvv}
        secureTextEntry
      />
      <Button title="Pay" onPress={processPayment} />
    </View>
  );
};

Styling

Customize SDK appearance.

// Note: Styling configuration should be done during initialization
YunoSdk.initialize({
  apiKey: 'your-key',
  countryCode: 'US',
  yunoConfig: {
    // Add styling options here
  },
});

Error handling

const handlePayment = async () => {
  useEffect(() => {
    const subscription = YunoSdk.onPaymentStatus((state) => {
      if (state.status === 'FAILED') {
        // Handle payment failure
        Alert.alert('Error', 'Payment failed. Please try again.');
      }
    });
    
    return () => subscription.remove();
  }, []);
  
  try {
    await YunoSdk.startPayment(true);
  } catch (error) {
    console.error('Payment error:', error);
    Alert.alert('Error', error.message);
  }
};

Testing and debug

// Use test mode with test API key
YunoSdk.initialize({
  apiKey: 'pk_test_your_key',
  countryCode: 'US',
});

Performance

Lazy loading

const PaymentScreen = () => {
  const [yunoLoaded, setYunoLoaded] = useState(false);
  
  useEffect(() => {
    // Load Yuno only when needed
    if (!yunoLoaded) {
      YunoSdk.initialize({
        apiKey: 'pk_test_key',
        countryCode: 'US',
      });
      setYunoLoaded(true);
    }
  }, []);
  
  // ...
};

Deep linking / external browser return

Handle users returning to your app after external payment flows like 3DS authentication challenges, bank transfer redirects, PIX payments, and alternative payment methods that redirect to external browsers.

1. Set callback_url in checkout session

Include callback_url when creating the checkout session on your backend:

{
  "callback_url": "myapp://return"
}

Without callback_url, users may be stranded in the external browser with no way to return to your app.

2. Configure deep links

iOS - Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.yourapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

Android - AndroidManifest.xml:

<activity android:name=".MainActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="myapp"
            android:host="return" />
    </intent-filter>
</activity>

3. Handle deep links in react-native

import { YunoSdk } from '@yuno-payments/yuno-sdk-react-native';
import { Linking } from 'react-native';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Handle initial URL (app opened from closed state)
    Linking.getInitialURL().then((url) => {
      if (url) {
        handleDeepLink(url);
      }
    });
    
    // Handle URL changes (app is running)
    const subscription = Linking.addEventListener('url', (event) => {
      handleDeepLink(event.url);
    });
    
    return () => {
      subscription.remove();
    };
  }, []);
  
  const handleDeepLink = async (url: string) => {
    console.log('Received deep link:', url);
    
    // Check if it's a payment return URL
    if (url.startsWith('myapp://return')) {
      try {
        await YunoSdk.receiveDeeplink(url);
        console.log('Deep link processed successfully');
      } catch (error) {
        console.error('Error processing deep link:', error);
      }
    }
  };
  
  return (
    // Your app
  );
}

4. Continue payment after return

After handling the deep link, continue the payment flow:

const handleDeepLink = async (url: string) => {
  if (url.startsWith('myapp://return')) {
    try {
      // Process the deep link
      await YunoSdk.receiveDeeplink(url);
      
      // Continue payment flow
      await YunoSdk.continuePayment(
        checkoutSessionId,
        'US',
        true // show payment status
      );
    } catch (error) {
      console.error('Error:', error);
    }
  }
};

Best practices: always include callback_url in payment flows that may redirect; test deep link handling on both iOS and Android devices; handle missing or malformed deep link data gracefully; update payment status in your UI after returning from external browser.

Platform-specific configuration

Handle differences between iOS and Android in your react-native app.

Conditional configuration

import { Platform } from 'react-native';
import { YunoSdk } from '@yuno-payments/yuno-sdk-react-native';

// Initialize with platform-specific config
await YunoSdk.initialize({
  apiKey: 'your-api-key',
  countryCode: 'US',
  yunoConfig: {
    language: 'en',
  },
  ...(Platform.OS === 'ios' && {
    iosConfig: {
      // iOS-specific settings
    },
  }),
  ...(Platform.OS === 'android' && {
    androidConfig: {
      // Android-specific settings
    },
  }),
});

Platform-specific features

Card scanning (Android only):

if (Platform.OS === 'android') {
  // Card scanning is available on Android
  // Automatically enabled when camera permission is granted
}

Deep link handling:

const handlePaymentReturn = async (url: string) => {
  if (Platform.OS === 'ios') {
    // iOS-specific handling
    await YunoSdk.receiveDeeplink(url);
  } else if (Platform.OS === 'android') {
    // Android-specific handling
    await YunoSdk.receiveDeeplink(url);
  }
};

Minimum version requirements

Platform	Minimum version
iOS	14.0+
Android	API 21 (5.0)+
react-native	0.70+

Platform-specific dependencies

Native SDK versions:

Platform	Native SDK	Version
Android	`com.yuno.sdk:yuno-sdk-android`	2.9.0
iOS	`YunoSDK`	2.11.1

Testing on both platforms

Always test your integration on both iOS and Android:

# iOS
npx react-native run-ios

# Android
npx react-native run-android

Common platform differences

Feature	iOS	Android
Card scanning	Not available	Available
Deep links	Universal Links	Intent Filters
Permissions	Info.plist	AndroidManifest.xml
UI components	Native iOS components	Jetpack Compose

Parameters used on this page

Parameter	Description
`checkoutSession`	Checkout session ID from your backend.
`methodSelected.paymentMethodType`	Payment method type (e.g. `CARD`, `PIX`).
`methodSelected.vaultedToken`	Saved payment method token, or `null` for new card.
`showPaymentStatus`	When `true`, SDK shows payment result UI.
`countryCode`	Optional ISO country code override (e.g. `US`).
`customerSession`	Customer session ID for enrollment flows.
`vault_on_success`	Backend flag to save card after successful payment.

Overview

Seamless SDK

Lite SDK

Headless SDK

Customization

Card Enrollment

Resources

Additional Platforms

Alternative mounting options

Custom payment method selection (`startPaymentLite`)

Simplified flow (`startPaymentSeamlessLite`)

Enrollment (save cards)

Save during payment

Separate enrollment

Vaulted token payments

Custom UI (headless integration)

Styling

Error handling

Testing and debug

Performance

Lazy loading

Deep linking / external browser return

1. Set callback_url in checkout session

2. Configure deep links

3. Handle deep links in react-native

4. Continue payment after return

Platform-specific configuration

Conditional configuration

Platform-specific features

Minimum version requirements

Platform-specific dependencies

Testing on both platforms

Common platform differences

Parameters used on this page

Overview

Seamless SDK

Lite SDK

Headless SDK

Customization

Card Enrollment

Resources

Additional Platforms

​Alternative mounting options

​Custom payment method selection (startPaymentLite)

​Simplified flow (startPaymentSeamlessLite)

​Enrollment (save cards)

​Save during payment

​Separate enrollment

​Vaulted token payments

​Custom UI (headless integration)

​Styling

​Error handling

​Testing and debug

​Performance

​Lazy loading

​Deep linking / external browser return

​1. Set callback_url in checkout session

​2. Configure deep links

​3. Handle deep links in react-native

​4. Continue payment after return

​Platform-specific configuration

​Conditional configuration

​Platform-specific features

​Minimum version requirements

​Platform-specific dependencies

​Testing on both platforms

​Common platform differences

​Parameters used on this page

Alternative mounting options

Custom payment method selection (`startPaymentLite`)

Simplified flow (`startPaymentSeamlessLite`)

Enrollment (save cards)

Save during payment

Separate enrollment

Vaulted token payments

Custom UI (headless integration)

Styling

Error handling

Testing and debug

Performance

Lazy loading

Deep linking / external browser return

1. Set callback_url in checkout session

2. Configure deep links

3. Handle deep links in react-native

4. Continue payment after return

Platform-specific configuration

Conditional configuration

Platform-specific features

Minimum version requirements

Platform-specific dependencies

Testing on both platforms

Common platform differences

Parameters used on this page