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

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.

O próprio plugin de configuração do pacote registra o scheme para ambas as plataformas em prebuild. Passe a ele uma opção scheme em app.json:

app.json

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

scheme deve corresponder ao valor passado em returnUrl (por exemplo, myappcheckout://return) e deve ser diferente de expo.scheme. O Expo já registra esse último em MainActivity, e reutilizá-lo pode direcionar o retorno do checkout para a tela errada.Recompile 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.Se android/app/build.gradle for mantido manualmente e não tiver um bloco defaultConfig { } padrão para o plugin encontrar, adicione o placeholder manualmente. Consulte a aba Android acima.

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

Encaminhando a URL de retorno

O listener Linking é necessário para o tratamento da URL de retorno no iOS. No Android, handleOpenURL é um no-op que resolve false, porque o core do Android trata 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 que o resultado significa

result.status é uma indicação de UI, não uma prova de pagamento. Confirme todos os pagamentos no seu backend, por meio do webhook payment.succeeded / subscription.active.

CheckoutStatus

obrigatório

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

string

Definido quando a URL de retorno incluía um. Exiba-o na UI; 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 chaves 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, sem alterações.

Verificar o pagamento

Webhooks

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

Get Payment Detail

Consulte paymentId com sua secret key para verificar o status diretamente.

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

Personalização da aparência

Personalize a barra de ferramentas, os botões e o esquema de cores do navegador de checkout por meio de customization em start(...). As opções são agrupadas por plataforma porque Custom Tab do Android e SFSafariViewController do iOS expõem diferentes controles nativos. Todos os campos são opcionais; omitir customization usa a aparência padrão de cada plataforma.

Android — Custom Tab

Cor de fundo da barra de ferramentas.

Cor da barra de navegação.

Cor do divisor acima da barra de navegação.

'default' | 'back'

default exibe o ícone de sistema “X”; back desenha uma seta de voltar.

'start' | 'end'

Em qual lado da barra de ferramentas o botão de fechar aparece.

Exibe o ícone de compartilhamento da barra de ferramentas.

boolean

Exibe o título da página abaixo da URL na barra de ferramentas.

boolean

Permite que a barra de ferramentas se oculte automaticamente conforme a página é rolada.

boolean

Exibe “Adicionar esta página aos favoritos” no menu de opções.

boolean

Exibe “Baixar página” no menu de opções.

'system' | 'light' | 'dark'

Força a aparência clara ou escura, independentemente da configuração do sistema do dispositivo.

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Rótulo ou ícone do botão de dispensar.

'pageSheet' | 'fullScreen'

pageSheet é apresentado como um cartão que pode ser dispensado deslizando; fullScreen cobre a tela inteira.

boolean

Permite que a barra de ferramentas seja recolhida durante a rolagem. Visível somente quando presentationStyle é fullScreen — pageSheet mantém as barras fixas, independentemente desta configuração.

'system' | 'light' | 'dark'

Força a aparência clara ou escura, independentemente da configuração do sistema do dispositivo.

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

Erros

start rejeita com um CheckoutError somente 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á há 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 reconcilie-a com 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

Encaminhando a URL de retorno

O que o resultado significa

Verificar o pagamento

Webhooks

Get Payment Detail

Personalização da aparência

Erros

Sessões abandonadas

Relacionados

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Instalação

​Uso

​Encaminhando a URL de retorno

​O que o resultado significa

​Verificar o pagamento

Webhooks

Get Payment Detail

​Personalização da aparência

​Erros

​Sessões abandonadas

​Relacionados

Mobile Integration Guide

Expo Boilerplate

Instalação

Uso

Encaminhando a URL de retorno

O que o resultado significa

Verificar o pagamento

Personalização da aparência

Erros

Sessões abandonadas

Relacionados