Lite SDK (Payment 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 IU pré-criados e opções de personalização.

Esta página fornece um guia para o Lite SDK Yuno Lite SDK para pagamentos Android. Esse SDK oferece um processo de integração simplificado com funcionalidade essencial de pagamento, tornando-o ideal para comerciantes que:

• Precisa de uma implementação rápida com requisitos mínimos de personalização
• Deseja se concentrar principalmente no processamento de pagamentos com cartão
• Prefira uma interface de usuário pronta para uso que lide com o fluxo de pagamento

O Lite SDK inclui recursos essenciais como:

• Componentes de IU de pagamento pré-criados
• Processamento de pagamentos com cartão
• Tratamento básico do status de pagamento
• Gerenciamento de erros essenciais

Para os comerciantes que precisam de recursos mais avançados, como vários métodos de pagamento, interface de usuário personalizada ou prevenção avançada contra fraudes, 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 credenciais de desenvolvedores do painel de controle do Yuno. Essas credenciais são necessárias para autenticar solicitações à API do 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

📘

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 5 da integração
• O checkout_session é exclusivo para cada tentativa de pagamento e não pode ser reutilizado

🚧

Tratamento de retorno do navegador externo

Se o seu fluxo de pagamento enviar os usuários para um navegador externo (por exemplo, para autenticação 3DS ou redirecionamentos bancários), certifique-se de definir o callback_url ao criar sua sessão de checkout. Para obter um guia passo a passo sobre como lidar com o retorno ao seu aplicativo, consulte Manipular o retorno do navegador externo (callback_url).

Etapa 3: Inclua a biblioteca em seu projeto

Inclua o arquivo Yuno SDK em seu projeto por meio do Gradle. 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}'
}

Permissões

O SDK do Yuno inclui o INTERNET por padrão, que é necessária para fazer solicitações de rede.

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

Etapa 4: Initialize o SDK com a chave pública

Initialize o SDK:

1. Obtenha suas chaves de API públicas no painel do Yuno
2. Crie uma classe de aplicativo personalizada se você não tiver uma
3. Initialize o SDK chamando Yuno.initialize() na seção onCreate() passando sua chave de API e configuração:

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

Use a classe de dados YunoConfig para personalizar o comportamento do SDK. Inclua essa configuração ao chamar Yuno.initialize(). As opções disponíveis são:

classe de dados YunoConfig(
    val cardFlow: CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean = false,
    val cardFormDeployed: 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
)

A tabela a seguir descreve cada opção de personalização:

Você também precisa atualizar seu manifesto para usar seu aplicativo:

<application android:name=".CustomApplication"></application>

Etapa 5: Inicie o processo de 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 Lite SDK:

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

A tabela a seguir descreve os parâmetros necessários para iniciar o checkout:

Estado do pagamento do retorno de chamada

O callbackPaymentState é uma função que retorna o processo de pagamento atual. O envio dessa função não é obrigatório se você não precisar do resultado. O bloco de código a seguir mostra os estados possíveis:

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 6: Iniciar o processo de pagamento

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

startPaymentLite(
   paymentSelected: PaymentSelected,
   callbackOTT:(String?) -> Unit,
   callBackTokenWithInformation:OneTimeTokenModel?) -> Unit,
   showPaymentStatus: Boolean,
)

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

Envie um parâmetro adicional, que é o token do cofre e/ou o tipo de pagamento que o usuário selecionou para fazer o pagamento:

PaymentSelected(
 vaultedToken : String "payment_vaulted_token",
 paymentMethodType : String "payment_type",
)

Etapa 7: obtenha o OTT ( token de uso único)

O token de uso único é um identificador exclusivo que representa uma sessão de pagamento. Esse token é necessário para criar um pagamento.

token único de retorno de chamada

A chamada de retorno token único retorna os seguintes parâmetros:

🚧

Manuseio do carregador

O comerciante é responsável pelo manuseio do carregador. A Yuno oferece uma opção para usar nosso carregador; no entanto, o comerciante pode usar seu próprio carregador e deve fazer as configurações correspondentes.

Etapa 8: Criar o pagamento

Depois de concluir as etapas anteriores, crie um pagamento chamando o endpoint Create Payment (Criar pagamento ) em seu backend. Esse endpoint de endpoint requer:

