Payment Webhooks
Payment webhooks are specific to payment events and are triggered on multiple occasions:
- 1.Once a payer has completed the payment process and awaits redirection. To get notified for this event, the webhook_url must either be sent via the Checkout API when the payment transaction is created or set as the default webhook_url in the Ottu dashboard to apply for all transactions.
- 2.If a payment transaction has an associated webhook_url, 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 here.
- 4.
- 5.When an inquiry API call is initiated by the merchant. Optionally, a notification can be sent to the webhook_url associated with the payment transaction or to a new one specified during the inquiry API call.
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.
Payment transaction due amount details
The code represents the used currency
3 letters
Payment transaction original amount. See amount
Max length: 24
Min value: 0.01
It represents a markup amount on the original amount
Max length: 24
Min value: 0.01
Indicates whether to capture delivery address.
Presence condition:
- The merchant should include it during the creation of the transaction.
Indicates whether to capture delivery location.
Presence condition:
- The merchant should include it during the creation of the transaction.
The currency code of the payment transaction
For more details, https://en.wikipedia.org/wiki/ISO_4217
3 letters code
Billing address information |
---|
Customer billing address data
Presence condition:
|
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:
- The customer should include it while making the payment of the transaction.
For the customer's first name
Max length 64
Presence condition:
- The customer 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 the creation of the transaction.
For the customer's last name
Max length 64
Presence condition:
- The customer should include it while making the payment of the transaction.
Where to pass the customer’s phone number
Max length 32
Presence condition:
- The customer should include it while making the payment of 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:
"extra":{
"flight-number":"43667",
"full_name":"abc"
},
It represents a markup amount on the original amount.
Max length: 24
Min value: 0.01
Presence condition:
- The merchant should add it in the currency configuration and include it during the transaction creation.
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:
- It is present only when Basic Authentication is used, because API Key Authentication is not associated with any user.
- 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
A message indicating the cause of a payment attempt failure., which is directly related to the payment attempt itself
Max length 255.
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.
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.
The amount remaining to be paid in the transaction. (amount – settled amount)
Max length: 24
Min value: 0.01
Presence condition:
- It will only be sent if the editable amount option is turned on.
Could be "success", "pending", "failed", "canceled", "error", and "cod". See payment transaction states.
Max length 50
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
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 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
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.
Transactions resulted to the PG operations performed on the parent transaction
See child transaction sate
Presence conditions:
- It will be sent only if operations processed on transaction and resulted child transaction records.
The amount of child transaction object represented in transactions Array
Must be positive
Max length: 24
Min value: 0.01
The code represents the used currency.
3 letters
The order_no of child transaction object represented in transactions Array
The unique session identifier of child transaction object represented in transactions Array
The state of a child transaction object represented in transactions Array
Represents token details.
- Presence conditions:
When user pays with a tokenized card, Ottu will include the token details in the response
The card brand (e.g., Visa, Mastercard) associated with the card. Display this information for customer reference.
Define if provided card token can be used to initiate auto debit requests.
The unique identifier for the customer who owns the card
Max length: 36
Specifies if the card requires the submission of a CVV for transactions. A card without CVV requirement can be used for auto-debit or recurring payments
The card's expiration month. Provide this information for transaction processing and validation.
Max length: 2
The card's expiration year. Provide this information for transaction processing and validation.
Max length: 2
A boolean field indicating whether the card has expired. Use this information to determine if the card is valid for transactions and to notify the customer if necessary.
Presence condition:
- It will only be present if a void action is being processed on the transaction and the voided amount is recorded.
Ottu notifies the webhook_url 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 Operation Webhook page.
Ensure you meet all the endpoint requirements mentioned in the Webhooks Overview here. Additionally, if you want the payer to be finally redirected to your website, ensure your endpoint returns an HTTP status of 200. Any other status will retain the payer on the Ottu payment details page. If you intentionally wish to keep the payer on the Ottu page, return a status code of 201. This will be interpreted by Ottu as a successful notification, and the payer won’t be redirected. Otherwise, Ottu will consider the notification as failed. In cases where you want to redirect the payer to a specific URL after the payment process, ensure you provide the redirect_url during the payment setup. This URL will be used by Ottu to guide the payer back to your platform or any desired page after the payment process is completed. See Webhooks Configuration.
To ensure a smooth redirection of the payer back to the designated redirect_url, it is essential that the
redirect_url
is accurately provided during the payment setup. Additionally, the webhook_url 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:
- status code 200, the customer will be redirected to redirect_url.
- status code 201, the customer will be redirected to Ottu payment summary page.
- status code 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
.png?alt=media&token=f7c7a515-1484-4436-a2eb-7712d7de5fb4)
{
"amount":"0.01",
"amount_details":{
"currency_code":"KWD",
"amount":"0.01",
"total":"0.01",
"fee":"0.00"
},
"currency_code":"KWD",
"customer_email":"[email protected]",
"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":"[email protected]", "phone":"+911111111111"
},
"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"
}
]
}
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).
- If the
result
issuccess
, it means the payment was successful. - If the
result
isfailure
, it indicates an unsuccessful payment attempt. - For cash payments, the
result
field will becod
, 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.
- The amount field provides the value the customer has paid in the currency set during the payment setup.
- However, the actual amount captured by the Payment Gateway (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 amount_details.amount. The currency in which this amount is denominated can be found in amount_details.currency_code.
- 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
.
For Cash on Delivery transactions, the result field will specifically be
cod
. This helps differentiate offline payments from online ones.By understanding and interpreting these fields correctly, you can ensure accurate and timely acknowledgment of all your payments, be they online or offline.
AWebhooks are automated messages sent from Ottu to a specified endpoint when a particular event occurs. They’re useful for real-time notifications, allowing you to automate reactions to events like payment completions or gateway operations without constantly polling our API.
There could be several reasons:
- 1.
- 2.Check that your endpoint meets all the requirements, such as being secure (HTTPS) and having a response time under 25 seconds.
- 3.Verify that your endpoint returns an HTTP status of 200 or 201 to acknowledge receipt.
- 4.If you’re still facing issues, reach out to our support team for assistance.
Ottu uses the SHA-256 signing mechanism to sign all webhook payloads. By verifying the signature attached to each payload, you can ensure its authenticity and integrity. Detailed steps on how to verify the signature can be found here.
Webhooks can be retried, especially in cases of timeouts. It’s essential to make your webhook processing idempotent, meaning processing the same webhook notification more than once should not have a different effect. Always check the event ID or transaction ID to ensure you’re not processing duplicates.
By default, Ottu will retry a webhook three times with a backoff factor of 5 seconds between retries. This behavior can be adjusted in the webhook settings.
Feel free to ask any other questions or provide more context, and we can craft more FAQs accordingly!
Last modified 16d ago