Seamless SDK (pagamento Android)

Esta página fornece um guia para o Yuno Seamless SDK para pagamentos Android.

👍

SDK recomendado

Recomendamos o uso do Android Seamless SDK para uma experiência de integração tranquila. Essa opção oferece uma solução de pagamento flexível com componentes de UI pré-criados e opções de personalização.

Esse SDK é ideal para comerciantes que:

• Deseja ter controle sobre o fluxo de pagamento e, ao mesmo tempo, aproveitar os componentes de IU pré-criados
• Necessidade de personalizar a experiência de pagamento e, ao mesmo tempo, manter a conformidade com a PCI
• Exigir um equilíbrio entre a velocidade de implementação e a personalização

O Seamless SDK inclui recursos como:

• Componentes de IU de pagamento pré-criados com opções de personalização
• Suporte a vários métodos de pagamento
• Tratamento avançado do status de pagamento
• Gerenciamento abrangente de erros

Para comerciantes que precisam de controle completo da interface do usuário ou de recursos mais avançados, considere usar nosso Full SDK em vez disso.

Requisitos

Antes de iniciar a integração do Yuno Android SDK, certifique-se de que seu projeto atenda aos requisitos técnicos. Além disso, certifique-se de que os seguintes pré-requisitos estejam em vigor:

• Você deve ter uma conta Yuno ativa.
• Você precisa de suas credenciais de API da Yuno (account_id, public-api-keye private-secret-key), que você pode obter no Seção de desenvolvedores do painel do Yuno. Essas credenciais são necessárias para autenticar solicitações à API da Yuno. A API é usada para:
  • Criar um customerque é necessário antes de iniciar os pagamentos
  • Criar um checkout_sessionque inicializa o fluxo de pagamento
  • Criar o pagamento associado à sessão

📘

Verificar a versão do SDK

Consulte as notas de versão ou o repositório do Yuno Android SDK para verificar a versão atual do SDK disponível.

Etapa 1: Criar um cliente

Crie um cliente usando o endpoint Criar cliente antes de iniciar os pagamentos. Essa etapa é necessária para:

• Identificar a pessoa que está fazendo o pagamento
• Ativar a funcionalidade de cartão salvo (se ativada)
• Acompanhar o histórico de pagamentos

O ID do cliente retornado desse endpoint será usado ao criar o checkout_session.

Etapa 2: Criar uma sessão de checkout

Criar um novo checkout_session usando o Criar sessão de checkout para initialize o fluxo endpoint pagamento. Certifique-se de que:

• Inclua o ID do cliente obtido na etapa anterior
• Armazene o checkout_session ID para uso na Etapa 6 da integração

💳

Controle a autenticação versus captura enviando payment_method.detail.card.capture na sessão de checkout: false = apenas autorizar, true = capturar imediatamente.

Parâmetros-chave

🚧

Uso da sessão de checkout

O checkout_session é exclusivo para cada tentativa de pagamento e não pode ser reutilizado.

Etapa 3: Adicione o SDK ao seu projeto

Adicione a fonte do repositório:

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

Inclua o seguinte código no arquivo build.gradle para adicionar a dependência do Yuno SDK ao aplicativo:

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

Etapa 4: Configurar permissões

O SDK da Yuno requer permissões de rede. Certifique-se de que a INTERNET A permissão está incluída em seu AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Etapa 5: Initialize o SDK

Recupere suas chaves públicas de API no painel do Yuno.

Se você não tiver implementado um aplicativo personalizado, crie um. Na seção onCreate() de sua classe de aplicativo, chame a função initialize (Yuno.initialize):

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Yuno.initialize(
            this,
            PUBLIC_API_KEY,
            config = YunoConfig()
        )
    }
}

Use o YunoConfig para definir configurações adicionais para o SDK. A tabela a seguir lista e descreve as opções de personalização:

O bloco de código a seguir mostra um exemplo de YunoConfig:

classe de dados YunoConfig(
    val cardFlow: CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean = false,
    val language: YunoLanguage? = null,
      val styles: YunoStyles? = null,
    val cardNumberPlaceholder: String? = null, // Opcional: texto personalizado para o campo do número do cartão
    val hideCardholderName: Boolean? = null // Opcional: defina como verdadeiro para ocultar o campo do nome do titular do cartão
)

Etapa 6: Iniciar o checkout

Ligue para o startCheckout no método onCreate() função da atividade que integra o SDK para iniciar um novo processo de pagamento com o Seamless SDK:

startCheckout(
 checkoutSession: "checkout_session",
  country_code: "US",
 callbackPaymentState: ((String?) -> Unit)?,
  merchantSessionId: String? = null
)

Os possíveis estados de pagamento retornados por callbackPaymentState são:

const val PAYMENT_STATE_SUCCEEDED =SUCCEEDED"
const val PAYMENT_STATE_FAIL = "FAIL" (Reprovado)
const val PAYMENT_STATE_PROCESSING = "PROCESSANDO"
const val PAYMENT_STATE_REJECT = "REJECT" (Rejeitado)
const val PAYMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR"
const val PAYMENT_STATE_STATE_CANCELED_BY_USER = "CANCELED" (Cancelado pelo usuário)

