Headless SDK (Payment Web)


👍

SDK recomendado

Recomendamos 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_token de 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:

  1. Inclusão direta de scripts HTML
  2. Injeção dinâmica de JavaScript
  3. 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 TypeScript

Se 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);
📘

Credenciais

Consulte 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âmetroDescrição
country_codeEsse 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_sessionRefere-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:

  1. 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.
  2. Exemplo 2: Crie um token de uso único usando o vaulted_token informações.
📘

Benefícios de usar um Token abobadado

Quando 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âmetroDescrição
checkout_sessionA sessão de checkout criada usando o endpoint Criar sessão de checkout
payment_method.typeTipo de método de pagamento, definido como "CARD" (cartão)
payment_method.vaulted_tokenOpcional: Use se você tiver um método de pagamento registrado anteriormente
card.saveOpcional: Defina como "true" para gerar um token de cofre para o cartão
card.detailInformações do cartão, incluindo número, validade, código de segurança e nome do titular
card.detail.typeTipo de cartão: "DEBIT" (débito) ou "CREDIT" (crédito)
card.installmentOpcional: Necessário apenas se um plano de parcelamento estiver configurado
customerOpcional: Objeto de informações do cliente
device_fingerprintOpcional: Necessário apenas se a triagem de fraude estiver configurada
third_party_session_idOpcional: 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âmetroDescrição
checkout_sessionA sessão de checkout criada usando o endpoint Criar sessão de checkout
payment_method.typeTipo de método de pagamento, definido como "CARD" (cartão)
payment_method.vaulted_tokenUsar o token protegido de um método de pagamento registrado anteriormente
card.detail.security_codeCódigo de segurança do cartão registrado
card.installmentOpcional: 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_required na 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_required será 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_SECURE tipo de transação.
  • Status igual a PENDING e sub status igual a WAITING_ADDITIONAL_STEP.
  • O sdk_action_required definido como true.

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

A 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

CampoDescrição
typeTipo de provedor de pagamento (por exemplo, MERCADO_PAGO, DLOCAL, etc.)
actionAção específica necessária para continuar o pagamento (por exemplo, REDIRECT_URL, OTP, etc.)
payment_codeUsado quando o provedor de pagamento emite um código de pagamento para pagamentos em dinheiro
imageUsado quando uma imagem (por exemplo, código QR) deve ser exibida para o usuário
redirectUsado quando um redirecionamento é necessário para fluxos de pagamento de terceiros
otpUsado quando o fluxo requer validação OTP (One-Time Password)
three_d_secure_redirectUsado para fluxos 3DS que redirecionam o usuário para uma etapa de verificação segura
transaction_idID exclusivo da transação, se disponível
request_htmlUsado para renderizar um formulário de pagamento com HTML e cabeçalhos dinâmicos
sdk_providerUsado para provedores baseados em SDK (por exemplo, Apple Pay, Google Pay)
render_htmlUsado para exibir conteúdo HTML diretamente no aplicativo
infoInformações gerais ou mensagens (por exemplo, mostrar mensagem de confirmação)
render_iframeUsado 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 provedorDescrição
MERCADO_PAGOProvedor de pagamentos do Mercado Pago
WOMPIProvedor de pagamento Wompi
PAYMENTEZProvedor de pagamento Paymentez
GETNETProvedor de pagamento Getnet
TRANSFEERAProvedor de pagamento Transfeera
CYBERSOURCE_3DSProvedor 3DS da Cybersource
NETCETERA_3DSProvedor Netcetera 3DS
XENDIT_3DSProvedor Xendit 3DS
DLOCALProvedor de pagamento DLocal
CIELOProvedor de pagamentos da Cielo
INSWITCHProvedor de pagamento Inswitch
PAGALEVEProvedor de pagamento Pagaleve
UNLIMINT_3DSProvedor Unlimint 3DS
Tipo de açãoDescrição
PAYMENT_CODEMostrar o código de pagamento ao usuário
IMAGEMostrar imagem (por exemplo, código QR)
REDIRECT_URLRedirecionar o usuário para uma página externa
FORMRenderize um formulário para coletar informações do usuário
INFOExibir tela informativa
OTPExigir a entrada de OTP do usuário
SDK_PROVIDERUse o SDK para processar o pagamento
THREE_D_SECURE_REDIRECT_URLIniciar a autenticação 3DS
REQUEST_HTMLEnviar uma solicitação de formulário HTML
RENDER_HTMLRenderizar HTML estático no aplicativo
RENDER_IFRAMERenderizar 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

Quando 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 pagamento

A 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ção

Alé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.