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:

ParametersDescriptionTypeComments
PaymentOrderIdPayment order identificationLONG (NUMBER)None
PaymentOrderStatusOperation statusSTRING (TEXT)None
TaxNumberCPF or CNPJ of the account issuing the payment orderSTRING (TEXT)None
PaymentDateDate of operation's paymentSTRING (TEXT)None
ReceiptUrlTransaction voucher URLSTRING (TEXT)None
IdentifierExternal identifier applied by the customer in the emissionSTRING (TEXT)None
MethodAPI MethodSTRING (TEXT)None
BusinessUnitIdBusiness Unit ID Provided by FitbankLONG (NUMBER)None
ReasonCodeReason for canceling the payment orderSTRING (TEXT)If the payment order is not canceled it will appear as null
EndToEndIdUnique external operation identifierSTRING (TEXT)None
SubReasonCodeDetail about the reason for canceling the payment orderSTRING (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:

StatusTypeDescription
0CreatedPayment Order was Created
2SettledPayment concluded either by PIX or TED
3CanceledEXC0023 - Beneficiary Diverges From PIX Key Owner.
EXC0024 - Consult PixKey Error.
EXC0025 - Beneficiary failed KYC process.
EXC0033 - Beneficiary requires qualification process.
4RegisteredPayment order was registered after transaction validations
6ErrorProcess failed

ReasonCode + SubReasonCode

ReasonCodeSubReasonCode
EXC0023 - Beneficiary Diverges From PIX Key OwnerNULL
EXC0024 - Consult PixKey ErrorEXCP002 - NotFound
EXCP004 - InvalidFormat
EXCP005 -Error
EXCP006 - InternalError
EXC0025 - Beneficiary failed KYC processEXCB0001 - Beneficiary appears on OFAC’s sanction list
EXCB0002 - Beneficiary appears on UN’s sanction list
EXCB0003 - Beneficiary appears on FitBank's internal block 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
EXCB0006 - Identified that the Beneficiary is on the internal list
EXC0026 - Payment Order failed Risk processNULL
EXC0028 - Payment Order process failedEXC0001 - 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.

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
}
ParametersDescriptionTypeComments
MethodAPI MethodSTRING (TEXT)None
BusinessUnitIdBusiness Unit ID Provided by FitbankLONG (NUMBER)None
BeneficiaryBeneficiary's InformationENTITYNone
NameBeneficiary's nameSTRING (TEXT)None
StatusBeneficiary Status IndicationLONG (NUMBER)Created = 0
Pending = 1
Approved = 2
Denied = 3
TaxNumberUser's Social Security Number (CPF or CNPJ)STRING (TEXT)None
PhoneBeneficiary's phoneSTRING (TEXT)None
MailBeneficiary's mailSTRING (TEXT)None
DescriptionBeneficiary's reason for denialSTRING (TEXT)If the Beneficiary is not Denied it will appear as null
QualifiedIs or is not a qualified personBOOLEANNone
MessageDefault message asking for Beneficiary DataSTRING (TEXT)If the Beneficiary is not Qualified it will appear as null
DataRequiredListResquested Data ListSTRING (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
}
ParametersDescriptionTypeComments
MessageNotification about any generated payment order that exceeds the configured maximum amountSTRING (TEXT)None
DocumentNumberIdOperation identifier generated after the successfull emissionLONG (NUMBER)None
BeneficiaryNameBeneficiary's nameSTRING (TEXT)None
BeneficiaryTaxNumberBeneficiary's CPF or CNPJLONG (NUMBER)None
MethodAPI MethodSTRING (TEXT)None
BusinessUnitIdBusiness Unit ID Provided by FitbankLONG (NUMBER)None

Response Webhook

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

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