Lite SDK (pagamento via Web)

Siga este guia passo a passo para implementar e ativar a funcionalidade do Lite Web SDK da Yuno em seu aplicativo.

Etapa 1: Inclua a biblioteca em seu projeto

Certifique-se de que o arquivo Yuno SDK esteja incluído em sua página da Web antes de fechar o arquivo </body> tag. Consulte o exemplo abaixo:

<script src="https://sdk-web.y.uno/v1.5/main.js"></script>

📘

Suporte a 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 o SDK com a chave pública

Em seu aplicativo JavaScript, crie uma instância do Yuno fornecendo uma classe PUBLIC_API_KEY. Verifique o Obtenha suas credenciais de API guia.

Como no exemplo abaixo, use a classe inicializada que é atribuída à classe yunoconstante.

const yuno = await YunoinitializePUBLIC_API_KEY);

Etapa 3: Inicie o processo de checkout

Você iniciará o processo de checkout. Para fazer isso, use o botão yuno.startCheckout e fornecer os parâmetros necessários.

A tabela a seguir lista todos os parâmetros obrigatórios e suas descrições. Para parâmetros opcionais, vá para Recursos complementares.

yuno.startCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "FR",
  language: "fr-FR",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  card: {
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
  onLoading: (args) => {
    console.log(args);
  },
  async yunoCreatePayment(oneTimeToken) {
    /**
     * The createPayment function calls the backend to create a payment in Yuno.
     * It uses the following endpoint https://docs.y.uno/reference/create-payment
     */
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘

Tipos de transação

Os pagamentos podem ser iniciados pelo cliente (CIT) ou pelo comerciante (MIT). Você encontrará mais informações sobre suas características em Credenciais armazenadas.

O passo a passo apresentado nesta página refere-se a uma transação iniciada pelo cliente sem a opção de recorrência. Normalmente, ela é usada em compras on-line únicas, compras em lojas, saques em caixas eletrônicos etc.

Etapa 4: montar o SDK

Em seguida, você deve montar o SDK, apresentando o checkout com base no método de pagamento selecionado pelo cliente. Lembre-se de que, ao usar o Lite SDK, você é responsável por exibir os métodos de pagamento e capturar a seleção do cliente. Acesse Lite SDK (Payment) para obter informações adicionais.

Use o yuno.mountCheckoutLite() selecionando um elemento HTML e usando um seletor CSS válido (#, ., [data-*]) para exibir o checkout para o método payment selecionado.

yuno.mountCheckoutLite({
  /**
   * can be one of 'PAYPAL' | 'PIX' | CARD
   */
  paymentMethodType: PAYMENT_METHOD_TYPE,
  /**
   * Vaulted token related to payment method type.
   * Only if you already have it
   * @optional
   */
  vaultedToken: VAULTED_TOKEN,
});

Depois de montar o SDK, o fluxo do método de payment selecionado será iniciado automaticamente.

Para o PayPal, a folha de pagamento do PayPal agora abre imediatamente após o comprador selecionar o PayPal, sem necessidade de clique de confirmação adicional.

📘

Google Pay e Apple Pay no Lite SDK

O Google Pay e o Apple Pay não estão disponíveis como opções de pagamento integradas no Lite SDK. Para usar esses métodos de pagamento, você deve usar o mountExternalButtons método. Veja Montagem de botões externos para obter mais informações.

Etapa 5: montar botões externos (opcional)

Se você quiser usar o Google Pay ou o Apple Pay no Lite SDK, poderá montar esses botões de pagamento externamente usando o mountExternalButtons method. Esse método permite que você escolha onde cada botão é exibido na interface do usuário.

// Mount external buttons
await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
]);

O mountExternalButtons aceita uma matriz de objetos, cada um contendo:

• paymentMethodType: Ou 'APPLE_PAY' ou 'GOOGLE_PAY'
• elementSelector: O seletor CSS para o elemento HTML em que o botão deve ser renderizado

Desmontagem de botões externos

Você pode desmontar um único botão externo:

yuno.unmountExternalButton('APPLE_PAY');

Ou desmonte todos os botões externos de uma só vez:

yuno.unmountAllExternalButtons();

Etapa 6: Iniciar o processo de pagamento

Depois que o usuário tiver selecionado um método payment , lembre-se de chamar yuno.startPayment() para iniciar o fluxo de payment . Abaixo, você encontrará um exemplo em que yuno.startPayment() é chamado quando o usuário clica em button-pay:

const PayButton = document.querySelector("#button-pay");

PayButton.addEventListener("click", () => {
  yuno.startPayment();
});

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

Depois que o cliente preenche os dados solicitados nos formulários de pagamento da Yuno, o SDK fornece o token de uso único. A função de configuração yunoCreatePayment(oneTimeToken) é acionado com o token de uso único.

yunoCreatePaymentoneTimeToken);

Você também pode usar tokenWithInformation para receber qualquer informação adicional que o cliente forneça no checkout, como parcelas ou tipo/número de documento.

yunoCreatePaymentoneTimeToken, tokenWithInformation);

📘

Gerenciamento de carregadores

O comerciante é responsável por gerenciar o carregador. A Yuno fornece uma opção de carregador padrão, mas os comerciantes podem implementar seu próprio carregador, se preferirem. Nesse caso, eles são responsáveis por fazer as configurações necessárias.

Etapa 8: Criar o pagamento

Depois de concluir as etapas descritas anteriormente, você poderá criar um pagamento. A criação do pagamento back-to-back deve ser realizada usando o endpoint Create Payment. O comerciante deve chamar seu backend para criar o pagamento dentro do Yuno, usando o token de uso único e a sessão de checkout.

