Praxis Wiki logo

Webhooks Notification


The notification request is sent to the merchant’s website or CRM each time a transaction status changes asynchronously.
Every transaction or Cashier login should be initiated with a notification_url parameter, which is then used as the destination for all related status notifications.

{danger.fa-exclamation} IMPORTANT 1:
If your API response contains "status": -1 or returns an unrecognized format, the notification will be automatically resent in approximately 5 minutes.


{danger.fa-exclamation} IMPORTANT 2:
Transaction and session amounts may change during processing. For more information, see: Understanding Amounts


{danger.fa-exclamation} IMPORTANT 3:
To receive additional notifications in the event of a timeout, please contact our support team and request to enable the “Notifications for delayed processing via Direct API” setting.
Note: The timeout is a configurable value (in seconds).


{danger.fa-exclamation} IMPORTANT 4:
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)
conversion_rate varchar(30) ? Conversion rate between currency and processed_currency applied during conversion from amount to processed_amount. Applies to successful transactions. The value is calculated as 1 processed_currency / 1 currency = conversion_rate
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",
    "conversion_rate": 1.000000,
    "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",
        "tid": 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",
            "card_holder": "John Johnson"
        },
        "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
}