Webhooks Validation

---

• REQUEST PARAMETERS
• RESPONSE PARAMETERS
• SIGNATURE
• EXAMPLE

Validation request is sent for Cashier and Virtual Terminal - immediately after the payment details have been submitted by the customer within the Cashier, or by the agent using the Virtual Terminal, and before the actual transaction processing. The validation call lets you apply the logic on the CRM side in order to confirm or reject this submission before the processing has been attempted.

{danger.fa-exclamation} IMPORTANT #1: The validation callback will be triggered only if the validation_url is provided within the Cashier session request.

---

{danger.fa-exclamation} IMPORTANT #2: In case if your API response contains "status":0, the validation is considered to be successfully passed, and the payment will be attempted.

Response containing any other status value is treated as failed validation, message in "description" parameter of the response will be shown to customer as reason for the blocked attempt.

Response timeout or malformed response (integer status or string description missing or having the wrong data type, response that appears to be not a JSON string, or a JSON that does not contain an object) is considered as an error, and the validation will be failed with a generic error.

REQUEST PARAMETERS

✓ - 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)

RESPONSE PARAMETERS

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)

Signature

The full signature generation algorithm can be found in the Authentication section.

Request signature parameters

1. merchant_id
2. application_key
3. timestamp
4. customer.customer_token
5. session.order_id
6. transaction_attempt.currency
7. transaction_attempt.amount
8. transaction_attempt.conversion_rate
9. transaction_attempt.attempted_currency
10. transaction_attempt.attempted_amount

Response signature parameters

1. status
2. timestamp

EXAMPLE

Incoming Request

{
    "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_token": "J-4-a0vPhjZ9R75JP98VDUFgbh9y8sYr",
            "card_type": "VISA",
            "card_number": "411111******1111",
            "card_exp": "12\/2024",
            "card_issuer_name": "Bank of Somewhere",
            "card_issuer_country": "GB"
        },
        "wallet_data": null,
        "withdrawal_request_id": null
    },
    "version": "1.3",
    "timestamp": 1590611635
}

Response (Success)

{
    "status": 0,
    "description": "Ok",
    "version": "1.3",
    "timestamp": 1590611635
}

Response (Error)

{
    "status": 1,
    "description": "Transaction already updated manually at the website to final status",
    "version": "1.3",
    "timestamp": 1590611635
}