Headless SDK (Payment Web)
SDK recomendadoRecomendamos o uso do Web 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.
O Headless SDK da Yuno permite que você crie pagamentos. Observe que, ao usar o Headless SDK, você precisará solicitar e enviar via API todos os campos obrigatórios que o provedor de pagamento exige para gerar o pagamento em sua API.
O Headless SDK da Yuno permite que você crie pagamentos em dois cenários diferentes:
- Crie um Token de uso único usando informações de cartão de crédito e, em seguida, crie um pagamento.
- Criar um Token de uso único usando um
vaulted_tokende um cartão de crédito registrado anteriormente e, em seguida, crie um pagamento.
As etapas a seguir descrevem a criação de um pagamento usando o Headless SDK da Yuno.
Etapa 1: Inclua a biblioteca em seu projeto
Antes de prosseguir com a implementação do Headless SDK , consulte a Visão geral da integração do SDK para obter instruções detalhadas sobre como integrar adequadamente o SDK ao seu projeto.
O guia de integração fornece três métodos flexíveis:
- Inclusão direta de scripts HTML
- Injeção dinâmica de JavaScript
- Instalação do módulo NPM
Escolha o método de integração que melhor se adapte ao seu fluxo de trabalho de desenvolvimento e aos requisitos técnicos. Após concluir a integração do SDK, você pode prosseguir com as etapas a seguir para implementar a funcionalidade de checkout sem cabeça.
Biblioteca TypeScriptSe você estiver usando TypeScript, a Yuno fornece uma biblioteca que pode ser usada para ver todos os métodos disponíveis no Yuno Web SDK.
Etapa 2: Initialize Headless SDK com a chave pública
Em seu aplicativo JavaScript, crie uma instância do Yuno fornecendo uma classe PUBLIC_API_KEY.
const yuno = await YunoinitializePUBLIC_API_KEY);
CredenciaisConsulte a página de credenciais para obter mais informações: https://docs.y.uno/reference/authentication
Etapa 3: Inicie o processo de checkout
Em seguida, você iniciará o processo de checkout usando o apiClientPayment fornecendo os parâmetros de configuração necessários.
Parâmetros
Configure o pagamento com as seguintes opções:
| Parâmetro | Descrição |
|---|---|
country_code | Esse parâmetro especifica o país para o qual o processo payment está sendo configurado. Use um ENUM que representa o código do país desejado. Você pode encontrar a lista completa de países compatíveis e seus códigos correspondentes no site Cobertura de países página. |
checkout_session | Refere-se à sessão de checkout do pagamento atual criada usando o Criar sessão de checkout endpoint. Exemplo: '438413b7-4921-41e4-b8f3-28a5a0141638' |
const apiClientPayment = yuno.apiClientPayment({
country_code: "US",
checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
});Etapa 4: Gerar token
Depois de coletar todas as informações do usuário, você pode iniciar o pagamento. Primeiro, você precisa criar um token de uso único (OTT) usando a função apiClientpayment.generateToken. Como se trata de uma função assíncrona, você pode usar try/catch para garantir que você tratará corretamente os erros acionados. Os exemplos a seguir mostram diferentes cenários para criar o token de uso único:
- Exemplo 1: Crie um token de uso único utilizando um cartão como método de pagamento e incluindo todas as informações necessárias sobre o cartão.
- Exemplo 2: Crie um token de uso único usando o
vaulted_tokeninformações.
Benefícios de usar um Token abobadadoQuando você usa um token abobadado com o SDK, todas as informações sobre fraudes dos provedores que você configurou no roteamento de cartões são coletadas e anexadas ao token de uso único. Além disso, você pode adicionar informações de parcelamento e um código de segurança, se o provedor assim o exigir.
const oneTimeToken = await apiClientPayment.generateToken({
checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
payment_method: {
type: "CARD",
vaulted_token: null,
card: {
save: false,
detail: {
expiration_month: 11,
expiration_year: 25,
number: "4111111111111111",
security_code: "123",
holder_name: "ANDREA B",
type: "DEBIT"
},
installment: {
id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
value: 1
}
},
customer: {},
device_fingerprint: "0753b47f-bb43-86ab-647b-d735b67baac6",
third_party_session_id: "QbJU2KolVUm1fhQR0s9qgrS0ArEQmEfE"
}
});Parâmetros para o Exemplo 1
| Parâmetro | Descrição |
|---|---|
checkout_session | A sessão de checkout criada usando o endpoint Criar sessão de checkout |
payment_method.type | Tipo de método de pagamento, definido como "CARD" (cartão) |
payment_method.vaulted_token | Opcional: Use se você tiver um método de pagamento registrado anteriormente |
card.save | Opcional: Defina como "true" para gerar um token de cofre para o cartão |
card.detail | Informações do cartão, incluindo número, validade, código de segurança e nome do titular |
card.detail.type | Tipo de cartão: "DEBIT" (débito) ou "CREDIT" (crédito) |
card.installment | Opcional: Necessário apenas se um plano de parcelamento estiver configurado |
customer | Opcional: Objeto de informações do cliente |
device_fingerprint | Opcional: Necessário apenas se a triagem de fraude estiver configurada |
third_party_session_id | Opcional: Necessário apenas se houver configuração de terceiros |
const oneTimeToken = await apiClientPayment.generateToken({
checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
payment_method: {
type: "CARD",
vaulted_token: "aad8578e-ac2f-40a0-8065-25b5957f6555",
card: {
detail: {
security_code: "123"
},
installment: {
id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
value: 1
}
}
}
});Parâmetros para o Exemplo 2
| Parâmetro | Descrição |
|---|---|
checkout_session | A sessão de checkout criada usando o endpoint Criar sessão de checkout |
payment_method.type | Tipo de método de pagamento, definido como "CARD" (cartão) |
payment_method.vaulted_token | Usar o token protegido de um método de pagamento registrado anteriormente |
card.detail.security_code | Código de segurança do cartão registrado |
card.installment | Opcional: Necessário apenas se um plano de parcelamento estiver configurado |
O bloco de código a seguir mostra o apiClientPayment.generateToken para os dois exemplos acima:
{
"token": "ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d",
"vaulted_token": null,
"vault_on_success": false,
"type": "CARD",
"card_data": {
"holder_name": "ANDREA B",
"iin": "41111111",
"lfd": "1111",
"number_length": 16,
"security_code_length": 3,
"brand": "VISA",
"type": "CREDIT",
"category": "CREDIT",
"issuer_name": "JPMORGAN CHASE BANK N A",
"issuer_code": null
},
"customer": {
"first_name": "Cesar",
"last_name": "Sanchez",
"email": "[email protected]",
"gender": "",
"phone": null,
"billing_address": null,
"document": null,
"browser_info": {
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
"accept_header": "*/*",
"accept_content": "*/*",
"accept_browser": "*/*",
"color_depth": "24",
"screen_height": "1080",
"screen_width": "2560",
"javascript_enabled": true,
"java_enabled": false,
"browser_time_difference": "300",
"language": "en-US"
},
"device_fingerprint": "19764508-c9df-a90b-a365-83b2d718c12e"
},
"installment": null,
"country": "CO"
}{
token: 'ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d',
vaulted_token: aad8578e-ac2f-40a0-8065-25b5957f6555,
vault_on_success: false,
type: 'CARD',
card_data: {
holder_name: 'ANDREA B',
iin: '41111111',
lfd: '1111',
number_length: 16,
security_code_length: 3,
brand: 'VISA',
type: 'CREDIT',
category: 'CREDIT',
issuer_name: 'JPMORGAN CHASE BANK N A',
issuer_code: null,
},
customer: {
first_name: 'Cesar',
last_name: 'Sanchez',
email: '[email protected]',
gender: '',
phone: null,
billing_address: null,
document: null,
browser_info: {
user_agent:
'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
accept_header: '*/*',
accept_content: '*/*',
accept_browser: '*/*',
color_depth: '24',
screen_height: '1080',
screen_width: '2560',
javascript_enabled: true,
java_enabled: false,
browser_time_difference: '300',
language: 'en-US',
},
device_fingerprint: '19764508-c9df-a90b-a365-83b2d718c12e',
},
installment: null,
country: 'CO',
}Etapa 5: Criar o Payment
Depois de receber o token de uso único, você pode criar o pagamento usando o Criar endpoint de pagamento para obter o resultado final do pagamento. Você informará o token único recebido em Etapa 4 por meio da solicitação payment_method.token parâmetro. O bloco de código a seguir mostra um exemplo de solicitação para criar um 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"
}
}A resposta endpoint fornece o sdk_action_required que define se ações adicionais são necessárias para concluir o pagamento:
- Se seu cliente selecionar um método de pagamento síncrono, o pagamento será concluído instantaneamente. Nesse cenário, o campo
sdk_action_requiredna resposta da API seráfalsee o processo de pagamento é concluído nessa etapa. - Quando uma interação adicional do SDK é necessária para concluir o fluxo de pagamento,
sdk_action_requiredserátrue. Se esse for o caso, você precisa seguir as instruções de Etapa 6.
Etapa 6: Obtenha o URL do desafio 3DS
Conforme descrito na página Verificação de cartão 3DS, um pagamento com 3DS pode exigir um desafio adicional para verificar a identidade do cliente. Se for necessária uma etapa de verificação adicional relacionada a um desafio de verificação do 3DS, a resposta ao endpoint Criar pagamento terá as seguintes informações:
- A
THREE_D_SECUREtipo de transação. - Status igual a
PENDINGe sub status igual aWAITING_ADDITIONAL_STEP. - O
sdk_action_requireddefinido comotrue.
Para obter o URL do desafio 3DS, você deve chamar o getThreeDSecureChallenge fornecendo a função checkoutSession usado para criar o pagamento.
const data = await apiClientPayment.getThreeDSecureChallenge(checkoutSession?: string): Promise<{url: string}>Se o cartão não exigir um desafio para verificar a identidade do cliente, o url retornará null.
Em um navegador da Web, você pode abrir o URL em uma nova guia ou em um IFrame. Para abrir o URL em um iframe, você deve definir o parâmetro embedded = true. Caso contrário, você pode omitir esse parâmetro, cujo valor padrão é false. O bloco de código a seguir mostra um exemplo de exibição do conteúdo do desafio 3DS em um IFrame:
document.querySelector('#element').innerHTML = `
<iframe
src="${data.url}&embedded=true"
height="700px"
width="100%"
border="0"
frameBorder="0">
</iframe>
`;
window.addEventListener('message', (event) => {
if (
!event.origin.toLocaleLowerCase().includes('sdk-3ds') ||
event?.data?.origin !== 'CHALLENGE'
) {
return
}
document.querySelector('#element').innerHTML = '';
if (event.data.status === 'ERROR') {
document.querySelector('#element').innerHTML = 'There was an error';
} else {
document.querySelector('#element').innerHTML = 'Challenge was finished';
}
});Você é responsável por redirecionar seus clientes para a URL fornecida pelo redirect_url para concluir o desafio. Quando o cliente concluir com êxito o desafio 3DS, ele será automaticamente redirecionado para a página callback_urlque você forneceu ao criar o checkout_session com o Criar sessão de checkout endpoint.
Para concluir o fluxo de pagamento do Headless SDK , você precisa usar o Yuno Webhooks, que o notificará imediatamente sobre o resultado do desafio 3DS e o status final do pagamento. O uso de webhooks garante que você receba atualizações em tempo real sobre o andamento da transação de pagamento. Além dos webhooks, você pode recuperar as informações de pagamento usando o endpoint Retrieve Payment by ID.
Etapa 7: Obter ações de pagamento
Às vezes, o pagamento pode exigir uma ação extra para continuar o fluxo de pagamento. Para determinar qual ação é necessária, você deve chamar a função getContinuePaymentAction fornecendo o método checkoutSession usado para criar o pagamento.
const data = await apiClientPayment.getContinuePaymentAction({ checkoutSession: string }): Promise<ContinuePaymentAction>O getContinuePaymentAction retorna um ContinuePaymentAction que descreve a ação específica necessária para continuar o fluxo de pagamento, dependendo do provedor e da etapa específica necessária.
ContinuePaymentAction estrutura de resposta
ContinuePaymentAction estrutura de respostaA resposta contém informações sobre o tipo de ação exigida e os dados necessários para executar essa ação:
type ContinuePaymentAction = {
type: Provider.Type;
action: Provider.Action;
payment_code?: {
code: string;
reference: string;
expiration_time?: number;
};
image?: {
type: string;
value: string;
reference: string;
expiration_time?: number;
additional_data?: Record<string, undefined>;
};
redirect?: {
init_url: string;
success_url: string;
error_url: string;
};
otp?: {
length: number;
expiration_time: number;
retries: {
accepts: boolean;
number: number;
};
resend: {
timer: number;
number: number;
};
payment_instructions: string;
};
three_d_secure_redirect?: {
init_url: string;
access_token: string;
redirect_url?: string;
};
transaction_id?: string;
request_html?: {
body?: Record<string, string>;
headers?: Record<string, string>;
method?: "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
url: string;
};
sdk_provider?: {
client_id?: string;
intent?: string;
components?: string;
gateway: string;
init_url?: string;
merchant_id: string;
amount: {
currency: string;
value: number;
};
protocol_version?: string;
provider_id?: string;
payment_methods?: string[];
supported_networks?: string[];
session?: {
epoch_timestamp: number;
expires_at: number;
merchant_session_identifier: string;
nonce: string;
merchant_identifier: string;
domain_name: string;
display_name: string;
signature: string;
operational_analytics_identifier: string;
retries: number;
psp_id: string;
};
provider_token_id?: string;
};
render_html?: {
content?: string;
redirect_url?: string;
};
info?: {
screen_info?: string;
};
render_iframe: {
init_url: string;
access_token: string;
redirect_url?: string;
};
};ContinuePaymentAction Campos
ContinuePaymentAction Campos| Campo | Descrição |
|---|---|
type | Tipo de provedor de pagamento (por exemplo, MERCADO_PAGO, DLOCAL, etc.) |
action | Ação específica necessária para continuar o pagamento (por exemplo, REDIRECT_URL, OTP, etc.) |
payment_code | Usado quando o provedor de pagamento emite um código de pagamento para pagamentos em dinheiro |
image | Usado quando uma imagem (por exemplo, código QR) deve ser exibida para o usuário |
redirect | Usado quando um redirecionamento é necessário para fluxos de pagamento de terceiros |
otp | Usado quando o fluxo requer validação OTP (One-Time Password) |
three_d_secure_redirect | Usado para fluxos 3DS que redirecionam o usuário para uma etapa de verificação segura |
transaction_id | ID exclusivo da transação, se disponível |
request_html | Usado para renderizar um formulário de pagamento com HTML e cabeçalhos dinâmicos |
sdk_provider | Usado para provedores baseados em SDK (por exemplo, Apple Pay, Google Pay) |
render_html | Usado para exibir conteúdo HTML diretamente no aplicativo |
info | Informações gerais ou mensagens (por exemplo, mostrar mensagem de confirmação) |
render_iframe | Usado quando o provedor precisa renderizar um iframe para a interação do usuário |
Tipos e ações do provedor
As enums a seguir definem os provedores de pagamento compatíveis e as ações possíveis:
export declare namespace Provider {
enum Type {
MERCADO_PAGO = "MERCADO_PAGO",
WOMPI = "WOMPI",
PAYMENTEZ = "PAYMENTEZ",
GETNET = "GETNET",
TRANSFEERA = "TRANSFEERA",
CYBERSOURCE_3DS = "CYBERSOURCE_3DS",
NETCETERA_3DS = "NETCETERA_3DS",
XENDIT_3DS = "XENDIT_3DS",
DLOCAL = "DLOCAL",
CIELO = "CIELO",
INSWITCH = "INSWITCH",
PAGALEVE = "PAGALEVE",
UNLIMINT_3DS = "UNLIMINT_3DS"
}
enum Action {
PAYMENT_CODE = "PAYMENT_CODE",
IMAGE = "IMAGE",
REDIRECT_URL = "REDIRECT_URL",
FORM = "FORM",
INFO = "INFO",
OTP = "OTP",
SDK_PROVIDER = "SDK_PROVIDER",
THREE_D_SECURE_REDIRECT_URL = "THREE_D_SECURE_REDIRECT_URL",
REQUEST_HTML = "REQUEST_HTML",
RENDER_HTML = "RENDER_HTML",
RENDER_IFRAME = "RENDER_IFRAME"
}
}Tipos e ações do provedor
| Tipo de provedor | Descrição |
|---|---|
MERCADO_PAGO | Provedor de pagamentos do Mercado Pago |
WOMPI | Provedor de pagamento Wompi |
PAYMENTEZ | Provedor de pagamento Paymentez |
GETNET | Provedor de pagamento Getnet |
TRANSFEERA | Provedor de pagamento Transfeera |
CYBERSOURCE_3DS | Provedor 3DS da Cybersource |
NETCETERA_3DS | Provedor Netcetera 3DS |
XENDIT_3DS | Provedor Xendit 3DS |
DLOCAL | Provedor de pagamento DLocal |
CIELO | Provedor de pagamentos da Cielo |
INSWITCH | Provedor de pagamento Inswitch |
PAGALEVE | Provedor de pagamento Pagaleve |
UNLIMINT_3DS | Provedor Unlimint 3DS |
| Tipo de ação | Descrição |
|---|---|
PAYMENT_CODE | Mostrar o código de pagamento ao usuário |
IMAGE | Mostrar imagem (por exemplo, código QR) |
REDIRECT_URL | Redirecionar o usuário para uma página externa |
FORM | Renderize um formulário para coletar informações do usuário |
INFO | Exibir tela informativa |
OTP | Exigir a entrada de OTP do usuário |
SDK_PROVIDER | Use o SDK para processar o pagamento |
THREE_D_SECURE_REDIRECT_URL | Iniciar a autenticação 3DS |
REQUEST_HTML | Enviar uma solicitação de formulário HTML |
RENDER_HTML | Renderizar HTML estático no aplicativo |
RENDER_IFRAME | Renderizar iframe para a UI do provedor |
Tratamento de diferentes tipos de ação
Com base no action na resposta, você deve tratar cada tipo de ação adequadamente:
REDIRECT_URL Ação
REDIRECT_URL AçãoQuando a ação é REDIRECT_URLvocê deve redirecionar o usuário para o URL fornecido em data.redirect.init_url:
if (data.action === "REDIRECT_URL") {
window.location.href = data.redirect.init_url;
}Outros tipos de ação
Cada tipo de ação requer um tratamento específico com base nos dados fornecidos:
- PAYMENT_CODE: Exibe o código de pagamento e a referência para o usuário
- IMAGEM: Mostrar um código QR ou outra imagem ao usuário
- OTP: apresente um formulário de entrada de OTP ao usuário
- SDK_PROVIDER: Initialize o SDK do provedor específico
- RENDER_IFRAME: Exibe um iframe com a interface do provedor
Tratamento de ações de pagamentoA implementação específica para lidar com cada tipo de ação dependerá da estrutura e dos requisitos da interface do usuário do seu aplicativo. Certifique-se de tratar todos os tipos de ação possíveis que seus provedores de pagamento configurados possam retornar.
Aplicativo de demonstraçãoAlém dos exemplos de código fornecidos, você pode acessar o aplicativo de demonstração para obter uma implementação completa dos SDKs da Yuno.
Mantenha-se atualizado
Acesse o changelog para obter as atualizações mais recentes do SDK e o histórico de versões.
Atualizado há 3 meses