Esta página aborda o pacote oficial do Dodo Payments para Flutter,
dodopayments_checkout no pub.dev. Também existe um pacote separado criado pela comunidade. Consulte
Projetos da comunidade.Checkout Sessions API
Crie o
checkout_url que este SDK abre a partir do seu backend.Mobile Integration Guide
Veja como este SDK se integra ao fluxo completo de pagamentos móveis.
dodopayments_checkout abre o checkout hospedado do Dodo Payments em SFSafariViewController no iOS e em uma Custom Tab no Android, e retorna um CheckoutResult tipado. Ele usa o mesmo código nativo que os SDKs independentes para iOS e
Android, e toda a lógica do checkout reside nesse código nativo. A camada Dart encaminha cada chamada por meio de um canal tipado do
Pigeon. O pacote não armazena nenhuma chave de API e nunca chama a API do Dodo Payments.
Requisitos: Flutter 3.44 ou posterior com Dart 3.12 ou posterior, iOS 16 ou posterior e Android minSdk 23.
Instalação
1
Add the Dependency
Adicione o pacote a A personalização da aparência requer a versão 1.1.0 ou posterior.O plugin do Android compila com o Android SDK 35 por padrão. Se outro plugin precisar de um
pubspec.yaml:pubspec.yaml
compileSdk superior, defina dodoCompileSdk no gradle.properties do seu app.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 ao seu app. Use esse esquema no
returnUrl que você transmite ao SDK e defina a mesma URL como return_url da sessão de checkout quando o backend criar a sessão. A URL não precisa carregar uma página real.- iOS
- Android
Adicione um tipo de URL para o seu esquema em
ios/Runner/Info.plist:ios/Runner/Info.plist
SFSafariViewController não consegue capturar a própria URL de retorno, então o iOS abre a URL no seu app. Encaminhe todas as URLs recebidas ao SDK, por exemplo a partir de
app_links:Você pode encaminhar todas as URLs.
handleOpenURL atua somente sobre uma URL que corresponda ao
returnUrl do checkout em andamento e resolve true para ela. Para qualquer
outra URL, resolve false. No Android, sempre resolve false.Uso
ChameDodoCheckout.instance.start com o checkout_url do seu backend:
onEvent recebe eventos cujo type é CheckoutEventType.opened, returnReceived ou closed. Use-os somente para logging, nunca para decidir o resultado.
O que o resultado significa
O SDK criaCheckoutResult a partir dos parâmetros de consulta na URL de retorno.
CheckoutStatus
obrigatório
Um de 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 de a URL de retorno chegar. O SDK não sabe o resultado, e o pagamento pode ter sido concluído; portanto, não mostre uma tela de falha. Em vez disso, faça a conciliação da sessão abandonada.pending: o pagamento é liquidado posteriormente (status=processingou qualquer valor derequires_*), ou o parâmetrostatusestava ausente ou não era reconhecido. Faça a conciliaçã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. Mostre-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.List<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.Map<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 com sua chave secreta 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, passe umBrowserCustomization como customization em CheckoutParams. As Custom Tabs do Android e SFSafariViewController do iOS expõem controles nativos diferentes, portanto as opções são divididas em AndroidBrowserOptions e IosBrowserOptions. Cada plataforma ignora as opções da outra. Todos os campos são opcionais e assumem null por padrão. Para um campo null, o SDK não define essa opção e a plataforma aplica seu próprio padrão.
Android — Custom Tab
Android — Custom Tab
Color?
Cor de fundo da barra de ferramentas.
Cor da barra de navegação.
Cor do divisor acima da barra de navegação.
CloseButtonStyle?
standard exibe o ícone de sistema “X”. back exibe uma seta de voltar desenhada pelo SDK.CloseButtonPosition?
O lado da barra de ferramentas em que o botão de fechar aparece:
start ou end.Exibe o ícone de compartilhamento da barra de ferramentas.
false o oculta.bool?
Exibe o título da página abaixo da URL na barra de ferramentas.
bool?
Oculta automaticamente a barra de ferramentas conforme a página rola.
bool?
Exibe “Adicionar esta página aos favoritos” no menu de opções.
bool?
Exibe “Baixar página” no menu de opções.
BrowserColorScheme?
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
DismissButtonStyle?
Estilo do botão de fechar:
done, close ou cancel. O iOS decide se ele será renderizado como um rótulo ou um ícone.PresentationStyle?
pageSheet (usado quando você deixa este null) exibe um cartão que o cliente pode deslizar para baixo para fechar. fullScreen ocupa a tela inteira.bool?
Permite que a barra de ferramentas seja recolhida conforme a página rola. Isso só produz efeito quando
presentationStyle é fullScreen. Com pageSheet, as barras permanecem fixas independentemente desta configuração.BrowserColorScheme?
light ou dark força essa aparência independentemente da configuração do sistema do dispositivo. system segue a configuração do sistema.SFSafariViewController foram descontinuadas a partir do iOS 26.
Erros
start lança CheckoutException somente em caso de uso incorreto ou falha da plataforma. Leia o motivo em code, um CheckoutErrorCode. A string do código nativo está em nativeCode.
Um cliente que cancela ou um pagamento recusado é sempre um resultado, nunca uma exceção.
invalidCheckoutUrl(INVALID_CHECKOUT_URL):checkoutUrlnão é uma URL de sessão de checkouthttps(caminho iniciado por/session/) emcheckout.dodopayments.comoutest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlnão é uma URL absoluta com esquema e host.alreadyInProgress(ALREADY_IN_PROGRESS): outro checkout está em execução. Somente um checkout pode ser executado por vez.platformError(PLATFORM_ERROR): falha inesperada da plataforma. Erros nativos desconhecidos também são mapeados para este código.
Sessões abandonadas
O SDK nativo registra a sessão de checkout quando o checkout começa e limpa o
registro somente quando o checkout termina com
succeeded, failed ou expired. O registro
permanece quando o app é encerrado durante o checkout e após um resultado cancelled ou pending.
Verifique sua existência na próxima inicialização 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 DateTime em que o checkout foi iniciado. Seu backend pode consultar a sessão com 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 React Native.
Community Projects
Também existe um pacote Flutter separado criado pela comunidade.