Headless SDK (Payment Android)
SDK recomendadoPara uma experiência de integração tranquila, recomendamos usar o Android Seamless SDK. Essa opção oferece uma solução de pagamento flexível com componentes de interface do usuário pré-construídos e opções de personalização.
Esta página fornece um guia para o Yuno Headless Android SDK para pagamentos.
Esse SDK é ideal para comerciantes que:
- Precisa de controle total sobre a interface de pagamento e a experiência do usuário
- Deseja criar fluxos de pagamento personalizados
- Exigir recursos avançados de integração
Headless SDK recursos essenciais como:
- Acesso direto à API para processamento de pagamentos
- Token para métodos de pagamento
- Tratamento de autenticação 3DS
- Coleta de dados de prevenção de fraudes
Para comerciantes que preferem uma solução de interface do usuário pré-construída, considere usar nosso Full SDK ou Lite SDK .
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-keyeprivate-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
- Criar um
Versão mais recente do SDKConsulte as notas de lançamento ou visite 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 método de pagamento 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_sessionID para uso em etapas posteriores
O checkout_session é exclusivo para cada tentativa de pagamento e não pode ser reutilizado.
Etapa 3: Inclua a biblioteca em seu projeto
Inclua o SDK Yuno em seu projeto através do Gradle. Adicione a fonte do repositório:
maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }Adicione a dependência do Yuno SDK ao seu aplicativo no build.gradle arquivo:
dependencies {
implementation 'com.yuno.payments:android-sdk:{last_version}'
}O Yuno SDK inclui, por padrão, o INTERNET que é necessária para fazer solicitações de rede.
<uses-permission android:name="android.permission.INTERNET" />
Etapa 4: Initialize headless SDK a chave pública
Importe o Yuno e forneça uma chave API pública válida PUBLIC_API_KEY para initialize Headless SDK. Se você não tiver suas credenciais de API, consulte a página Desenvolvedores (Credenciais) para verificar como recuperá-las do painel.
Crie um aplicativo personalizado, caso ainda não o tenha feito. Na seção onCreate() método da sua classe de aplicativo, initialize SDK chamando o método Yuno.initialize() função:
class CustomApplication : Application() {
override fun onCreate() {
super.onCreate()
Yuno.initialize(
this,
PUBLIC_API_KEY,
config: YunoConfig,
)
}
}Etapa 5: Inicie o processo de checkout
Ligue para o apiClientPayment função após o cliente selecionar um método de pagamento para iniciar o processo de checkout. Essa função requer parâmetros de configuração e inicia a coleta de informações necessárias para a autenticação 3DS e as ferramentas de prevenção de fraudes configuradas em seu roteamento.
A tabela a seguir descreve os parâmetros necessários:
Parâmetro | Descrição |
|---|---|
|
|
| |
|
|
|
O bloco de código a seguir mostra um exemplo da configuração dos parâmetros:
val apiClientPayment = Yuno.apiClientPayment(
country_code = "US",
checkoutSession "74bf4b96-6b35-42a6-8c73-2fe094c34ca9",
context = this
)
Etapa 6: Gerar token
Após coletar as informações do usuário, crie um token único token OTT) usando o apiClientPayment.generateToken função. Como essa é uma função assíncrona, use um try/catch bloco para lidar com quaisquer erros que possam ocorrer. Os exemplos a seguir mostram dois cenários diferentes para a criação de um token único:
- Exemplo 1: Crie um token único token um cartão como método de pagamento e incluindo todas as informações necessárias do cartão.
- Exemplo 2: Crie um token de uso único usando o
vaulted_tokeninformações.
Benefícios de usar um token armazenado em cofre
Quando você usa um token armazenado token o SDK, todas as informações sobre fraudes dos provedores que você configurou no roteamento do cartão são coletadas e anexadas ao token único. Você também pode adicionar informações sobre parcelamento e um código de segurança, se o provedor exigir.
apiClientPayment.generateToken(
collectedData = TokenCollectedData(
checkoutSession "checkout_session",
métodoDePagamento = MétodoDePagamento (
tipo = "CARTÃO",
vaultedToken nulo,
cartão = DadosDoCartão(
salvar = verdadeiro,
detalhes = Detalhes(
mêsDeValidade = 11,
anoDeValidade = 55,
número = "4111111111111111",
securityCode = "123",
holderName = "Nome Sobrenome",
type = CardType.DEBIT
),
installment = Installment(
id = "id",
value = 12
)
),
cliente = Cliente(
id = "id",
merchantCustomerId = "merchant_customer_id",
primeiroNome = "primeiroNome",
sobrenome = "sobrenome",
sexo = Sexo.NB,
dataDeNascimento = "DD/MM/AAAA",
email "[email ]",
país = "EUA",
documento = Documento(
tipoDeDocumento = "PAS",
númeroDoDocumento = "PAS12312"
),
telefone = Telefone(
número = "321123321123",
códigoDoPaís = "1"
)
)
)
),
contexto = este
)
apiClientPayment.generateToken(
collectedData = TokenCollectedData(
checkoutSession "checkout_session",
paymentMethod = PaymentMethod(
type = "CARD",
vaultedToken "a1c7c5d1-b260-4dc6-909a-8368704233cf",
card = CardData(
save = true,
detail = Detail(
expirationMonth = 11,
expirationYear = 55,
number = "4111111111111111",
securityCode = "123",
holderName = "Nome Sobrenome",
type = CardType.DEBIT
),
parcelamento = Parcelamento(
id = "id",
valor = 12
)
),
cliente = Cliente(
id = "id",
merchantCustomerId = "merchant_customer_id",
nome = "nome",
sobrenome = "sobrenome",
sobrenome = "sobrenome",
sexo = Sexo.NB,
dataDeNascimento = "DD/MM/AAAA",
email "[email ]",
país = "CO",
documento = Documento(
tipoDeDocumento = "PAS",
númeroDoDocumento = "PAS12312"
),
phone = Phone(
number = "321123321123",
countryCode "57"
)
)
)
),
context = this
)
O apiClientPayment.generateToken retorna um tipo Observable, que é uma subclasse de LiveData. Você pode observar a resposta como uma resposta comum. LiveData com o seguinte tipo SingleLiveEvent<Map<String, Any?>>, que é um LiveData que só emite uma vez. O tipo de resposta é um Map contendo toda a resposta. O bloco de código a seguir mostra exemplos de respostas após chamar o apiClientPayment.generateToken função.
["token": "9ee44ac7-9134-4598-ae28-a26fec03099d",
"type": "CARD",
"customer": ["billing_address": null,
"first_name": null,
"gender": "",
"phone": nil,
"browser_info": ["color_depth": null,
"language": "en",
"accept_header": "*/*",
"browser_time_difference": nulo,
"accept_content": nulo,
"accept_browser": nulo,
"java_enabled": nulo,
"user_agent": "YunoSDK_Example/1 CFNetwork/1406.0.4 Darwin/22.6.0",
"screen_height": "844.0",
"screen_width": "390.0",
"javascript_enabled": null],
"documento": nulo,
"sobrenome": nulo,
"impressão digital do dispositivo": nulo,
"email": nulo],
"país": "EUA",
"token armazenado": nulo,
"parcela": ["taxa": "",
"id": "cca80084-961b-4212-9c34-54f03f4f10ae",
"value": 24,
"amount": null],
"card_data": null]
["token": "9ee44ac7-9134-4598-ae28-a26fec03099d",
"type": "CARD",
"customer": ["billing_address": null,
"first_name": null,
"gender": "",
"phone": nil,
"browser_info": ["color_depth": null,
"language": "en",
"accept_header": "*/*",
"diferença_de_tempo_do_navegador": nulo,
"aceitar_conteúdo": nulo,
"aceitar_navegador": nulo,
"java_habilitado": nulo,
"agente_do_usuário": "YunoSDK_Example/1 CFNetwork/1406.0.4 Darwin/22.6.0",
"screen_height": "844.0",
"screen_width": "390.0",
"javascript_enabled": null],
"document": null,
"last_name": null,
"device_fingerprint":null,
"email": null],
"country": "BR",
"vaulted_token":"a1c7c5d1-b260-4dc6-909a-8368704233cf",
"installment": ["rate": "",
"id": "cca80084-961b-4212-9c34-54f03f4f10ae",
"value": 24,
"amount": null],
"card_data": null]
A resposta endpoint fornece o sdk_action_required que define se ações adicionais são necessárias.
O bloco de código a seguir mostra um exemplo de observação da resposta:
apiClientPayment.generateToken(data, context).observe(context) { response ->
val token response["token"] como String?
val error = response["error"] como String?
}
Etapa 7: Criar o pagamento
Após gerar o token único, crie o pagamento chamando o método Criar endpoint de pagamento. Inclua o token único token em Etapa 6 no payment_method.token parâmetro da sua solicitação. O bloco de código a seguir mostra um exemplo de solicitação de criação de pagamento:
{
"merchant_order_id": "0000022",
"country": "US",
"account_id": "<Your account_id>",
"description": "Test",
"amount": {
"currency": "USD",
"value": 500
},
"customer_payer": {
"id": "cfae0941-7234-427a-a739-ef4fce966c79"
},
"checkout": {
"session": "<checkout session>"
},
"workflow": "SDK_CHECKOUT",
"payment_method": {
"type":"CARD",
"token": "2cd31999-e44e-4de3-bbe4-179981ff4295"
}
}endpoint inclui o sdk_action_required que indica se são necessárias ações adicionais para concluir o pagamento:
- Para métodos de pagamento síncronos, o pagamento é concluído instantaneamente. Nesse caso,
sdk_action_requiredseráfalsena resposta da API e o processo de pagamento é encerrado - Para fluxos de pagamento que exigem interação adicional com o SDK,
sdk_action_requiredserátrue. Quando isso acontecer, prossiga para Etapa 8 para as próximas etapas
Etapa 8: obtenha o URL do desafio 3DS (se necessário)
Quando um pagamento requer autenticação 3DS, pode ser necessário um desafio adicional para verificar a identidade do cliente. Para obter mais detalhes sobre esse processo, consulte a página 3D Secure. Se for necessário um desafio de verificação 3DS, endpoint Criar pagamento incluirá o seguinte:
- A
THREE_D_SECUREtipo de transação - Status igual a
PENDINGe sub status igual aWAITING_ADDITIONAL_STEP sdk_action_required = true
Ligue para o getThreeDSecureChallenge e fornecer a função checkoutSession usado para criar o pagamento para obter a URL do desafio 3DS. Após obter a URL, redirecione seu cliente para concluir o desafio. O bloco de código a seguir mostra como usar o getThreeDSecureChallenge função:
fun ApiClientPayment.getThreeDSecureChallenge(
context: Context,
checkoutSession: String? = null,
): SingleLiveEvent<ThreeDSecureChallengeResponse>
O getThreeDSecureChallenge A função retorna o ThreeDSecureChallengeResponse classe de dados, descrita no seguinte bloco de código:
classe de dados ThreeDSecureChallengeResponse(
val type: String,
val data: String,
)O type pode retornar ERROR ou URLdefinindo se a função retornou um URL válido para o desafio:
- Se
type = URL,dataconterá o URL que o cliente precisa acessar para concluir o desafio 3DS. - Se
type = ERROR,dataconterá a mensagem de erro, informando a origem do problema.
O bloco de código a seguir mostra um exemplo de como você pode observar a resposta de ThreeDSecureChallengeResponse:
apiClientPayment.getThreeDSecureChallenge(this)?.observe(this) {
se (it.type == "URL") {
} else
}
Quando o tipo de resposta for "URL", você poderá carregar o URL do desafio 3DS na visualização de sua preferência (WebView, guia personalizada ou navegador). Se o tipo de resposta não for "URL", isso indica que ocorreu um erro e você deve tratá-lo adequadamente exibindo uma mensagem de erro para o usuário.
Para concluir o desafio 3DS, redirecione os clientes para a URL retornada por getThreeDSecureChallenge(context). Após a conclusão bem-sucedida, os clientes são automaticamente redirecionados para o callback_url que você especificou ao criar o checkout_session usando o Criar sessão de checkout endpoint. O exemplo a seguir mostra como carregar a URL do desafio 3DS em um WebView:
val webView = WebView(this)
webViewContainer.addView(
webView,
ConstraintLayout.LayoutParams(
ConstraintLayout.LayoutParams.MATCH_PARENT,
ConstraintLayout.LayoutParams.MATCH_PARENT
)
)
webView.settings.javaScriptEnabled = true
webView.addJavascriptInterface(
object {
@JavascriptInterface
fun messageFromWeb(data: String?) {
}
},
"Android"
)
webView.loadUrl(url)
A interface JavaScript deve usar o nome messageFromWeb(data : String?) e ser adicionado com o nome Android. Isso permite que você capture eventos de desafio e determine quando eles são concluídos.
Para concluir o fluxo Headless SDK :
-
Use os Webhooks da Yuno para receber notificações sobre:
- O resultado do desafio 3DS
- O status do pagamento final
-
Opcionalmente, recupere os detalhes do pagamento usando o endpoint Recuperar pagamento por ID.
Para obter o guia completo de implementação de pagamentos, consulte Headless SDK Pagamento).
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.
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.
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.
Acesse o aplicativo de demonstraçãoAlé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.
Atualizado há 3 meses