Transactions external validation
This feature allows you to validate or refuse end users payments, in real-time and based on your own criteria.
Information – Treezor offers its own Transaction Rules Engine
Therefore, you no longer need to implement your criteria with the external validation. Contact Treezor to find out which option works best for you.
General process
The external validation process works as follows.
- Authorization Request – The end user makes a purchase with a Card.
- External Validation Request – Treezor sends you an HTTP Request to a predefined endpoint of your own REST API.
- External Validation Response – Your software makes a decision based on your own criteria and returns the decision in the HTTP Response.
- If you refuse, the transaction is declined.
- If you fail to answer within the allowed timeframe, the transaction is declined.
- If you accept, Treezor handles the Authorization request like it would normally (Authorized Balance verifications, MID/MCC restrictions, etc.).
- A
cardtransaction.create
webhook is sent. It includes therequestId
of the External Validation request.
Information – Your response must be provided within an allotted timeframe
The timeframe is defined on a per-client basis. In the absence of a response in the allotted time, the Authorization is automatically declined.
Request example
A POST request is sent to your own API endpoint, as defined during the subscription to this feature.
json
{
"request_id": "e03df174-ff01-571c-8677-e52af53affda", // UUIDv5
"card_public_token": "988927734", // card Public Token
"request_date": "2021-04-20T10:29:44+00:00", // Date/time of sending (RFC 3339 format)
"payment_amount": {
"value": 17.01, // Payment amount, including all fees, float. Positive for a Debit, Negative for a Credit.
"value_smallest_unit": 1701, // Payment amount, including all fees, in the smallest unit of associated currency
"currency_code": "978" // Billing currency - ISO 4217 3 digit
},
"payment_local_amount": {
"value": 7.01, // Payment amount in local currency, float
"value_smallest_unit":701, // Payment amount in local currency, in the smallest unit of associated currency
"currency_code": "978" // Local currency - ISO 4217 3 digit
},
"payment_local_time": "145958", // Local time of transaction - “hhmmss”
"authorization_issuer_id": "928257521", // Transaction Unique ID from the Card Processor
"merchant_data" : {
"id": "000980200909995", // Merchant ID
"name": "PAYPAL ", // Merchant Name
"city": "PARIS", // Merchant City
"country": "FRA", // Merchant Country - ISO 3-alpha country code
"mcc": "4512", // Merchant Category Code
"acquirer_id": "06004441", // Acquirer ID
}
}
Response example
All requests must be answered to.
If you approve the transaction
You can answer with the following JSON response
json
{
"response_date": "2021-04-20T10:29:49+00:00", // Date/time of your decision (RFC 3339 format)
"response_code" : "AUTHORIZED", // Your decision
"response_id": "e03df174-ff01-571c-8677-e52af53affda" // Unique response ID that you have generated (It can be a signature of the provided requestId)
}
If you refuse the transaction
You can answer with the following JSON response
json
{
"response_date": "2021-04-20T10:29:49+00:00", // Date/time of your decision (RFC 3339 format)
"response_code" : "DECLINED", // Your decision, other values are available in the list below
"response_id": "e03df174-ff01-571c-8677-e52af53affda" // Unique response ID that you have generated (It can be a signature of the provided requestId)
}
Responses Codes (responseCode
)
You can anwser to an External Validation request with the following codes:
Code | |
---|---|
AUTHORIZED | |
DECLINED | |
DECLINED_INSUFFICIENT_FUNDS | |
DECLINED_LOCAL_CURRENCY_INVALID | |
DECLINED_DATETIME_INVALID | |
DECLINED_CARD_UNKNOW | |
DECLINED_MCC_INVALID | |
DECLINED_MERCHANTID_INVALID | |
DECLINED_MERCHANT_CITY_INVALID | |
DECLINED_MERCHANT_COUNTRY_INVALID |
Information – Other responses may occur
Any other response will be considered as DECLINED
.
Special case of Balances not managed by Treezor
In the use case where you manage the Balance and Authorized Balance yourself:
- No funds withholding will take place, as Treezor doesn't manage the funds
- At settlement, the funds will be debted or credited on your main Wallet (which should be provisioned accordingly).