Payment Notification
Last updated
Last updated
Payment webhooks are specific to payment events and are triggered on multiple occasions:
If a payment transaction has an associated , it can be notified during the automatic inquiry process. This can happen immediately after the payer completes the payment process or later if the payment encounters an error. More details about the timings for automatic inquiry can be found .
Configuring URLs:
Via Checkout API: Provide the and an optional when calling the .
Using Plugin Config: Set the webhook_url and redirect_url globally via the plugin config, applicable to either or t plugins. Even if these values are set globally, they can be overridden for specific transactions when using the Checkout API. For more details on this configuration, click .
Redirecting the Payer:
Successful Redirect: If you aim for the payer to be redirected back to your website post-payment, your endpoint should return an HTTP status of 200. Any other status will keep the payer on the Ottu payment details page.
Retaining on Ottu Page: If you intentionally want the payer to remain on the Ottu page post-payment, return a status code of 201. Ottu will interpret this as a successful notification, and the payer won’t be redirected. Any other status will be deemed as a failed notification by Ottu.
A pre-established contractual agreement with the customer making the payment, allowing the merchant to securely retain and later use their payment details for particular purposes. This might include agreements like regular payments for services such as mobile subscriptions, payments in installments for purchases, arrangements for one-time charges like account reloads, or adhering to common industry practices such as penalty fees for missed appointments
Presence Condition:
Payment transaction due amount details
By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active.
Presence Condition:
The merchant should add it when setting up the payment transaction.
By enabling this, you will ask for user's delivery location on a map.
Presence Condition:
The merchant should provide it during the creation of the transaction.
Presence condition:
Customer billing address data
Presence Condition:
The presence of each parameter is contingent on the provision of any selection of "customer billing address data" parameters during payment transaction creation.
The city where the customer is living and registered Max length: 40
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
Customer's street & house data Max length: 255
Postal code. Max length 12 (it may have different length for different countries)
Where to pass the customer’s email address Have to be a valid email address Max length 128
Presence Condition:
It needs to be included when generating the payment transaction.
For the customer's first name Max length 64
Presence Condition:
The merchant should include it while making the payment of the transaction.
Customer ID is created by a merchant, and stored in the merchant database Max length 64
Presence Condition:
The merchant should include it during initiating the payment transaction.
For the customer's last name Max length 64
Presence Condition:
The merchant should include it while making the payment of the transaction.
Where to pass the customer’s phone number Max length 32
Presence Condition:
The merchant should include it when processing the payment for the transaction.
The extra information for the payment details, which the merchant has sent it in key value form.
Presence Condition:
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:
It represents a markup amount on the original amount. Max length: 24 Min value: 0.01
Presence Condition:
It will contain the raw payment gateway response sent by the payment gateway to Ottu.
Presence Condition:
It will only be present in response to the PG's callback request for the transaction.
This object contains information about the user who created the transaction from Ottu side, specifically, the user who generated the payment URL
Presence Condition:
Merchant includes the initiator ID in the payload when creating the transaction.
Whether the transaction was carried out in a sandbox environment.
Presence Conditions:
It will only be present when PG's setting configured as sandbox
Presence Condition:
It will only be present if a payment attempt records an error.
It is a specific code that is assigned to a transaction by the merchant. By assigning a unique identifier to each transaction, the merchant can easily retrieve and review transaction details in the future, as well as identify any issues or discrepancies that may arise. such like : ABC123_1, ABC123_2 Max length 128
Presence Condition:
It will be present only if order_no has been provided in the request payload.
It is the amount that is credited to the merchant's bank account Max length: 24 Min value: 0.01
Presence Condition:
It will only be present if a capture action is being processed on the transaction and the paid amount is recorded.
If auto_debit is selected:
Ottu simplifies payment integration by standardizing inconsistent callback payloads from various payment gateways. Since transaction details like IDs, status codes, amounts, and timestamps vary in structure and labeling, merchants face challenges in processing this data reliably. OTTU extracts the essential details from any gateway’s payload and converts them into a unified pg_paramsobject, ensuring a consistent format that simplifies transaction management and integration.
Each parameter in pg_params represents a specific transaction-related attribute, stored as an object containing:
value: The actual data returned by the payment gateway.
verbose_name_ar: The Arabic label for the parameter.
verbose_name_en: The English label for the parameter.
These labels (verbose_name_ar/en) can be used to dynamically display user-friendly field names in multilingual interfaces, ensuring clarity and accessibility for users in different languages.
It is a unique identifier for the payment attempt, which can be used as a tracking identifier Max length 128
The payment amount paid back from the merchant to the customer. Max length: 24 Min value: 0.01
Presence Condition:
It will only be present if a refund action is being processed on the transaction and the refunded amount is recorded.
Presence Condition:
It will only be sent if the editable amount option is turned on.
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 on-editable amount: The settled amount is the same value as the original payment amount
Presence Condition:
It will be present only if the transaction is paid, authorized or cod.
A cryptographic hash used to guarantee data integrity and authenticity during client-server exchanges. This hash ensures that the API payload has not been tampered with, and can only be verified by authorized parties.
It represents the timestamp at which Ottu processed the transaction. While this often corresponds to the payment time, it's important to note that it might not always be the case. Payments can be acknowledged at a later time, so this timestamp might not align precisely with the actual payment time..
The ID of the transaction log associated with the transaction. Max length 32-bit String (2^31 - 1)
Presence Condition:
It will be sent only if the transaction type is BULK as it's a bulk identifier.
Represents token details.
Presence Conditions:
When user pays with a tokenized card, Ottu will include the token details in the response
Presence Conditions:
It will be sent only if operations processed on transaction and resulted child transaction records.
Presence Condition:
It will only appear if a void action is being performed on the transaction, and the voided amount is documented.
When you receive a payment notification, it’s crucial to understand and acknowledge the payment’s status and details. Here’s how you can interpret the information:
There are several types of payment events you might encounter:
Payment: This indicates a direct payment transaction.
Authorization: This signifies a payment authorization, which might be captured later.
Cash (Offline): This represents an offline payment, often referred to as Cash on Delivery (COD).
result fieldIf the result is success, it means the payment was successful.
If the result is failure, it indicates an unsuccessful payment attempt.
For cash payments, the result field will be cod, indicating Cash on Delivery.
The operation field provides insight into the type of transaction:
If the operation is payment, it indicates a direct payment.
If the operation is authorization, it signifies a payment that’s been authorized but not yet captured.
In most scenarios, cross-referencing with the amount field should suffice. But if there are discrepancies or if you’ve set up fees or currency conversions, it’s advisable to verify with amount_details.
By understanding and interpreting these fields correctly, you can ensure accurate and timely acknowledgment of all your payments, be they online or offline.
Endpoint Requirements: Ensure your endpoint adheres to all the stipulations outlined in the Webhook Overview. To review the requirements, click .
Specific Redirects: If you have a particular URL to which you wish to redirect the payer after the payment process, ensure you specify the during the payment setup. Ottu will use this URL to navigate the payer back to your platform or any designated page post-payment.
The merchant should include it when creating the payment transaction, typically provided during the setup within the initiation process.
It becomes a mandatory requirement when the is specified as "auto_debit".
In certain agreement types, the condition state becomes a required element. For further details on which parameters are mandatory for recurring agreements, please refer .
Denotes the total sum of the payment transaction, which encompasses the cost of the procured items or services, excluding any supplementary fees or charges. See
The specified currency represents the denomination of the transaction. Nevertheless, it doesn't necessarily mandate payment in this exact currency. Due to potential currency conversions or exchanges, the final charge may be in a different currency. See . 3 letters
Denotes the comprehensive total of the payment transaction, incorporating both the principal amount and any associated fees. (+)
It outlines the rules for a card's payment eligibility See the request parameter for more information.
Any child parameter provided with the object in the request payload will be populated in the response as child parameter.
The currency code of the payment transaction For more details, 3 letters code
Additional data for accuracy purpose for Max length: 255
State of the customer’s (sometimes the same as the ) Max length 40
The merchant should add it in the and include it during the transaction creation.
The of the payment gateway used to proceed the payment Max length 16
The name of the used to proceed the payment Max length 64
It is present only when is used, because is not associated with any user.
A message indicating the cause of a failure., which is directly related to the payment attempt itself Max length 255.
Enum: "one_off" , "auto_debit"
Type of payment. Choose one_off for payments that occur only once without future commitments. Choose auto_debit for payments that are automatically deducted, such as recurring subscriptions, installments, or unscheduled auto-debits. for more information about auto-debit API, please refer to .
and parameters will also be mandatory.
Only PG codes supporting can be selected. As a side effect, the card used for the payment will be associated with the supplied agreement.id. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments
The amount remaining to be paid in the transaction. ( – ) Max length: 24 Min value: 0.01
Could be "success", "pending", "failed", "canceled", "error", and "cod". See .
Max length 50
Ottu unique identifier which gets generated when the transaction is created. It can be used to perform subsequent operations, like . Max length 128
It is one of the . And could one of the below: created, pending, attempted, authorized, paid, failed, canceled, expired, invalided, or cod. Max length 50
Transactions resulted to the PG operations performed on the parent transaction See
The payment amount resulted by performing operation Max length: 24 Min value: 0.01
Ottu notifies the for all payment event types, not just success. This includes statuses like error, failed, pending, rejected, etc. The payload provides enough context to identify the status of the event.
Events like Refund, Void, or Capture are considered operation events and not payment events. If you’re looking for information on these, please refer to the .
To ensure a smooth redirection of the payer back to the designated , it is essential that the redirect_url is accurately provided during the payment setup. Additionally, the must respond with a status code of 200. This specific status code serves as a confirmation of successful interaction between the involved systems, ultimately guaranteeing the seamless progression of the redirection process as originally intended.
Redirect behavior based on webhook_url response: - 200, the customer will be redirected to . - 201, the customer will be redirected to Ottu payment summary page. - any other code, the customer will be redirected to Ottu payment summary page. For this particular case, Ottu can notify on the email, when Enable webhook notifications? Activated
The field is your primary indicator of the payment’s outcome:
The field provides the value the customer has paid in the currency set during the payment setup.
However, the actual amount captured by the (PG) might differ. This can be due to additional fees, currency conversion, or other factors. To get the exact amount captured by the PG, refer to . The currency in which this amount is denominated can be found in .
For Cash on Delivery transactions, the field will specifically be cod. This helps differentiate offline payments from online ones.
In Conclusion, As you navigate the intricacies of Ottu’s payment webhooks, it’s paramount to ensure you’re well-acquainted with all the general guidelines. We strongly recommend reviewing our comprehensive for a holistic understanding. Additionally, if you find yourself with questions or uncertainties, our section might already have the answers you seek. We’re committed to ensuring a seamless experience, and your thorough understanding of our systems is a crucial part of that journey.
