Payment Notification

Overview

The Ottu payment system provides a webhook designed specifically for payment events, including authorization, purchase, failed, canceled, and error. Whenever any of these payment events occur, Ottu will automatically trigger the webhook, sending a JSON payload to the specified webhook_url provided in the Checkout API. This JSON payload includes all relevant payment event results, payment details, and payment gateway responses, allowing merchants to receive and process this information in real-time, and to update their own systems accordingly.

By integrating with Ottu's payment webhook, merchants can streamline their payment processes and enhance their payment workflows. With publicly documented details and straightforward integration instructions, developers can seamlessly integrate Ottu's payment system into their own applications and online stores. Ultimately, the Ottu payment webhook provides a reliable, secure, and efficient way for merchants to manage their payment processing, enabling them to focus on growing their business and serving their customers.

Payload structure

amount string mandatory

The initial amount of the payment transaction. See amount Must be positive Max length: 24 Min value: 0.01

The merchant should always check if the received amount from Ottu side is the amount of the order, to avoid user changing the cart amount in between.

amount_detials object optional

Details

It will be present only if the currency_config has been configured in the PG settings from the Ottu admin panel. See currency configuration & payment gateway configuration

1️currency_code string mandatory

The code represents the used currency 3 letters

2️amount string mandatory

Payment transaction original amount. See amount Must be positive Max length: 24 Min value: 0.01

3️ total string mandatory

It represents the whole payment amount (amount+fee) Must be positive Max length: 24 Min value: 0.01

4️ fee string optional

It represents a markup amount on the original amount Must be positive Max length: 24 Min value: 0.01

capture_delivery_address bool optional

Indicates whether to capture delivery address It will be present only if the merchant includes it during the creation of the transaction.

capture_delivery_location bool optional

Indicates whether to capture delivery location It will be present only if the merchant includes it during the creation of the transaction.

currency_code string mandatory

The currency code of the payment transaction For more details, https://en.wikipedia.org/wiki/ISO_4217 3 letters code

Billing address information

Details

It will be present only if the customer includes it while making the payment of the transaction.

1️customer_address_city string optional

The city where the customer is living and registered Max length: 40

2️customer_address_country string optional

The country where the customer is living and registered Based on ISO 3166-1 Alpha-2 code Validation will be performed against existing countries Max length: 2

3️customer_address_line1 string optional

Customer's street & house data Max length: 255

4️customer_address_line2 string optional

Additional data for accuracy purpose for line1 Max length: 255

5️ customer_address_postal_code string optional

Postal code. Max length 12 (it may have different length for different countries)

6️customer_address_state string optional

State of the customer’s city (sometimes the same as the city) Max length 40

customer_email string optional

Where to pass the customer’s email address Have to be a valid email address It will be present only if the customer includes it while making the payment of the transaction. Max length 128

customer_first_name string optional

For the customer's first name It will be present only if the customer includes it while making the payment of the transaction. Max length 64

customer_id string optional

Customer ID is created by a merchant, and stored in the merchant database It will be present only if the merchant includes it during the creation of the transaction. Max length 64

customer_last_name string optional

For the customer's last name It will be present only if the customer includes it while making the payment of the transaction. Max length 64

customer_phone string optional

Where to pass the customer’s phone number It will be present only if the customer includes it while making the payment of the transaction Max length 32

extra object optional

The extra information for the payment details, which the merchant has sent it in key value form. The presence of the element will depend on whether the merchant includes it during transaction creation by adding each element from the plugin field configuration. For example:

   "extra":{
      "flight-number":"43667",
      "full_name":"abc"
   },

fee string optional

It represents a markup amount on the original amount. It will only be present if the merchant adds it in the currency configuration and includes it during the transaction creation. Must be positive Max length: 24 Min value: 0.01

gateway_account string mandatory

The code of the payment gateway used to proceed the payment Max length 16

gateway_name string mandatory

The name of the payment gateway used to proceed the payment Max length 64

gateway_response object optional

It will contain the raw payment gateway response sent by the payment gateway to Ottu It will only be present in response to the PG's callback request for the transaction.

initiator object optional

