5 - Webhooks

Payment Order Webhook - UpdatePaymentOrderStatus

This webhook notifies the Payment Order Status.

{
  "PaymentOrder": {
    "PaymentOrderId": 15273,
    "PaymentOrderStatus": "Created",
    "TaxNumber": "43071723024",
    "PaymentDate": "2024-01-18T00:00:00",
    "PartnerId": 1057,
    "ReceiptUrl": "",
    "Identifier": "1a1560db-86af-4d41-9cb6-5a22dc43078c",
    "ReasonCode": null,
    "EndToEndId": null,
    "SubReasonCode": null
  },
  "Method": "UpdatePaymentOrderStatus",
  "BusinessUnitId": 1642
}

{
  "PaymentOrder": {
    "PaymentOrderId": 15273,
    "PaymentOrderStatus": "Registered",
    "TaxNumber": "43071723024",
    "PaymentDate": "2024-01-18T00:00:00",
    "PartnerId": 1057,
    "ReceiptUrl": "",
    "Identifier": "1a1560db-86af-4d41-9cb6-5a22dc43078c",
    "ReasonCode": null,
    "EndToEndId": null,
    "SubReasonCode": null
  },
  "Method": "UpdatePaymentOrderStatus",
  "BusinessUnitId": 1642
}

{
  "PaymentOrder": {
    "PaymentOrderId": 15273,
    "PaymentOrderStatus": "Settled",
    "TaxNumber": "43071723024",
    "PaymentDate": "2024-01-18T00:00:00",
    "PartnerId": 1057,
    "ReceiptUrl": "https://sandboxreceipt.fitbank.com.br/receipt/2024-01-18/lekuizmi.pdf",
    "Identifier": "1a1560db-86af-4d41-9cb6-5a22dc43078c",
    "ReasonCode": null,
    "EndToEndId": "E673417123241719767656176378168",
    "SubReasonCode": null
  },
  "Method": "UpdatePaymentOrderStatus",
  "BusinessUnitId": 1642
}

{
  "PaymentOrder": {
    "PaymentOrderId": 15274,
    "PaymentOrderStatus": "Canceled",
    "TaxNumber": "43071723024",
    "PaymentDate": "2024-01-18T00:00:00",
    "PartnerId": 1057,
    "ReceiptUrl": "",
    "Identifier": "ee6439ed-fd80-40d5-915b-106812c9d6bc",
    "ReasonCode": "EXC0026 - Payment Order failed Risk process",
    "EndToEndId": null,
    "SubReasonCode": null
  },
  "Method": "UpdatePaymentOrderStatus",
  "BusinessUnitId": 1642
}

{
  "PaymentOrder": {
    "PaymentOrderId": 277,
    "PaymentOrderStatus": "Error",
    "TaxNumber": "20282702091",
    "PaymentDate": "2022-06-06T00:00:00",
    "PartnerId": 30749,
    "ReceiptUrl": "",
    "Identifier": "7a8b29f5-e73d-4393-b028-62c185e7d9a-00047",
    "ReasonCode": null,
    "EndToEndId": null,
    "SubReasonCode": null	
	},
	"Method": "UpdatePaymentOrderStatus",
	"BusinessUnitId": 61799
}

Description:

Parameters	Description	Type	Comments
PaymentOrderId	Payment order identification	LONG (NUMBER)	None
PaymentOrderStatus	Operation status	STRING (TEXT)	None
TaxNumber	CPF or CNPJ of the account issuing the payment order	STRING (TEXT)	None
PaymentDate	Date of operation's payment	STRING (TEXT)	None
ReceiptUrl	Transaction voucher URL	STRING (TEXT)	None
Identifier	External identifier applied by the customer in the emission	STRING (TEXT)	None
Method	API Method	STRING (TEXT)	None
BusinessUnitId	Business Unit ID Provided by Fitbank	LONG (NUMBER)	None
ReasonCode	Reason for canceling the payment order	STRING (TEXT)	If the payment order is not canceled it will appear as null
EndToEndId	Unique external operation identifier	STRING (TEXT)	None
SubReasonCode	Detail about the reason for canceling the payment order	STRING (TEXT)	If the payment order is not canceled it will appear as null

