Skip to main content
Esta página aborda o SDK oficial de checkout do Dodo Payments para React Native, @dodopayments/react-native-checkout. Ele abre o checkout hospedado do Dodo Payments em uma visualização de navegador nativa e retorna um resultado tipado. Um pacote mais antigo, dodopayments-react-native-sdk (sem escopo), tem uma API diferente. Esta página documenta somente o pacote com escopo.

Checkout Sessions API

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

Mobile Integration Guide

Veja como este SDK se encaixa no fluxo completo de pagamentos móveis.
O SDK para React Native é um Turbo Module que encapsula os SDKs nativos de checkout para iOS e Android. Ele abre SFSafariViewController no iOS e uma Custom Tab no Android. Ele não armazena nenhuma chave de API e não possui lógica própria de checkout, portanto nunca chama a API do Dodo Payments. O checkout é executado na visualização do navegador. O SDK exibe e fecha essa visualização e lê o resultado da URL de retorno.
Este SDK oferece suporte somente à New Architecture. Ele requer React Native 0.77 ou posterior, iOS 16 ou posterior e Android minSdk 24. Seu app Android deve ser compilado com compileSdk 34 ou posterior.

Instalação

1

Install the Package

O pacote é vinculado automaticamente e obtém com.dodopayments.api:checkout-android do Maven Central.
A dependência nativa é resolvida automaticamente, portanto nenhuma outra etapa de instalação é necessária.
A personalização da aparência requer a versão 1.2.0 ou posterior.
2

Register a Callback URL Scheme

Registre um esquema de URL para que o sistema operacional encaminhe a URL de retorno do checkout de volta para o seu app.
Defina o esquema como um manifest placeholder em android/app/build.gradle:
android/app/build.gradle
Substitua "myapp" pelo esquema do seu app.
Em todas as plataformas, defina a mesma URL usada como return_url da sessão de checkout quando o backend criar a sessão. O SDK compara a URL de retorno pelo esquema, host e caminho. A URL não precisa carregar uma página real.

Uso

Chame DodoCheckout.start com o checkout_url do seu backend:
onEvent recebe eventos com um type de checkout.opened, checkout.return_received ou checkout.closed. Use-os somente para logging, nunca para decidir o resultado.

Encaminhar a URL de retorno

O iOS precisa do listener Linking para lidar com a URL de retorno, porque SFSafariViewController não consegue capturar sua própria URL de retorno. No Android, handleOpenURL não faz nada e resolve false, porque o SDK do Android captura o redirect nativamente. Você pode registrar o listener em ambas as plataformas.
No iOS, handleOpenURL resolve true quando a URL pertence ao checkout em andamento, e false para qualquer outra URL.

O que o resultado significa

O SDK cria o resultado a partir dos parâmetros de consulta na URL de retorno.
result.status é uma indicação da UI, não uma prova de pagamento. Confirme todos os pagamentos a partir do seu backend, usando o webhook payment.succeeded ou subscription.active.
CheckoutStatus
obrigatório
Um dos cinco valores:
  • succeeded: a URL de retorno tem status=succeeded (pagamento único) ou status=active (assinatura).
  • failed: o pagamento foi recusado (status=failed).
  • cancelled: o cliente fechou a visualização do navegador antes da chegada da URL de retorno. O SDK não sabe qual foi o resultado, e o pagamento pode ter sido concluído; portanto, não exiba uma tela de falha. Em vez disso, reconcilie a sessão abandonada.
  • pending: o pagamento é liquidado posteriormente (status=processing ou qualquer valor de requires_*), ou o parâmetro status estava ausente ou não foi reconhecido. Faça a reconciliação como em cancelled.
  • expired: a sessão de checkout expirou (status=expired).
string
O parâmetro de consulta payment_id, quando a URL de retorno inclui um. Exiba-o na sua UI, mas não o use para conceder acesso. Consulte Verificar o pagamento.
string
O parâmetro de consulta subscription_id. Definido para checkouts de assinatura.
string[]
O parâmetro de consulta license_key. Definido quando o checkout inclui produtos com chaves de licença.
string
O parâmetro de consulta email. Definido quando o checkout captura um endereço de e-mail.
Record<string, string>
Todos os parâmetros de consulta da URL de retorno, literalmente.

