Integração de Pagamentos com Storefront API

Documentação Geral: Integração de Pagamentos com Storefront API

Esta documentação descreve o fluxo necessário para implementar a funcionalidade de pagamentos em uma aplicação headless utilizando o Storefront API da Wake.

A principal premissa é que a aplicação cliente será responsável por construir a interface do usuário, mas deverá respeitar:

• Estrutura de dados retornada pela API
• Fluxo de chamadas
• Atributos HTML obrigatórios

Isso garante compatibilidade com os scripts de pagamento dos gateways.

Para exemplos de referência, utilize o repositório:
👉 wake-components

---

Pré-requisitos: Scripts Essenciais

Antes de iniciar o fluxo de pagamento, é fundamental garantir que os seguintes scripts estejam carregados na aplicação:

HTML

<script>
  var Fbits = Fbits || {};
  Fbits.Debug = { IsDebug: false };
</script>

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://static.fbits.net/j/jquery.mask.min.js"></script>

<script src="https://static.fbits.net/scripts/checkout/Fbits.Util.js"></script>
<script src="https://static.fbits.net/scripts/checkout/Fbits.Gateway.Framework.js"></script>

 

Fluxo Geral de Implementação

O processo de pagamento segue três etapas principais:

1. Seleção e Renderização – a aplicação seleciona o método de pagamento, renderiza os formulários e carrega os scripts necessários.
2. Atualização de Valores – caso múltiplos métodos de pagamento sejam utilizados, a aplicação deve recalcular valores e parcelamentos.
3. Finalização da Compra – a aplicação coleta, formata e envia os dados para a API para completar o checkout.

Etapa 1: Seleção do Método de Pagamento e Renderização

1.1 Consultar Possibilidades de Combinação

Quando o usuário optar por combinar meios de pagamento (ex.: Pix + Cartão, ou Carteira de Créditos + Cartão), utilize a query abaixo para exibir as combinações possíveis:

GraphQL

query MultiplePaymentMethodsSelector($checkoutId: Uuid!, $selected: [String]) {
  multiplePaymentMethodsSelector(
    checkoutId: $checkoutId
    selected: $selected
  ) {
    selections {
      displayName
      optionId
      selected
      canBeSelected
      balance
    }
    selectedPaymentMethod {
      id
      name
      type
    }
  }
}

• O campo selections informa quais métodos podem ser combinados (canBeSelected = true).
• O campo selected indica quais opções foram enviadas no array selected.
• Quando uma combinação válida é encontrada, o campo selectedPaymentMethod retorna o id do pagamento a ser selecionado pela mutation de seleção.

1.2 Executar a Mutation de seleção

Quando o usuário seleciona um método de pagamento (ex.: cartão de crédito, Pix, múltiplos cartões, ou combinação de pagamentos), utilize a mutation:

GraphQL

mutation CheckoutSelectPaymentMethod($checkoutId: Uuid!, $paymentMethodId: ID!, $customerAccessToken: String!) {
  result: checkoutSelectPaymentMethod(
    checkoutId: $checkoutId
    paymentMethodId: $paymentMethodId
    customerAccessToken: $customerAccessToken
  ) {
    selectedPaymentMethods {
      id
      paymentMethodId
      html
      scripts
      value
      minInstallmentValue
      installments { number total value adjustment }
      selectedInstallment { number }
      saveCard
      suggestedCards { key name number brand }
    }
    total
  }
}

1.2 Renderizar a Interface

Para cada método de pagamento retornado:

• Crie um container principal com data-payment-transaction-id="{{payment.id}}".
• Adicione campos do formulário (“fake form”) para dados do cartão (número, nome, validade, CVV).
• Preencha o campo de valor (payment.value) e renderize as opções de parcelamento (payment.installments).
• Injete o HTML retornado no campo html (contém inputs e tokens do gateway).
• Carregue dinamicamente os scripts listados em payment.scripts.
• Após o carregamento, execute Fbits.Gateway.ExecuteLoadedCallbacks().
• Inicialize bibliotecas de UI, como InitializeJpCardLibrary(isMultiPayment) para aplicar máscara e validar inputs de cartão.

Etapa 2: Atualização de Valores (Múltiplos Métodos)

Quando múltiplos métodos de pagamento forem usados (ex.: dois cartões de crédito), os valores devem ser recalculados pela API.

2.1 Mutation de Atualização

GraphQL

mutation CheckoutChangeMultiPaymentValues($checkoutId: Uuid!, $payments: [MultiPaymentValueInput!]!) {
  checkout: checkoutChangeMultiPaymentValues(
    checkoutId: $checkoutId
    payments: $payments
  ) {
    selectedPaymentMethods {
      id
      value
      installments { number total value adjustment }
      selectedInstallment { number }
    }
  }
}

2.2 Considerações

• Capture a alteração de valor no campo do pagamento (ex.: input do primeiro cartão).
• Envie apenas os inputs habilitados para a API (ex.: se houver 2 pagamentos, somente 1 input deve estar habilitado).
• Atualize os valores e parcelamentos exibidos conforme a resposta da mutation.

Exemplo prático: em um fluxo com 2 cartões, ao alterar o valor do primeiro, o segundo é automaticamente ajustado pela API.

Etapa 3: Finalização da Compra

3.1 Executar Callbacks do Gateway

Antes de enviar os dados, execute os callbacks de validação e pagamento:

JavaScript

const validateResult = await Fbits.Gateway.ExecuteValidateCallbacks();
if (!validateResult.every(item => item === true)) {
  // Mostra erro de validação
  return;
}

await Fbits.Gateway.ExecutePayCallbacks();

3.2 Coletar e Formatar os Dados

• Crie um array com todos os pagamentos exibidos.
• Cada item deve conter:
  • paymentId: do atributo data-payment-transaction-id.
  • paymentData: query string com inputs do formulário + tokens gerados pelo gateway.

Exemplo de estrutura:

JSON

[
  {
    "paymentId": "d39a3b...",
    "paymentData": "name=...&cardToken=tk_123..."
  },
  {
    "paymentId": "e45b1c...",
    "paymentData": "name=...&cardToken=tk_456..."
  }
]

• Converta o array em JSON (JSON.stringify).
• Codifique em Base64 (btoa).

3.3 Enviar para a API

Mutation de finalização:

GraphQL

mutation checkoutComplete($checkoutId: Uuid!, $paymentData: String!) {
  data: checkoutComplete(checkoutId: $checkoutId, paymentData: $paymentData) {
    completed
    orders {
      orderId
      totalValue
    }
  }
}

Se bem-sucedido, redirecione o usuário para a página de confirmação do pedido.

Considerações Finais

• Este fluxo é genérico e funciona para qualquer cliente que deseje integrar pagamentos via Wake de forma headless.
• Para múltiplos métodos de pagamento, adapte conforme a necessidade (exemplo: 2 cartões, cartão + Pix, etc.).
• Sempre utilize o repositório wake-components como referência prática para a implementação.