Seamless SDK (pagamento via Web)

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

👍

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.

📘

Devo usar o Seamless SDK Lite ou o Seamless SDK completo?

Use o Seamless SDK Full Seamless SDK para a listagem automática de métodos de pagamento e a exibição separada de botões de pagamento (como o PayPal). O Seamless SDK Lite Seamless SDK oferece mais controle sobre como os métodos de pagamento são exibidos e organizados.

Etapa 1: Inclua a biblioteca em 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 Seamless.

📘

Biblioteca TypeScript

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

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

Initialize o Yuno SDK em seu aplicativo JavaScript fornecendo um 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: Crie uma sessão de checkout

📘

Se o seu fluxo de trabalho exigir o envio do additional_data objeto, ele pode ser enviado como parte da sessão de checkout.

Para initialize o fluxo de pagamento, crie um novo checkout_session usando o Criar sessão de checkout endpoint.

• Primeiro, crie um cliente ou recupere um ID de cliente existente
• Inclua-o ao criar o checkout_session

💳

Para controlar a autorização e a captura com cartões, inclua payment_method.detail.card.capture na sessão de checkout: definir false autorizar apenas, true para capturar imediatamente.

Parâmetros-chave

📘

onPaymentMethodSelect 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 startSeamlessCheckout antes de mountSeamlessCheckout.

📘

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: Inicie o processo de checkout

Use a configuração abaixo para oferecer uma experiência de pagamento perfeita e fácil de usar para seus clientes:

yuno.startSeamlessCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "US",
  language: "en-US",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  onLoading: (args) => console.log(args),
  renderMode: {
    type: "modal",
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
  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
  },
  texts: {},
  async yunoCreatePayment(oneTimeToken, tokenWithInformation) {
    await createPayment({ 
      oneTimeToken, 
      checkoutSession,
      vault_on_success: true 
    });
    yuno.continuePayment({ showPaymentStatus: true });
  },
  yunoPaymentMethodSelected(data) {
    console.log("Payment method selected:", data);
  },
  yunoPaymentResult(data) {
    console.log("Payment result:", data);
    yuno.hideLoader();
  },
  yunoError(error, data) {
    console.error("An error occurred:", error);
    yuno.hideLoader();
  },
});

Ao usar startSeamlessCheckoutespecifique os retornos de chamada para lidar com os pagamentos. Você também pode personalizar a interface de checkout usando a função texts objetos.

Parâmetros

Configure o checkout contínuo com as seguintes opções:

📘

Transações iniciadas pelo cliente e pelo comerciante

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 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 5: montar o SDK

Para apresentar o processo de checkout com base no método de pagamento selecionado, use a opção yuno.mountSeamlessCheckout() função. Essa etapa garante que o SDK seja montado corretamente no elemento HTML escolhido.

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

Consulte a página Tipo de pagamento para ver a lista completa de tipos de métodos de pagamento que você pode usar ao montar o SDK.

O vaultedToken é opcional. Ele representa um método de pagamento registrado anteriormente. Se você fornecer o vaultedTokenSe o usuário não precisar fornecer as informações de pagamento novamente, já que elas foram fornecidas em uma transação anterior.

Após a montagem, você deve iniciar o fluxo de checkout chamando yuno.startPayment(). Se você pular essa chamada, o formulário de pagamento não será aberto.

Etapa 6: iniciar o fluxo de pagamento (obrigatório)

Chamada yuno.startPayment() imediatamente após yuno.mountSeamlessCheckout() para abrir a interface do usuário do método de pagamento selecionado:

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

yuno.startPayment();

Como alternativa, é possível acionar o início a partir de uma ação do usuário, como um clique em um botão:

const payButton = document.querySelector('#button-pay');
payButton.addEventListener('click', () => {
  yuno.startPayment();
});

📘

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.

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();

Registrando métodos de pagamento em um fluxo contínuo

Você pode cadastrar métodos de pagamento (armazenar cartões para uso futuro) diretamente durante o fluxo de pagamento contínuo, definindo payment_method.vault_on_success = true no Criação de sessão de checkout.

Quando vault_on_success é definido como true:

• O método de pagamento será automaticamente registrado se o status do pagamento for SUCCEEDED
• Se o pagamento não for bem-sucedido, não ocorrerá nenhum vaulting.
• A resposta de pagamento incluirá um vaulted_token que você pode usar para transações futuras

Exemplo:

{
    "account_id": "...",
    ...
    "payment_method": {
        "vault_on_success": true
    }
}

📘

Requisitos para o salto

Para gerar e receber um vaulted_token quando vault_on_success = trueO pagamento deve fazer referência a um cliente Yuno existente por meio de customer_payer.id na sessão de checkout. Criar ou enviar os dados do cliente em linha dentro da solicitação de pagamento não cria o cliente do nosso lado, portanto, não ocorrerá nenhum armazenamento.

Para obter mais informações sobre como cadastrar métodos de pagamento, consulte Cadastrar métodos de pagamento.

Mantenha-se atualizado

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