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.
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.
Instalação
1
Install the Package
- Android
- iOS
- Expo
O pacote é vinculado automaticamente e obtém A dependência nativa é resolvida automaticamente, portanto nenhuma outra etapa de instalação é necessária.
com.dodopayments.api:checkout-android do Maven Central.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.Em todas as plataformas, defina a mesma URL usada como
- Android (Gradle)
- iOS (Info.plist)
- Expo (both platforms)
Defina o esquema como um manifest placeholder em Substitua
android/app/build.gradle:android/app/build.gradle
"myapp" pelo esquema do seu app.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
ChameDodoCheckout.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 listenerLinking 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.
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.CheckoutStatus
obrigatório
Um dos cinco valores:
succeeded: a URL de retorno temstatus=succeeded(pagamento único) oustatus=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=processingou qualquer valor derequires_*), ou o parâmetrostatusestava ausente ou não foi reconhecido. Faça a reconciliação como emcancelled.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.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, passecustomization 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.
Android — Custom Tab
Android — Custom Tab
string
Cor de fundo da barra de ferramentas, como uma string hexadecimal:
"#RRGGBB" ou "#AARRGGBB".Cor da barra de navegação, como uma string hexadecimal.
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.
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.iOS — SFSafariViewController
iOS — SFSafariViewController
'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.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:checkoutUrlnão é uma URL de sessão de checkouthttps(caminho iniciado por/session/) emcheckout.dodopayments.comoutest.checkout.dodopayments.com.INVALID_RETURN_URL:returnUrlnã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 comsucceeded, 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.