Documentação
DocumentaçãoAPIStatusSuporteFAQscelcoin.com

Modelos de webhooks do Pix

Suggest Edits

Confirmação de Recebimentos (RECEIVEPIX)

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 entrar em contato com a nossa equipe de suporte informando a URL de seu webhook, senha e usuário, no formato BASIC, desta forma eles irão realizar o cadastro em nossa plataforma, para que seja possível o envio dos gatilhos.

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

O campo createdTimestamp segue o padrão de formato "MM/DD/YYYY hh:mm:ss" e é fornecido no fuso horário brasileiro (UTC -03:00).

🚧

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 (STATIC_QRCODE)

{
	"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"
		},
    "TransactionId": 1980712754,
    "TransactionIdBRrcode": 1980712753,
    "TransactionIdentification": "fe0486da-cd8d-4bbb-be9c-997c72d658bf",
		"PaymentType": "IMMEDIATE",
		"InitiationType": "STATIC_QRCODE",
		"Urgency": "HIGH",
		"EndToEndId": "string",
		"TransactionId": bigInt/long
	}
}

Recebimento por QR Code dinâmico de cobrança imediata ou com vencimento (DYNAMIC_QRCODE)

📘

Contempla modelos de QR Codes gerados pelos endpoints:
pix/v1/brcode/dynamic;
pix/v1/location + pix/v1/collection/immediate;
pix/v1/location + 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 (PAYMENT)

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 (REVERTPIX)

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.

1️⃣

POST https://sandbox.openfinance.celcoin.dev/pix/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.

2️⃣

POST https://sandbox.openfinance.celcoin.dev/pix/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 (REVERTED).

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.

Updated 9 days ago