GuidesCommunity
Guides

Postbacks - Callbacks - Webhooks

Comunicação Transacional

Suggest Edits

A API de PIX Boleto oferece uma variedade de tipos de postbacks (callbacks/webhooks) que têm a finalidade de notificar o cliente sobre o progresso ou conclusão de transações que seguem um fluxo assíncrono.

O postback é uma funcionalidade que permite a transmissão de dados em tempo real entre sistemas ou aplicativos distintos, possibilitando a integração de diferentes sistemas para manter os dados da aplicação e dos clientes sincronizados. Sempre que um evento relevante ocorre em um dos sistemas, relacionado a uma transação, os dados são enviados por meio de um postback. Por exemplo, isso ocorre quando um pagamento é realizado por meio de um QR Code (PIX IN).

🔐

Saiba sobre Notificações Assinadas acessando: Assinatura de Notificação

Postback PIX Boleto

O produto de Pix Boleto utiliza o conceito de FSM (Finite State Machine) para gestão dos estados de suas transações.

Para cada mudança de estado, o cliente receberá um postback o informando do novo estado. Assim como dados da transações são atualizadas a cada mudança.

Atualmente os estados de uma transação do Pix Boleto são:

pix_pending_payment - Representa o estado inicial da transação, aguardando o pagamento do QRCode gerado.

pix_paid - Pix pago - (estado intermediário da transação)

