Secure Fields (pagamento)

Siga este guia passo a passo para implementar e ativar as funcionalidades de checkout Secure Fields da Yuno em seu aplicativo.

Etapa 1: Inclua a biblioteca em seu projeto

Antes de prosseguir com a implementação do Secure Fields, 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 campos seguros.

📘

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 campos seguros 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

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

Os parâmetros essenciais são countrycode, que determina o país para o qual o processo de pagamento está configurado, e checkoutSessionque se refere à sessão de checkout do pagamento atual.

Parâmetros

Configure os campos seguros com as seguintes opções:

const secureFields = yuno.secureFields({
  countrycode: country,
  checkoutSession,
  installmentEnable: false
});

📘

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 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: Monte os campos seguros

Depois de definir os parâmetros, você definirá, configurará e montará os campos seguros. Para cada Secure Field, você precisa definir o parâmetro name e options ao criá-lo com o secureFields.create função.

A tabela a seguir mostra todas as configurações disponíveis:

Depois de definir o parâmetro, você renderizará o Secure Field criado com o parâmetro render selecionando um elemento HTML usando um seletor CSS válido (#, ., [data-*]).

O bloco de código a seguir mostra um exemplo da configuração de parâmetros para três campos seguros e, à medida que são montados, os campos são apresentados ao usuário:

Parâmetros do campo seguro

Dados disponíveis na chamada de retorno onChange

Quando o onChange é acionado, o data O parâmetro contém:

• Informações do IIN do cartão: Detalhes do emissor do cartão, incluindo esquema, marca, tipo e informações do emissor
• Planos de parcelamento: Opções de parcelamento disponíveis para a conta, se configuradas
• Carregando estados: isCardIINLoading e isInstallmentLoading sinalizadores booleanos

const secureNumber = secureFields.create({
    name: 'pan',
    options: {
      placeholder: '0000 0000 0000 0000',
      styles: ``,
      label: 'Card Number',
      showError: true,
      errorMessage: "Custom Error",
      validateOnBlur: false,
      onChange: ({ error,data }) => {
        if (error) {
          console.log('error_pan')
        } else {
          console.log('not_error_pan')
        }
      },
      onBlur() {
        console.log('blur_pan')
      },
      onFocus: () => {
        console.log('focus_pan')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureNumber.render('#pan')

  const secureExpiration = secureFields.create({
    name: 'expiration',
    options: {
      placeholder: 'MM / YY',
      styles: ``,
      label: 'Card Expiration',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_expiration')
        } else {
          console.log('not_error_expiration')
        }
      },
      onBlur() {
        console.log('blur_expiration')
      },
      onFocus: () => {
        console.log('focus_expiration')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureExpiration.render('#expiration')


  const secureCvv = secureFields.create({
    name: 'cvv',
    options: {
      placeholder: 'CVV',
      styles: ``,
      label: 'CVV',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_cvv')
        } else {
          console.log('not_error_cvv')
        }
      },
      onBlur() {
        console.log('blur_cvv')
      },
      onFocus: () => {
        console.log('focus_cvv')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureCvv.render('#cvv')

Abaixo, você pode ver um GIF que mostra como você pode configurar os Secure Fields:

Etapa 5: Gerar um OTT ( token de uso único)

Com todas as informações do usuário em mãos, você pode iniciar o pagamento. Primeiro, você precisa criar um One-Time Token usando a função secureFields.generateToken. Como se trata de uma função assíncrona, você pode usar try/catch para garantir que você tratará corretamente os erros acionados. O exemplo a seguir mostra como criar um token de uso único usando vaultedToken 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.

Gerar parâmetros de Token

const oneTimeToken = await secureFields.generateToken({
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

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

Create a one-time token with error handling:
const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

Etapa 6: Criar o pagamento

Depois de receber o token de uso único, você pode criar o pagamento usando uma das seguintes opções:

• Crie o pagamento usando o endpoint Criar pagamento.
• Use o createPayment função.

Ambas as opções exigem que você forneça o oneTimeToken e o checkoutSession. Como a criação do pagamento pode gerar erros, a Yuno recomenda que você use uma função try/catch aqui.

Depois disso, você pode verificar o status do pagamento usando o yuno.mountStatusPayment função. O exemplo a seguir usa a função createPayment para criar o pagamento e a função mountStatusPayment para exibir o status do pagamento:

Fluxo de criação de pagamentos

1. Criar Payment: Use o createPayment com o token de uso único e a sessão de checkout
2. Verificar ação do SDK: Se sdk_action_required for verdadeiro, chame yuno.continuePayment() para ações adicionais do cliente
3. Status da montagem: Se nenhuma ação do SDK for necessária, use yuno.mountStatusPayment() para exibir o status do pagamento

Status de montagem Parâmetros de pagamento

const payment = await createPayment({ oneTimeToken, checkoutSession })

if (payment.checkout.sdk_action_required) {
      yuno.continuePayment()
} else {
  yuno.mountStatusPayment({
    checkoutSession: checkoutSession,
    countrycode: 'US',
    language: 'en',
    yunoPaymentResult(data) {
      console.log('yunoPaymentResult', data)
    },
  })
}

📘

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 Secure Fields oferece serviços e configurações adicionais que você pode usar para melhorar a experiência dos clientes:

• Configurar e usar o TypeScript
• Persistir as informações do cartão de crédito para tentar novamente os pagamentos
• Limpar os valores inseridos nos campos do cartão
• Foco na entrada
• Forçar validação
• Definir mensagem de erro personalizada
• Definir tipo de cartão

Configurar e usar o TypeScript

Para usar o TypeScript com o Yuno Secure Fields SDK, comece instalando as definições de tipo via npm:

npm install @yuno-payments/sdk-web-types

Após concluir a instalação, inclua as definições de tipo em sua configuração do TypeScript. Atualize o tsconfig.json para incluir o arquivo @yuno-payments/sdk-web-types na matriz de tipos, como no exemplo a seguir:

{
  "compilerOptions": {
    "types": ["@yuno-payments/sdk-web-types"]
  }
}

Com as definições de tipo instaladas e configuradas, agora você pode usá-las em seu código. O bloco de código a seguir mostra um exemplo de como initialize o Yuno e criar uma instância:

import { YunoInstance } from '@yuno-payments/sdk-web-types/dist/types';

const yunoInstance: YunoInstance = await Yuno.initialize('yourPublicApiKey');

Lembre-se de substituir o yourPublicApiKey com sua chave de API pública real.

Persistir as informações do cartão de crédito para tentar novamente os pagamentos

Se uma transação for rejeitada, você poderá manter os dados do cartão de crédito para tentar novamente um pagamento depois que o cliente inserir os detalhes do cartão de crédito. Para fazer isso, você precisa seguir as etapas abaixo:

1. Adicione o parâmetro apresentado no bloco de código a seguir ao criar o token de uso único na Etapa 5. Ele permitirá que você receba qualquer informação adicional fornecida pelo cliente durante o checkout, como parcelas, tipo de documento ou número do documento.

const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
})

2. Caso a transação seja rejeitada, você precisará: i. Criar uma nova sessão de checkout. ii. Gerar um novo token de uso único. Na geração token de uso único, envie a nova sessão de checkout no arquivo checkoutSession parâmetro.
3. Continue com o novo checkout e o token único com o fluxo de pagamento regular.

Limpar os valores inseridos nos campos do cartão

Em relação à funcionalidade anterior, o comerciante pode configurar para limpar as informações inseridas em qualquer campo do cartão. Para isso, é necessário executar o método secureFieldInstance.clearValue()para cada campo que você deseja limpar ou excluir. O exemplo a seguir mostra como:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.clearValue()

Foco na entrada

O comerciante pode definir o foco em uma entrada específica. Para isso, é necessário executar o método secureFieldInstance.focus()para cada campo em que você deseja se concentrar. O bloco de código a seguir mostra um exemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.focus()

Forçar validação

O comerciante pode forçar a validação de uma determinada entrada. Para isso, é necessário executar o método secureFieldInstance.validate()para cada campo que você deseja validar. O bloco de código a seguir mostra um exemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.validate()

Definir mensagem de erro personalizada

O comerciante pode definir uma mensagem de erro personalizada após uma validação de entrada. Para isso, é necessário executar o método secureFieldInstance.setError()para cada campo para o qual você deseja definir uma mensagem de erro personalizada. O bloco de código a seguir mostra um exemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstancesetError('Erro personalizado')

Definir tipo de cartão

O comerciante pode definir o tipo de cartão que o cliente usa para o pagamento. Para isso, você precisa executar o método secureFieldInstance.setCardType() e enviar "DEBIT" (débito) ou "CREDIT" (crédito) para cada cenário. Isso é útil para cartões duplos, em que o mesmo cartão pode ser usado como crédito ou débito, como no Brasil. O bloco de código a seguir mostra um exemplo:

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.setCardType('CREDIT')

O que vem a seguir?

Você pode acessar outras funções disponíveis no Yuno Web SDK:

• Personalizações do SDK: Altere a aparência do SDK para que corresponda à sua marca.
• Status do pagamento: Atualiza o usuário sobre o processo de pagamento.

Mantenha-se atualizado

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