Transaction Validations
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
}
}'
Updated about 2 months ago