Troca na forma de pagamento do pedido

Suggest Edits

A funcionalidade de Troca na Forma de Pagamento permite que usuários modifiquem a forma de pagamento de seus pedidos que estão com status "Aguardando Pagamento".

📘
Importante!
No caso de pedidos com diferentes centros de distribuição, onde o pedido original é separado em vários pedidos "filhos", a transação com o gateway de pagamento é única e compartilhada entre os pedidos de split. Por este motivo, a troca na forma de pagamento sempre será replicada para todos os pedidos relacionados.
Exemplo:

Pedido Original - XYZ

Pedido X - Centro de Distribuição 1 - Boleto

Pedido Y - Centro de Distribuição 2 - Boleto

Pedido Z - Centro de Distribuição 3 - Boleto

Quando o consumidor alterar a forma de pagamento do Pedido X para a opção de cartão de crédito, os pedidos Y e Z serão alterados para cartão de crédito automaticamente, sempre mantendo a forma de pagamento atual.

👍
Modelos de JS e CSS prontos!
Para simplificar o processo e auxiliar no desenvolvimento, disponibilizamos scripts e folhas de estilo CSS que podem ser facilmente adaptados às suas necessidades. Esses recursos são projetados para facilitar a implementação e garantir uma integração a plataforma.

Script JS: Clique aqui

CSS: Clique aqui

Se preferir criar seus próprios arquivos, basta seguir o passo a passo abaixo.

Instruções Iniciais - Vincular Scripts e CSS

Acesse o painel administrativo de sua loja.
Vincule um script e um arquivo de estilo CSS através do Gestor de Scripts no link: https://SUALOJA.fbits-admin.net/GestorScript
Preencha o campo "Identificador de Página" com o valor MinhaConta/Pedido. Isso garantirá que os scripts sejam exibidos somente nessas páginas específicas.
veja o procedimento na imagem a seguir:

Minha conta > Meus Pedidos

Na loja, dentro de Minha Conta > Meus Pedidos, na listagem dos pedidos, utilize JavaScript para adicionar um link a todos os pedidos que apresentam o status "Aguardando pagamento". Veja o exemplo abaixo para referência:
Para sinalizar a intenção de alterar a forma de pagamento, sugerimos que você configure o link para direcionar o usuário à página de detalhes do pedido, incluindo o ID do pedido e adicionando um parâmetro específico.
Exemplo: /minhaconta/Pedido/Details/${ORDER_ID}?changePayment=true.

📘
Nota:
Esta é apenas uma abordagem sugerida, utilizando a passagem de parâmetros via query string. Entretanto, você, como desenvolvedor, tem a liberdade de escolher a metodologia que melhor atende às suas necessidades, seja ela através de cookies, local storage ou qualquer outro meio que considere apropriado.

📘
Importante
Alguns conectores, como no caso do Paypal Plus, os campos serializados vem de inputs hiddens.
Esses campos são preenchidos e tokenizados após o carregamentos dos scripts do conector, para evitar o envio de informações incompletas ou vazias durante o processo de pagamento.
Por isso é necessário carregar o script respectivo do conector que faz essas validações, e esse script é obtido na mesma api que obtém mais detalhes do pagamento.
Lembre-se de tambem carregar os scripts complementares conforme descrito nesse tópico
.

Minha Conta > Meus Pedidos > Detalhe do Pedido

Para o funcionamento adequado do fluxo de troca de pagamento é essencial incluir scripts específicos, que podem ser vinculados através do gestor de scripts ou carregados diretamente via JavaScript. Confira a lista dos scripts necessários:

Validador de padrão de cartão de crédito - https://static.fbits.net/app/ValidacaoCartaoCredito/fbits.cardPattern.js
Framework do gateway de pagamento - https://static.fbits.net/scripts/checkout/Fbits.Gateway.Framework.js
Biblioteca para mascaramento de inputs - https://static.fbits.net/j/jquery.mask.min.js
Utilitários diversos - https://static.fbits.net/scripts/checkout/Fbits.Util.js
Ferramentas de mascaramento - https://static.fbits.net/scripts/checkout/Fbits.Mask.js

Certifique-se de carregar todos esses scripts para garantir a funcionalidade correta da página.

Iniciando a Listagem de Pagamentos dentro do Detalhe do Pedido

Para iniciar a listagem de opções de pagamento, é necessário fazer uma chamada à API correspondente. Esta chamada requer a inclusão do ID do carrinho associado ao pedido em questão na URL da solicitação.

