React Native

यह पृष्ठ आधिकारिक Dodo Payments React Native checkout SDK को कवर करता है, @dodopayments/react-native-checkout। यह Dodo Payments hosted checkout को native browser view में खोलता है और typed result लौटाता है। एक पुराना package, dodopayments-react-native-sdk (unscoped), अलग API रखता है। यह पृष्ठ केवल scoped package का दस्तावेज़ीकरण करता है।

Checkout Sessions API

अपने backend से वह checkout_url बनाएँ जिसे यह SDK खोलता है।

Mobile Integration Guide

देखें कि यह SDK पूरे mobile payment flow में कैसे फिट होता है।

React Native SDK एक Turbo Module है जो native iOS और Android checkout SDKs को wrap करता है। यह iOS पर SFSafariViewController और Android पर Custom Tab खोलता है। इसमें कोई API key नहीं होती और इसका अपना कोई checkout logic नहीं है, इसलिए यह Dodo Payments API को कभी call नहीं करता। Checkout browser view में चलता है। SDK उस view को दिखाता और dismiss करता है तथा return URL से result पढ़ता है।

यह SDK केवल New Architecture को support करता है। इसके लिए React Native 0.77 या बाद का संस्करण, iOS 16 या बाद का संस्करण और Android minSdk 24 आवश्यक है। आपके Android ऐप को compileSdk 34 या बाद के संस्करण के साथ build होना चाहिए।

Installation

Install the Package

Android
iOS
Expo

यह package autolinked है और Maven Central से com.dodopayments.api:checkout-android लाता है।

npm i @dodopayments/react-native-checkout

Native dependency अपने-आप resolve हो जाती है, इसलिए किसी अन्य install step की आवश्यकता नहीं है।

npm i @dodopayments/react-native-checkout
cd ios && pod install

Package में Swift core bundled है और CocoaPods इसे install करता है।

SDK केवल development builds में काम करता है, Expo Go में नहीं।

npm i @dodopayments/react-native-checkout

फिर अगले step में दिखाए अनुसार plugin को app.json में configure करें।

Appearance customization के लिए version 1.2.0 या बाद का संस्करण आवश्यक है।

एक URL scheme register करें ताकि operating system checkout के return URL को आपके ऐप पर वापस route कर सके।

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

android/app/build.gradle में scheme को manifest placeholder के रूप में set करें:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

"myapp" को अपने ऐप के scheme से बदलें।

ios/YourApp/Info.plist में URL type जोड़ें:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

आप Xcode में Info → URL Types के अंतर्गत भी URL type जोड़ सकते हैं।

Package का config plugin prebuild के दौरान दोनों platforms के लिए scheme register करता है। scheme को plugin के scheme option के रूप में app.json में pass करें:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

Plugin का scheme उस returnUrl के scheme से match होना चाहिए जिसे आप pass करते हैं, जैसे myappcheckout://return। ऐसा scheme इस्तेमाल करें जो expo.scheme से अलग हो। Expo पहले से expo.scheme को MainActivity पर register करता है, इसलिए इसे दोबारा इस्तेमाल करने पर Android में checkout return गलत activity पर जा सकता है और plugin आपको चेतावनी देता है। Plugin http, https और अन्य system schemes को reject करता है।app.json edit करने के बाद native project को rebuild करें:

npx expo prebuild --clean

Plugin केवल development builds में काम करता है, Expo Go में नहीं। iOS पर आपको Forwarding the Return URL में Linking listener की अभी भी आवश्यकता होगी।यदि android/app/build.gradle में defaultConfig { } block नहीं है, तो plugin prebuild को error के साथ रोक देता है। ऐसी स्थिति में Android tab में दिखाए अनुसार placeholder स्वयं जोड़ें।

हर platform पर वही URL set करें जो आपका backend session बनाते समय checkout session के return_url के रूप में उपयोग करता है। SDK return URL को scheme, host और path के आधार पर match करता है। URL का किसी वास्तविक page को load करना आवश्यक नहीं है।

उपयोग

अपने backend से प्राप्त checkout_url के साथ DodoCheckout.start को call करें:

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': await reconcileAbandonedSession(); break; // outcome unknown, not a failure
  case 'pending':   await reconcileAbandonedSession(); break;
  case 'expired':   showExpired(); break;
}

onEvent ऐसे events प्राप्त करता है जिनमें type का मान checkout.opened, checkout.return_received या checkout.closed होता है। इनका उपयोग केवल logging के लिए करें, outcome तय करने के लिए कभी नहीं।

Return URL को forward करना

iOS को return URL handle करने के लिए Linking listener की आवश्यकता होती है, क्योंकि SFSafariViewController अपना return URL catch नहीं कर सकता। Android पर handleOpenURL कुछ नहीं करता और false resolve करता है, क्योंकि Android SDK अपने redirect को native रूप से catch करता है। आप listener को दोनों platforms पर register कर सकते हैं।

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

iOS पर, जब URL चल रहे checkout से संबंधित होता है, तब handleOpenURL true resolve करता है और किसी अन्य URL के लिए false resolve करता है।

Result का अर्थ

SDK return URL के query parameters से result बनाता है।

result.status एक UI hint है, payment का प्रमाण नहीं। हर payment की पुष्टि अपने backend से payment.succeeded या subscription.active webhook के साथ करें।

CheckoutStatus

आवश्यक

पाँच में से एक value:

succeeded: return URL में status=succeeded (one-time payment) या status=active (subscription) है।
failed: payment decline हो गया (status=failed)।
cancelled: return URL आने से पहले customer ने browser view बंद कर दिया। SDK को outcome पता नहीं है और payment सफल हो सकता है, इसलिए failure screen न दिखाएँ। इसके बजाय abandoned session को reconcile करें।
pending: payment बाद में settle होता है (status=processing या कोई भी requires_* value), या status parameter missing या unrecognized था। इसे cancelled की तरह reconcile करें।
expired: checkout session expire हो गया (status=expired)।

