Documentação

Postback

Suggest Edits

Quando é utilizado?

O postback é utilizado para envio de status e informações adicionais após o fluxo do pedido.

Exemplos

  • Fluxos que utilizam Antifraude e que costumam não ter retorno da aprovação do pagamento em tempo real.
  • Envio de informações adicionais do pedido como o id de uma assinatura.
  • Atualização de status de pedidos

📘

Consultando pedidos pendentes

O postback pode ser utilizado para atualizar a situação de pedidos posteriormente, para consultar os pedidos com status "Aguardando Pagamento" ou "Aprovado Análise", por exemplo, veja como fazer acessando a documentação.

Modelo Postback - "Status" + "Informações Adicionais"

Método

  • POST

Campos esperados (JSON)

  • status - int.

https://gateway-postback.fbits.net/api/Custom/{chave_transacao}

No campo Chave_transação, será inserida a chave única enviada no request

Esse campo recebe o nome de Chave e está em formato GUID.

chave":"f50dc736-14cc-4e09-b7df-f2f5836ed095"

Segue evidenciado no trecho do código abaixo: 

{
    "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"
    },

Exemplo de utilização

{
  "status": 1 ,
	"informacoesAdicionais": [
	{
		"Nome": "Teste1",
		"Valor": "Valor1"
	},
	{
		"Nome": "Teste2",
		"Valor": "Valor2"
	}						
	]
}

{
  "status": 2,
  "informacoesAdicionais": [
	{
		"Nome": "Teste3",
		"Valor": "Valor3"
	}					
	]
}

{
  "status": 3 
}

{
  "status": 4 
}

📘

Informações adicionais

Utilize o array de informações adicionais para enviar os seguintes dados obrigatórios quando existirem nas transações de cartão ou Pix: TID, NSU e Auth. Essas informações são essenciais, pois nossos clientes as utilizam para a conciliação de transações.

Outros dados, como o Código da Adquirente, podem ser incluídos caso estejam disponíveis e sejam relevantes para o parceiro, porém não são obrigatórios. Não há limitação no envio de campos de chave e valor.

Por fim, é importante que os dados sejam enviados exatamente como aparecem no painel da adquirente para facilitar o processo de conciliação.

❗️

Erros de pagamento

Importante: É essencial que, ao ocorrer um erro de pagamento, o parceiro insira as informações relacionadas ao erro dentro do array de informações adicionais.

Esses dados são fundamentais para que o lojista consiga identificar a causa do problema e tomar as medidas necessárias para solucioná-lo de forma ágil.

Exemplo de requisição

{
    "informacoesAdicionais": [
        {
            "nome": "ErroNumeroCartao",
            "valor": "O campo do número não é um número de cartão válido"
        }
    ]
}

Obs: O Campo nome valor tem no máximo100 caracteres e o campo valor máximo de 5000 caracteres.

Confira, na tabela abaixo, a explicação de cada Id de status e sua respectiva ação:

Id
1Aguardando pagamentoMantém o pedido com o status Aguardando Pagamento.
2Não autorizadoAtualiza o pedido para Cancelado/Negado.
3PagoAtualiza o pedido para Pago.
4AutorizadoAtualiza o status do pedido para Autorizado na plataforma. Usado em processamento Two-steps (Autorização separada da Captura).

🚧

Informações Adicionais enviadas sem atualização de status nesse postback não serão gravadas.

Para enviar apenas informações adicionais, utilize o modelo de postback "Apenas Informações Adicionais" exemplificado mais abaixo na documentação.


📘

Devolução de dados para envio ao antifraude

Precisamos que, após a autorização do pedido no fluxo de "two steps", sejam devolvidos os seguintes dados na requisição: CartaoNome, CartaoBandeira ,CartaoValidade, CartaoBin e CartaoQuatroUltimosDigitos . Esses dados são fundamentais para que possamos realizar o envio adequado das informações para a validação do antifraude, garantindo uma análise precisa e segura das transações, além de contribuir para a mitigação de riscos de fraude.

Modelo Postback - Apenas "Informações Adicionais"

Método

  • POST

Campos esperados (JSON)

  • informacoesAdicionais - lista.

Passando a chave única da transação:

https://gateway-postback.fbits.net/api/Custom/informacoesadicionais/{chave_transacao}

Esse campo recebe o nome de Chave e está em formato GUID.

chave":"f50dc736-14cc-4e09-b7df-f2f5836ed095"

Passando o Id da transação:

https://gateway-postback.fbits.net/api/custom/informacoesadicionais/idTransacao/45879078

Exemplo de requisição

