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.
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.
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.
Using Plugin Config: Set the webhook_url and redirect_url globally via the plugin config, applicable to either E-Commerce or Payment request 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 here.
Endpoint Requirements:
Ensure your endpoint adheres to all the stipulations outlined in the Webhook Overview. To review the requirements, click here.
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.
Specific Redirects: If you have a particular URL to which you wish to redirect the payer after the payment process, ensure you specify the redirect_url during the payment setup. Ottu will use this URL to navigate the payer back to your platform or any designated page post-payment.
A unique identifier for the agreement established with the payer. This ID links to the specific terms and conditions the payer has authorized for processing their stored card details. Use cases include:
Installment Payments: Multiple charges for a single purchase over time.
Unscheduled: Future payments as required, e.g., account top-ups.
Industry Practice: Standard business practices related to an original payment, e.g., hotel charges after checkout.
Possible values:<= 128 characters
max_amount_per_cyclestring<decimal>
The maximum amount for a single payment in the series as agreed with the payer.
seller object
Details about the retailer, if the agreement is for installment payments.
category_codestring
A 4-digit code classifying the retailer's business by the type of goods or services it offers.
Possible values:<= 64 characters
namestring
The retailer's trading name.
Possible values:<= 128 characters
short_namestring
Abbreviation of the retailer's trading name, suitable for payer's statement display.
Possible values:<= 64 characters
start_datestring<date>
Date on which the agreement with the payer to process payments starts.
total_cyclesinteger
The number of merchant-initiated payments within the recurring payment agreement.
Possible values:>= 1 and <= 999
typestring
The type of commercial agreement that the payer has with the merchant.
Note: For unscheduled agreements, the allowed values should be configured as follows:
id - Accepts any value.
frequency.
type.
This configuration ensures that only specific values are permitted for each field when the type is Unscheduled.
Note: For recurring agreements, the following fields are mandatory as follows:
amount_variability
cycle_interval_days
expiry_date
requency`
id
total_cycles
This configuration ensures that the required values are mandatory for each field when the type is Recurring.
event_based - Event Based
installment - Installment
recurring - Recurring
unscheduled - Unscheduled
other - Other
Possible values: [event_based, installment, recurring, unscheduled, other]
Default value: recurring
amountstringrequired
Denotes the total sum of the payment transaction, which encompasses the cost of the procured items or services, excluding any supplementary fees or charges.
amount_details objectrequired
A comprehensive set of amount details includes: Currency Code, Amount, Total, Fee.
amountstring
Represents the total amount of the payment transaction, which includes the cost of the purchased items or services but excludes any additional fees or charges
Possible values:<= 120 characters
currency_codestringrequired
exchange_ratestring
The conversion rate used for currency conversion during payment. This value reflects the rate locally calculated.
feestringrequired
The Fee indicates the sum disbursed by the customer in their chosen currency for the payment. Note, this currency could vary from the currency used for the transaction.
totalstringrequired
Denotes the comprehensive total of the payment transaction, incorporating both the principal amount and any associated fees.
capture_delivery_addressboolean
By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active.
By enabling this, you will ask for user's delivery location on a map.
card_acceptance_criteria objectrequired
This field allows you to define specific rules and conditions that a card must meet to be eligible for payment. These stipulations apply regardless of whether a customer chooses to pay using a saved card or opts to add a new card for the transaction. By leveraging the card_acceptance_criteria, you gain the power to fine-tune your payment processing strategy, tailoring acceptance rules to align with your business needs, security standards, and risk management policies.
Example: If you run an exclusive service that caters predominantly to premium customers, you might set criteria that only allow transactions from high-tier credit cards like VISA Platinum. This ensures that payments align with the exclusivity and branding of your services. Remember to configure these criteria thoughtfully. Striking the right balance between security, risk mitigation, and user experience is paramount.
Note: The card_acceptance_criteria field is applicable only for direct payments and not for hosted session payments.
min_expiry_timeinteger
Specifies the minimum required validity period, in days, for a card to be eligible for payment. If set to 30 days, for example, cards set to expire within the next month would be declined. This ensures short-lived cards nearing their expiration date are filtered out, reducing chances of payment failures. When implementing, balance your operational needs with customer convenience. Setting it too stringent might increase payment declines, while a lenient approach could risk future payment failures.
Additionally, it defaults to 30 days when the payment_type is auto_debit. If any other payment type is selected, no default value is set.
Possible values:>= 1 and <= 365
currency_codestringrequired
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.
Possible values:>= 3 characters and <= 3 characters
customer_address_citystring
The city of the customer's billing address. This field may be used to send the billing address to the payment gateway.
Possible values:<= 40 characters
customer_address_countrystringrequired
The country of the customer's billing address, formatted as a two-letter ISO country code (e.g., 'US' for United States, 'CA' for Canada). This field may be used to send the billing address to the payment gateway.
Possible values:>= 2 characters and <= 2 characters
customer_address_line1Customer address line 1 (string)
The first line of the customer's billing street address. This field may be used to send the billing address to the payment gateway.
customer_address_line2Customer address line 2 (string)
The second line of the customer's billing street address, if available. This field may be used to provide additional address information, such as an apartment or suite number.
customer_address_postal_codestring
The postal code of the customer's billing address. This field may be used to send the billing address to the payment gateway.
Possible values:<= 12 characters
customer_address_statestring
The state or region of the customer's billing address. This field may be used to send the billing address to the payment gateway.
Possible values:<= 40 characters
customer_birthdatestring,null<date>nullable
The customer's date of birth in ISO format (YYYY-MM-DD).
customer_emailstring
The email address of the customer that is used to send payment notifications and receipts, and can be used for fraud prevention. This field is mandatory and is always sent to the payment gateway. It may also be included in the invoice, receipt, email, and displayed on the payment page.
Possible values:<= 128 characters
customer_first_namestring
The first name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.
Possible values:<= 64 characters
customer_idstring
The customer ID is a unique identifier for the customer within the merchant's system. It is also used as a merchant identifier for the customer and plays a critical role in tokenization. All the customer's cards will be associated with this ID.
Possible values:<= 64 characters
customer_last_namestring
The last name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.
Possible values:<= 64 characters
customer_phonestring
Customer phone number associated with the payment. This might be sent to the payment gateway and depending on the gateway, it may trigger a click to pay process on the payment page. The phone number will also be included in the invoice, receipt, email, and displayed on the payment page.
Possible values:<= 32 characters
extra
The extra information for the payment details, which the merchant has sent it in key value form.
feestringrequired
The fee denotes the sum the customer pays in their chosen payment currency. This may vary from the transaction's designated currency. The fee is computed once to maintain precision and uniformity throughout the payment procedure.
gateway_accountstringrequired
This code corresponds to the payment gateway and plays an essential role in facilitating payment transactions.
gateway_namestringrequired
The name of the payment gateway service being utilized.
gateway_response objectrequired
This field stores the processed response received from the payment gateway and forwarded to Ottu.
property name*any
This field stores the processed response received from the payment gateway and forwarded to Ottu.
initiator object
The user who initiated the creation of this payment transaction, if available. This field is optional and may be used to track who created the payment transaction. Note that if the payment transaction was using API Key auth initiator_id can be set to any value that corresponds to an existing ACTIVE user in the system
emailstring<email>required
Possible values:<= 254 characters
first_namestring
Possible values:<= 32 characters
idintegerrequired
last_namestring
Possible values:<= 32 characters
phonePhone number (string)
Possible values:<= 128 characters
usernamestringrequired
Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
Possible values:<= 150 characters, Value must match regular expression ^[\w.@+-]+$
is_sandboxIs Sandbox? (boolean)
Indicates whether the operation was performed in a test environment or not.
messagestringrequired
This represents the message, either transmitted by the Payment Gateway (PG) or established by Ottu, that provides a detailed illustration of the payment's current status.
order_nostring | nullnullable
The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.
Possible values:<= 128 characters
paid_amount objectrequired
The paid amount encompasses fees or captured amounts from authorized transactions. This total is derived from the specified 'amount' field, converting foreign currencies to the default as necessary. This might result in minor variations due to fluctuations in exchange rates.
oneOf
number
string
number
string
payment_typestring
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.
Choose save_card if you want to perform a card tokenization operation.
NOTE: If auto_debit is selected:
agreement and customer_id parameters will also be mandatory.
Only PG codes supporting tokenization 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.
NOTE: If save_card is selected:
The amount must be zero for the save card operation.
The selected MID(pg_code) must support tokenization to enable the save card operation.
Please note that the save card operation is considered successful without any funds being charged.
Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.
When the transaction type is save_card, all previously saved cards returned in the sdk_preload_payload should be hidden since the user is saving a new card and does not need to select from existing ones.
one_off - One Off
auto_debit - Auto Debit
save_card - Save Card
Possible values: [one_off, auto_debit, save_card]
pg_params objectrequired
Normalized payment gateway response parameters. Ottu maps varied PG responses into these fixed fields, so you can interpret payment results consistently regardless of which gateway processed the transaction. Use these fields instead of parsing the raw gateway_response object.
auth_code
Authorization code returned by the payment gateway for the transaction.
card_details
Additional card details object as returned by the payment gateway.
card_expiry
Card expiry date in a gateway-specific format.
card_expiry_month
Expiry month of the card (e.g., "01", "12").
card_expiry_year
Expiry year of the card (e.g., "2025", "25").
card_holder
Full name of the cardholder as provided by the payment gateway.
card_issuer
The issuing bank or financial institution of the card.
card_number
Masked card number (PAN) used for the transaction (e.g., "411111******1111").
card_type
The type of card used (e.g., "credit", "debit", "prepaid").
cardholder_email
Email address of the cardholder, if provided by the payment gateway.
dcc_payer_amount
The amount in the payer's currency when Dynamic Currency Conversion (DCC) is applied.
dcc_payer_currency
The payer's local currency code when DCC is applied (e.g., "USD", "EUR").
dcc_payer_exchange_rate
The exchange rate applied for DCC conversion.
decision
The gateway's final decision on the transaction (e.g., "ACCEPT", "REJECT", "REVIEW").
full_card_expiry
Full card expiry in MM/YY or MM/YYYY format, as returned by the gateway.
payment_id
Payment identifier from the payment gateway, used for tracking and reconciliation.
pg_message
Human-readable message from the payment gateway describing the transaction outcome.
post_date
The date the transaction was posted/settled by the payment gateway.
receipt_no
Receipt number generated by the payment gateway for the transaction.
ref
Gateway-specific reference identifier for the transaction.
result
The normalized transaction result from the payment gateway (e.g., "CAPTURED", "APPROVED", "DECLINED").
rrn
Retrieval Reference Number — a unique identifier used for transaction lookups and dispute resolution.
track_id
Tracking identifier assigned by the payment gateway for reconciliation.
transaction_id
Unique transaction identifier assigned by the payment gateway.
transaction_no
Transaction number assigned by the gateway, often different from transaction_id.
reference_numberstringrequired
refunded_amountnumber<double>
The total refunded amount for the payment transaction.
remaining_amountnumber<double>required
The residual amount due. Together with the editable amount, it indicates the outstanding balance of a transaction awaiting settlement.
resultstringrequired
Indicates the outcome of the operation. success denotes a successful operation.
Possible values: [pending, success, failed, canceled, error, cod]
session_idstring
A unique identifier for each payment transaction, used to maintain the session state during the payment process.
Possible values:<= 128 characters
settled_amountnumber<double>required
The amount that has been paid or authorized in its original currency, excluding any fees.
signaturestringrequired
Signature Field: 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.
statestringrequired
timestamp_utcstring<date-time>required
This field 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.
token object
Represents token details, only if the user pays with a tokenized card, Ottu will include the token details in the response.
agreementsrequired
List of agreements associated with this card.
brandstring | nullnullablerequired
The card brand (e.g., Visa, Mastercard) associated with the card. Display this information for customer reference.
Possible values:<= 32 characters
customer_idstringrequired
The unique identifier for the customer who owns the card
Possible values:<= 36 characters
cvv_requiredbooleanrequired
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.
expiry_monthstringrequired
The card's expiration month. Provide this information for transaction processing and validation.
Possible values:<= 2 characters
expiry_yearstringrequired
The card's expiration year. Provide this information for transaction processing and validation.
Possible values:<= 2 characters
is_expiredbooleanrequired
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.
is_preferredbooleanrequired
Indicates if the card is the customer's preferred payment option. Order cards with this attribute set to true at the top of the list for easy access.
name_on_cardstring | nullnullablerequired
The cardholder's name as it appears on the card. Display this information for customer verification.
Possible values:<= 64 characters
numberstring | nullnullablerequired
The masked card number to be displayed, ensuring customer privacy and security while providing essential information.
Possible values:<= 19 characters
pg_codestringrequired
The pg_code associated with the card's creation.
pg_namestringrequired
The payment gateway associated with the user's card. The available values depend on the gateways configured for your merchant account.
tokenstringrequired
The unique token associated with the card, required for tokenized card payments. Use this value to securely process transactions.
Possible values:<= 50 characters
transaction_log_idinteger | nullnullable
Identifies the transaction log associated with the payment transaction. A transaction log is created for each record that is dispatched during a bulk dispatch process.
Possible values:>= 0 and <= 2147483647
transactions object[]
A list of dictionaries is generated, each containing a concise summary of each child payment transaction that has been created.
Array [
amountstringrequired
currency_codestringrequired
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.
Possible values:>= 3 characters and <= 3 characters
order_nostring | nullnullable
The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.
Possible values:<= 128 characters
session_idstring
A unique identifier for each payment transaction, used to maintain the session state during the payment process.
Possible values:<= 128 characters
statestring
The current state of the payment transaction, it helps to understand the progress of the payment.
paid - paid
refunded - refunded
refund_queued - refund_queued
refund_rejected - refund_rejected
voided - voided
Possible values: [paid, refunded, refund_queued, refund_rejected, voided]
]
voided_amountnumber<double>
The total voided amount for the payment transaction.
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.
info
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.
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
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:
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.
Every webhook payload includes a signature field — an HMAC-SHA256 hash that proves the payload came from Ottu and hasn’t been tampered with. Always verify this signature before processing the payment.
For implementation details and code examples in Python, PHP, Node.js, Java, C#, Ruby, and Go, see Verify Signatures.
danger
Never process a payment webhook without verifying the signature. An unverified payload could be forged by an attacker.
The pg_params object contains normalized payment gateway response fields. Instead of parsing the raw gateway_response (which varies by gateway), use pg_params for consistent field access across all 60+ gateways.
For the complete searchable reference of all fields, see PG Params.
Why pg_params matters
Ottu normalizes responses from all payment gateways into fixed fields. This means you can switch gateways — from KNET to MPGS to Cybersource — without changing a single line of your webhook handling code. Instead of parsing each gateway’s unique response format, just read from pg_params.
For general webhook setup and configuration, see the Webhooks Overview.
