React Native

Este é o SDK oficial de checkout do Dodo Payments para React Native, @dodopayments/react-native-checkout. Ele abre o checkout hospedado do Dodo em uma visualização de navegador nativa e retorna um resultado tipado. Observação: existe um pacote mais antigo e não relacionado chamado dodopayments-react-native-sdk (sem escopo), com uma API completamente diferente. Esta página documenta apenas o pacote oficial com escopo atual.

Checkout Sessions API

Crie o checkout_url que este SDK abre a partir do seu backend.

Mobile Integration Guide

Veja como isso se encaixa no fluxo completo de pagamento móvel.

O SDK do React Native é um wrapper fino de Turbo Module sobre os mesmos núcleos nativos em Swift e Kotlin. Ele abre SFSafariViewController no iOS e uma Chrome Custom Tab no Android, não armazena nenhuma chave de API e nunca chama a API do Dodo diretamente. Toda a lógica do checkout é executada no navegador; o SDK simplesmente gerencia o ciclo de vida da visualização e captura a URL de retorno.

Este SDK requer apenas a New Architecture, React Native 0.76+, iOS 16+ e Android minSdk 24.

Instalação

Install the Package

Android
iOS
Expo

O pacote é vinculado automaticamente e obtém com.dodopayments.api:checkout-android do Maven.

npm i @dodopayments/react-native-checkout

Não é necessária nenhuma configuração adicional; a dependência nativa é resolvida automaticamente.

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

O núcleo Swift é incluído no pacote e instalado por meio do CocoaPods.

Apenas builds de desenvolvimento (não o Expo Go).

npm i @dodopayments/react-native-checkout
npx expo install expo-build-properties

Em seguida, configure o seu app.json (consulte Registrar um esquema de URL de callback abaixo).

Seu app deve registrar um esquema de URL para receber a URL de retorno do checkout.

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

Em android/app/build.gradle:

android/app/build.gradle

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

Substitua "myapp" pelo esquema do seu app.

Em ios/YourApp/Info.plist:

Info.plist

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

Você também pode adicionar isso pela interface Info → URL Types do Xcode.

Em app.json:

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "manifestPlaceholders": {
              "dodoCallbackScheme": "myapp"
            }
          }
        }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [
          {
            "CFBundleURLSchemes": ["myapp"]
          }
        ]
      }
    }
  }
}

O pacote também inclui um plugin de configuração do Expo @dodopayments/react-native-checkout, mas atualmente ele não grava nenhum esquema de URL nem nenhum placeholder de manifesto. Adicioná-lo sozinho não registrará o esquema de callback — use a configuração expo-build-properties e infoPlist acima.

Reconstrua o projeto nativo depois de editar app.json:

npx expo prebuild --clean

Isso funciona apenas com builds de desenvolvimento, não com o Expo Go.

Uso

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));

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': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}

Encaminhamento da URL de retorno

O listener Linking é necessário para o tratamento da URL de retorno no iOS. No Android, handleOpenURL é uma operação no-op que resolve false porque o núcleo do Android gerencia o redirecionamento nativamente. É seguro registrar o listener incondicionalmente em ambas as plataformas.

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

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

O significado do resultado

result.status é uma indicação da UI, não uma prova de pagamento. Confirme cada pagamento a partir do seu backend, por meio do webhook payment.succeeded / subscription.active.

CheckoutStatus

obrigatório

Um de succeeded, failed, cancelled, pending, expired.

string

Definido quando a URL de retorno incluía um. Exiba-o na UI, mas não o use para conceder acesso. Consulte Verificar o pagamento abaixo.

string

Definido para checkouts de assinatura.

string[]

Definido quando o checkout inclui produtos com chave de licença.

string

Definido quando o checkout captura um e-mail.

Record<string, string>

Todos os parâmetros de consulta da URL de retorno, literalmente.

Verificar o pagamento

Webhooks

O Dodo Payments chama o seu backend quando um pagamento é bem-sucedido ou uma assinatura é ativada.

Get Payment Detail

Consulte paymentId usando a sua chave secreta para verificar o status diretamente.

Conceda acesso depois que um desses confirmar o pagamento, nunca com base apenas em result.status.

Erros

start rejeita com um CheckoutError apenas em caso de uso incorreto ou falha da plataforma. Um pagamento cancelado ou recusado sempre é um resultado, nunca uma exceção.

INVALID_CHECKOUT_URL: não é uma URL de sessão checkout.dodopayments.com.
INVALID_RETURN_URL: não é uma URL absoluta válida.
ALREADY_IN_PROGRESS: já existe um checkout em execução.
PLATFORM_ERROR: falha inesperada da plataforma.

Sessões abandonadas

Se o app ou o bundle JS for encerrado durante o checkout, a promise será perdida, mas a camada nativa manterá a sessão. Recupere-a na próxima montagem e faça a reconciliação com o seu backend.

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

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Instalação

Uso

Encaminhamento da URL de retorno

O significado do resultado

Verificar o pagamento

Webhooks

Get Payment Detail

Erros

Sessões abandonadas

Relacionado

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Instalação

​Uso

​Encaminhamento da URL de retorno

​O significado do resultado

​Verificar o pagamento

Webhooks

Get Payment Detail

​Erros

​Sessões abandonadas

​Relacionado

Mobile Integration Guide

Expo Boilerplate

Instalação

Uso

Encaminhamento da URL de retorno

O significado do resultado

Verificar o pagamento

Erros

Sessões abandonadas

Relacionado