Implementação Full SDK (Web)

Esta página fornece um guia passo a passo para implementar e ativar a funcionalidade do Full Web SDK da Yuno em seu aplicativo.

📘

Referência do registro de alterações:

Este guia abrange a versão atual do SDK. Para obter detalhes sobre versões anteriores, consulte o registro de alterações.

Etapa 1: Inclua a biblioteca em seu projeto

Adicione a seguinte tag de script ao seu arquivo HTML para incluir o Yuno Web SDK:

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

Como alternativa, você pode instalá-lo via npm:

npm install @yuno-payments/sdk-web

Após concluir a integração do SDK, prossiga com as etapas a seguir para implementar a funcionalidade completa de checkout.

📘

Biblioteca TypeScript

Se você estiver usando TypeScript, a Yuno fornece uma biblioteca para ver todos os métodos disponíveis no Yuno Web SDK.

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

Crie uma instância do Yuno fornecendo uma classe PUBLIC_API_KEY. Veja o credenciais para obter mais informações.

Initialize o SDK com sua chave de API pública:

const yuno = await YunoinitializePUBLIC_API_KEY);

Etapa 3: Inicie o processo de checkout

Use o yuno.startCheckout para iniciar o processo de checkout com os parâmetros necessários.

Veja o Tabela de parâmetros abaixo para todas as opções que você pode usar com startCheckout.

Para obter mais personalização ou configurações avançadas/opcionais, consulte a seção Recursos complementares.

Parâmetros

A tabela a seguir lista todos os parâmetros disponíveis para o startCheckout com descrições:

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);
  },
  yunoPaymentMethodSelected: () => {
    console.log("Payment method selected");
  },
  yunoPaymentResult: (status) => {
    console.log("Payment result:", status);
  },
  yunoError: (message, data) => {
    console.error("Payment error:", message, data);
  },
  async yunoCreatePayment(oneTimeToken) {
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘

Modo de renderização

Por padrão, o Yuno SDK é renderizado como um modal. No entanto, você pode especificar o elemento em que o SDK será renderizado. Para obter informações adicionais, acesse Modo de renderização na página de recursos complementares.

📘

onPaymentMethodSelected Evento

Para todos os APMs, incluindo Google Pay, Apple Pay e PayPal, onPaymentMethodSelected é acionado assim que o cliente escolhe a forma de payment (antes do início do fluxo de payment ). Definir onPaymentMethodSelected em startCheckout antes de mountCheckout.

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

📘

Exibição do Google Pay e do Apple Pay

A partir da versão 1.5 do SDK, o Google Pay e o Apple Pay aparecem como botões diretos em vez de botões de rádio na lista de métodos de pagamento. Eles são exibidos separadamente de outros métodos de pagamento.

Etapa 4: montar o SDK

Exibir os métodos de pagamento:

yunomountCheckout();

Monte com um método de pagamento padrão selecionado:

yuno.mountCheckout({
  paymentMethodType: PAYMENT_METHOD_TYPE,
  vaultedToken: VAULTED_TOKEN,
});

Etapa 5: Iniciar o processo de payment

Chamada yuno.startPayment() para iniciar o fluxo de pagamento depois que o usuário seleciona um método de pagamento:

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

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

Etapa 6: 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 yuno.CreatePayment(oneTimeToken) é acionado com o token de uso único.

yunoCreatePaymentoneTimeToken);

Você também pode usar tokenWithInformation para receber informações adicionais fornecidas pelo cliente no checkout, como parcelas ou tipo/número do 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 7: Criar o pagamento

Depois de concluir as etapas anteriores, prossiga para criar um pagamento. A criação de um pagamento back-to-back deve ser realizada usando o endpoint Criar pagamento. O backend do comerciante deve chamar esse endpoint para criar o pagamento no Yuno usando o token de uso único e a sessão de checkout.

📘

Concluir a integração

Após a Etapa 7, você implementou com êxito o fluxo de pagamento básico. Para testar sua integração, crie um pagamento de teste usando a sessão de checkout e o token de uso único. Para obter recursos adicionais e configurações avançadas, consulte a seção Recursos complementares abaixo.

❗️

Método ContinuePayment

