Praxis Wiki logo
Praxis Wiki
Version:
latest (API 1.3)
  • 3.3 (API 1.1)
  • 3.4 (API 1.2)
  • latest (API 1.3)

    • Webhooks Validation

    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_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
}
    2022 © PRAXIS CASHIER