Status

Upon receiving the Payment Order, the customer is then notified as to its status:

Status	Type	Description
0	Created	Payment Order was Created
2	Settled	Payment concluded either by PIX or TED
3	Canceled	EXC0023 - Beneficiary Diverges From PIX Key Owner. EXC0024 - Consult PixKey Error. EXC0025 - Beneficiary failed KYC process. EXC0033 - Beneficiary requires qualification process.
4	Registered	Payment order was registered after transaction validations
6	Error	Process failed

ReasonCode + SubReasonCode

ReasonCode	SubReasonCode
EXC0023 - Beneficiary Diverges From PIX Key Owner	NULL
EXC0024 - Consult PixKey Error	NULL
EXC0025 - Beneficiary failed KYC process	EXCB0001 - Beneficiary appears on OFAC’s sanction list EXCB0002 - Beneficiary appears on UN’s sanction list EXCB0004 - Situation with data inconsistency that does not allow to claim that the hit is false. More identification information related to the beneficiary is needed EXCB0005 - The beneficiary is sanctioned INF0002 - Identified that the Beneficiary is on the internal list
EXC0026 - Payment Order failed Risk process	NULL
EXC0028 - Payment Order process failed	EXC0001 - Occurrence with Type {0} not found.. OCR0001 - Insufficient balance to pay the transaction and/or fees. OCR0002 - Transaction canceled by the Institution. OCR0003 - Transaction canceled by user request. SPI0001 - An error occurred while processing the PIX transaction. SPI0002 - Transaction settlement interrupted due to SPI timeout. SPI0003 - Transaction interrupted due to an error on the receiving user's participant. SPI0004 - PIX transaction sender timeout. SPI0005 - Invalid/non-existent agency and/or account number of the receiving user. SPI0006 - Blocked payee account. SPI0007 - Receiving user's account is closed. SPI0008 - Incorrect type for the receiving user's transactional account. SPI0009 - The transaction type is not supported/authorized in the receiving user's account. SPI0010 - Transaction with this Processing Type is not allowed. SPI0011 - Returning an instant payment is not allowed. SPI0012 - The direct participant is not settling the paying user. SPI0013 - PIX transaction with zero value is not allowed. SPI0014 - Money Order/Return Exceeds Allowed Limit for Account Type. SPI0015 - Insufficient balance in the paying user's PI account. SPI0017 - Divergence between the sum of block values. SPI0018 - Invalid number of transactions. SPI0019 - CPF/CNPJ of the recipient differs from the Account holder's data. SPI0020 - Unauthorized PIX transaction initiator. SPI0022 - Incorrect receiving user's CPF/CNPJ. SPI0023 - Incorrect or incompatible message content. SPI0024 - Transaction rejected by receiving user participant. SPI0025 - Participant who signed the message is not authorized. SPI0026 - Transaction rejected due to time exceeded between messages. SPI0027 - The participant is not registered or has not yet started the operation in the SPI. SPI0028 - Invalid message sending date and time. SPI0029 - The transaction exceeds the maximum time limit for returning a PIX transaction. SPI0030 - Inconsistency between transaction purpose and message. SPI0032 - ISPB of the participant facilitating service PIX Withdrawal or PIX Exchange non-existent. SPI0033 - Invalid or non-existent Paying Participant ISPB. SPI0034 - Invalid or non-existent receiving participant's ISPB. SPI0035 - Transaction rejected because paying user is sanctioned.
EXC0054 - Operating Limit Exceeded	NULL

Beneficiary Webhook - UpdateBeneficiaryStatus

This webhook notifies the Beneficiary Status.