{
    "informacoesAdicionais": [
        {
            "nome": "TID",
            "valor": "0556481403201"
        },
        {
            "nome": "NSU",
            "valor": "167450"
        }
        {
            "nome": "Auth",
            "valor": "250700"
        }
          {
            "nome": "CartaoBin",
            "valor": "123456"
        }
         {
            "nome": "CartaoBandeira",
            "valor": "Mastercard"
        }
        {
            "nome": "CartaoNome",
            "valor": "João Teste"
        }
         {
            "nome": "CartaoQuatroUltimosDigitos",
            "valor": "1234"
        }
         {
            "nome": "CartaoValidade",
            "valor": "12/2024"
        }
        
  
  
    ]
}

❗️

Os valores apresentados nesta documentação são meramente exemplificativos e têm fins de referência técnica.

📘

Nesse modelo, não será necessário informar o campo status.

📘

Informamos que as Informações Adicionais devem ser enviadas no body da sua requisição.

❗️

Erros de pagamento

Importante: É essencial que, ao ocorrer um erro de pagamento, o parceiro insira as informações relacionadas ao erro dentro do array de informações adicionais.

Esses dados são fundamentais para que o lojista consiga identificar a causa do problema e tomar as medidas necessárias para solucioná-lo de forma ágil.

Exemplo de requisição

{
    "informacoesAdicionais": [
        {
            "nome": "ErroNumeroCartao",
            "valor": "O campo do número não é um número de cartão válido"
        }
    ]
}

_Obs: O Campo nome valor tem no máximo100 caracteres e o campo valor máximo de 5000 caracteres.

📘

Formas de pagamento Pix e Boleto

Para as formas de pagamento Pix e boleto, é necessário que o array de informações adicionais inclua os campos abaixo. Dessa forma, essas informações serão exibidas no ADM do pedido e na seção "Minha Conta" do cliente, permitindo que o mesmo tenha mais flexibilidade para concluir sua compra em um momento posterior, caso não seja possível finalizá-la no fechamento do pedido.

Exemplo de requisição Pix

{
    "informacoesAdicionais": [
        {
            "nome": "PixQrCodeUrl",
            "valor": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgBBBpQAAAKUAQAAAACStJWRAAAB60lEQVR4nO3YwW3DMAwFUG3g/bfMBi7Q2iYl2QkaM4cWjwcjFsmn3D6StpbXozGZTCaTyWQymUwmk8lkMplMJpPJZDL/g9nGWn4m2jHbtrnlapjJZDKZzAIzzi9Wc2MeZjKZTCazytyWl/y6xVuk3cUwk8lkMpkfMifu7IcXk8lkMpkfN9c024Yuk8lkMpkfMqfXWXoyzGQymUxmgTlURNnZYx5mMplMJrPAPK/HsbCn3esNJpPJZDLvmLE1SEOoLXlpuofJZDKZzNvmNrYcr8PZWffBZDKZTGadOaRYXt2l3IiNLvKYTCaTySwwp9gKc6+hu50xmUwmk1ljnuVZ5pY8lyNv6jKZTCaTecccuG41wu+7pk9MJpPJZFaZkXFRQ9rtoXb2ymQymUxmgRkTObH2y3K3uzF2mUwmk8ksMDPc7V82ott/ASaTyWQyb5rTFa3/l6/7vy+uYDKZTCazymxjdasbtzfiMdzDZDKZTOZdM87XvJUfw2WtT0Amk8lkMmvM2MqrZ3BU91WYTCaTyaw34+w7yqYfXu2NjGMymUwm8y0zpIBD2hork8lkMpl15nTFy4wb1phMJpPJvGsOtcfbMZvOcvfpby4mk8lkMn9nVhWTyWQymUwmk8lkMplMJpPJZDKZTCbzD5tfrqaQR3sEp6cBBBBBSUVORK5CYII="
        },
        {
            "nome": "PixQrCode",
            "valor": "00020101021226950014br.gov.bcb.pix21081234567822041234230912344567824200123456789012345678952040000530398656074043.985802BR5915FABRICA DE BITS6008Curitiba62180514T0I18424023I0T80760014br.gov.bcb.pix2546bx.com.br/pix/0A0104AB02011D439F327DBD6C1186AD6304C7DD"
        },
        {
            "nome": "DataExpiracaoQrCode",
            "valor": "04/11/2024 12:16:20"
        }
    ]
}

PixQrCodeUrl: imagem do Pix em base 64 (enviar no formato: "data:image/png;base64, {imagemBase64}")
PixQrCode: copiável do Pix
DataExpiracaoQrCode: data de expiração do Pix


Exemplo de requisição Boleto

{
    "informacoesAdicionais": [
        {
            "nome": "LinhaDigitavel",
            "valor": "12345656029000471149635005393703774970000001111"
        },
        {
            "nome": "LinkPagamento",
            "valor": "https://wake.com/boleto/1b4f1fb6-38db-4e90-9582-f3908570b12a"
        }
    ]
}

LinhaDigitavel: Copia e cola do boleto

LinkPagamento: Link para abertura do boleto

Updated 4 days ago