Praxis Wiki logo

Webhooks 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 the validation_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 other status 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 or description, 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 a null value should be skipped when building the signature.

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_number": "411111******1111",
            "card_exp": "12\/2024",
            "cvv": "***"
        },
        "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
}