Primeiro, obtenha o ID do carrinho utilizando o seguinte método:

var carrinhoId = Fbits.MinhaConta.Pedido.CarrinhoId;

Com esse ID em mãos, você pode montar a URL para acessar os detalhes de pagamento da seguinte maneira:

https://pub-gateway.fbits.net/${carrinhoId}

Essa ação irá iniciar a listagem das formas de pagamento disponíveis, permitindo que o usuário prossiga com a alteração conforme necessário.

Lembre-se de tratar exceções e erros que possam ocorrer durante a chamada à API para garantir uma experiência suave ao usuário.

Após realizar a chamada anterior, a API retornará um array de objetos contendo as informações das formas de pagamento disponíveis. Cada objeto terá a seguinte estrutura:

[
    {
        "Id": 7377,
        "Nome": "Pagar.me 2.0 - Cartão de Crédito",
        "Imagem": "https://conector.ecommercegateway.com.br/Recursos/Imagens/a48fc953-d363-43a5-987f-232e07f072c2.png"
    },
    ...
]

Cada objeto representa uma forma de pagamento disponível para o usuário:

Id: É o identificador único da forma de pagamento.
Nome: O nome descritivo da forma de pagamento.
Imagem: URL da imagem associada a essa forma de pagamento.

Seleção e Confirmação do Meio de Pagamento

Quando o usuário selecionar uma forma de pagamento, você deve realizar uma nova chamada POST para confirmar a seleção e obter mais detalhes:

 https://pub-gateway.fbits.net/api/pagamentos/TrocaPagamento/{NOME_LOJA}/{ID_GRUPO_FORMA_PAGAMENTO}/{ID_DO_CARRINHO}/

Onde:

${NOME_LOJA}: é o nome da loja no admin da plataforma.

${ID_GRUPO_FORMA_PAGAMENTO}: é o ID do Grupo da forma de pagamento escolhida pelo usuário (por exemplo, 7377, conforme o objeto acima).

${ID_DO_CARRINHO}: é o ID do carrinho associado ao pedido, o mesmo usado anteriormente (Fbits.MinhaConta.Pedido.CarrinhoId).

Após essa chamada, a API fornecerá os detalhes e instruções necessárias para proceder com a alteração da forma de pagamento.

Lembre-se de lidar adequadamente com possíveis erros ou exceções que possam surgir durante essas chamadas para garantir uma experiência fluida ao usuário.

Detalhes da Forma de Pagamento Selecionada

Ao chamar a API para confirmar a forma de pagamento escolhida, ela retornará um objeto com informações detalhadas e específicas sobre a forma selecionada. Abaixo está uma estrutura representativa de como esses detalhes podem aparecer:

{
    "Id": "acff12a5-3dea-433f-8a60-a80fb857f253",
    "Html": "<div data-gateway-cartao></div><div class='forminline'><label>CPF</label><input type='tel' id='pagarmev5-cpf' name='cpf' placeholder='CPF' data-mask='cpf' /></div>",
    "Scripts": [
        "https://pub-gateway.fbits.net/scripts/pagarmev5/cartao.js"
    ],
    "CartoesSugeridos": null,
    "Parcelamento": [
        {
            "Parcelas": 1,
            "Valor": 955.60
        }
    ] 
}

Entendendo os Campos da Resposta

Id: Identificador único da forma de pagamento.

Html: Código HTML dos campos extras cadastrados via painel administrativo. Este deve ser renderizado na tela para permitir a interação do usuário com os campos da forma de pagamento.

Scripts: Lista de scripts associados à forma de pagamento selecionada, cruciais para validações e processamentos específicos, como verificação de número de cartão e validade.

CartoesSugeridos: Campo que pode apresentar sugestões de cartões, se disponível.

Parcelamento: Opções de parcelamento disponíveis, onde cada item indica o número de parcelas e o valor respectivo.

Nota: No exemplo dado, a forma de pagamento é cartão de crédito, retornando assim um array de parcelamento. Algumas formas de pagamento podem retornar este campo vazio.

Certifique-se de renderizar o HTML retornado e de carregar os scripts indicados na página. Esses scripts são vitais para a correta validação dos campos da forma de pagamento, como CPF, nome, validade, entre outros.

Processamento do Pedido e Tokenização dos Dados de Pagamento

Para processar o pedido de forma segura, é crucial tokenizar os dados do pagamento. A tokenização converte as informações sensíveis do usuário em um token único e não descritivo. Esse processo protege os dados do cliente e permite que você realize transações sem expor diretamente essas informações.

