During the debit transaction creation process, you can include a set of validations that the transaction must pass. If any validation fails, the entire transaction will be rejected.

Each validation consists of a key-value pair: the key specifies the type of validation, while the value defines the criteria or data to be validated.

Validation Structure

The validations are passed in the following format:

{
  "key": "KEY_NAME",
  "value": "VALUE"
}

• Key: Represents the validation type
• Value: Varies based on the validation and corresponds to the expected data or condition.

In the event of a validation failure, the transaction status will change to FAILED and will include the following information:

{
    "status": "FAILED",
    "reason": {
        "code": "VALIDATION_FAILED",
        "message": "Transaction failed due to validations failure.",
        "details": {
            "validations": [
                {
                    "key": "TAX_ID_MUST_MATCH",
                }
            ]
        }
    },
    "createdAt": "2024-09-06T23:32:08.824+0000"
}

Available Validations

The following validations can be applied during the transaction process:

Priority Mechanism

Our validation system includes a priority mechanism that ensures unnecessary validations are avoided when a prior validation has already failed. If one validation fails, subsequent validations will not be executed. This is particularly useful for avoiding unnecessary costs associated with expensive validations, such as checking if a tax ID is active.

Example:
Consider a transaction with two validations: TAX_ID_MUST_MATCH and TAX_ID_MUST_BE_ACTIVE.

If the TAX_ID_MUST_MATCH validation fails, the TAX_ID_MUST_BE_ACTIVE validation will not be executed.

Important Notes

• Validations are optional: If no validations are provided, the transaction will proceed without validation checks.
• The value type for each key must match the expected type.

By following these guidelines, you ensure that transactions are processed in compliance with business rules, preventing issues related to tax IDs or other critical validations.

Sandbox Environment

In the sandbox environment, it is possible to simulate a failure in the TAX_ID_MUST_BE_ACTIVE validation by creating a DICT Key transaction for the key 4df2d71a-1637-44f3-ae57-fa311ee03793.

Example:

curl --location 'https://faas.sandbox.tracefinance.io/pix/api/transactions/dictKey' \
--header 'X-Trace-Version: 2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ***' \
--data '{
  "dictKeyValue": "4df2d71a-1637-44f3-ae57-fa311ee03793",
  "idempotentId": "c5196b16-d445-4435-8b95-d9b7fe2d92be",
  "validations": [
    {
      "key": "TAX_ID_MUST_BE_ACTIVE",
      "value": true
    }
  ],
  "amount": {
    "value": 100
  }
}'