A tabela a seguir fornece informações adicionais sobre os possíveis estados:

Validação do status do pagamento

Esta seção explica como o SDK lida com o status do pagamento quando os usuários cancelam ou abandonam os fluxos de pagamento e como o status do SDK se relaciona com o status do pagamento no back-end nesses cenários.

Sincronizar métodos de pagamento (Google Pay)

Para métodos de pagamento síncronos, como o Google Pay, quando um usuário cancela ou fecha a interface do usuário da carteira antes de receber a resposta do provedor de serviços de pagamento (PSP):

• Status do SDK: Devoluções CANCELED (CANCELLED)
• Status do pagamento no backend: Restos mortais PENDING até ao tempo limite do PSP ou ao cancelamento pelo comerciante
• Importante: O SDK não retornará REJECT ou PROCESSING nesse cenário

Isso garante que o pagamento no backend permaneça em estado pendente e possa ser tratado adequadamente pelo sistema do comerciante.

Formas de pagamento assíncronas (PIX e métodos baseados em QR)

Para métodos de pagamento assíncronos como o PIX, quando um usuário fecha a janela do código QR (clica em X) antes de concluir o pagamento:

• Status do SDK: Devoluções PROCESSING, opcionalmente com um subestatuto, como CLOSED_BY_USER
• Status do pagamento no backend: Restos mortais PENDING e o código QR permanece válido até ao seu prazo de validade.
• Reutilização da sessão de checkout: reabrir a mesma sessão de checkout pode exibir o mesmo código QR válido.
• Sem cancelamento automático: O pagamento PIX não é cancelado automaticamente quando o usuário fecha a janela do QR.

Esse comportamento permite que os usuários retornem ao fluxo de pagamento e concluam a transação usando o mesmo código QR antes que ele expire.

Pagamentos assíncronos expirados

Se um código QR PIX expirar naturalmente:

• Status do backendAtualizado para EXPIRED
• Status do SDK: endpoints de chamadas de retorno do SDK e endpoints de pesquisa EXPIRED de forma consistente

Isso garante que os comerciantes recebam informações precisas sobre o status quando um método de pagamento expirar.

Etapa 7: Obter o token de uso único (OTT) para pagamento

Chamar o método startPaymentSeamlessLite para iniciar um processo de pagamento:

startPaymentSeamlessLite(
   paymentSelected: PaymentSelected,
   callbackPaymentState: ((String?) -> Unit)?,
   showPaymentStatus: Boolean,
)

A tabela a seguir descreve os parâmetros para iniciar o pagamento:

Você receberá o status do pagamento por meio de callbackPaymentStateque indicará se o pagamento foi bem-sucedido ou se ocorreu algum problema.

Etapa 8: Criar pagamento

Chamar o método startPaymentSeamlessLite com o método de pagamento selecionado para concluir o processo de pagamento:

startPaymentSeamlessLite(
   paymentSelected: PaymentSelected,
   callbackPaymentState: ((String?) -> Unit)?,
   showPaymentStatus: Boolean,
)

Recursos complementares

O Yuno Android SDK fornece serviços e configurações adicionais que você pode usar para melhorar a experiência dos clientes. Use a personalização do SDK para alterar a aparência do SDK de acordo com sua marca ou para configurar o carregador.

styles

Com o styles opção de personalização, você pode definir estilos visuais globais por meio de um YunoStyles objeto. Ele permite que você aplique uma marca consistente em todo o SDK, personalizando a aparência e a tipografia do botão.

classe de dados YunoStyles(
    val buttonStyles: YunoButtonStyles? = null,
    val fontFamily: FontFamily? = null
)

O YunoButtonStyles permite que você defina configurações específicas para a aparência do botão:

classe de dados YunoButtonStyles(
    val backgroundColor: Color? = null,
    val contentColor: Color? = null,
    val cornerRadius: Dp? = null,
    val elevation: Dp? = null,
    val padding: Dp? = null,
    val fontFamily: FontFamily? = null,
    val fontSize: TextUnit? = null,
    val fontStyle: FontStyle? = null
)

Use o YunoConfig descrita na Etapa 5, para usar a classe de dados styles opção de personalização.

Carregador

A funcionalidade do carregador é controlada por meio do keepLoader no parâmetro YunoConfig que está documentada em linha na seção de configuração do SDK acima.

Salvar o cartão para pagamentos futuros

Você também pode exibir uma caixa de seleção para salvar ou registrar cartões usando cardSaveEnable: true. Os exemplos a seguir mostram a caixa de seleção para ambas as renderizações do formulário de cartão:

Opções de renderização

Você pode escolher entre duas opções de renderização de formulário de cartão. As capturas de tela a seguir mostram a diferença entre cardFormType ONE_STEP e STEP_BY_STEP:

📘

Acesso ao aplicativo de demonstração

Além dos exemplos de código fornecidos, você pode consultar o repositório do Yuno para concluir a implementação dos SDKs do Yuno para Android.