Siga os passos abaixo para realizar a tokenização dos dados:

Coleta dos Dados de Pagamento:
Colete os dados de pagamento a partir dos campos do formulário na sua página. Seja qual for o método que você use para pegar esses dados, o objetivo é obter todas as informações do formulário de pagamento.
Por exemplo, usando jQuery, você pode obter esses dados através do seguinte código:
```
 let paymentData = $('[data-gateway-pagamento]').find("*").serialize();
```

Após a serialização, o resultado pode se parecer com:
'number=4111%201111%201111%201111&name=Joao%20Pedro&month=04&year=2027&expiry=04%2F2027&cvc=123&cpf=987.654.321-00'

Solicitação de Tokenização:
Com os dados do pagamento em mãos, faça uma requisição POST para a API de tokenização.
Endpoint: https://pub-token.fbits.net/api/new
Objeto esperado:
```
  const requestData = {
      data: paymentGatewayData,  // Dados serializados do passo anterior
      conector: '',               // Podemos deixar vazio esse campo
      tipo: 1                    // Tipo padrão para esta operação, podemos deixar sempre 1
}
```
Se tudo ocorrer como esperado , a API retornará um token similar ao objeto abaixo:
```
{
    "success": true,
    "message": null,
    "token": "6ce43945-88ae-4ad4-8147-95b9a9db1c58"
}
```
Processamento do Pedido
Após a primeira etapa de tokenização, você estará de posse de um token. Este será utilizado na segunda etapa de tokenização.
Segunda Etapa de Tokenização
Endpoint: Para realizar a segunda etapa, faça uma requisição ao endpoint formatado da seguinte forma:
https://pub-gateway.fbits.net/[ID_PAGAMENTO]/[TOKEN]
Neste formato, você substituirá [ID_PAGAMENTO] pelo identificador único do pagamento e [TOKEN] pelo token gerado no passo anterior.
Exemplo
https://pub-gateway.fbits.net/a55d54a8-ea58-4046-a852-c86a6cc117c8/d1437e7a-974a-4ccb-9ec1-18d97cd877d7
Resposta esperada: Ao chamar esse endpoint, a API deverá retornar uma resposta igual a:
```
{ "success": true }
```
Finalização do Pedido
Após receber a confirmação de sucesso da segunda etapa de tokenização, você pode prosseguir para finalizar o pedido.
Endpoint: Faça uma requisição ao endpoint:
https://pub-gateway.fbits.net/[ID_PAGAMENTO]
Resposta esperada: A API retornará uma confirmação de que o processo foi bem-sucedido:
```
{ "success": true }
```
Navegação pós-finalização: Uma vez que o pagamento é finalizado com sucesso, apresente ao usuário uma mensagem de confirmação e redirecione-o para a página de resumo de seus pedidos. Se o método de pagamento selecionado foi PIX ou boleto bancário, assegure-se de que o usuário tenha a opção de visualizar e/ou imprimir o comprovante diretamente dessa tela.

Updated about 2 months ago

Troca na forma de pagamento do pedido

📘
Importante!

👍
Modelos de JS e CSS prontos!

Instruções Iniciais - Vincular Scripts e CSS

Minha conta > Meus Pedidos

📘
Nota:

📘
Importante

Minha Conta > Meus Pedidos > Detalhe do Pedido

Iniciando a Listagem de Pagamentos dentro do Detalhe do Pedido

Seleção e Confirmação do Meio de Pagamento

Detalhes da Forma de Pagamento Selecionada

Entendendo os Campos da Resposta

Processamento do Pedido e Tokenização dos Dados de Pagamento

Siga os passos abaixo para realizar a tokenização dos dados:

📘Importante!

👍Modelos de JS e CSS prontos!

Instruções Iniciais - Vincular Scripts e CSS

Minha conta > Meus Pedidos

📘Nota:

📘Importante

Minha Conta > Meus Pedidos > Detalhe do Pedido

Iniciando a Listagem de Pagamentos dentro do Detalhe do Pedido

Seleção e Confirmação do Meio de Pagamento

Detalhes da Forma de Pagamento Selecionada

Entendendo os Campos da Resposta

Processamento do Pedido e Tokenização dos Dados de Pagamento

Siga os passos abaixo para realizar a tokenização dos dados:

📘
Importante!

👍
Modelos de JS e CSS prontos!

📘
Nota:

📘
Importante