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.

1. Authorization Request – The end user makes a purchase with a Card.
2. External Validation Request – Treezor sends you an HTTP Request to a predefined endpoint of your own REST API.
3. 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.).
4. A cardtransaction.create webhook is sent. It includes the requestId 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).