Validation
The validation request is sent for both Cashier and Virtual Terminal sessions — immediately after the customer (or agent) submits the payment details, and before the transaction is actually processed.
This call allows your CRM to apply business logic in real time, approving or rejecting the submission prior to payment processing.
{danger.fa-exclamation} IMPORTANT 1:
The validation callback is only triggered if thevalidation_url
is provided in the Cashier session request.
{danger.fa-exclamation} IMPORTANT 2:
If your API response contains"status": 0
, the validation is considered successful, and the payment attempt will proceed.
Any otherstatus
value is treated as failed validation. The message from the"description"
field will be shown to the customer as the reason for rejection.If the response times out or is malformed (e.g., missing
status
ordescription
, incorrect data types, a non-JSON response, or a JSON that does not contain a valid object), it will result in a validation failure with a generic error message.
{danger.fa-exclamation} IMPORTANT 3:
Fields with anull
value should be skipped when building the signature.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
merchant_id | varchar(50) | ✓ | Merchant API client account identifier |
application_key | varchar(32) | ✓ | Identifier of your application (website) |
customer | <Object> | ✓ | Customer object |
session | <Object> | ✓ | Session object |
transaction_attempt | <Object> | ✓ | Transaction attempt object |
version | varchar(3) | ✓ | API version |
timestamp | int(11) | ✓ | Request time (unix timestamp, seconds) |
Variable | Type | Description | |
---|---|---|---|
status | int | ✓ | API communication status - for transaction processing status please refer to transaction.transaction.status - 0 if the request was successful - Negative integer if internal server/network error occurs - Positive integer if application/logical error occurs |
description | varchar(256) | ✓ | Accurate description of the result. Return the actual error for any exception as it helps to diagnose issues in production. |
version | varchar(3) | ✓ | API version |
timestamp | int(11) | ✓ | Response time (unix timestamp, seconds) |
The full signature generation algorithm can be found in the Authentication section.
Request signature parameters
merchant_id
application_key
timestamp
customer.customer_token
session.order_id
transaction_attempt.currency
transaction_attempt.amount
transaction_attempt.conversion_rate
transaction_attempt.attempted_currency
transaction_attempt.attempted_amount
Response signature parameters
status
timestamp
{
"merchant_id": "Test-Integration-Merchant",
"application_key": "Sandbox",
"customer": {
"customer_token": "87cfb23a8f1e68e162c276b754d9c061",
"country": "GB",
"first_name": "John",
"last_name": "Johnson",
"avs_alert": 0,
"verification_alert": null
},
"session": {
"auth_token": "8a7sd87a8sd778ac961062c6bedddb8",
"intent": "payment",
"session_status": "created",
"order_id": "test-1560610955",
"currency": "EUR",
"amount": 100,
"conversion_rate": 1.000000,
"processed_currency": "EUR",
"processed_amount": 100,
"payment_method": "Credit Card",
"gateway": null,
"pin": "1",
"variable1": "your variable",
"variable2": "if that is not enough, you can pass even one more variable",
"variable3": null
},
"transaction_attempt": {
"intent": "sale",
"currency": "EUR",
"amount": 100,
"conversion_rate": 1.000000,
"attempted_currency": "EUR",
"attempted_amount": 100,
"payment_method": "Credit Card",
"card_data": {
"card_number": "411111******1111",
"card_exp": "12\/2024",
"cvv": "***"
},
"wallet_data": null,
"withdrawal_request_id": null
},
"version": "1.3",
"timestamp": 1590611635
}
{
"status": 0,
"description": "Ok",
"version": "1.3",
"timestamp": 1590611635
}
{
"status": 1,
"description": "Transaction already updated manually at the website to final status",
"version": "1.3",
"timestamp": 1590611635
}