Praxis Wiki logo

Payment API | Notification


Notification is sent in case of asynchronous flow (3D Secure confirmation by the customer) - when the transaction status has changed to it's final status, usually it's confirmation, cancellation or timeout.

The asynchronous flow can be recognized by the transaction status received in response - pending_async.

{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: Sometimes transaction_id (PSP transaction identifier) is empty, this may happen in the cases when the PSP has rejected the processing attempt due to input validation or payment service unavailability.

REQUEST PARAMETERS

Variable Type Description
amount int(20) Required. Processed amount in cents.
Please note: for certain currencies (JPY, CLP, KRW, VND, BHD, IQD, JOD, LYD, OMR, TND) the amount is sent as-in without being converted to cents, this is important if you multiply by 100 to send the amount in cents
currency varchar(10) Required. Processed currency
merchant_id varchar(50) Required. Merchant API client account identifier
order_id varchar(50) Required. Transaction identifier in your system
trace_id int(11) Required. Transaction identifier in Praxis
transaction_id varchar(50) Optional. Transaction identifier in PSP
payment_processor varchar(25) Required. Gateway doing the processing
transaction_status varchar(16) Required.
- pending - processing initiated, final response expected from PSP
- approved - processing was successful
- declined - processing failed
- cancelled - processing cancelled by the merchant or client
- requested - merchant action expected (approval)
error_code int(10) Optional. Error code for rejected transactions
error_details varchar(256) Optional. Error description for rejected transactions
timestamp int(11) Required. Request time. URL will be active during 1 min after this time
version varchar(3) Required. API version
signature varchar(96) Required. sha384 HASH code of response (same as in request)

RESPONSE PARAMETERS

Variable Type Description
status int Required.
- 0 if the request was successful
- Negative integer if internal server/network error occurs
- Positive integer if application/logical error occurs
description varchar(256) Required. Accurate description of the result. Return the actual error for any exception as it helps to diagnose issues in production
timestamp int(11) Required. Request time. URL will be active during 1 min after this time
version varchar(3) Required. API version
signature varchar(96) Required. sha384 HASH code of response (same as in request)

EXAMPLE

For example below: Merchant Secret = "MerchantSecretKey"

Request

curl -X POST \ https://api.merchant.com/v1/deposits/tx-1560610955 \
-H 'Content-Type: application/json' \
-d '{
    "amount":100,
    "currency":"USD",
    "description":"approved",
    "merchant_id":"Test-Integration-Merchant",
    "order_id":"test-1560610955",
    "payment_processor":"Test PSP",
    "timestamp":1561329539,
    "trace_id":1000000680,
    "transaction_id":"15607165967613",
    "transaction_status":"declined",
    "error_code": 711,
    "error_details": "PreAuth error",
    "version":"1.1",
    "signature":"7f4d9d16324ecf08d92db27265fb32be82c32e4d06b49910704d2a6f39101519fd839d41c2fdec41009b66778955d08f"
}'

Response (OK)

{
    "description":"Notification registered successfully",
    "status":0,
    "timestamp":1560644992,
    "version":"1.1",
    "signature":"8c9e2bc711f64671fec91dee9a948388496a1476ffc8c90de6d581ed3189f086432428fb7455bf074c0d8ce4c6949432"
}

Response (ERR)

{
    "description":"Notification handling failed",
    "status":1,
    "timestamp":1560645019,
    "version":"1.1",
    "signature":"050c43f373b452b741ba3a972dd5f324f4bf2ea55822da0b1610755a66375c361c234cf11b2e486d30232b98eac2f61e"
}

Please refer to How to Build Signature for details on signing the request.