• O token de uso único obtido na Etapa 7
• O checkout_session obtido na Etapa 2

🚧

Continuar a integração do método de pagamento

Yuno requer você integra o continuePayment do SDK depois que o pagamento for criado, porque determinados métodos de pagamento assíncronos exigem uma ação adicional do cliente para concluí-lo. A API informará você sobre esse cenário por meio da função sdk_action_required da resposta, que será retornado como verdadeiro. O campo yuno.continuePayment() exibirá as telas adicionais para os clientes, onde eles poderão executar as ações necessárias para concluir o pagamento sem precisar que você lide com cada cenário.

Para métodos de pagamento que exigem ações adicionais do cliente (como desafios de autenticação 3DS) ou processamento assíncrono (como transferências bancárias), você precisará integrar o continuePayment depois de criar o pagamento. A resposta da API Create Payment inclui um sdk_action_required que indica se essa etapa é necessária:

• Se TRUE: Chamada yuno.continuePayment() para exibir telas adicionais para ações do cliente (por exemplo, autenticação 3DS, páginas de redirecionamento do banco)
• Se FALSE: Ignore essa etapa, pois não é necessária nenhuma interação adicional com o cliente

O bloco de código a seguir mostra como implementar o fluxo de continuação de pagamento:

continuePayment(
   showPaymentStatus: Boolean = true,
   checkoutSession: String? = null,
   countryCode: String? = null,
   callbackPaymentState: ((String?) -> Unit)? = null
)

Enviar FALSE no showPaymentStatus para mostrar suas telas de status de pagamento. Em seguida, obtenha o estado do pagamento por meio de callback.

Modo de renderização (integração avançada)

Para os desenvolvedores que precisam de controle avançado de UI, o Lite SDK também oferece suporte à integração do modo de renderização. Esse modo fornece componentes de interface do usuário baseados em fragmentos que podem ser integrados a layouts personalizados, oferecendo mais flexibilidade e mantendo a funcionalidade simplificada Lite SDK .

Configuração básica do modo de renderização

Uso startPaymentRender para integração avançada com a interface do usuário:

fun Activity.startPaymentRender(
   checkoutSession: String? = null,
   countryCode: String? = null,
    coroutineScope: CoroutineScope,
   paymentSelected: PaymentSelected,
    listener: YunoPaymentRenderListener,
): YunoPaymentFragmentController

Exemplo de implementação

class PaymentActivity : Activity() {

    private lateinit var fragmentController: YunoPaymentFragmentController

    private fun initializeRenderMode() {
        fragmentController = startPaymentRender(
            checkoutSession = checkoutSessionId,
            countryCode = "US",
            coroutineScope = lifecycleScope,
            paymentSelected = PaymentSelected.CARD,
            listener = object : YunoPaymentRenderListener {
                override fun showView(fragment: Fragment) {
                    supportFragmentManager.beginTransaction()
                        .replace(R.id.payment_container, fragment)
                        .commit()
                }

                override fun returnOneTimeToken(oneTimeToken: String, additionalData: OneTimeTokenModel?) {
                    processPayment(oneTimeToken) {
                        fragmentController.continuePayment()
                    }
                }

                override fun returnStatus(resultCode: Int, paymentStatus: String) {
                    handlePaymentResult(paymentStatus)
                }

                override fun loadingListener(isLoading: Boolean) {
                    updateLoadingUI(isLoading)
                }
            }
        )
    }
}

Principais benefícios

• Integração de interface do usuário personalizada: Incorpore componentes de pagamento em seus layouts existentes
• Compatibilidade de fragmentos: Funciona com XML e Jetpack Compose
• Controle de fluxo: Gerencie o envio de formulários e a continuação do pagamento manualmente

🚧

Recurso avançado

O modo de renderização foi projetado para desenvolvedores que precisam de integração personalizada da interface do usuário. Para implementações mais simples, use os métodos padrão Lite SDK descritos nas etapas anteriores.

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 4, 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:

Personalização do SDK

Você pode alterar a aparência do SDK para que corresponda à sua marca. Para obter mais informações, consulte a página de personalização do SDK.

📘

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.