Verificar o pagamento

Webhooks

O Dodo Payments chama seu backend quando um pagamento é concluído ou uma assinatura é ativada.

Get Payment Detail

Consulte paymentId usando sua secret key para verificar o status.
Conceda acesso somente depois que uma dessas opções confirmar o pagamento. Não dependa apenas de result.status.

Personalização da aparência

Para alterar a barra de ferramentas, os botões e o esquema de cores do navegador do checkout, passe customization para start(...). As Custom Tabs do Android e SFSafariViewController do iOS expõem controles nativos diferentes, portanto as opções são agrupadas em um objeto android e um objeto ios. Cada plataforma lê somente seu próprio objeto. Todos os campos são opcionais. Quando você omite um campo, a plataforma aplica seu próprio padrão.
string
Cor de fundo da barra de ferramentas, como uma string hexadecimal: "#RRGGBB" ou "#AARRGGBB".
string
Cor da barra de navegação, como uma string hexadecimal.
string
Cor do divisor acima da barra de navegação, como uma string hexadecimal.
'default' | 'back'
default exibe o ícone “X” do sistema. back exibe uma seta de voltar desenhada pelo SDK.
'start' | 'end'
O lado da barra de ferramentas onde o botão de fechar aparece.
boolean
Exibe o ícone de compartilhamento da barra de ferramentas. false o oculta.
boolean
Exibe o título da página abaixo da URL na barra de ferramentas.
boolean
Oculta automaticamente a barra de ferramentas à medida que 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'
light ou dark força essa aparência independentemente da configuração do sistema do dispositivo. system segue a configuração do sistema.
'done' | 'close' | 'cancel'
Estilo do botão de fechar. O iOS decide se ele será renderizado como um rótulo ou um ícone.
'pageSheet' | 'fullScreen'
pageSheet (o padrão) apresenta um cartão que o cliente pode deslizar para baixo para fechar. fullScreen cobre a tela inteira.
boolean
Permite que a barra de ferramentas seja recolhida à medida que a página é rolada. Ela só tem efeito visível quando presentationStyle é fullScreen. Com pageSheet, as barras permanecem fixas independentemente desta configuração.
'system' | 'light' | 'dark'
light ou dark força essa aparência independentemente da configuração do sistema do dispositivo. system segue a configuração do sistema.
O iOS não tem uma opção de cor da barra de ferramentas, porque as propriedades tint do SFSafariViewController subjacente estão obsoletas desde o iOS 26.

Erros

start rejeita com um CheckoutError somente em caso de uso incorreto ou falha da plataforma. Leia o motivo em error.code. Um cliente que cancela ou um pagamento recusado sempre gera um resultado, nunca uma rejeição.
  • INVALID_CHECKOUT_URL: checkoutUrl não é uma URL de sessão de checkout https (caminho iniciado por /session/) em checkout.dodopayments.com ou test.checkout.dodopayments.com.
  • INVALID_RETURN_URL: returnUrl não é uma URL absoluta com esquema e host.
  • ALREADY_IN_PROGRESS: outro checkout está em execução. Apenas um checkout pode ser executado por vez.
  • PLATFORM_ERROR: falha inesperada da plataforma. O SDK também informa qualquer erro nativo não reconhecido com este código.

Sessões abandonadas

O SDK nativo registra a sessão de checkout quando o checkout é iniciado e limpa o registro somente quando o checkout termina com succeeded, failed ou expired. O registro permanece quando o app ou o bundle JavaScript é encerrado durante o checkout, o que faz perder a promise start, e após um resultado cancelled ou pending. Verifique sua existência na próxima montagem e após cada resultado cancelled ou pending:
abandoned.sessionId é o ID da sessão de checkout, que começa com cks_. abandoned.createdAt é o Date em que o checkout foi iniciado. Seu backend pode consultar a sessão usando Obter sessão de checkout, que retorna payment_id e payment_status. Até que o pagamento alcance um status final, trate-o como pendente, não como falha.

Relacionado

Mobile Integration Guide

O mesmo contrato para Android, iOS e Flutter.

Expo Boilerplate

Um exemplo completo de Expo com integração de checkout.
Última modificação em 26 de setembro de 2026