From 8a56ec89da65af9e8234262fd9f0bcad42618484 Mon Sep 17 00:00:00 2001
From: Suliman Awad <suliman.awad@kuwaitnet.email>
Date: Mon, 25 May 2026 13:11:25 +0300
Subject: [PATCH 1/2] add Payment Transaction and Payment Attempt field
 reference pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add docs/business/payment-management/transaction-fields.md — full field
  reference for PaymentTransaction (identifiers, state, amounts with worked
  examples, gateway & routing, customer details, URLs, notifications, misc,
  relationships, and internal fields)
- Add docs/business/payment-management/attempt-fields.md — full field
  reference for PaymentAttempt (identifiers, state, amounts, gateway
  interaction, webhook diagnostics, and internal fields)
- Add both pages to the Payment Management sidebar in sidebars.ts
---
 .../payment-management/attempt-fields.md      | 129 ++++
 .../payment-management/transaction-fields.md  | 593 ++++++++++++++++++
 sidebars.ts                                   |   2 +
 3 files changed, 724 insertions(+)
 create mode 100644 docs/business/payment-management/attempt-fields.md
 create mode 100644 docs/business/payment-management/transaction-fields.md

diff --git a/docs/business/payment-management/attempt-fields.md b/docs/business/payment-management/attempt-fields.md
new file mode 100644
index 0000000..4e39dea
--- /dev/null
+++ b/docs/business/payment-management/attempt-fields.md
@@ -0,0 +1,129 @@
+---
+title: Payment Attempt Fields
+sidebar_label: Attempt Fields
+---
+
+# Payment Attempt Fields
+
+A **payment attempt** is one individual try at completing a payment through a specific [payment gateway](/business/payments/gateways). Each time a customer hits "Pay" — succeeds or fails — Ottu creates a new attempt record. One [payment transaction](/business/payment-management/transaction-fields) can have many attempts (the customer's first card declines, they retry with a different card), but at most one ever reaches a successful state.
+
+Attempt records are where you find the gateway-level detail: which card was used, what the gateway responded, what error the customer saw, and exactly what Ottu sent over to your [webhook](/business/settings/webhooks). When a payment goes wrong, the attempt is where you investigate.
+
+This page lists every field on a payment attempt.
+
+:::tip Looking for the transaction-level fields?
+For fields that belong to the parent [payment transaction](/glossary#term-payment-transaction) — order number, customer details, callback URLs, lifecycle state — see [Payment Transaction Fields](/business/payment-management/transaction-fields).
+:::
+
+---
+
+## Identifiers
+
+### reference_number
+
+A unique identifier for this payment attempt, sent to the payment gateway as the merchant reference. One [transaction](/business/payment-management/transaction-fields#session_id) can have multiple reference numbers — one per attempt.
+
+### transaction
+
+Reference back to the parent [payment transaction](/business/payment-management/transaction-fields) this attempt belongs to.
+
+---
+
+## State & lifecycle
+
+### state
+
+The current status of this payment attempt — whether it is pending, successfully processed, failed, canceled, or encountered an error. Also supports the Cash on Delivery payment method.
+
+### state_changed_at
+
+Timestamp of the most recent state change on this attempt. Useful for measuring how long the customer spent on the gateway and for ordering attempts in support views.
+
+### message
+
+The human-readable error message when the attempt didn't succeed. Sourced from the gateway. Empty for successful attempts.
+
+---
+
+## Amounts
+
+### amount
+
+The amount the gateway was asked to settle for this attempt, in [`currency_code`](#currency_code). For non-editable transactions this equals the [transaction `amount`](/business/payment-management/transaction-fields#amount); for editable ones it's whatever the customer entered before submitting this attempt.
+
+### fee
+
+The [fee](/business/payment-management/transaction-fields#fee) the customer is paying on top of [`amount`](#amount) for this attempt, in the customer's chosen currency.
+
+### total
+
+
+### currency_code
+
+The currency the gateway was charged in. May differ from the parent transaction's currency if the customer chose to pay in a different one — in that case [`exchange_rate`](#exchange_rate) records the conversion used.
+
+### exchange_rate
+
+The conversion rate Ottu used if this attempt involved a currency conversion (i.e. the customer paid in a currency other than the transaction's). 1.0 when no conversion happened. See the [Exchange Rate](/glossary#term-exchange-rate) glossary entry.
+
+---
+
+## Gateway interaction
+
+### settings
+
+
+### card
+
+The card used for this payment attempt.
+
+### gateway_response
+
+The full response received from the payment gateway for this attempt.
+
+---
+
+## Webhook diagnostics
+
+These fields tell you what Ottu delivered to your [webhook URL](/business/settings/webhooks) for this attempt — useful when you can't find a payment notification in your own system.
+
+### disclosed_to_merchant
+
+When true, Ottu successfully delivered a webhook for this attempt. When false, either no webhook was attempted yet, or every delivery attempt failed (see [`disclosure_url_error`](#disclosure_url_error)).
+
+### disclosed_data
+
+The exact payload Ottu posted to your webhook URL. Use this to confirm what was sent if your own system shows different data.
+
+### disclosed_states
+
+A read-only convenience field that pulls just the state values out of [`disclosed_data`](#disclosed_data) — useful when an attempt has been webhooked more than once and you want to see the state at each delivery.
+
+### disclosure_url_error
+
+The error reason logged when Ottu could not reach the merchant webhook URL.
+
+---
+
+## Internal & diagnostic fields
+
+<details>
+<summary>Internal fields (2) — expand to see one-line notes</summary>
+
+### data
+
+Stores useful information for internal purposes.
+
+### request_data
+
+Technical data of the request that triggered this attempt.
+
+</details>
+
+---
+
+## What's Next?
+
+- [Payment Transaction Fields](/business/payment-management/transaction-fields) — fields on the parent transaction
+- [Transaction States](/business/payment-management/transaction-states) — how attempts roll up into the parent state
+- [Webhooks](/business/settings/webhooks) — set up the URL the diagnostic fields above describe
diff --git a/docs/business/payment-management/transaction-fields.md b/docs/business/payment-management/transaction-fields.md
new file mode 100644
index 0000000..d85f6fd
--- /dev/null
+++ b/docs/business/payment-management/transaction-fields.md
@@ -0,0 +1,593 @@
+---
+title: Payment Transaction Fields
+sidebar_label: Transaction Fields
+---
+
+import PaymentObjectModel from '@site/src/components/PaymentObjectModel.mdx';
+
+# Payment Transaction Fields
+
+A **payment transaction** is the top-level record that represents a customer's intent to pay. It carries the order context — amount, currency, allowed gateways, customer details, callback URLs, and lifecycle [state](/business/payment-management/transaction-states) — and it lives from the moment a payment is created until it is paid, expired, canceled, or invalidated. One payment transaction can have many [payment attempts](/business/payment-management/attempt-fields) underneath it, but only one attempt ever succeeds.
+
+This page lists every field you might see on a payment transaction in the dashboard, in a [webhook](/business/settings/webhooks) payload, or in an API response.
+
+<PaymentObjectModel />
+
+:::tip Looking for the per-attempt fields?
+For fields that belong to an individual [payment attempt](/glossary#term-payment-attempt) (the gateway-level retry), see [Payment Attempt Fields](/business/payment-management/attempt-fields).
+:::
+
+---
+
+## Identifiers
+
+### session_id
+
+A unique identifier for the payment transaction, generated by Ottu when the transaction is created. This is the primary identifier you'll use when calling the API, querying status, or correlating webhook events. Always prefer `session_id` over [`reference_number`](#reference_number) when integrating.
+
+### order_no
+
+The merchant's own reference for the order this transaction belongs to (purchase order, cart ID, invoice number, etc.). Set by the merchant when creating the transaction; not changed afterwards. Appears on receipts, in notifications, and as a query parameter on the [`redirect_url`](#redirect_url).
+
+### reference_number
+
+An auto-generated internal identifier for the transaction. Can be used for tracking and reporting, but [`session_id`](#session_id) covers the same use cases and is preferred.
+
+### short_url
+
+A short URL that, when opened, redirects to the checkout page for this payment. Can be shared with the customer to allow them to easily access and complete the payment.
+
+---
+
+## State & lifecycle
+
+### state
+
+The current [status](/business/payment-management/transaction-states) of the transaction — `created`, `pending`, `attempted`, `authorized`, `paid`, `failed`, `canceled`, `expired`, `invalid`, or `cod`. The state is updated automatically as the customer interacts with the checkout and as you perform [operations](/business/operations).
+
+### state_changed_at
+
+The timestamp of the most recent state change. Useful for reconciliation and identifying stale transactions.
+
+### type
+
+The kind of transaction, this is set when the transaction is created and never changes afterwards.
+Its values:
+
+- `e_commerce` — initiated from an external storefront (Shopify, WooCommerce, Magento, custom checkout) via the [E-commerce Payment](/glossary#term-e-commerce-payment) flow.
+- `payment_request` — a merchant-initiated [Payment Request](/glossary#term-payment-request), typically delivered to the customer as a payment link.
+- Other types (`bulk`, `event`, `food_ordering`, …) — set by specific plugins.
+
+### payment_type
+
+How the payment is intended to be charged:
+
+- `one_off` — a single payment with no future commitment.
+- `auto_debit` — used for recurring or scheduled charges; requires an [`agreement`](#agreement) and links the customer's card for future debits. See [recurring payments](/developers/cards-and-tokens/recurring-payments).
+- `save_card` — a zero-amount transaction whose only purpose is to [tokenise](/developers/cards-and-tokens/tokenization) a card for later use.
+
+### operation
+
+Whether the gateway should charge the customer immediately or only hold the funds:
+
+- `purchase` — funds are captured (charged) at the moment of payment.
+- `authorize` — funds are reserved on the customer's card but not captured. The actual charge happens when a [capture](/business/operations) operation is applied.
+
+### expiration_time
+
+How long the transaction stays valid after it's created. The customer must complete payment within this window or the transaction moves to [`expired`](/business/payment-management/transaction-states#parent-states). Defaults to 24 hours; configurable per transaction.
+
+### due_date
+
+The date by which the customer is expected to pay. May be used to help remind the customer to complete the payment before this date. If this passes, the transaction can still be paid — unlike [`expiration_time`](#expiration_time), it does not block payment.
+
+### due_datetime
+
+The date and time by which the payment is due. May be used to help remind the customer to complete the payment before this date and time. If this passes, the transaction can still be paid — unlike [`expiration_time`](#expiration_time), it does not block payment.
+
+### invalidation_reason
+
+If the transaction has moved to the [`invalid`](/business/payment-management/transaction-states#parent-states) state, this field carries a short reason — typically a configuration change (gateway disabled, currency missed) that makes the payment no longer accepted.
+
+### payment_date
+
+The timestamp at which the transaction reached the `paid` state. Empty for transactions that never paid.
+
+---
+
+## Amounts
+
+The amount fields are the most-asked-about part of a payment transaction. This section groups them with a quick-reference table, then a worked example, then definitions.
+
+:::tip Quick reference
+| Field | What it represents | Includes fee? |
+| --- | --- | --- |
+| [`amount`](#amount) | The original amount the transaction was created for | No |
+| [`settled_amount`](#settled_amount) | The amount the customer committed to pay | No |
+| [`paid_amount`](#paid_amount) | The amount actually transferred to the merchant | Yes |
+| [`remaining_amount`](#remaining_amount) | Outstanding balance | No |
+| [`refunded_amount`](#refunded_amount) | Total returned to the customer | No |
+| [`voided_amount`](#voided_amount) | Total released from an authorisation before capture | No |
+| [`fee`](#fee) | Extra amount the customer pays on top | — |
+| [`delivery_fee`](#delivery_fee) | Delivery charge added to catalogue orders | — |
+:::
+
+### Worked examples
+
+**Example A — purchase, no refund.** You sell an item for 100 KWD with a 2 KWD fee. The customer pays the full amount.
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 100   |
+| `paid_amount`      | 102   |
+| `refunded_amount`  | 0     |
+| `voided_amount`    | 0     |
+| `remaining_amount` | 0     |
+
+**Example B — purchase with partial refund.** You sell an item for 100 KWD with a 2 KWD fee. Customer pays, then you refund 30 KWD.
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 100   |
+| `paid_amount`      | 102   |
+| `refunded_amount`  | 30    |
+| `voided_amount`    | 0     |
+| `remaining_amount` | 0     |
+
+**Example C — purchase with full refund.** You sell an item for 100 KWD with a 2 KWD fee. Customer pays, then you refund the full settled amount (the fee is not refunded).
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 100   |
+| `paid_amount`      | 102   |
+| `refunded_amount`  | 100   |
+| `voided_amount`    | 0     |
+| `remaining_amount` | 0     |
+
+**Example D — authorisation with full capture.** You authorise 100 KWD with a 2 KWD fee, then capture the full amount.
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 100   |
+| `paid_amount`      | 102   |
+| `voided_amount`    | 0     |
+| `refunded_amount`  | 0     |
+| `remaining_amount` | 0     |
+
+**Example E — authorisation with partial capture.** You authorise 100 KWD with a 2 KWD fee, then capture only 50 KWD.
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 100   |
+| `paid_amount`      | 50    |
+| `voided_amount`    | 0     |
+| `refunded_amount`  | 0     |
+| `remaining_amount` | 0     |
+
+**Example F — authorisation followed by void.** You authorise 100 KWD with a 2 KWD fee, never capture it, then void. No payment happens, so no fee is charged.
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 100   |
+| `paid_amount`      | 0     |
+| `voided_amount`    | 100   |
+| `refunded_amount`  | 0     |
+| `remaining_amount` | 0     |
+
+**Example G — editable amount, partial payment.** A 100 KWD invoice with a 2 KWD fee and [`is_amount_editable`](#is_amount_editable) on; the customer pays 80 KWD.
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 80    |
+| `paid_amount`      | 82    |
+| `voided_amount`    | 0     |
+| `refunded_amount`  | 0     |
+| `remaining_amount` | 20    |
+
+**Example H — failed payment.** You create a 100 KWD transaction with a 2 KWD fee, but the customer never completes payment (card declined, abandoned checkout, etc.).
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 100   |
+| `fee`              | 2     |
+| `settled_amount`   | 0     |
+| `paid_amount`      | 0     |
+| `voided_amount`    | 0     |
+| `refunded_amount`  | 0     |
+| `remaining_amount` | 100   |
+
+**Example I — save card (zero-amount tokenisation).** You create a transaction with [`payment_type: save_card`](#payment_type) to tokenise the customer's card for later use. The amount must be zero.
+
+| Field              | Value |
+| ------------------ | ----- |
+| `amount`           | 0     |
+| `fee`              | 0     |
+| `settled_amount`   | 0     |
+| `paid_amount`      | 0     |
+| `voided_amount`    | 0     |
+| `refunded_amount`  | 0     |
+| `remaining_amount` | 0     |
+
+### amount
+
+**What it represents:** The total amount the transaction was created for, in the transaction's [`currency_code`](#currency_code). Excludes any [`fee`](#fee) — this is the price of the goods or services itself.
+
+**When it changes:** Set when the transaction is created. Never changes afterwards — not when the customer pays, not when you refund or void.
+
+**How it differs from the others:**
+
+- `amount` is what the merchant **asked for**.
+- [`settled_amount`](#settled_amount) is what the customer **committed to pay** (can be less if the amount is editable).
+- [`paid_amount`](#paid_amount) is what was **actually transferred to the merchant** (includes the fee).
+
+See [Example A](#worked-examples) — `amount = 100`, customer pays in full, `paid_amount` = 102.
+
+### settled_amount
+
+**What it represents:** The amount the customer has committed to pay (paid or authorised), in the transaction's currency. Excludes any [`fee`](#fee).
+
+**When it changes:** Updated when the customer completes payment or authorisation. Stays at zero if the customer never pays.
+
+**How it differs from the others:**
+
+- [`amount`](#amount) is what was asked for. `settled_amount` is what was actually committed.
+- For **non-editable** transactions: `settled_amount` equals `amount` once paid.
+- For **editable** transactions: `settled_amount` equals what the customer entered (may be less than `amount`).
+- [`paid_amount`](#paid_amount) adds the fee on top — `settled_amount + fee` for purchases.
+
+See [Example G](#worked-examples) — editable 100 KWD invoice, customer pays 80, so `settled_amount = 80`.
+
+### paid_amount
+
+**What it represents:** The amount actually transferred to the merchant's bank account, in the transaction's currency. Includes any [`fee`](#fee).
+
+**When it changes:**
+
+- For **purchase** transactions: set once the customer pays.
+- For **authorize** transactions: set when funds are captured. Stays at zero until a capture happens; equals the captured amount (full or partial).
+
+**How it differs from the others:**
+
+- [`amount`](#amount) is what was asked for, [`settled_amount`](#settled_amount) is what was committed — both **exclude** the fee.
+- `paid_amount` is what the merchant actually received — **includes** the fee.
+- For purchases: `paid_amount = settled_amount + fee`.
+- For authorisations: `paid_amount` depends on what was captured, not what was authorised.
+
+See [Example A](#worked-examples) (purchase, `paid_amount = 102`) and [Example D](#worked-examples) (authorise + full capture, also `paid_amount = 102`).
+
+### remaining_amount
+
+**What it represents:** The outstanding balance still due on the transaction, in the transaction's currency. Calculated as `amount − settled_amount`.
+
+**When it changes:** Recalculated automatically whenever [`settled_amount`](#settled_amount) changes (e.g. the customer pays part of an editable invoice).
+
+**How it differs from the others:**
+
+- [`amount`](#amount) is the full price; [`settled_amount`](#settled_amount) is what has been committed so far; `remaining_amount` is whatever is left.
+- Most useful with [editable amounts](#is_amount_editable), where customers can pay in installments.
+- For non-editable transactions: `remaining_amount` equals `amount` before payment, or zero after payment.
+
+See [Example G](#worked-examples) — 100 KWD editable invoice, customer pays 80, so `remaining_amount = 20`.
+
+### refunded_amount
+
+**What it represents:** The total amount returned to the customer, in the transaction's currency. Accumulated across all partial [refunds](/business/operations). Excludes the [`fee`](#fee) — refunds only return the settled amount.
+
+**When it changes:** Increases each time a refund is performed (full or partial). Refunds can be issued back to the original payment method or to the customer's [wallet](/business/wallet#refund-to-wallet).
+
+**How it differs from the others:**
+
+- [`paid_amount`](#paid_amount) includes the fee; `refunded_amount` does not.
+- [`voided_amount`](#voided_amount) is for authorisations rolled back **before** capture; `refunded_amount` is for charges returned **after** payment.
+
+See [Example B](#worked-examples) (partial refund of 30) and [Example C](#worked-examples) (full refund of 100 — the 2 KWD fee is not refunded).
+
+### voided_amount
+
+**What it represents:** The amount released back to the customer when an authorised transaction is voided (rolled back) before any capture happens, in the transaction's currency. Excludes the [`fee`](#fee) — because no payment occurred before the void, no fee was charged.
+
+**When it changes:** Set when a [void operation](/business/operations) succeeds. Only possible on authorised transactions that have never been captured — even a partial capture blocks voids (use a [refund](#refunded_amount) instead).
+
+**How it differs from the others:**
+
+- `voided_amount` is for authorisations rolled back **before** capture; [`refunded_amount`](#refunded_amount) is for charges returned **after** payment.
+- A void releases the entire authorisation — there is no partial void.
+- Once any capture happens, voids are blocked.
+
+See [Example F](#worked-examples) — 100 KWD authorisation never captured, then voided.
+
+### fee
+
+**What it represents:** An additional amount added on top of [`amount`](#amount) that the customer pays. Expressed in the currency the customer chose to pay in, which may differ from the transaction's currency.
+
+**When it changes:** Computed once when the transaction is created. Stays fixed throughout the payment process.
+
+**How it differs from the others:**
+
+- [`amount`](#amount) and [`settled_amount`](#settled_amount) exclude the fee; [`paid_amount`](#paid_amount) includes it.
+- Refunds and voids do not return the fee.
+- Whether a fee applies depends on the [currency configuration](/business/payments/currencies) and the [payment gateway](/business/payments/gateways).
+- [`delivery_fee`](#delivery_fee) is a separate charge for catalogue-based orders only.
+
+See [Example A](#worked-examples) — 100 KWD amount with 2 KWD fee, customer pays 102.
+
+### delivery_fee
+
+The delivery fee for the order. Only applies to catalogue transactions. Unlike [`fee`](#fee), which can apply to any transaction type, `delivery_fee` is specific to catalogue-based plugins.
+
+### currency_code
+
+The currency in which the transaction is denominated. The customer may end up paying in a different currency due to currency conversions or exchanges — see [currencies](/business/payments/currencies).
+
+### is_amount_editable
+
+When true, the customer can modify the payment amount and choose the amount they wish to pay. When false, the amount is fixed at the [`amount`](#amount) the merchant set.
+
+### minimal_amount
+
+---
+
+## Gateway & routing
+
+### pg_codes
+
+A list of [PG Codes](/glossary#term-pg-code) (payment gateway codes) the customer can choose from at checkout. Each code identifies a specific payment gateway. Set at creation time. If only one code is in the list, the checkout skips the gateway-picker step.
+
+### gateway_code
+
+The [payment gateway](/business/payments/gateways) code the customer chose to perform the payment or authorization.
+
+### service_code
+
+The code that identifies the payment service used to perform the payment or authorization. See also [`payment_service`](#payment_service), which identifies the same concept.
+
+### router_identifiers
+
+A list of smart router identifiers, each of which groups a set of payment gateway codes.
+
+### payment_service
+
+The payment service the customer used to make the payment — for example, Apple Pay, Samsung Pay, or Google Pay. See also [`service_code`](#service_code), which identifies the same concept.
+
+### routers_pgmids
+
+A list of all available payment gateway IDs from the routers associated with this transaction.
+
+---
+
+## Customer details
+
+### customer_id
+
+The merchant's unique identifier for this customer, kept consistent across all of that customer's transactions. Used to link saved cards and [auto-debit agreements](#agreement) to a specific customer.
+
+### customer_first_name
+
+The customer's first name, shown on receipts, invoices, and notifications, and sent to the gateway when required.
+
+### customer_last_name
+
+The customer's last name, shown alongside [`customer_first_name`](#customer_first_name) in the same places.
+
+### customer_full_name
+
+A convenience field that combines first and last name. Read-only.
+
+### customer_email
+
+The customer's email address. Used for sending notifications and receipts, and frequently required by the gateway for fraud screening. Always sent to the gateway.
+
+### customer_phone
+
+The customer's primary phone number. May be sent to the gateway and, depending on the gateway, may trigger a click-to-pay flow on the payment page.
+
+### customer_additional_phone
+
+A secondary phone number for the customer. The customer can edit this on the payment page or in the Checkout SDK.
+
+### customer_birthdate
+
+The customer's date of birth, in `YYYY-MM-DD` format. Used by gateways that require age verification or by compliance workflows that need date-of-birth.
+
+### customer_address_line1
+
+The first line of the customer's billing street address. May be sent to the payment gateway.
+
+### customer_address_line2
+
+The second line of the customer's billing street address, if available — for example, an apartment or suite number. May be sent to the payment gateway.
+
+### customer_address_city
+
+The city of the customer's billing address. May be sent to the payment gateway.
+
+### customer_address_state
+
+The state or region of the customer's billing address. May be sent to the payment gateway.
+
+### customer_address_country
+
+The country of the customer's billing address, as a two-letter ISO country code (e.g. `KW`, `US`, `GB`). May be sent to the payment gateway.
+
+### customer_address_postal_code
+
+The postal code of the customer's billing address. May be sent to the payment gateway.
+
+### customer_shipping_address
+
+The customer's shipping address — where the product or service will be delivered. May be used for fraud prevention and displayed on invoices, receipts, and other communications.
+
+---
+
+## URLs & callbacks
+
+### redirect_url
+
+The URL the customer is sent back to after they finish paying. Only used when the webhook delivery is success. Ottu appends [`order_no`](#order_no), [`reference_number`](#reference_number), and [`session_id`](#session_id) as query parameters.
+
+### disclosure_url
+
+The [webhook URL](/business/settings/webhooks) where Ottu sends a POST request with the payment result after the customer completes the payment session. The payment result is included in the request body.
+
+### attachment_url
+
+The full URL where the [`attachment`](#attachment) file can be accessed.
+
+### attachment_short_url
+
+A short URL linking to the attachment associated with this payment. May be included in email or SMS notifications, or displayed on the checkout page for easy access.
+
+### receipt_short_url
+
+A short URL linking to the receipt for this payment. May be included in email or SMS notifications, or displayed on the checkout page for easy access.
+
+---
+
+## Notifications
+
+### notifications
+
+The notification settings for this transaction, including which channels (email, SMS) are used and on which payment events (created, paid, refund, canceled, etc.) notifications are sent.
+
+### email_recipients
+
+A list of email addresses for recipients who will receive email notifications sent to the customer regarding their payment.
+
+### notification_set
+
+
+---
+
+## Misc
+
+### extra
+
+Extra information for the payment, provided by the merchant in key-value form.
+
+### vendor_name
+
+The name of the vendor associated with this payment. May be used for accounting and reporting.
+
+### product_type
+
+The type of product or service being purchased. May be used for tracking and reporting.
+
+### qr_code
+
+A QR code image that, when scanned, opens the checkout page for this transaction. Generated only when QR generation was requested at creation time.
+
+### attachment
+
+An optional file attached to this transaction. Included in email notifications sent to the customer and available for download on the checkout page.
+
+### initiator
+
+The user who created the transaction. Empty when the authentication method is API key.
+
+### company_name
+
+The company name used for the invoice of this transaction.
+
+### language
+
+The language used for all customer-facing communications — the payment page, receipt, invoice, email, SMS, and any other related communications.
+
+### branding_options
+
+Per-payment-method branding customization provided by the merchant, keyed under payment_methods.`{pg_code}`.
+
+### capture_delivery_location
+
+When enabled, the checkout page asks the customer to provide their delivery location on a map.
+
+### capture_delivery_address
+
+When true, the checkout page asks the customer for a full delivery address. Requires [`capture_delivery_location`](#capture_delivery_location) to also be on.
+
+### agreement
+
+The contractual arrangement that lets you charge a customer's stored card later — required when [`payment_type`](#payment_type) is `auto_debit`. Defines whether the card is used for recurring subscriptions, instalments, unscheduled top-ups, or other agreed scenarios. Don't set this if you only want the card on file for the customer to use themselves; use [tokenization](/developers/cards-and-tokens/tokenization) instead.
+
+### card_acceptance_criteria
+
+Defines the rules and conditions a card must meet to be accepted for this transaction. These rules apply whether the customer pays with a saved card or a new one, giving you control over which card types, brands, or issuing countries are allowed. Only applicable for direct payments.
+
+**Example:** You can set criteria to only allow transactions from high-tier credit cards like VISA Platinum, ensuring payments align with the exclusivity of your service.
+
+### is_auto_debit
+
+A flag indicating whether this transaction was set up as an auto-debit.
+
+### parent
+
+If this transaction was created as the result of a [refund, void, or capture](/business/operations), `parent` points back to the original payment.
+
+### bulk
+
+The bulk-upload batch this transaction belongs to.
+
+### bulk_transaction
+
+### booking_event
+
+### attempt_reference
+
+<details>
+<summary>Internal & diagnostic fields (10) — expand to see one-line notes</summary>
+
+### is_sandbox
+
+Marks whether the transaction was created against a sandbox (test) environment. Sandbox transactions don't move real money.
+
+### is_deleted
+
+When true, the transaction has been archived. Archived transactions are hidden from the default views but kept for audit purposes.
+
+### transaction_log_id
+
+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.
+
+### in_es
+
+### email_seen_at
+
+A timestamp indicating when the email notification was seen or opened by the customer or any other guest user.
+
+### seen_at
+
+A timestamp indicating when the payment link was seen or opened by the customer or any other guest user.
+
+### data
+
+Used to store useful information for internal purposes.
+
+### es_id
+
+### parent_es_id
+
+### unit_config
+
+</details>
+
+---
+
+## What's Next?
+
+- [Payment Attempt Fields](/business/payment-management/attempt-fields) — fields on a single gateway-level try
+- [Transaction States](/business/payment-management/transaction-states) — what each `state` value means
+- [Transaction Insights](/business/payment-management/transaction-insights) — see these fields in the dashboard
+- [Operations](/business/operations) — captures, refunds, voids that drive the amount changes above
diff --git a/sidebars.ts b/sidebars.ts
index 8f03ee1..9d342ed 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -597,6 +597,8 @@ const sidebars: SidebarsConfig = {
             "business/payment-management/transaction-insights",
             "business/payment-management/transaction-states",
             "business/payment-management/notifications-timing",
+            "business/payment-management/transaction-fields",
+            "business/payment-management/attempt-fields",
           ],
         },
         {

From 14bd7b928b0e6970c5ab5ad8d7d928cca4c87a9c Mon Sep 17 00:00:00 2001
From: Suliman Awad <suliman.awad@kuwaitnet.email>
Date: Mon, 25 May 2026 15:01:27 +0300
Subject: [PATCH 2/2] apply review notes on Payment Transaction field reference

- Fix grammar in `redirect_url` description and clarify when it is used
- Rename `disclosure_url` heading to `webhook_url` to match the API parameter name
- Clarify that `customer_shipping_address` is a structured object with sub-fields
- Split a comma splice in the `type` field description
- Pull internal & diagnostic fields out of the trailing list into their own section
---
 .../payment-management/transaction-fields.md       | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/business/payment-management/transaction-fields.md b/docs/business/payment-management/transaction-fields.md
index d85f6fd..81f08f8 100644
--- a/docs/business/payment-management/transaction-fields.md
+++ b/docs/business/payment-management/transaction-fields.md
@@ -51,8 +51,7 @@ The timestamp of the most recent state change. Useful for reconciliation and ide
 
 ### type
 
-The kind of transaction, this is set when the transaction is created and never changes afterwards.
-Its values:
+The kind of transaction. This is set when the transaction is created and never changes afterwards. Its values:
 
 - `e_commerce` — initiated from an external storefront (Shopify, WooCommerce, Magento, custom checkout) via the [E-commerce Payment](/glossary#term-e-commerce-payment) flow.
 - `payment_request` — a merchant-initiated [Payment Request](/glossary#term-payment-request), typically delivered to the customer as a payment link.
@@ -429,7 +428,7 @@ The postal code of the customer's billing address. May be sent to the payment ga
 
 ### customer_shipping_address
 
-The customer's shipping address — where the product or service will be delivered. May be used for fraud prevention and displayed on invoices, receipts, and other communications.
+The customer's shipping address — where the product or service will be delivered. A structured object with sub-fields (`line1`, `line2`, `city`, `state`, `country`, `postal_code`). May be used for fraud prevention and displayed on invoices, receipts, and other communications.
 
 ---
 
@@ -437,9 +436,9 @@ The customer's shipping address — where the product or service will be deliver
 
 ### redirect_url
 
-The URL the customer is sent back to after they finish paying. Only used when the webhook delivery is success. Ottu appends [`order_no`](#order_no), [`reference_number`](#reference_number), and [`session_id`](#session_id) as query parameters.
+The URL the customer is sent back to after they finish paying. Only used when the webhook delivery is successful. Ottu appends [`order_no`](#order_no), [`reference_number`](#reference_number), and [`session_id`](#session_id) as query parameters.
 
-### disclosure_url
+### webhook_url
 
 The [webhook URL](/business/settings/webhooks) where Ottu sends a POST request with the payment result after the customer completes the payment session. The payment result is included in the request body.
 
@@ -469,7 +468,6 @@ A list of email addresses for recipients who will receive email notifications se
 
 ### notification_set
 
-
 ---
 
 ## Misc
@@ -546,6 +544,10 @@ The bulk-upload batch this transaction belongs to.
 
 ### attempt_reference
 
+---
+
+## Internal & diagnostic fields
+
 <details>
 <summary>Internal & diagnostic fields (10) — expand to see one-line notes</summary>