Versão Completa

A versão Completa da URL é utilizada para pagamentos customizados mais robustos, onde temos funcionalidades como Cartões salvos, HTML customizado, Scripts customizados e Parcelamento customizado.
São 5 requisições feitas pela plataforma.

Abaixo apresentamos os modelos de Requisição, com o objeto enviado, e o modelo de Response, esperado pela plataforma:

Modelos de Requisição e de Response - v2

Modelo esperado quando se é utilizada a versão Completa da URL.

Na versão Completa da URL, você poderá utilizar features customizadas e a plataforma irá enviar a requisição para o endpoint utilizando como base o endereço cadastrado no campo Url, juntamente com os headers cadastrados na seção "Headers", no formato de chave e valor. Toda requisição vai acompanhada dos headers cadastrados.

No processo temos 5 requisições (Payment details, card, payment, capture e chargeback) que são feitas para a Url base no seguinte estrutura {urlbase}/payment-details, por exemplo.

Para melhor entendimento neste tópico vamos apresentar o modelo de requisição e o modelo de response na sequencia, separado pelas requisições:

Payment Details

Quando é utilizada?
Quando o usuário seleciona a opção de pagamento customizada no Checkout.

Estrutura da chamada
{urlbase}/payment-details
utiliza método POST enviando os dados do carrinho + headers e espera receber o objeto de retorno informado abaixo.

Modelo de Requisição da Payment Details
Estrutura do objeto enviado e seus dados:

