Notifications

Notifications about changes in transaction statuses are sent via callback from our Back-end to the address specified in the notify_url parameter (prepare_payment) and are received only for those payments that were created through the Octo system API.

Callback notifications

Callback structure

{
  "shop_transaction_id": "7339d5be-871b-45d8-ab07-dbbd51364c2f",
  "octo_payment_UUID": "4556a13e-f763-4b91-9387-92395fd51ccf",
  "status": "succeeded",
  "signature": "64F35398F22FE63FE780583F8BEEDE170094CE5D",
  "hash_key": "e27d3f79-3189-44e9-8a66-566a141025df",
  "total_sum": 1,
  "transfer_sum": 0.97,
  "refunded_sum": 0,
  "card_country": "UZ",
  "maskedPan": "427831** **** 3011",
  "rrn": "436456776123",
  "riskLevel": 0,
  "payed_time": "2024-12-25 15:25:14",
  "card_type": "internationalVisa"
}

Callback parameters

Parameter	Type	Required	Description
shop_transaction_id	String	Yes	Unique transaction identifier in the partner's system
octo_payment_UUID	String	Yes	Unique payment identifier in the Octo system
status	String	Yes	Payment status
signature	string	Yes	Cryptographic signature for data authenticity verification
hash_key	String	Yes	Hashing key for data validation
total_sum	Decimal	No	Total payment amount
transfer_sum	Decimal	No	Amount credited to the partner’s account after commission deduction
refunded_sum	Decimal	No	Amount refunded to the client (if there was a refund)
card_country	String	No	The country where the card was issued
maskedPan	String	No	Masked client card number
rrn	String	No	Retrieval Reference Number — unique transaction identifier in the processing system
riskLevel	Integer	No	Transaction risk level (e.g., from 0 to 5)
payed_time	String	No	Date and time of successful payment in YYYY-MM-DD HH:MM:SS format
card_type	String	No	Card type
is_physical_card	Boolean	No	Flag indicating whether the card is physical (true) or virtual (false)

Note

Verification of signature and hash_key is performed by calculating the hash using the formula:
sha1(sha1(secret, hash_key), uuid, status) where:

• secret – a secret key known only to the sender and recipient;
• hash_key – a hashing key, possibly unique for each transaction;
• uuid – the payment identifier (e.g., octo_payment_UUID);
• status – the payment status (succeeded, failed etc.).

Notification Setup

• The URL for receiving notifications must be specified in the shop's Personal Account.
• The specified URL will be displayed in the notify_url parameter in all requests related to these payments.

Note

Ensure that the specified URL is valid and accessible for processing notifications from Octo.