iOS

Esta página aborda o SDK oficial de checkout do Dodo Payments para iOS e Swift. Ele abre o checkout hospedado do Dodo Payments em uma visualização de navegador nativa e retorna um resultado tipado.

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 iOS abre o checkout hospedado do Dodo Payments em SFSafariViewController e retorna um CheckoutResult tipado quando o cliente conclui ou sai do checkout. Ele não armazena nenhuma API key e não contém código de rede, portanto nunca chama a API do Dodo Payments. O checkout é executado na visualização do navegador. O SDK apresenta e fecha essa visualização e lê o resultado da URL de retorno. Requisitos: iOS 16 ou posterior e Swift 6.2 ou posterior (o pacote declara swift-tools-version: 6.2). O SDK não tem dependências de terceiros.

Instalação

Add the Package

No Xcode, acesse File → Add Package Dependencies e insira a URL do pacote:

https://github.com/dodopayments/dodopayments-mobile-sdk-ios

Selecione a versão 1.1.0 ou posterior. A personalização da aparência requer a versão 1.1.0.Para adicionar o pacote em Package.swift, em vez disso, adicione esta dependência:

Package.swift

.package(url: "https://github.com/dodopayments/dodopayments-mobile-sdk-ios", from: "1.1.0")

O produto da biblioteca é DodoCheckout.

Registre um esquema de URL para que o iOS encaminhe a URL de retorno do checkout de volta ao seu app. Adicione um tipo de URL ao seu 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 o tipo de URL no Xcode em Info → URL Types.Use este esquema no returnUrl que você passa ao SDK, por exemplo myapp://checkout/return, e defina a mesma URL como return_url da sessão de checkout quando o seu 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

DodoCheckout.start é uma função async que é executada no ator principal. Passe checkoutUrl como um URL criado a partir do checkout_url retornado pelo seu backend:

import DodoCheckout

// showSuccess(_:), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,   // from your backend's checkout session
    returnUrl: URL(string: "myapp://checkout/return")!,
    onEvent: { event in print(event.name) }  // logging only
)

switch result.status {
case .succeeded: showSuccess(result.paymentId)
case .failed:    showFailure()
case .cancelled: await reconcileAbandonedSession()  // outcome unknown, not a failure
case .pending:   await reconcileAbandonedSession()
case .expired:   showExpired()
}

onEvent recebe eventos .opened, .returnReceived e .closed. Seus valores name são checkout.opened, checkout.return_received e checkout.closed. Use os eventos apenas para logging, nunca para decidir o resultado.

Encaminhamento da URL de retorno

SFSafariViewController não pode capturar sua própria URL de retorno, então o iOS abre a URL no seu app. Encaminhe cada URL recebida para DodoCheckout.handleOpenURL(_:). Em um app sem cenas, chame-o a partir do application(_:open:options:) do app delegate.

SwiftUI
SceneDelegate

.onOpenURL { url in
    DodoCheckout.handleOpenURL(url)
}

SceneDelegate.swift

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    DodoCheckout.handleOpenURL(url)
}

Você pode encaminhar todas as URLs. handleOpenURL atua apenas em uma URL que corresponde ao returnUrl do checkout em andamento e retorna true para ela. Para qualquer outra URL, ele retorna false; portanto, trate essa URL por conta própria.

O significado do resultado

O SDK cria CheckoutResult a partir dos parâmetros de consulta na URL de retorno.

result.status é uma indicação para a UI, não uma prova de pagamento. Confirme cada pagamento 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 sheet antes que a URL de retorno chegasse. O SDK não conhece o resultado, e o pagamento pode ter sido bem-sucedido; portanto, não exiba uma tela de falha. Em vez disso, faça a reconciliação da sessão abandonada.
pending: o pagamento é liquidado posteriormente (status=processing ou qualquer valor 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. 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.

[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.

[String: String]

Cada parâmetro 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 com 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 o botão de fechamento da sheet, o estilo de apresentação e o esquema de cores, passe um BrowserCustomization como customization para start(...). Todos os campos são opcionais. Para um campo nil, o SDK não define essa opção e o iOS aplica seu próprio padrão. A exceção é presentationStyle, em que nil significa pageSheet.

DismissButtonStyle?

Estilo do botão de fechamento: done, close ou cancel. O iOS decide se ele será renderizado como um rótulo ou um ícone.

PresentationStyle?

pageSheet (o padrão) apresenta um cartão que o cliente pode deslizar para baixo para fechar. fullScreen cobre a tela inteira e não tem gesto de fechamento.

Bool?

Permite que a barra de ferramentas seja recolhida conforme a página rola. Ela só tem efeito visível quando presentationStyle é fullScreen. Com pageSheet, as barras permanecem fixas independentemente desta configuração.

ColorScheme?

light ou dark força essa aparência independentemente da configuração do sistema do dispositivo. system segue a configuração do sistema. Esta opção aplica o tema somente aos controles nativos ao redor da página. O modo claro ou escuro da própria página de checkout vem de customization.theme na sessão de checkout, e suas cores vêm de customization.theme_config.

O iOS não tem uma opção de cor da barra de ferramentas. As propriedades de tonalidade do SFSafariViewController subjacente estão obsoletas a partir do iOS 26.

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        dismissButtonStyle: .close,
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)

Erros

start lança CheckoutError somente em caso de uso incorreto ou falha da plataforma. Leia o motivo em error.code. O cancelamento por parte do cliente ou um pagamento recusado sempre é um resultado, nunca um erro lançado.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): checkoutUrl não é uma URL de sessão de checkout https (caminho começando com /session/) em checkout.dodopayments.com ou test.checkout.dodopayments.com.
invalidReturnUrl (INVALID_RETURN_URL): returnUrl não é uma URL absoluta com esquema e host.
alreadyInProgress (ALREADY_IN_PROGRESS): outro checkout está em execução. Apenas um checkout pode ser executado por vez.
platformError (PLATFORM_ERROR): falha inesperada da plataforma, como a ausência de um view controller a partir do qual apresentar.

Depois de um erro lançado, verifique também se há uma sessão abandonada. Se a sheet não tiver confirmado que apareceu, o SDK mantém a sessão registrada porque o checkout ainda pode estar aberto. A exceção é alreadyInProgress: um registro encontrado nesse momento pertence ao checkout que ainda está em execução.

Sessões abandonadas

O SDK registra a sessão de checkout quando apresenta o checkout 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 se há um registro na próxima inicialização e após cada resultado cancelled ou pending.

import DodoCheckout

if let abandoned = DodoCheckout.getAbandonedSession() {
    // Ask your backend for the outcome of abandoned.sessionId, and show it.
    // Clear the record only after the outcome is final:
    DodoCheckout.clearAbandonedSession()
}

abandoned.sessionId é o ID da sessão de checkout, que começa com cks_. abandoned.createdAt é o checkout Date 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 falho.

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

Personalização da aparência

Erros

Sessões abandonadas

Relacionado

Mobile Integration Guide

React Native SDK

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

​Personalização da aparência

​Erros

​Sessões abandonadas

​Relacionado

Mobile Integration Guide

React Native SDK

Instalação

Uso

Encaminhamento da URL de retorno

O significado do resultado

Verificar o pagamento

Personalização da aparência

Erros

Sessões abandonadas

Relacionado