Depois de criar um payment, a Yuno requer para integrar o continuePayment do SDK. Isso é necessário porque alguns métodos payment assíncronos exigem ações adicionais do cliente para concluir o processo. A resposta da API indicará esse cenário definindo o parâmetro sdk_action_required para verdadeiro. Quando isso ocorrer, você deverá chamar yuno.continuePayment()que apresentará automaticamente as telas necessárias ao cliente, permitindo que ele conclua o fluxo de payment sem que você precise lidar com cada caso manualmente.

continuePayment valor de retorno ou nulo

Para métodos payment que exigem uma ação do lado do comerciante (por exemplo, quando o provedor de payment exige um URL de redirecionamento em uma visualização da Web), o await yuno.continuePayment() retorna um objeto com a seguinte estrutura ou nulo:

{
  action: 'REDIRECT_URL'
  type: string
  redirect: {
    init_url: string
    success_url: string
    error_url: string
  }
} | null

Quando o método retorna um objeto, você pode tratar os fluxos de pagamento do seu aplicativo que exigem tratamento de redirecionamento personalizado. Quando ele retorna null, nenhuma ação adicional do lado do comerciante é necessária.

📘

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. O aplicativo de demonstração inclui exemplos funcionais de todos os SDKs do Yuno e pode ser clonado do repositório do GitHub.

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
• Modo de renderização
• Configurações de formato de cartão
  • Salvar cartão para pagamentos futuros
  • Modos 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

Você pode usar o mountExternalButtons para renderizar os botões do Google Pay e do Apple Pay em locais personalizados em sua interface do usuário. Isso lhe dá controle sobre onde esses botões são exibidos.

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 de formulários

Controle o uso da carregadeira:

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

Formulário do emissor

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

Modo de renderização

yuno.startCheckout({
  renderMode: {
    type: "modal",
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
});

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

Você 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:

Modos de renderização

As capturas de tela a seguir mostram a diferença entre:

• 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 pagamento depois que o cliente tiver inserido os detalhes do cartão de crédito. Para fazer isso:

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. Se a transação for rejeitada:
   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 botão de pagamento

Você pode ocultar o botão Pagar ao apresentar o formulário de dados do cartão ou do cliente. Definir showPayButton para false ao iniciar o checkout com o comando startCheckout função:

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

As imagens a seguir mostram exemplos do Customer Data Form com e sem o botão Pay (Pagar):

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

Se você ocultar o botão Pagar, 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:

yuno.submitOneTimeTokenForm();

Inicialização opcional options parâmetro

Esse recurso opcional destina-se a casos de uso avançado em que você precisa personalizar a forma como a identificação do dispositivo é tratada por meio de cookies.

A partir do Yuno SDK v1.2, o Yuno.initialize suporta um novo parâmetro opcional chamado options. Isso permite a configuração avançada, como a personalização do nome do cookie usado para a identificação do dispositivo.

Opções de inicialização

A assinatura da função atualizada é:

const yuno = await Yunoinitialize(publicApiKey, applicationSession, options);

• publicApiKey (string): Sua chave de API pública.
• applicationSession (string | undefined): ID de sessão opcional.

  Recomendação: Deixe isso como undefined para que o SDK possa gerar e gerenciar sua própria sessão internamente. Defina isso somente se você precisar de uma estratégia de gerenciamento de sessão personalizada.

• options (object | undefined): Objeto opcional para configuração avançada.

Estrutura de opções

O options suporta a seguinte estrutura:

const options = {
  cookies: {
    deviceId: {
      name: "customCookieName",
    },
  },
};

Se deviceId.name não for especificado, o padrão do SDK é "yuno" como o nome do cookie.

Exemplo de implementação

const publicApiKey = "your-public-api-key";
const options = {
  cookies: {
    deviceId: {
      name: "custom-device-id",
    },
  },
};

const yuno = await Yuno.initialize(publicApiKey, undefined, options);

O que vem a seguir?

Saiba mais sobre as configurações adicionais do Full SDK acessando Recursos complementares. Você também pode acessar outras funções disponíveis no Yuno Web SDK:

• Personalizações do SDK: Altere a aparência do SDK para combinar com sua marca
• StatusPayment : Atualizar o usuário sobre o processo de payment
• SDK de configuração do 3DS: Integre o 3DS em seu fluxo de payment

Mantenha-se atualizado

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