Praxis Wiki logo

Webhooks Notification


Notification request is sent to the merchant's website or CRM each time that a transaction status has been changed asynchronously. Each transaction and cashier login is initiated with notification_url parameter, which is further used as destination URL for notifications.

{danger.fa-exclamation} IMPORTANT #1: In case if your API response contains "status":-1 or responds in unrecognized format, the notification will be resent automatically within approximately 5 minutes.


{danger.fa-exclamation} IMPORTANT #2: The transaction and session amounts may change during processing. More information can be found here: Understanding Amonts

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 <Object> ? Transaction object. Appears as null in case of expired session.
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.tid
  7. transaction.currency
  8. transaction.amount
  9. transaction.conversion_rate
  10. transaction.processed_currency
  11. transaction.processed_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": {
        "transaction_type": "sale",
        "transaction_status": "approved",
        "trace_id": 756850,
        "transaction_id": "13348",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.000000,
        "processed_currency": "EUR",
        "processed_amount": 100,
        "fee": 0,
        "fee_included": 0,
        "fee_type": "flat",
        "payment_method": "Credit Card",
        "payment_processor": "TestCardProcessor",
        "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
        "card": {
            "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": null,
        "is_async": 0,
        "is_cascade": 0,
        "cascade_level": 0,
        "reference_id": null,
        "withdrawal_request_id": null,
        "created_by": "INTERNET",
        "edited_by": "INTERNET",
        "status_code": "SC-002",
        "status_details": "Transaction approved"
    },
    "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
}