string

payment_id query parameter, जब return URL में मौजूद हो। इसे अपने UI में दिखाएँ, लेकिन access देने के लिए इसका उपयोग न करें। Verify the Payment देखें।

string

subscription_id query parameter। Subscription checkouts के लिए set होता है।

string[]

license_key query parameter। Checkout में license key products शामिल होने पर set होता है।

string

email query parameter। Checkout द्वारा email address capture करने पर set होता है।

Record<string, string>

Return URL के हर query parameter को verbatim।

Payment सत्यापित करें

Webhooks

Payment सफल होने या subscription activate होने पर Dodo Payments आपके backend को call करता है।

Get Payment Detail

इसकी status जाँचने के लिए अपनी secret key से paymentId को look up करें।

इनमें से किसी एक द्वारा payment की पुष्टि होने के बाद ही access दें। केवल result.status पर निर्भर न रहें।

Appearance Customization

Checkout browser के toolbar, buttons और color scheme को बदलने के लिए customization को start(...) में pass करें। Android Custom Tabs और iOS SFSafariViewController अलग-अलग native controls expose करते हैं, इसलिए options को android object और ios object में group किया गया है। हर platform केवल अपना object पढ़ता है। हर field optional है। जब आप कोई field omit करते हैं, तो platform अपना default लागू करता है।

Android — Custom Tab

Toolbar का background color, hex string के रूप में: "#RRGGBB" या "#AARRGGBB"।

Navigation bar का color, hex string के रूप में।

Navigation bar के ऊपर divider का color, hex string के रूप में।

'default' | 'back'

default system का “X” icon दिखाता है। back SDK द्वारा draw किया गया back arrow दिखाता है।

'start' | 'end'

Toolbar का वह side जहाँ close button दिखाई देता है।

Toolbar का share icon दिखाता है। false इसे छिपाता है।

boolean

Toolbar में URL के नीचे page title दिखाता है।

boolean

Page scroll होने पर toolbar को अपने-आप छिपाता है।

boolean

Overflow menu में “Bookmark this page” दिखाता है।

boolean

Overflow menu में “Download page” दिखाता है।

'system' | 'light' | 'dark'

light या dark device की system setting की परवाह किए बिना उस appearance को force करता है। system system setting का पालन करता है।

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Dismiss button की style। iOS तय करता है कि इसे label या icon के रूप में render करना है।

'pageSheet' | 'fullScreen'

pageSheet (default) एक card दिखाता है जिसे customer dismiss करने के लिए नीचे swipe कर सकता है। fullScreen पूरी screen को cover करता है।

boolean

Page scroll होने पर toolbar को collapse होने देता है। इसका प्रभाव तभी दिखाई देता है जब presentationStyle, fullScreen हो। pageSheet के साथ bars इस setting की परवाह किए बिना pinned रहती हैं।

'system' | 'light' | 'dark'

iOS में toolbar color का कोई option नहीं है, क्योंकि underlying SFSafariViewController tint properties iOS 26 से deprecated हैं।

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

Errors

start केवल misuse या platform failure के लिए CheckoutError के साथ reject करता है। Reason error.code से पढ़ें। Customer द्वारा cancel करना या payment decline होना हमेशा result होता है, rejection नहीं।

INVALID_CHECKOUT_URL: checkoutUrl, checkout.dodopayments.com या test.checkout.dodopayments.com पर /session/ से शुरू होने वाला https checkout session URL नहीं है।
INVALID_RETURN_URL: returnUrl scheme और host वाला absolute URL नहीं है।
ALREADY_IN_PROGRESS: कोई अन्य checkout चल रहा है। एक समय में केवल एक checkout चल सकता है।
PLATFORM_ERROR: unexpected platform failure। SDK किसी भी unrecognized native error को भी इसी code के साथ report करता है।

Abandoned Sessions

Native SDK checkout शुरू होने पर checkout session record करता है और record केवल तब clear करता है जब checkout succeeded, failed या expired के साथ समाप्त होता है। Checkout के दौरान app या JavaScript bundle kill होने पर record बना रहता है, जिससे start promise खो जाता है, और cancelled या pending result के बाद भी। अगली mount पर और हर cancelled या pending result के बाद इसकी जाँच करें:

import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // Ask your backend for the outcome of abandoned.sessionId, and show it.
  // Clear the record only after the outcome is final:
  await DodoCheckout.clearAbandonedSession();
}

abandoned.sessionId checkout session ID है, जो cks_ से शुरू होती है। abandoned.createdAt वह Date है जब checkout शुरू हुआ था। आपका backend Get Checkout Session के साथ session look up कर सकता है, जो उसका payment_id और payment_status लौटाता है। जब तक payment final status तक न पहुँच जाए, उसे failed नहीं बल्कि pending मानें।

Mobile Integration Guide

Android, iOS और Flutter के लिए यही contract।

Expo Boilerplate

Checkout integration के साथ एक complete Expo example।

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

उपयोग

Return URL को forward करना

Result का अर्थ

Payment सत्यापित करें

Webhooks

Get Payment Detail

Appearance Customization

Errors

Abandoned Sessions

संबंधित

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Installation

​उपयोग

​Return URL को forward करना

​Result का अर्थ

​Payment सत्यापित करें

Webhooks

Get Payment Detail

​Appearance Customization

​Errors

​Abandoned Sessions

​संबंधित

Mobile Integration Guide

Expo Boilerplate

Installation

उपयोग

Return URL को forward करना

Result का अर्थ

Payment सत्यापित करें

Appearance Customization

Errors

Abandoned Sessions

संबंधित