This object contains information about the user who created the transaction from Ottu side, specifically, the user who generated the payment URL It will only be present if the merchant includes the initiator ID in the payload when creating the transaction

is_sandbox bool optional

Whether the transaction was carried out in a sandbox environment. It will only be present when PG's setting configured as sandbox

message string optional

A message indicating the cause of a payment attempt failure., which is directly related to the payment attempt itself It will only be present if a payment attempt records an error. Max length 255.

order_no string optional

Merchant unique identifier for the transaction such like : ABC123_1, ABC123_2 Max length 128

paid_amount string optional

It is the amount that is credited to the merchant's bank account It will only be present if a capture action is being processed on the transaction and the paid amount is recorded Must be positive Max length: 24 Min value: 0.01

reference_number string mandatory

It is a unique identifier for the payment attempt, which can be used as a tracking identifier Max length 128

refunded_amount string optional

The payment amount paid back from the merchant to the customer. It will only be present if a refund action is being processed on the transaction and the refunded amount is recorded. Must be positive Max length: 24 Min value: 0.01

remaining_amount string optional

The amount remaining to be paid in the transaction. (amount – settled amount) Must be positive It will only be sent if the editable amount option is turned on. Max length: 24 Min value: 0.01

result string optional

Could be "success", "pending", "failed", "canceled", "error", and "cod". See payment transaction states Max length 50

session_id string mandatory

Ottu unique identifier which gets generated when the transaction is created. It can be used to perform subsequent operations, like retrieve, acknowledge, refund, capture, and cancelation Max length 128

settled_amount string optional

Is the amount with the same currency of the initiating amount,

• For editable amount: It is the amount that the customer enters at the checkout page

• For non-editable amount: The settled amount is the same value as the original payment amount

It will be present only if transaction is paid, authorized or cod

state string mandatory

It is one of the Payment transaction state. And could one of the below: created, pending, attempted, authorized, paid, failed, canceled, expired, invalided, or cod. Max length 50

transaction_log_id string optional

The ID of the transaction log associated with the transaction. Max length 32-bit String (2^31 - 1) It will be sent only if transaction type is BULK as it's a bulk identifier.

transaction array optional

Details

Transactions resulted to the PG operations performed on the parent transaction See child transaction sate It will be sent only if operations processed on transaction and resulted child transaction records

1️amount string optional

The amount of child transaction object represented in transactions Array Must be positive Max length: 24 Min value: 0.01

1️currency_code string optional

The code represents the used currency. 3 letters

3️order_no string optional

The order_no of child transaction object represented in transactions Array

4️ session_id string optional

The unique session identifier of child transaction object represented in transactions Array

5️state string optional

The state of child transaction object represented in transactions Array

voided_amount string optional

The payment amount resulted by performing void operation It will only be present if a void action is being processed on the transaction and the voided amount is recorded Must be positive Max length: 24 Min value: 0.01

Payload example (attempted)

Payload example (attempted)

{
    "amount":"0.01",
    "amount_details":{
       "currency_code":"KWD",
       "amount":"0.01",
       "total":"0.01",
       "fee":"0.00"
    },
    "currency_code":"KWD",
    "customer_email":"[e-mail]",
    "customer_phone":"96511111111",
    "fee":"0.00 KWD",
    "gateway_account":"test",
    "gateway_name":"test",
    "message":"test",
    "gateway_response":{
        "It will contain the raw pg response sent by the pg to Ottu"
    },
    "initiator": {
        "id": 1, "first_name":"test", "last_name":"test", "username":"test", "email":"[e-mail]", "phone":"[phone]"
    },
    "is_sandbox":true,
    "order_no":"t-1111",
    "paid_amount":"0.01",
    "reference_number":"test111",
    "result":"success",
    "session_id":"111111111111111111111111111111111111",
    "settled_amount":"0.01",
    "signature":"11111111111111111111111111111111111111111111111111111111",
    "state":"paid",
    "transactions":[
       {
          "amount":"0.01",
          "currency_code":"KWD",
          "order_no":"None",
          "session_id":"1111111111111111111111111111111111111111111",
          "state":"refund_queued"
       }
    ]
 }