Modelos de webhooks do Participante Indireto Pix
Confirmação de Recebimentos
Webhooks de confirmações para transações de recebimento como:
- Recebimento por Chave Pix (DICT);
- Recebimento por dados bancários (MANUAL);
- Recebimento por QR Code estático; e
- Recebimento por QR Code dinâmico de cobrança imediata ou cobrança com vencimento.
Para realizar a configuração de um webhook é necessário realizar o cadastro via API, seguindo a documentação disponível em https://developers.celcoin.com.br/docs/celbricks-cadastrar-e-gerenciar-webhooks
Antes de tudo é preciso explicar o significado de PSP, que significa Provedor de Serviço de Pagamento. Em uma operação de transferência via Pix, sempre haverá dois PSPs: o recebedor e o pagador. O PSP do recebedor é a instituição financeira responsável pela conta do destinatário. Já o PSP do pagador é a instituição financeira de origem dos recursos, ou seja, de onde o dinheiro é transferido.
Após o PSP recebedor (Celcoin) aprovar o recebimento, você será notificado via webhook sobre a confirmação de sua transação de recebimento através dos modelos abaixo.
O campo PersonType informa se o crédito ou débito está sendo para um CPF ou CNPJ.
"NATURAL_PERSON" - Pessoa fisica
"LEGAL_PERSON" - Pessoa juridica
IMPORTANTE: O campo EndToEndId é único para cada recebimento e, portanto, deve ser validado se já existe no sistema, para evitar duplicidade de recebimento.
É muito importante realizar a validação entre o valor da cobrança e o valor informado no campo "Amount" do webhook de recebimento, com intuito de conciliar o montante esperado com o que efetivamente foi pago e evitar possíveis prejuízos
Recebimento por Chave Pix (DICT)
{
"RequestBody": {
"DebitParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"AccountType": "TRAN",
"Name": "string"
},
"TransactionTypePix": "TRANSFER",
"TransactionType": "RECEIVEPIX",
"Tenant": "string",
"withdrawalAgentMode": "AGTEC",
"Amount": decimal,
"CreditParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"createTimestamp": "05/15/2024 11:30:58",
"AccountType": "TRAN",
"Name": "string",
"Key": "string"
},
"PaymentType": "IMMEDIATE",
"InitiationType": "DICT",
"Urgency": "HIGH",
"EndToEndId": "string",
"TransactionId": bigInt/long
}
}
Recebimento por dados bancários (MANUAL)
{
"RequestBody": {
"DebitParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"AccountType": "TRAN",
"Name": "string"
},
"TransactionTypePix": "TRANSFER",
"TransactionType": "RECEIVEPIX",
"Tenant": "string",
"withdrawalAgentMode": "AGTEC",
"Amount": decimal,
"CreditParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"createTimestamp": "05/15/2024 11:30:58",
"AccountType": "TRAN",
"Name": "string"
},
"PaymentType": "IMMEDIATE",
"InitiationType": "MANUAL",
"Urgency": "HIGH",
"EndToEndId": "string",
"TransactionId": bigInt/long
}
}
Neste modelo, o campo creditParty.key somente estará presente quando a modalidade de pagamento for iniciada com uma consulta ao DICT. Recebimentos iniciados por preenchimento de dados bancários não possuem chave Pix. Esta requisição deve ser respondida apenas com um HTTP status 200.
Recebimento por QR Code estático
{
"RequestBody": {
"DebitParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"AccountType": "TRAN",
"Name": "string"
},
"TransactionTypePix": "TRANSFER",
"TransactionType": "RECEIVEPIX",
"Tenant": "string",
"withdrawalAgentMode": "AGTEC",
"Amount": decimal,
"CreditParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"createTimestamp": "05/15/2024 11:30:58",
"AccountType": "TRAN",
"Name": "string",
"Key": "string"
},
"PaymentType": "IMMEDIATE",
"InitiationType": "STATIC_QRCODE",
"Urgency": "HIGH",
"EndToEndId": "string",
"TransactionId": bigInt/long
}
}
Recebimento por QR Code dinâmico de cobrança imediata ou cobrança com vencimento
Contempla modelos de QR Codes gerados pelos endpoints:
/pix-indirect/v1/pix/v1/brcode/dynamic;
pix-indirect/v1/location + /pix-indirect/v1/pix/v1/collection/immediate
pix/v1/location + /pix-indirect/v1/pix/v1/collection/duedate;
{
"RequestBody": {
"DebitParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"AccountType": "TRAN",
"Name": "string"
},
"TransactionTypePix": "TRANSFER",
"TransactionType": "RECEIVEPIX",
"createTimestamp": "05/15/2024 11:30:58",
"Tenant": "string",
"withdrawalAgentMode": "AGTEC",
"Amount": decimal,
"CreditParty": {
"Account": "string",
"Bank": "string",
"Branch": "string",
"PersonType": "NATURAL_PERSON",
"TaxId": "string",
"AccountType": "TRAN",
"Name": "string",
"Key": "string"
},
"PaymentType": "IMMEDIATE",
"transactionIdentification": "string",
"transactionIdBRCode": "string",
"InitiationType": "DYNAMIC_QRCODE",
"Urgency": "HIGH",
"EndToEndId": "string",
"TransactionId": bigInt/long
}
}
Neste modelo, o campo TransactionId traz a informação do identificador transacional do recebimento. Ele não tem relação com o QR Code gerado. O campo transactionIdentification é o mesmo informado no resultado da criação do QR Code e o campo transactionIdBRCode traz o mesmo transactionId associado ao QR Code gerado. Esta requisição deve ser respondida apenas com um HTTP status 200.
Atenção para os significados dos campos a seguir.
InitiationType - Tipo de iniciação do pagamento:
- MANUAL: Pagamento via dados transacionais da conta (transactionIdentification, e transactionIdBRCode não serão enviados)
- DICT: Pagamento via chave. (transactionIdentification, e transactionIdBRCode não serão enviados)
- STATIC_QRCODE: Pagamento via QR Code estático. (transactionIdentification, e transactionIdBRCode serão enviados)
- DYNAMIC_QRCODE: Pagamento via QR Code dinâmico. (transactionIdentification, e transactionIdBRCode serão enviados)
TransactionTypePix - Tipo da transação Pix:
- TRANSFER: Usado para transferências ou pagamentos comuns (default);
- CHANGE: Usado para Pix Troco;
- WITHDRAWAL: Usado para Pix Saque
PaymentType - Tipo de pagamento:
- IMMEDIATE: Usado para pagamentos imediatos (default);
- FRAUD: Usado para pagamento por suspeita de fraude;
- SCHEDULED: Usado apenas para pagamentos agendados.
Urgency - Determina a urgência do pagamento:
- HIGH: usado para pagamentos imediatos (default);
- NORMAL: usado para pagamentos agendados.
Confirmação de pagamento
Contempla webhooks de confirmações para transações de pagamento como:
- Pagamento por dados bancários;
- Pagamento por chave Pix;
- Pagamento por leitura de QR Code estático;
- Pagamento por leitura de QR Code dinâmico de cobrança imediata ou cobrança com vencimento;
Após o PSP recebedor aprovar o recebimento (banco de destino), você será notificado via webhook sobre a confirmação de sua transação de pagamento através do modelo abaixo.
Para pagamentos bem sucedidos
{
"RequestBody": {
"TransactionTypePix": "TRANSFER",
"TransactionType": "PAYMENT",
"Tenant": "string",
"ClientCode": "string",
"PaymentType": "IMMEDIATE",
"InitiationType": "MANUAL",
"Urgency": "HIGH",
"StatusCode": {
"Description": "string",
"StatusId": int
},
"EndToEndId": "string",
"TransactionId": bigInt/long
}
}
Neste modelo, o campo TransactionId é o mesmo informado no resultado da requisição de pagamento do endpoint payment. Esta requisição deve ser respondida apenas com um HTTP status 200.
Para pagamentos que tenham algum erro após a requisição
{
"RequestBody": {
"TransactionTypePix": "TRANSFER",
"TransactionType": "PAYMENT",
"Tenant": "string",
"ClientCode": "string",
"Error": {
"Description": "string",
"Code": "string"
},
"PaymentType": "IMMEDIATE",
"InitiationType": "MANUAL",
"Urgency": "HIGH",
"StatusCode": {
"Description": "string",
"StatusId": int
},
"EndToEndId": "string",
"TransactionId": bigInt/long
}
}
Neste modelo, o campo TransactionId é o mesmo informado no resultado da requisição de pagamento do endpoint payment. Esta requisição deve ser respondida apenas com um HTTP status 200.
Caso você queira simular o pagamento rejeitado recebendo o gatilho PAYMENT com status diferente de 2, basta alterar o payload alterando o atributo "txid": "85290472061" .
Confirmação de devolução de recebimento
Ocorre quando realizamos uma devolução para a origem de um recebimento. Após o PSP recebedor aprovar o recebimento (banco de destino), você será notificado via webhook sobre a confirmação de sua transação de devolução através do modelo abaixo.
POST https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/reverse/{transactionId}
Para devolução bem sucedida (v1)
{
"RequestBody": {
"AdditionalInformation": "string",
"TransactionType": "REVERTPIX",
"ReturnIdentification": "string",
"OriginalEndToEndId": "string",
"Tenant": "string",
"Amount": decimal,
"ClientCode": "string",
"StatusCode": {
"Description": "string",
"StatusId": int
},
"Reason": "string",
"TransactionId": bigInt/long
}
}
Neste modelo, o campo TransactionId é o mesmo informado no resultado da requisição de pagamento do endpoint payment. Esta requisição deve ser respondida apenas com um HTTP status 200.
Para devolução que tenha algum erro após a requisição (v1)
{
"RequestBody": {
"AdditionalInformation": "string",
"TransactionType": "REVERTPIX",
"ReturnIdentification": "string",
"OriginalEndToEndId": "string",
"Tenant": "string",
"Amount": decimal,
"ClientCode": "string",
"StatusCode": {
"Description": "string",
"StatusId": int
},
"Reason": "string",
"TransactionId": int64/long,
"Error": {
"Code": "string",
"Description": "string"
}
}
}
Esta requisição deve ser respondida apenas com um HTTP status 200.
POST https://sandbox.openfinance.celcoin.dev/pix-indirect/v2/reverse/pi/{transactionId}
Para devolução bem sucedida (v2)
{
"RequestBody": {
"AdditionalInformation": "string",
"TransactionType": "REVERTPIX",
"ReturnIdentification": "string",
"OriginalEndToEndId": "string",
"Tenant": "string",
"Amount": decimal,
"ClientCode": "string",
"StatusCode": {
"Description": "string",
"StatusId": int
},
"Reason": "string",
"TransactionId": bigInt/long
}
}
Neste modelo, o campo TransactionId é o mesmo informado no resultado da requisição de pagamento do endpoint payment. Esta requisição deve ser respondida apenas com um HTTP status 200.
Para devolução que tenham algum erro após a requisição (v2)
{
"RequestBody": {
"AdditionalInformation": "string",
"TransactionType": "REVERTPIX",
"ReturnIdentification": "string",
"OriginalEndToEndId": "string",
"Tenant": "string",
"Amount": decimal,
"ClientCode": "string",
"StatusCode": {
"Description": "string",
"StatusId": int
},
"Reason": "string",
"TransactionId": bigInt/long,
"Error": {
"Code": "string",
"Description": "string"
}
}
}
Esta requisição deve ser respondida apenas com um HTTP status 200.
Confirmação recebimento de devoluções.
Ocorre quando recebemos de volta o valor de um pagamento que realizamos. Após o PSP recebedor aprovar o recebimento (Celcoin), você será a notificação via webhook sobre a confirmação de sua transação de recebimento de devolução através do modelo abaixo.
Para recebimento de devolução
{
"RequestBody": {
"TransactionType": "REVERTED",
"ReturnIdentification": "string",
"createTimestamp": "05/15/2024 11:30:58",
"TransactionIdPayment": int64/long,
"OriginalEndToEndId": "string",
"Tenant": "string",
"Amount": decimal,
"ClientCode": "string",
"Reason": "string",
"TransactionId": bigInt/long
}
}
Neste modelo, o campo TransactionId é referente a identificação da transação de devolução que está sendo recebida. O campo TransactionIdPayment é o identificador de referência ao pagamento que foi realizado e está sendo devolvido.
Webhooks sobre ações do Mecanismo Especial de Devoluções (MED)
{
"analysisResult": "TOTALLY_ACCEPTED",
"id": "23e51565-a66a-43bb-a266-6a40f3562f71",
"refundAmount": "50.0000",
"refundDetails": "Suspeita de Fraude",
"refundReason": "FRAUD",
"status": "OPEN",
"contestedParticipant": "13935893",
"requestingParticipant": "20757199",
"creationTime": "09/27/2023 18:40:45",
"lastModified": "09/27/2023 18:40:45",
"transactionId": null,
"correlationId": null,
"responseTime": "09/27/2023 18:40:45",
"analysisDetails": null,
"infractionReportId": "9d3c314f-4825-4180-a6f6-f50180c91143",
"refundTransactionId": null
}
}
Webhooks sobre ações relacionadas às Infractions
{
"pactualId":"1d2ec316-45cd-4447-afc6-bb8085435b0a",
"clientRequestId":"50f7d6f9-e681-4acc-af66-d019dde5574e",
"createTimestamp":"2024-05-13T20:36:18.530Z",
"lastUpdateTimestamp":"2024-05-13T20:36:18.530Z",
"entity":"DictClaim",
"status":"CANCELLED",
"body":{
"lastUpdateTimestamp":"2024-04-02T01:04:45.087",
"pactualId":"3bf93161-f5ab-4006-9dc6-a37edd0adf9d",
"clientRequestId":"513645019",
"body":{
"infractionType":"REFUND_REQUEST",
"creationTime":"2024-05-13T14:38:01.117",
"reportDetails":"Cliente alega golpe, \n\nPossui saldo em conta? ",
"responseTime":"2024-04-02T01:04:45.087",
"analysisResult":"DISAGREED",
"endToEndId":"E139358932024040204047bBw4LL13uS",
"reportedBy":"DEBITED_PARTICIPANT",
"infractionData":{
"taxIdNumber":"52201341000129",
"infractingAccountData":{
"accountNumber":"19270007357",
"branch":1
},
"debitedParticipant":"13935893",
"reportedBy":"DEBITED_PARTICIPANT",
"transactionDate":"2024-04-02T01:04:43.62",
"creditedParticipant":"13203354",
"key":"df3a7baf-1e9f-4e43-90c9-3fd3cf5ab8bc"
},
"transactionId":"E139358932024040204047bBw4LL13uS",
"creditedParticipant":"13203354",
"transactionType":"TRANSFER",
"id":"82e5d3d6-cd0c-427b-8b78-32c9dc3abb9c",
"debitedParticipant":"13935893",
"lastModified":"2024-05-14T06:03:18.467",
"status":"CLOSED"
},
"entity":"InfractionReport",
"transactionId":2193359172,
"createTimestamp":"2024-04-02T01:04:43.62",
"status":"CLOSED"
}
}
Webhooks sobre ações de reivindicações de Chave Pix
{
"pactualId":"1d2ec316-45cd-4447-afc6-bb8085435b0a",
"clientRequestId":"50f7d6f9-e681-4acc-af66-d019dde5574e",
"createTimestamp":"2024-05-13T20:36:18.530Z",
"lastUpdateTimestamp":"2024-05-13T20:36:18.530Z",
"entity":"DictClaim",
"status":"CANCELLED",
"body":{
"status":"CANCELLED",
"claimer":{
"Name":"Rebeca Monteiro de Oliveira Barros",
"TradeName":null,
"TaxIdNumber":"51077460805",
"Type":"NATURAL_PERSON"
},
"claimerAccount":{
"Branch":"1",
"AccountNumber":"66470370189",
"AccountType":"TRAN",
"Participant":"10573521",
"OpeningDate":"2021-11-15T13:31:46.000Z"
},
"keyType":"CPF",
"resolutionPeriodEnd":"2024-05-13T20:36:00.000Z",
"confirmReason":null,
"completionPeriodEnd":null,
"donorParticipant":"13935893",
"lastModified":"2024-05-13T20:36:18.530Z",
"type":"PORTABILITY",
"cancelReason":"DEFAULT_OPERATION",
"id":"ee8db557-ea28-454b-b21d-f15265d48d59",
"key":"51077460805"
}
}
Para maiores informações da configuração dos webhooks, acesse o link abaixo:
Updated 11 days ago