{
  "Beneficiary": {
  "Name": "João Victor Montenegro Rocha 00042",
  "Status": "Denied",
  "TaxNumber": "20282702091",
  "Phone": "+5585997784745",
  "Mail": "[email protected]",
  "Description": "Is a qualified person",
  "QualifiedBeneficiary": {
  "Qualified": true,
    "Message": "Please, in the next requisition with this beneficiary, inform these data:",
    "DataRequiredList": [
      "BirthDate",
      "AccountInfo",
      "Country"
      ]
    }
	},
  "Method": "UpdateBeneficiaryStatus",
  "BusinessUnitId": 61799
}

{
  "Beneficiary": {
  "Name": "João Victor Montenegro Rocha 00042",
  "Status": "Approved",
  "TaxNumber": "20282702091",
  "Phone": "+5585997784745",
  "Mail": "[email protected]",
  "Description": null,
  "QualifiedBeneficiary": {
  "Qualified": false,
    "Message": null,
    "DataRequiredList": []
    }
	},
  "Method": "UpdateBeneficiaryStatus",
  "BusinessUnitId": 61799
}

{
  "Beneficiary": {
  "Name": "João Victor Montenegro Rocha 00042",
  "Status": "Pending",
  "TaxNumber": "20282702091",
  "Phone": "+5585997784745",
  "Mail": "[email protected]",
  "Description": null,
  "QualifiedBeneficiary": {
  "Qualified": false,
    "Message": null,
    "DataRequiredList": []
    }
	},
  "Method": "UpdateBeneficiaryStatus",
  "BusinessUnitId": 61799
}

{
  "Beneficiary": {
  "Name": "João Victor Montenegro Rocha 00042",
  "Status": "Created",
  "TaxNumber": "20282702091",
  "Phone": "+5585997784745",
  "Mail": "[email protected]",
  "Description": null,
  "QualifiedBeneficiary": {
  "Qualified": false,
    "Message": null,
    "DataRequiredList": []
    }
	},
  "Method": "UpdateBeneficiaryStatus",
  "BusinessUnitId": 61799
}

Parameters	Description	Type	Comments
Method	API Method	STRING (TEXT)	None
BusinessUnitId	Business Unit ID Provided by Fitbank	LONG (NUMBER)	None
Beneficiary	Beneficiary's Information	ENTITY	None
Name	Beneficiary's name	STRING (TEXT)	None
Status	Beneficiary Status Indication	LONG (NUMBER)	Created = 0 Pending = 1 Approved = 2 Denied = 3
TaxNumber	User's Social Security Number (CPF or CNPJ)	STRING (TEXT)	None
Phone	Beneficiary's phone	STRING (TEXT)	None
Mail	Beneficiary's mail	STRING (TEXT)	None
Description	Beneficiary's reason for denial	STRING (TEXT)	If the Beneficiary is not Denied it will appear as null
Qualified	Is or is not a qualified person	BOOLEAN	None
Message	Default message asking for Beneficiary Data	STRING (TEXT)	If the Beneficiary is not Qualified it will appear as null
DataRequiredList	Resquested Data List	STRING (TEXT)	If the Beneficiary is not Qualified it will appear as null

Maximum amount for payment reached - UpdateLimitPaymentOrder

This webhook notifies payment orders with amounts above normal

{
  "Message": "There was a payment order exceeding the parameterized value limit of 'R$1000,00'",
  "DocumentNumberId": 79,
  "BeneficiaryName": "joao beneficiary",
  "BeneficiaryTaxNumber": "74311850069",
  "Method": "UpdateLimitPaymentOrder",
  "BusinessUnitId": 61799
}

Parameters	Description	Type	Comments
Message	Notification about any generated payment order that exceeds the configured maximum amount	STRING (TEXT)	None
DocumentNumberId	Operation identifier generated after the successfull emission	LONG (NUMBER)	None
BeneficiaryName	Beneficiary's name	STRING (TEXT)	None
BeneficiaryTaxNumber	Beneficiary's CPF or CNPJ	LONG (NUMBER)	None
Method	API Method	STRING (TEXT)	None
BusinessUnitId	Business Unit ID Provided by Fitbank	LONG (NUMBER)	None

Response Webhook

To confirm receipt of the webhook, return us the following json:

{
"Success": true,
"Message": "Operation successfully completed."
}