Pix
Confira os eventos relativos a Pix.
beta
Os eventos de Pix disparam mensagens que comunicam ao destinatário movimentações relacionadas a cash-in (recebimento de valores provenientes de pagamentos, transferências ou devoluções) e a cash-out (pagamentos e transferências via Pix, assim como o seu cancelamento).
Como esses eventos chegam ao recebedor via webhook, é preciso realizar previamente a sua configuração.
Contexto e nome do evento
Nos eventos Pix, o campo context sempre informará “Pix”, enquanto o campo name poderá variar de acordo com a transação, conforme a tabela a seguir:
| Nome do evento (name) | Descrição |
|---|---|
| PIX_CASH_IN_WAS_RECEIVED | O valor foi recebido no core bancário Bankly. |
| PIX_CASH_IN_WAS_CLEARED | O valor foi liberado na conta destino. |
| PIX_REFUND_WAS_RECEIVED | O valor devolvido foi recebido no core bancário Bankly. |
| PIX_REFUND_WAS_CLEARED | O valor devolvido foi liberado na conta destino. |
| PIX_CASHOUT_WAS_COMPLETED | Pagamento via Pix finalizado. |
| PIX_CASHOUT_WAS_CANCELED | Pagamento via Pix cancelado. Nesse caso, o valor não sai da conta do pagador e, portanto, não ocorre estorno. |
| PIX_CASHOUT_WAS_UNDONE | Pagamento via Pix desfeito. A operação de transferência de valor ocorre, mas, devido a algum erro no recebedor, ela não pode ser completada. Nesse caso, acontece o estorno. |
EntityId
O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.
No contexto de Pix, o entityId é o AuthenticationCode (código identificador da transação).
Exemplos de eventos
[
{
"entityId": "5304d083-5686-4e0a-b8f4-230b950e6d96",
"companyKey": "ACESSO",
"idempotencyKey": "b365a637-8175-4d93-9284-7981506deefd",
"context": "Pix",
"name": "PIX_CASH_IN_WAS_RECEIVED",
"timestamp": "2021-11-22T14:21:51.8586571Z",
"correlationId": "4d3c0c7f-1af4-45fa-9dab-626ca44f3380",
"metadata": null,
"data": {
"addressingKey": {
"value": "12345678900",
"type": "CPF"
},
"authenticationCode": "5304d083-5686-4e0a-b8f4-230b950e6123",
"amount": {
"value": 1,
"currency": "BRL"
},
"recipient": {
"document": {
"value": "00987654321",
"type": "Undefined"
},
"name": "Peter Parker",
"account": {
"branch": "0001",
"number": "123456",
"type": "Checking",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
}
},
"channel": {
"name": "SPI",
"sender": {
"document": {
"value": "00000000000",
"type": "Undefined"
},
"name": "Carol Denvers",
"account": {
"branch": "0001",
"number": "654321",
"type": "Checking",
"bank": {
"ispb": "00000000"
}
}
},
"end2EndId": "E1314008820211122142121920882256",
"receiverReconciliationId": "TesteConciliationWebhook",
"pixInitializationType": "StaticQrCode",
"pixPaymentPriority": "Priority",
"pixPaymentPriorityType": "Priority",
"pixPaymentPurpose": "PurchaseOrTransfer"
},
"createdAt": "2021-11-22T14:21:51.7758706Z"
}
}
]
[
{
"entityId": "a79753ae-6d68-4e81-b4a4-14147063b12b",
"idempotencyKey": "86447d19-687f-4fa8-80cf-a5aa406457b9",
"companyKey": "ACESSO",
"context": "Pix",
"name": " PIX_CASH_IN_WAS_CLEARED",
"timestamp": "2021-10-05T00:00:00.000Z",
"correlationId": "61833e96-86ea-4248-9700-5fd08a00bcb2",
"version": "1",
"metadata": {
"key": "Complement event info"
},
"data": {
"amount": {
"value": 0,
"currency": "BRL"
},
"recipient": {
"document": {
"value": "12346789000",
"type": "CPF"
},
"name": "string",
"status": "APPROVED",
"account": {
"branch": "00001",
"number": "1234",
"balance": {
"value": 0,
"currency": "BRL"
},
"status": "ACTIVE",
"bank": {
"ispb": "12345678"
}
}
},
"channel": {
"end2EndId": "c518e3b7-196d-473e-a26e-f17723cf5690",
"name": "SPI",
"sender": {
"document": {
"value": "12346781234",
"type": "CPF"
},
"name": "string",
"status": "APPROVED",
"account": {
"branch": "0001",
"number": "123456",
"bank": {
"ispb": "12345678",
"code": "123",
"name": "Test Bank"
}
}
}
},
"receiverReconciliationId": "560ef98b-a9f2-4f09-9b40-242f73bc00c7",
"pixInitializationType": "string",
"pixPaymentPriority": "string",
"pixPaymentPriorityType": "string",
"pixPaymentPurpose": "string"
}
}
]
[
{
"entityId": "ac833e56-aae4-4db7-a181-f6be343e3b49",
"companyKey": "ACESSO",
"idempotencyKey": "e7d58dbc-fd76-4330-bdd7-906e4a0bb9e1",
"context": "Pix",
"name": "PIX_REFUND_WAS_RECEIVED",
"timestamp": "2021-12-03T10:53:07.5872852Z",
"correlationId": "d386aee5-c0da-43ee-87dc-b3ee947172cf",
"metadata": null,
"data": {
"authenticationCode": "ac833e56-aae4-4db7-a181-f6be343e3b49",
"amount": {
"value": 0.25,
"currency": "BRL"
},
"recipient": {
"document": {
"value": "00000000000",
"type": "CPF"
},
"type": "Customer",
"account": {
"branch": "0001",
"number": "111111111",
"type": "Checking",
"bank": {
"ispb": "13140088"
}
}
},
"channel": {
"end2EndIdOriginal": "E1314008820211203105231257961793",
"refundReason": "BANK_RETURN",
"errorCode": "MD06",
"errorReason": "",
"name": "SPI",
"sender": {
"document": {
"value": "12345678900",
"type": "CPF"
},
"type": "Customer",
"name": "string",
"account": {
"branch": "0001",
"number": "22631530",
"type": "Checking",
"bank": {
"ispb": "00000000"
}
}
},
"end2EndId": "D18236120202112031052s0056352CWL"
},
"createdAt": "2021-12-03T10:53:06.6893633Z"
}
}
]
[
{
"entityId": "ac833e56-aae4-4db7-a181-f6be343e3b49",
"companyKey": "ACESSO",
"idempotencyKey": "fc8cebd1-d1fa-4b4b-ac31-680e01cb206b",
"context": "Pix",
"name": "PIX_REFUND_WAS_CLEARED",
"timestamp": "2021-12-03T10:53:08.1980309Z",
"correlationId": "d386aee5-c0da-43ee-87dc-b3ee947172cf",
"metadata": null,
"data": {
"authenticationCode": "ac833e56-aae4-4db7-a181-f6be343e3b49",
"amount": {
"value": 0.25,
"currency": "BRL"
},
"recipient": {
"document": {
"value": "12345678900",
"type": "CPF"
},
"type": "Customer",
"account": {
"branch": "0001",
"number": "11111111",
"type": "Checking",
"bank": {
"ispb": "13140088"
}
}
},
"channel": {
"end2EndIdOriginal": "E1314008820211203105231257961793",
"refundReason": "BANK_RETURN",
"errorCode": "MD06",
"errorReason": "",
"name": "SPI",
"sender": {
"document": {
"value": "1234567999",
"type": "CPF"
},
"type": "Customer",
"name": "string",
"account": {
"branch": "0000",
"number": "1234567",
"type": "Checking",
"bank": {
"ispb": "00000000"
}
}
},
"end2EndId": "D18236120202112031052s0056352CWL"
},
"createdAt": "2021-12-03T10:53:06.6893633Z"
}
}
]
{
"entityId": "38d841f5-35a4-4297-b2db-f94e2664e74b",
"companyKey": "Acesso",
"idempotencyKey": "873b6c8d-af27-46ec-a4ab-02f836b6f1fc",
"context": "Pix",
"name": "PIX_CASHOUT_WAS_COMPLETED",
"timestamp": "2022-02-09T19:36:18.1299919Z",
"correlationId": "38d841f5-35a4-4297-b2db-f94e2674e74b",
"metadata": {
"RequestedAt": 1644435378
},
"data": {
"authenticationCode": "38d841f5-35a4-4297-b2db-f94e2664e74b",
"amount": {
"value": 328.4,
"currency": "BRL"
},
"description": "c3ee8cc4-f88f-4b65-988f-87bd96142cb4",
"sender": {
"document": {
"value": "12345678900123",
"type": "CNPJ"
},
"type": "Business",
"name": "SenderName",
"account": {
"branch": "0001",
"number": "1234567",
"type": "Checking",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
}
},
"channel": {
"name": "SPI",
"destination": {
"document": {
"value": "12345678900",
"type": "CPF"
},
"type": "Customer",
"name": "Peter Parker",
"account": {
"branch": "7293",
"number": "654321",
"type": "Checking",
"bank": {
"ispb": "00000000",
"code": "000",
"name": "BankName"
}
}
},
"endToEndId": "E1314008820220209193614764471951",
"initializationType": "Manual",
"paymentPurpose": "PurchaseOrTransfer",
"paymentPriority": "Priority",
"paymentPriorityType": "Priority",
"isPixOpenBanking": false,
"isInternal": false
},
"paymentDate": "2022-02-09T19:36:14.140084Z",
"isRefund": false
}
}
{
"entityId": "90b9c655-74db-415a-9a51-69289442ec98",
"companyKey": "Acesso",
"idempotencyKey": "d0811671-00e3-4c3a-880d-029aab311b5a",
"context": "Pix",
"name": "PIX_CASHOUT_WAS_CANCELED",
"timestamp": "2022-02-09T19:38:27.3457184Z",
"correlationId": "90b9c655-74db-415a-9a51-69289442ec98",
"metadata": {
"RequestedAt": 1644435507
},
"data": {
"authenticationCode": "90b9c655-74db-415a-9a51-692489442ec98",
"amount": {
"value": 305.35,
"currency": "BRL"
},
"description": "Despesas",
"sender": {
"document": {
"value": "80318509768",
"type": "Undefined"
},
"name": "Peter Parker",
"account": {
"branch": "0001",
"number": "12345678",
"type": "Payment",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
}
},
"channel": {
"name": "SPI",
"destination": {
"document": {
"value": "111112223344",
"type": "Undefined"
},
"name": "Carol Denvers",
"account": {
"branch": "1867",
"number": "12345666",
"type": "Checking",
"bank": {
"ispb": "00000000",
"code": "000",
"name": "BankName"
}
}
},
"initializationType": "Manual",
"paymentPurpose": "PurchaseOrTransfer",
"paymentPriority": "Priority",
"paymentPriorityType": "Priority",
"isPixOpenBanking": false,
"isInternal": false,
"refusalReason": "AC14-Pagamento rejeitado pelo PSP do recebedor"
},
"paymentDate": "2022-02-09T19:38:23.975911Z",
"isRefund": false
}
}
{
"entityId": "f50a4aef-68eb-4146-8dc2-24d75f1a012f",
"companyKey": "Acesso",
"idempotencyKey": "29bfdded-f24b-4c46-970f-994b40b679b3",
"context": "Pix",
"name": "PIX_CASHOUT_WAS_UNDONE",
"timestamp": "2022-02-09T19:40:08.3554947Z",
"correlationId": "f50a4aef-68eb-4146-8dc2-24d75f1a012f",
"metadata": {
"requestedAt": 1644435608
},
"data": {
"authenticationCode": "f50a4aef-68eb-4146-8dc2-24d75f1a012f",
"amount": {
"value": 305.35,
"currency": "BRL"
},
"description": "Despesas ",
"sender": {
"document": {
"value": "12345678900",
"type": "Undefined"
},
"name": "Peter Parker",
"account": {
"branch": "0001",
"number": "12345678",
"type": "Payment",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
}
}
},
"channel": {
"name": "SPI",
"destination": {
"document": {
"value": "00345678900",
"type": "Undefined"
},
"name": "Carol Denvers",
"account": {
"branch": "1867",
"number": "22222222",
"type": "Checking",
"bank": {
"ispb": "00000000",
"code": "000",
"name": "BankName"
}
}
},
"initializationType": "Manual",
"paymentPurpose": "PurchaseOrTransfer",
"paymentPriority": "Priority",
"paymentPriorityType": "Priority",
"isPixOpenBanking": false,
"isInternal": false,
"refusalReason": "AC14-Pagamento rejeitado pelo PSP do recebedor"
},
"paymentDate": "2022-02-09T19:40:05.3680743Z",
"isRefund": false
}
}
Importante
Para conhecer a estrutura básica dos eventos com os campos que chegarão à sua API, consulte nossa documentação específica de Eventos.
Objeto data nos eventos Pix
O objeto data traz detalhes específicos do contexto em que o evento ocorre. No caso de eventos Pix, esse objeto trará os seguintes campos:
amount: objeto contendo o valor da transação e a moeda utilizada;recipient: objeto contendo os dados do recebedor, como nome, documento, status e dados de sua conta;channel: objeto contendo os dados do canal de pagamento, além da identificação da transação e dos dados do pagador:name: nome do canal de pagamento que, no caso do Pix, é SPI;sender: objeto contendo os dados do pagador, como nome, documento, status e dados de sua conta;
end2EndId: identificador único dessa transação Pix;receiverReconciliationId: em caso de pagamentos com QR Code, esse campo retornará o ID de conciliação, que é uma informação utilizada para conciliação dos pagamentos;pixInitializationType: o modo pelo qual a transação ocorreu ("key", "staticQrCode", "dynamicQrCode" ou "manual");pixPaymentPriority: prioridade de pagamento (que pode ser “Priority” e “NonPriority”);pixPaymentPriorityType: tipo de prioridade de pagamento (que pode ser: “Priority”, “AntifraudAnalysis” e “ScheduledPayment”);PixPaymentPurpose: razão do pagamento Pix. Exemplo: "PurchaseOrTransfer".
Em casos de devolução Pix, o data também trará os seguintes dados:
End2EndIdOriginal: informa o endToEndId da transação de Pix cash-out inicial;RefundReason: descreve o motivo da devolução do valor;ErrorCodeeErrorReason: esses campos trazem os códigos e os motivos da devolução, que podem ser:- BE08: devolução de pagamento instantâneo devido a erro do PSP;
- FR01: devolução de pagamento motivada por fundada suspeita de fraude;
- MD06: devolução de pagamento instantâneo solicitada pelo usuário recebedor pagamento original;
- SL02: devolução motivada por um erro relacionado ao saque Pix.
Updated 12 months ago