{
  "Loja": "Nome da Loja",
  "PedidoId": 41282742,
  "ValorFrete": 13.27,
  "ValorTotal": 130.79,
  "Usuario": {
    "IdUsuario": 899988,
    "Nome": "nome cliente",
    "CPF": "11111111111",
    "CNPJ": "",
    "Email": [email protected],
    "Telefone": "41999999999",
    "Endereco": {
      "Logradouro": "Nunes Machado",
      "Numero": "68",
      "Complemento": "902",
      "Bairro": "Batel",
      "Cep": "80420120",
      "Cidade": "Curitiba",
      "Estado": "PR"
    }
  },
  "Produtos": [
    {
            "Codigo": 257442,
            "Nome": "Kit de Cervejas em Lata - Compre 6 e Leve 10",
            "Valor": 119.9,
            "Quantidade": 1,
            "Personalizacao": [
                {
                    "Nome": "Número",
                    "Valor": "12",
                    "Custo": 5.0
                }
    }
  ]
}

Tabela de detalhamento dos campos da requisição da Payment Details:

Modelo do response esperado da Payment Details:

{
        "html": "<div data-gateway-cartao>\n  <div class='forminline'>\n   <input type=\"hidden\" name=\"paymentMethod\" value=\"1\" />\n  </div>\n</div>",
        "scriptUrls": ["https://dominio.com.br/scripts/custom.js","https://domínio.com;br/scripts/custom-v3.js"],
        "cartoesSugeridos": [
          {
						"chave": "1234567",
						"nome": "JOAO SILVA",
						"numero": "411111XXXXXX1111",
						"bandeira": "visa"
					},
          {
						"chave": "1236547",
						"nome": "JOAO SILVA",
						"numero": "511111XXXXXX1122",
						"bandeira": "mastercard"
					}                           
                            ],
        "parcelamento": [{
						"parcelas": 6,
						"valor": 20.0,
						"ajuste": 0.0
		}]

}

👍

É possível utilizar as funcionalidades separadamente

Para isso, basta retornar "null" nos objetos e a plataforma irá utilizar o padrão.
Ou seja, caso o HTML seja enviado como "null", a plataforma irá verificar o campo Editor HTML e apresentar o que está configurado neste campo.
O mesmo se aplica para as demais funcionalidades "scriptUrls", "cartoesSugeridos" e "parcelamento".

Tabela de detalhamento dos campos do response da Payment Details:

🚧

Importante

O Parcelamento deve ser o mesmo configurado no Admin > Pagamentos > Grupos e Parcelamentos > Parcelamentos.

Card

Quando é utilizada?
Quando o usuário exclui o cartão salvo que está sendo apresentado na opção de pagamento customizado no Checkout.
Para isso, será necessário criar o botão de "excluir" via front-end vinculado ao cartão salvo, permitindo ao usuário excluir, caso seja estratégico para o lojista.

Estrutura da chamada
{urlbase}/card
utiliza método DELETE enviando o token do cartão que o usuário deseja remover dos cartões salvos.

Modelo de requisição da Card
Estrutura do objeto enviado e seus dados:

{
  "loja": "string",
  "idUsuario": "string",
  "email": "string",
  "chaveCartao": "string"
}

Tabela de detalhamento dos campos da requisição da Card

Modelo de Response esperado da Card:

200

🚧

Em caso de erro

Caso o retorno não seja 200, basta retornar o outro código relacionado com o erro em questão.

Tabela de detalhamento dos campos esperados no response da Card:

Payment

Quando é utilizada?
Quando o usuário fecha o pedido utilizando o pagamento customizado no checkout.

Estrutura da chamada
{urlbase}/payment
utiliza método POST enviando os dados do carrinho + headers + pagamento para realizar a cobrança do pedido.

Modelo de Requisição da Payment
Estrutura do objeto enviado e seus dados:

{
    "id": 189539,
    "loja": "Nome da Loja",
    "chave": "2D39FE37-611E-4015-1AF6-F62A2223B8D7",
    "pedido": 41282742,
    "frete": 13.27,
    "desconto": 0,
    "total": 130.79,
    "primeiroPedidoAssinatura": false,
    "assinatura": {
        "id": 1,
        "tipo": "recorrencia"
    },
    "usuario": {
        "nome": "nome cliente",
        "cpf": "11111111111",
        "cnpj": "",
        "email": "[email protected]",
        "endereco": {
            "logradouro": "Nunes Machado",
            "numero": "68",
            "complemento": "902",
            "bairro": "Batel",
            "cep": "80420120",
            "cidade": "Curitiba",
            "estado": "PR"
        },
        "telefone": "41999999999"
    },
    "produtos": [
        {
            "codigo": 257442,
            "nome": "Kit de Cervejas em Lata - Compre 6 e Leve 10",
            "cd": 123,
            "sku": "5784545",
            "valor": 119.9,
            "quantidade": 1,
            "personalizacao": [
                {
                    "nome": "Número",
                    "valor": "12",
                    "custo": 5.0
          },
        	{
            "codigo": 257440,
            "nome": "Kit de Cervejas em Lata 2",
            "cd": 321,
            "sku": "",
            "valor": 0.0,
            "quantidade": 1,
            "personalizacao": [
                {
                    "nome": "Número",
                    "valor": "",
                    "custo":
                }
            ]
        }
    ],
    "pagamento": {
        "parcelas": 2,
        "valor": 130.79,
        "ajuste": 0.0,
        "total": 130.79,
        "ip": "",
        "endereco": {
            "logradouro": "Nunes Machado",
            "numero": "68",
            "complemento": "902",
            "bairro": "Batel",
            "cep": "80420120",
            "cidade": "Curitiba",
            "estado": "PR"
        },
        "form": {
            "cpf": "111.111.111-11",
            "number": "5555 5555 5555 5555",
            "name": "nome cliente",
            "month": "1",
            "year": "2222",
            "expiry": "10/2222",
            "cvc": "222",
						"saveCard": true
       }
    }
}

🚧

Salvar e Excluir cartões

Para utilizar a funcionalidade de Cartões Salvos, é necessário permitir ao usuário Salvar o Cartão através do formulário do Novo Cartão de Crédito. A plataforma irá enviar o campo "saveCard" na requisição como "true" ou "false".

Os cartões salvos são de responsabilidade da aplicação responsável pela integração.
É recomendado que somente o cartão tokenizado junto ao Gateway/Adquirente seja salvo na base, juntamente com os dados básicos para utilização visual no checkout.

É possível permitir ao usuário Excluir o cartão salvo apresentado no método de pagamento customizado.
Como informado na Requisição Card para deletar o cartão.

👍

Boa prática

Como boa prática e para manter um padrão da plataforma, somente os tokens dos cartões que retornaram com a transação aprovada devem ser salvos na base, garantindo assim que somente cartões válidos serão salvos na aplicação e utilizados com sucesso pelos consumidores posteriormente.

🚧

Objeto "form" padrão

O objeto "form" padrão é composto somente pelo "cpf" e "saveCard" de forma nativa.
No caso do campo "saveCard", por padrão ele estará oculto e desabilitado no checkout. Para mostrar o campo no checkout e determinar se deve ou não estar sempre marcado por padrão, basta inserir o input abaixo no "Editor HTML":

Alterando o value para "true", o campo sempre abrirá marcado por padrão.

As demais informações devem ser inseridas via script no checkout. No exemplo acima, a aplicação responsável pela integração necessita de todos esses dados para cartão de crédito.

Modelo de Objeto "form" para Boleto e Pix

No exemplo de requisição acima, temos um formulário com informações necessárias para cartão de crédito. Porém o formulário é flexível e pode ser alterado de acordo com o método de pagamento utilizado. Segue abaixo um exemplo de "form" para Boleto:

"form": {
		"cpf": "111.111.111-11",
		"Loja": "nome da loja",
    "paymentMethod": "3"
}

Tabela de detalhamento dos campos da requisição de Payment:

Modelo do response esperado da Payment

{
  "statusId":1,
  "message":"Minha mensagem"
}
{
  "statusId":2,
  "message":"Minha mensagem"
}
{
  "statusId":3,
  "message":"Minha mensagem"
}
{
  "statusId":4,
  "message":"Minha mensagem"
}

Tabela de detalhamento dos campos do response acima:

Tabela de Status:

📘

Nesse modelo, quando no response for enviado "statusId":2, que se refere a um pagamento "Não Autorizado", será exibido o pop-up do checkout online para que o comprador corrija os dados do cartão e refaça o pagamento.

Lembrando que o retorno exibido no pop-up é padrão e o texto não pode ser personalizado.

📘

Processamento Two-Steps

No processamento "two-steps", a Autorização é feita separada da Captura do pagamento no cartão. Por tanto, deve-se responder nossa requisição com o status 4 e, posteriormente quando o pedido for "Aprovado", será feita uma nova requisição solicitando a Captura.

🚧

Aviso em Tempo Real

Com o JSON recebido na URL cadastrada, o pagamento pode ser capturado e o retorno do status para informar o comprador pode ser em tempo real, via response ou posteriormente, via postback.

Quando realizada integração via postback, a plataforma sempre informará no pedido o status de "aguardando pagamento" até que um novo status seja enviado.
Veja como utilizar o Modelo Postback.

Authorize (Autorização)

Quando é utilizada?
Quando o usuário deseja que o pedido seja processado em Two-steps, onde a transação deverá ser primeiro Autorizada e, após o Antifraude aprovar, a transação seja Capturada junto a aplicação do terceiro.
Essa requisição será enviada pela plataforma usando a estrutura abaixo.

Estrutura da chamada
{urlbase}/authorize
utiliza método POST enviando os dados do carrinho + headers + pagamento para realizar a cobrança do pedido.

Modelo de Requisição da Authorize
Estrutura do objeto enviado e seus dados:

{
    "id": 189539,
    "loja": "Nome da Loja",
    "chave": "2D39FE37-611E-4015-1AF6-F62A2223B8D7",
    "pedido": 41282742,
    "frete": 13.27,
    "desconto": 0,
    "total": 130.79,
    "primeiroPedidoAssinatura": false,
    "assinatura": {
        "id": 1,
        "tipo": "recorrencia"
    },
    "usuario": {
        "nome": "nome cliente",
        "cpf": "11111111111",
        "cnpj": "",
        "email": "[email protected]",
        "endereco": {
            "logradouro": "Nunes Machado",
            "numero": "68",
            "complemento": "902",
            "bairro": "Batel",
            "cep": "80420120",
            "cidade": "Curitiba",
            "estado": "PR"
        },
        "telefone": "41999999999"
    },
    "produtos": [
        {
            "codigo": 257442,
            "nome": "Kit de Cervejas em Lata - Compre 6 e Leve 10",
            "cd": 123,
            "sku": "5784545",
            "valor": 119.9,
            "quantidade": 1,
            "personalizacao": [
                {
                    "nome": "Número",
                    "valor": "12",
                    "custo": 5.0
          },
        	{
            "codigo": 257440,
            "nome": "Kit de Cervejas em Lata 2",
            "cd": 321,
            "sku": "",
            "valor": 0.0,
            "quantidade": 1,
            "personalizacao": [
                {
                    "nome": "Número",
                    "valor": "",
                    "custo":
                }
            ]
        }
    ],
    "pagamento": {
        "parcelas": 2,
        "valor": 130.79,
        "ajuste": 0.0,
        "total": 130.79,
        "ip": "",
        "endereco": {
            "logradouro": "Nunes Machado",
            "numero": "68",
            "complemento": "902",
            "bairro": "Batel",
            "cep": "80420120",
            "cidade": "Curitiba",
            "estado": "PR"
        },
        "form": {
            "cpf": "111.111.111-11",
            "number": "5555 5555 5555 5555",
            "name": "nome cliente",
            "month": "1",
            "year": "2222",
            "expiry": "10/2222",
            "cvc": "222",
						"saveCard": true
       }
    }
}

🚧

Salvar e Excluir cartões

Para utilizar a funcionalidade de Cartões Salvos, é necessário permitir ao usuário Salvar o Cartão através do formulário do Novo Cartão de Crédito. A plataforma irá enviar o campo "saveCard" na requisição como "true" ou "false".

Os cartões salvos são de responsabilidade da aplicação responsável pela integração.
É recomendado que somente o cartão tokenizado junto ao Gateway/Adquirente seja salvo na base, juntamente com os dados básicos para utilização visual no checkout.

É possível permitir ao usuário Excluir o cartão salvo apresentado no método de pagamento customizado.
Como informado na Requisição Card para deletar o cartão.

👍

Boa prática

Como boa prática e para manter um padrão da plataforma, somente os tokens dos cartões que retornaram com a transação aprovada devem ser salvos na base, garantindo assim que somente cartões válidos serão salvos na aplicação e utilizados com sucesso pelos consumidores posteriormente.

🚧

Objeto "form" padrão

O objeto "form" padrão é composto somente pelo "cpf" e "saveCard" de forma nativa.
No caso do campo "saveCard", por padrão ele estará oculto e desabilitado no checkout. Para mostrar o campo no checkout e determinar se deve ou não estar sempre marcado por padrão, basta inserir o input abaixo no "Editor HTML":

Alterando o value para "true", o campo sempre abrirá marcado por padrão.

As demais informações devem ser inseridas via script no checkout. No exemplo acima, a aplicação responsável pela integração necessita de todos esses dados para cartão de crédito.

📘

Importante

Este fluxo de Antifraude, no Pagamento Customizado, é exclusivamente compatível com o modelo completo de integração e não é suportado no modelo simplificado. Certifique-se de que sua integração esteja configurada conforme o modelo completo para garantir o funcionamento correto deste fluxo de Antifraude.

Modelo de Objeto "form" para Boleto e Pix

No exemplo de requisição acima, temos um formulário com informações necessárias para cartão de crédito. Porém o formulário é flexível e pode ser alterado de acordo com o método de pagamento utilizado. Segue abaixo um exemplo de "form" para Boleto:

"form": {
		"cpf": "111.111.111-11",
		"Loja": "nome da loja",
    "paymentMethod": "3"
}

Tabela de detalhamento dos campos da requisição de Authorize:

Modelo do response esperado da Authorize

{
  "statusId":1,
  "message":"Minha mensagem"
}
{
  "statusId":2,
  "message":"Minha mensagem"
}
{
  "statusId":3,
  "message":"Minha mensagem"
}
{
  "statusId":4,
  "message":"Minha mensagem"
}

Tabela de detalhamento dos campos do response acima:

Tabela de Status:

📘

Nesse modelo, quando no response for enviado "statusId":2, que se refere a um pagamento "Não Autorizado", será exibido o pop-up do checkout online para que o comprador corrija os dados do cartão e refaça o pagamento.

Lembrando que o retorno exibido no pop-up é padrão e o texto não pode ser personalizado.

📘

Processamento Two-Steps

No processamento "two-steps", a Autorização é feita separada da Captura do pagamento no cartão. Por tanto, deve-se responder nossa requisição com o status 4 e, posteriormente quando o pedido for "Aprovado", será feita uma nova requisição solicitando a Captura.

🚧

Aviso em Tempo Real

Com o JSON recebido na URL cadastrada, o pagamento pode ser autorizado e o retorno do status para informar o comprador pode ser em tempo real, via response ou posteriormente, via postback.

Quando realizada integração via postback, a plataforma sempre informará no pedido o status de "aguardando pagamento" até que um novo status seja enviado.
Veja como utilizar o Modelo Postback.

Capture (Captura)

Quando é utilizada?
Quando o usuário deseja que o pedido Aprovado pós Antifraude seja Capturado junto a aplicação do terceiro.
Essa requisição será enviada pela plataforma usando a estrutura abaixo.

Estrutura da chamada
{urlbase}/capture
utiliza método POST enviando o id do pedido, nome da loja, chave da transação e número do pedido em uma estrutura json.

Modelo de requisição da Capture
Estrutura do objeto enviado e seus dados:

{
	"id": 189539,
  "loja": "Nome da Loja",
  "chave": "2D39FE37-611E-4015-1AF6-F62A2223B8D7",
  "pedido": 41282742,
}

Tabela de detalhamento dos campos da requisição da Capture

Modelo de Response esperado da Capture:

{
  "statusId":3,
  "message":"Minha mensagem"
}

Tabela de detalhamento dos campos do response acima:

Tabela de Status:

📘

Processamento Two-Steps

No processamento "two-steps", a Autorização é feita separada da Captura do pagamento no cartão. Por tanto, deve-se responder á nossa requisição /capture com o status 2 (Não autorizado) ou 3 (Pago), conforme response esperado.

Chargeback (Estorno)

Quando é utilizada?
Quando o usuário deseja que o estorno parcial ou total do seu pedido seja realizado.
Este processo é feito via API Pública, usando uma aplicação externa para solicitar o estorno através de um post no endpoint https://api.fbits.net/pedidos/estorno/{pedidoId}.

Uma vez solicitado o estorno via API Pública, a plataforma irá enviar uma requisição usando a estrutura abaixo para o endpoint cadastrado no campo "URL" e aguardando o retorno da aplicação.

Estrutura da chamada
{urlbase}/chargeback
utiliza método POST enviando o número do pedido e o valor a ser estornado em uma estrutura json.

Modelo de requisição da Chargeback
Estrutura do objeto enviado e seus dados:

{
  "Pedido": 123456,
  "Valor": 10.50
}

Tabela de detalhamento dos campos da requisição da Chargeback

Modelo de Response esperado da Chargeback:

200

🚧

Em caso de erro

Caso o retorno não seja 200, basta retornar o outro código relacionado com o erro em questão.

Tabela de detalhamento dos campos esperados no response da Chargeback:

👍

Agora vamos deixar a opção de pagamento visível no Checkout!

Após o desenvolvimento da aplicação no Pagamento Customizado, é necessário realizar as configurações no Admin para que as opções de Pagamento Customizado sejam disponibilizadas no Checkout da loja.

Para isso, acesse nossas documentações funcionais clicando aqui.