📘

Continuar com o método Payment

A Yuno recomenda a integração do continuePayment do SDK depois que o payment é criado. Isso ocorre porque determinados métodos payment assíncronos exigem uma ação adicional do cliente para concluir o payment. 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á telas adicionais para os clientes, nas quais eles poderão executar as ações necessárias para concluir o payment. Se sdk_action_required for falso, essa etapa não é necessária.

Recursos complementares

O Yuno Web SDK fornece serviços e configurações adicionais que você pode usar para melhorar a experiência dos clientes:

• Montagem de botões externos
• Carregador de formulários
• Lista de emissores bancários
• Modo de renderização
• Configurações de formato de cartão
  • Salvar cartão para pagamentos futuros
  • Modo de renderização
  • Botões de formulário de payment de texto
  • Formulário de cartão de crédito persistente para tentar novamente os pagamentos
  • Ocultar o botão Pagar

Montagem de botões externos

Use o mountExternalButtons para renderizar os botões do Google Pay e do Apple Pay em sua interface de usuário personalizada. Esse método é necessário se você quiser usar esses métodos de pagamento no Lite SDK, pois eles não estão disponíveis como opções de pagamento incorporadas.

await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
]);

Parâmetros

Botões de desmontagem

Você pode desmontar um único botão externo por tipo de método de pagamento:

yuno.unmountExternalButton('APPLE_PAY');

Ou desmonte todos os botões externos de uma só vez:

yuno.unmountAllExternalButtons();

Carregador

Controle o uso da carregadeira.

yuno.startCheckout({
  showLoading: true,
});

Forma do emissor

yuno.startCheckout({
  issuersFormEnable: true,
});

Modo de renderização do formulário

📘

Modo de renderização aprimorado no Lite SDK v2.0

O Lite SDK v2.0 aprimorado oferece recursos avançados de modo de renderização que incorporam os formulários de checkout da Yuno diretamente em sua interface. Isso lhe dá controle total sobre a jornada de checkout, incluindo carregamento, status e telas de entrada de pagamento, com personalização visual completa e integração perfeita de UX.

yuno.startCheckout({
  renderMode:

Configurações de formato de cartão

yuno.startCheckout({
  card: {
    type: "extends",
    styles: "",
    cardSaveEnable: false,
    texts: {},
    cardNumberPlaceholder: "Enter card number", // Optional: Custom placeholder text
    hideCardholderName: false, // Optional: Set to true to hide cardholder name field
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
});

Salvar o cartão para pagamentos futuros

Além disso, você pode exibir uma caixa de seleção para salvar ou registrar cartões usando a opção cardSaveEnable: true. Abaixo estão exemplos da caixa de seleção para ambas as renderizações do formulário de cartão.

Modos de renderização

Abaixo você encontra capturas de tela que apresentam a diferença entre as seguintes opções:

• Modos de renderização modal e elements para a lista de métodos payment
• Modos de renderização step e extends para o formulário de cartão de crédito

Você também pode escolher uma das opções de renderização para o formulário do cartão, step e extends:

Botões de formulário de payment de texto

yuno.startCheckout({
  texts: {
    customerForm?: {
      submitButton?: string;
    }
    paymentOtp?: {
      sendOtpButton?: string;
    }
  }
})

Formulário de cartão de crédito persistente para tentar novamente os pagamentos

Se uma transação for rejeitada, você poderá usar o formulário de cartão de crédito para tentar novamente um payment depois que o cliente tiver inserido os detalhes do cartão de crédito. Para fazer isso, você precisará:

1. Adicione o seguinte parâmetro ao inicializar o SDK para manter o formulário de cartão de crédito depois que o token de uso único for criado:
   JavaScript

   yuno.startCheckout({
     automaticallyUnmount: false,
   });

2. Caso a transação seja rejeitada, você precisará:
   1. Executar o método yuno.notifyError() para excluir o CVV inserido anteriormente para a primeira transação.
   2. Crie uma nova sessão de checkout e atualize o SDK com a nova sessão executando yuno.updateCheckoutSession(checkoutsession)
3. Continue com o novo checkout e o token de uso único com o fluxo de pagamento regular.

Ocultar o botão Pagar

Você pode ocultar o Pagamento ao apresentar os formulários de dados do cartão ou do cliente. Para controlar esse recurso, você definirá showPayButton para false ao iniciar o checkout com o comando startCheckout função. O bloco de código abaixo apresenta um exemplo de como ocultar o botão payment :

yuno.startCheckout({
  /**
   * Hide (false) or show (true) the customer or card form pay button
   * @default true
   * @optional
   */
  showPayButton: false,
});

As imagens a seguir apresentam exemplos do Formulário de dados do cliente com e sem o botão Pagar:

As imagens a seguir apresentam exemplos do Formulário de cartão com e sem o botão Pagar:

Se você ocultar o Pagamento você precisará iniciar a criação do token de uso único por meio do seu código. Para criar o token de uso único e continuar o pagamento em seu backend, chame a função submitOneTimeTokenForm função. O bloco de código abaixo apresenta como usar a função submitOneTimeTokenForm função.

/**
 * Essa função aciona a mesma funcionalidade que é chamada quando o cliente clica no botão do formulário de pagamento. Essa abordagem não funcionará se você tiver escolhido a etapa para o modo de renderização.
 */
yuno.submitOneTimeTokenForm();

Mantenha-se atualizado

Acesse o changelog para obter as atualizações mais recentes do SDK e o histórico de versões.