boleto_paid - Representa o estado final da transação no fluxo de sucesso (PIX (QR Code) pago e boleto pago com sucesso

boleto_refunded - Representa um estado final da transação no fluxo de falha, quando há o estorno do pagamento do boleto pelo banco liquidante, pode ocorrer em até 5 dias úteis pós liquidação, nesse cenário o status vai evoluir para falha ("boleto_refunded" e "pix refunded")

Ver abaixo "Fluxo de Falha 2"

boleto_error_payment - Falha no pagamento do boleto - Pode representar ou não um status final, se o erro apresentado no pagamento for passível de uma nova tentativa, a mesma será feita e o status pode evoluir para sucesso ("boleto_paid") se de fato não for possível reprocessar, o status vai evoluir para falha ("boleto_error_payment" e "pix refunded")

Ver abaixo "Fluxo de Falha 1"

pix_refunded - Representa o estado final da transação (quando não foi possível pagar o boleto e o PIX foi estornado) - Pix estornado a origem

pix_error_refunded - Falha no estorno do PIX - Representa um status intermediário, onde o Refund pode ser reprocessado até o sucesso ("pix refunded")

{
	"id": "c6cbf689-492d-4492-b5f0-a1cb917fe412",
	"city": "São Paulo",
	"amount": "120.9",
	"states": [
		{
			"status": "pix_paid",
			"createdAt": "2023-10-05T19:38:25.208Z",
			"additionalData": {
				"amount": "120.90",
				"endToEndId": "E03311443202310051938AzSVG1brdaE",
				"transactionId": "4e33204c-4837-4c65-b0fb-19b2095ce46d",
				"clientExternalId": "PIBf5b953de750644baa8edd5fcea83bf4b",
				"externalTransactionId": "1327f327-762d-4912-8dda-3471909996d6"
			}
		},
		{
			"id": "16596d56-84ab-4712-89d8-d06b7dec6c59",
			"status": "pix_pending_payment",
			"createdAt": "2023-10-05T19:35:57.468Z",
			"additionalData": "{}"
		}
	],
	"customId": "2b06ce16-fcc0-4133-a977-3d86144252e5",
	"walletId": "615abd61-cb2b-4d07-84f3-81708885afa3",
	"createdAt": "2023-10-05T19:35:57.468Z",
	"payerName": "Jamerson Vasconcelos",
	"lastStatus": "pix_paid",
	"payerTaxId": "03842023065",
	"destination": "640de746-de7a-4b3e-892e-1a0eabc9ca15",
	"digitableLine": "36490000190001508760400000706457500000000009990",
	"boletoExpiresAt": "2023-10-10T18:00:00.000Z",
	"qrcodeExpiresAt": "2023-10-10T18:00:00.000Z",
	"clientExternalId": "PIBf5b953de750644baa8edd5fcea83bf4b",
	"coreTransactionId": "1327f327-762d-4912-8dda-3471909996d6"
}

{
	"id": "c6cbf689-492d-4492-b5f0-a1cb917fe412",
	"city": "São Paulo",
	"amount": "120.9",
	"states": [
		{
			"id": "3570a7c2-1354-4b24-9c7e-214f01113765",
			"status": "boleto_paid",
			"createdAt": "2023-10-05T19:38:32.230Z",
			"additionalData": {
				"type": "payment",
				"status": "executed",
				"boletoId": "1327f327-762d-4912-8dda-3471909996d6"
			}
		},
		{
			"id": "1200717f-0f00-4c93-ba85-11e24414754f",
			"status": "pix_paid",
			"createdAt": "2023-10-05T19:38:25.208Z",
			"additionalData": {
				"amount": "120.90",
				"endToEndId": "E03311443202310051938AzSVG1brdaE",
				"transactionId": "4e33204c-4837-4c65-b0fb-19b2095ce46d",
				"clientExternalId": "PIBf5b953de750644baa8edd5fcea83bf4b",
				"externalTransactionId": "1327f327-762d-4912-8dda-3471909996d6"
			}
		},
		{
			"id": "16596d56-84ab-4712-89d8-d06b7dec6c59",
			"status": "pix_pending_payment",
			"createdAt": "2023-10-05T19:35:57.468Z",
			"additionalData": "{}"
		}
	],
	"customId": "2b06ce16-fcc0-4133-a977-3d86144252e5",
	"walletId": "615abd61-cb2b-4d07-84f3-81708885afa3",
	"createdAt": "2023-10-05T19:35:57.468Z",
	"payerName": "Jamerson Vasconcelos",
	"lastStatus": "boleto_paid",
	"payerTaxId": "03842023065",
	"destination": "640de746-de7a-4b3e-892e-1a0eabc9ca15",
	"digitableLine": "36490000190001508760400000706457500000000009990",
	"boletoExpiresAt": "2023-10-10T18:00:00.000Z",
	"qrcodeExpiresAt": "2023-10-10T18:00:00.000Z",
	"clientExternalId": "PIBf5b953de750644baa8edd5fcea83bf4b",
	"coreTransactionId": "1327f327-762d-4912-8dda-3471909996d6"
}

{
  "id": "07893270-4553-40a3-bf0a-509d22115ea2",
  "digitableLine": "00190000090283633605305416182177190730000009900",
  "city": "Barueri",
  "customId": "customFXYENTD1",
  "payerName": "Mr. Denise Gleichner @ develop Pagador do Pix Boleto",
  "payerTaxId": "56715772999",
  "amount": "0.26",
  "boletoExpiresAt": "2023-03-01T02:59:59.000Z",
  "qrcodeExpiresAt": "2023-02-28T20:59:59.000Z",
  "clientExternalId": "PIB1400c695832648ca93c0de3499bca7ea",
  "walletId": "b1612595-3988-4b9b-810d-4df9b6fa1e7f",
  "createdAt": "2023-02-27T14:23:47.052Z",
  "lastStatus": "pix_refunded",
  "states": [
    ...,
    {
      "id": "e88a9c01-1f17-430c-bb93-a126a69e2a36",
      "status": "boleto_paid",
      "createdAt": "2023-02-27T14:23:47.052Z"
    },
    {
      "id": "e88a9c01-1f17-430c-bb93-a126a69e2a36",
      "status": "boleto_error_payment",
      "createdAt": "2023-02-27T14:32:47.052Z",
      "reason": "Codigo de barras invalido" //motivo de falha no pagamento do boleto
    },
    {
      "id": "e88a9c01-1f17-430c-bb93-a126a69e2a36",
      "status": "pix_refunded",
      "createdAt": "2023-02-27T15:13:47.052Z",
      "reason": "Codigo de barras invalido" //motivo do estorno do pix
    }
  ]
}

{
	"id": "71ecc9a7-e5d6-4d76-8560-485262faf6b7",
	"city": "Jijoca de Jericoacoara",
	"amount": "1.09",
	"states": [
		{
			"id": "c78aa5e0-788f-4678-87c5-6ee0bfdfd07f",
			"reason": "teste",
			"status": "boleto_refunded",
			"createdAt": "2023-10-05T19:00:07.665Z",
			"reasonCode": "teste",
			"additionalData": {
				"id": "teste",
				"amount": "1.09",
				"reason": "teste",
				"status": "refunded",
				"refundId": "testeid",
				"reasonCode": "teste",
				"refundDate": "2023-10-05",
				"idempotency": "PIBQywXkNTnnJPSaA95YNt476z",
				"digitableLine": "23793381286008301352856000063307789840000150000"
			}
		},
		{
			"id": "a07a7a7f-bce7-447b-8dc4-0c6814c32440",
			"status": "boleto_paid",
			"createdAt": "2023-10-05T18:50:18.276Z",
			"additionalData": "{\"boletoId\":\"40085e20-1fb6-4461-9663-40fde64a7702\",\"type\":\"payment\",\"status\":\"executed\"}"
		},
		{
			"id": "936a3bdc-ae87-4b14-a18d-4df9ff83ae9b",
			"status": "pix_paid",
			"createdAt": "2023-10-05T18:50:10.579Z",
			"additionalData": "{\"transactionId\":\"33b21906-cb95-41b2-84ec-78597dd6350e\",\"amount\":\"1.09\",\"externalTransactionId\":\"40085e20-1fb6-4461-9663-40fde64a7702\",\"clientExternalId\":\"PIBQywXkNTnnJPSaA95YNt476z\",\"endToEndId\":\"E03311443202310051850It8fcFJgUnc\"}"
		},
		{
			"id": "250664c6-c7da-4fd8-8886-f1c58cf9330e",
			"status": "pix_pending_payment",
			"createdAt": "2023-10-05T18:49:43.506Z",
			"additionalData": "{}"
		}
	],
	"customId": "custom_FHZIGNR1643",
	"walletId": "930c6c45-b3ae-463b-8558-3b4e989e4146",
	"createdAt": "2023-10-05T18:49:43.506Z",
	"payerName": "Estelle Hayes DVM @ staging Pagador do Pix Boleto",
	"lastStatus": "boleto_refunded",
	"payerTaxId": "03495664999",
	"destination": "529a41f4-bfad-444e-9fb5-80346919b079",
	"digitableLine": "23793381286008301352856000063307789840000150000",
	"boletoExpiresAt": "2023-10-30T16:00:00.000Z",
	"qrcodeExpiresAt": "2023-10-30T16:00:00.000Z",
	"clientExternalId": "PIBQywXkNTnnJPSaA95YNt476z",
	"coreTransactionId": "40085e20-1fb6-4461-9663-40fde64a7702"
}

{
    "id": "b50dfb6a-86ef-41de-99fb-32895b564308",
    "city": "Jijoca de Jericoacoara",
    "amount": "0.9",
    "states": [
        {
            "id": "b9f9dce3-b315-4856-a12c-76f82b2bb62e",
            "reason": "Linha Digitavel Invalida",
            "status": "boleto_error_payment",
            "createdAt": "2023-10-06T17:15:53.317Z",
            "reasonCode": "999",
            "additionalData": {
                "reason": "Linha Digitavel Invalida",
                "reasonCode": "999"
            }
        },
        {
            "id": "7616e7a5-5750-48b5-99a0-036d733385f1",
            "status": "pix_paid",
            "createdAt": "2023-10-06T17:15:51.620Z",
            "additionalData": {
                "amount": "0.90",
                "endToEndId": "E03311443202310061715OXlvj168vBs",
                "transactionId": "ba90778f-bef1-42f9-a0eb-f98c5e2005b0",
                "clientExternalId": "PIBQFojpAhpOprxIwurR3m2LC4",
                "externalTransactionId": "976e31e2-70c6-4666-a097-799136ac5236"
            }
        },
        {
            "id": "41a233af-3074-4216-900c-f72cbe969861",
            "status": "pix_pending_payment",
            "createdAt": "2023-10-06T17:15:36.489Z",
            "additionalData": "{}"
        }
    ],
    "customId": "custom_FMNANOB1",
    "walletId": "930c6c45-b3ae-463b-8558-3b4e989e4146",
    "createdAt": "2023-10-06T17:15:36.488Z",
    "payerName": "Anne Fritsch III @ staging Pagador do Pioleto",
    "lastStatus": "boleto_error_payment",
    "payerTaxId": "99988877700",
    "destination": "529a41f4-bfad-444e-9fb5-80346919b079",
    "digitableLine": "78630685707399455301722774103195280971277050914",
    "boletoExpiresAt": "2023-10-30T16:00:00.000Z",
    "qrcodeExpiresAt": "2023-10-30T16:00:00.000Z",
    "clientExternalId": "PIBQFojpAhpOprxIwurR3m2LC4",
    "coreTransactionId": "976e31e2-70c6-4666-a097-799136ac5236"
}

Descrição de Campos

CAMPOTIPODESCRIÇÃO
idstringIdentificador da transação
digitableLinestringLinha digitável do boleto associado
citystringCidade de origem da emissão do QRCode
customIDstringIdentificador customizado informado na criação do qrcode
payerNamestringNome do indivíduo ao ser cobrado
payerTaxIdstringDocumento do indivíduo ao ser cobrado
amountstringValor da transação
boletoExpiresAtstringData/hora de expiração do boleto
qrcodeExpiresAtstringData/hora de expiração do QRCode
clientExternalIdstringIdentificador interno do PixBoleto
Informado na criação do QRCode
walletIdstringWallet transacionada
createdAtdateData/hora de criação da transação
updatedAtdateData/hora da última atualização da transação
lastStatusstringÚltimo status da transação
statesarrayArray com a lista de status movimentados na transação
reasonstringMotivo pelo qual ocorreu o fluxo de falha

📘

Informação:

A lista de motivos de fluxo de falha, não pagamento de boleto ou devolução de pagamento de boleto estão disponíveis nos links abaixo:

Erros de Pagamento de boletos
https://developers.bitcapital.com.br/docs/pagar-um-boleto

Motivos de devolução
[<https://developers.bitcapital.com.br/docs/consultar-devolu%C3%A7%C3%B5es](<https://developers.bitcapital.com.br/docs/consultar-devolu%C3%A7%C3%B5es)

Evolução dos status de transação:

Updated 8 months ago