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:

Key	Value Type	Description
TAX_ID_MUST_BE_ACTIVE	String (Tax ID)	Verify if the provided tax ID is active. If it is not, the transaction will fail.
TAX_ID_MUST_MATCH	String (Tax ID)	Verify if the destination's tax ID matches the tax ID provided in the value. If they do not match, the transaction will fail.
NAME_MUST_NOT_BE_RESTRICTED	String (Name)	Verify if the provided name appears on any restriction lists. If found, the transaction will fail.

Default Validations

Some validations are set as default and are automatically processed depending on the transaction type:

Key	Transaction Type	Description
DICT_KEY_MUST_BE_VALID	Debit DICT Key	Verify if the provided DICT Key is valid. If it is not, the transaction will fail.

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, you can test failure scenarios for validations by following these criteria:

Key	Value
TAX_ID_MUST_BE_ACTIVE	50676745000143
NAME_MUST_NOT_BE_RESTRICTED	John Doe

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": "50676745000143"
    },
		{
      "key": "NAME_MUST_NOT_BE_RESTRICTED",
      "value": "John Doe"
    }
  ],
  "amount": {
    "value": 100
  }
}'