Payment API Notification

---

• REQUEST PARAMETERS
• RESPONSE PARAMETERS
• EXAMPLE

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: It is important to always pay attention at charge_amount. Sometimes the amount processed differs from amount due to conversion rate (especially for crypto currencies) or fees applied.

---

{danger.fa-exclamation} IMPORTANT #3: 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
transaction_type	varchar(16)	Required. Transaction type. Allowed values are: sale (deposit) payout (withdrawal) refund (return deposit funds) authorize (authorization and capture)
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)
transaction_id	varchar(50)	Optional. PSP transaction identifier
trace_id	int(11)	Required. transaction identifier
order_id	varchar(50)	sale - Optional. Transaction identifier in your system payout - Required. Transaction identifier in your system
frontend	varchar(256)	Required. Cashier FrontEnd name, normally it is a common name of the website. Linked to a specific base currency.
pin	varchar(50)	Required. Unique customer id in your system
amount	int(20)	Required. Transaction amount in cents Please note: for certain currencies (see full list here) there is a fraction other than 100 cents per unit, this is important if you multiply by 100 to send the amount in cents
currency	varchar(3)	Required. Transaction currency
charge_amount	int(20)	Required. Amount (in actual processing currency) in cents. Please note: for certain currencies (see full list here) there is a fraction other than 100 cents per unit, this is important if you multiply by 100 to send the amount in cents
charge_currency	varchar(3)	Required. Actual currency processed
payment_method	varchar(50)	Required. Payment method
payment_processor	varchar(50)	Required. Payment processor
gateway	varchar(32)	Optional. Gateway doing the processing
created_by	varchar(50)	Optional. Transaction was created by
edited_by	varchar(50)	Optional. Transaction was edited by
auth_token	varchar(32)	Optional. Auth token provided upon Cashier session init call
merchant_id	varchar(50)	Required. Merchant API client account identifier
card_number	varchar(19)	Optional. Customer card number (4444 44** **** 1233)
card_type	varchar(10)	Optional. Customer card type (AMEX, DinersClub, Discover, Electron, JCB, Maestro, MasterCard, Mir, VISA)
card_exp	varchar(8)	Optional. Customer card exp (10/2023)
account_identifier	varchar(256)	Optional. Customer account ID or login at PSP
cascade_level	int(2)	Optional. Transaction retry number
is_cascade	int(1)	Optional. Is this transaction goes through cascade
error_code	varchar(32)	Optional. Error code for rejected transactions
error_details	varchar(256)	Optional. Error description for rejected transactions
reference_id	int(11)	Optional. ID of transaction to reverse
version	varchar(16)	Required. API version
timestamp	int(11)	Required. Request time. URL will be active during 1 min after this time
variable1	varchar(256)	Optional. Your custom field which will consist some neсessary information
variable2	varchar(256)	Optional. Your custom field which will consist some neсessary information
variable3	varchar(256)	Optional. Your custom field which will consist some neсessary information
signature	varchar(96)	Required. Request signature. Please refer to How to Build Signature for details on signing the 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(16)	Required. API version
signature	varchar(96)	Required. sha384 HASH code of response (same algorithm as request signature)

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 '{
    "account_identifier": null,
    "amount": 2500,
    "auth_token": "a60927468a5b32afe31468d780c57a32",
    "card_exp": "12\/2024",
    "card_number": "411111******1111",
    "card_type": "VISA",
    "cascade_level": null,
    "created_by": "INTERNET",
    "currency": "EUR",
    "edited_by": "INTERNET",
    "error_code": null,
    "error_details": null,
    "frontend": "Sandbox EUR",
    "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
    "merchant_id": "Test-Integration-Merchant",
    "order_id": null,
    "payment_method": null,
    "payment_processor": "TestPP",
    "pin": "7",
    "reference_id": null,
    "timestamp": 1578878718,
    "trace_id": 756850,
    "transaction_id": "13348",
    "transaction_status": "approved",
    "transaction_type": "sale",
    "version": "1.1",
    "signature": "84f6b844435c640002f56ef95275b48bdd6a55ee9e6251faaee702cc7d26c711cecbf1509ccbb994bc73f121c73745e8"
}'

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.