diff --git a/.claude/skills/svg-diagram/SKILL.md b/.claude/skills/svg-diagram/SKILL.md new file mode 100644 index 00000000..11473824 --- /dev/null +++ b/.claude/skills/svg-diagram/SKILL.md @@ -0,0 +1,120 @@ +--- +name: svg-diagram +description: >- + Create or update a documentation diagram for the Ottu docs as a single, + hand-built, theme-aware inline SVG rendered through the React + component. This is the PRIMARY way to make any docs diagram — architecture + diagrams, payment/data flows, sequence-style flows, system overviews, "how it + works" visuals. Use it whenever the user asks to add, create, draw, design, + build, illustrate, or visualize a diagram, flow, architecture, or system + picture on a docs page — even if they don't say "SVG" — and whenever they ask + to replace, upgrade, or restyle an existing Mermaid diagram. Mermaid is now + only a fallback left over from content migration; prefer this skill and + convert Mermaid diagrams to inline SVG as you encounter them. Also triggers on + "diagram for this page", "make this look better", or "we need a visual here". +--- + +# Ottu SVG Diagram + +Produce documentation diagrams as **a single, hand-built, theme-aware inline SVG** — premium, restrained, on-brand. The diagram renders *in the page DOM* (via the `` component), so it inherits the site's **Poppins** font and switches light/dark instantly with the page. One file, no ``, no second file to keep in sync. + +The diagrams on `/overview/architecture/` and `/developers/payments/wallet/` are the bar. New diagrams match them; Mermaid diagrams get converted to this style over time. + +**What you deliver:** one inline SVG (scoped + dual-theme), embedded in a tiny `src/diagrams/.tsx` module, rendered on the page with ``. + +## Why inline SVG (and not Mermaid, and not ``) + +- **Not Mermaid:** Mermaid auto-lays-out nodes and can't render Poppins without overflow, so it's locked to a generic look. Hand-built SVG gives full control over composition, type, and the palette — the point of a *premium* diagram. Mermaid stays a quick fallback but is being phased out. +- **Not ``/ThemedImage:** an ``-loaded SVG is an isolated document — it can't use the page's Poppins and can't react to the theme toggle, which forces a second dark file. Rendering the SVG **inline** (in the DOM) is the frontend best practice: one file, true Poppins, instant CSS theme switch, nothing to drift. + +## The aesthetic, in one line + +> **Almost everything is grey. Blue is a spotlight, not a paint job.** + +Most nodes are neutral scaffolding; only the 1–2 nodes the diagram is *about* get Ottu blue (`#0B82BE`). Stripe docs / Apple keynote, not a rainbow flowchart. The locked palette, fonts, and shape grammar live in [`references/design-tokens.md`](references/design-tokens.md) — read it before choosing any colour or font. + +## Workflow + +### 1. Understand the flow before drawing it + +A diagram is a teaching tool, not decoration. Pin down: the **actors/pieces** (respect the payment-domain roles in the repo `CLAUDE.md` — merchant calls APIs, customer only touches checkout UI, Ottu sits between merchant and gateway); the **direction** (usually left-to-right); the **ONE thing to notice** (the 1–2 Ottu pieces that become the accent nodes); and **what to leave out** (status codes, retries, protocol minutiae belong in prose beside the diagram). If the request is vague, read the surrounding page and let the prose tell you what to illustrate. + +### 2. Design pass — borrow the eye of `frontend-design`, keep Ottu's rails + +Invoke the **`frontend-design`** skill for the composition judgement: hierarchy, alignment, balance, whitespace, the "is this actually premium?" eye. But it defaults to **bold, grid-breaking, anti-Inter maximalism**, which would shatter a brand-locked system — so hold the rails firm: + +- **Palette is locked** to the Ottu tokens — `#0B82BE` accent, neutral greys, `#ED2833` for genuine risk only. No new hues, no gradients. +- **Font is locked** to Poppins. +- **The aesthetic is refined restraint**, which `frontend-design` explicitly supports ("Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details"). That's the part you want. + +**`frontend-design` supplies the eye; Ottu's tokens supply the rails. Apply the craft *within* the constraints.** + +### 3. Author the light SVG + +Start from [`assets/template.svg`](assets/template.svg) — root element, accessibility block, the single shared arrow marker, and the light ` + + + + + + + OTTU PLATFORM + + + + Merchant Backend + Your server + + + + Ottu Service + Api-Key auth + + + + Downstream + e.g. gateway + + + + + REST call + + + + routes + + + + + webhook + diff --git a/.claude/skills/svg-diagram/evals/evals.json b/.claude/skills/svg-diagram/evals/evals.json new file mode 100644 index 00000000..5024e4e9 --- /dev/null +++ b/.claude/skills/svg-diagram/evals/evals.json @@ -0,0 +1,47 @@ +{ + "skill_name": "svg-diagram", + "notes": "Baseline = no skill (creating a new skill). Each eval is a realistic docs-author request covering one core use case: build-from-prose (small, security-flavored), convert-an-existing-Mermaid, and synthesize-a-large-end-to-end. The shared expectations encode the skill's hard invariants; eval-specific ones check task fidelity. Subjective quality (composition, premium feel, right accent choice) is judged in the human review viewer, not asserted here.", + "shared_expectations": [ + "Produced both a light and a dark SVG file", + "Both SVGs are well-formed XML", + "Light and dark differ only inside the + + + + Merchant Backend + + + Tokenization API + Api-Key auth + + + Gateway Vault + PCI-compliant + + + + + store + +``` + +Run `scripts/inline-svg.py ` on it, drop the result into a `src/diagrams/.tsx` module, and render it with `` — one file, theme-aware. diff --git a/.claude/skills/svg-diagram/references/svg-conventions.md b/.claude/skills/svg-diagram/references/svg-conventions.md new file mode 100644 index 00000000..49d96445 --- /dev/null +++ b/.claude/skills/svg-diagram/references/svg-conventions.md @@ -0,0 +1,154 @@ +# SVG Conventions + +How an Ottu diagram is structured. The palette lives in `design-tokens.md`; this file is the *skeleton* — the root element, accessibility, the arrow marker, the building blocks, and how the finished SVG gets delivered inline. + +**You author a clean, light-only SVG** (plain class names, a plain ` + +``` + +The arrowhead's colour comes from the `.arrow-head` **class** (so the dark override restyles it for free). Author `id="arrow"` plainly; `inline-svg.py` renames it to `arrow-` and rewrites the `url(#arrow)` references. + +## Building blocks + +Assemble from these. Coordinates are illustrative — align columns and rows deliberately. + +### Boundary container (draw first, behind the nodes) + +```xml + +OTTU PLATFORM +``` + +### External actor (pill) + +```xml + +Customer +``` + +### Service node (title + subtitle) + +```xml + +Merchant Backend +Your server +``` + +### The accent node — the one the diagram is about + +```xml + +REST API +Api-Key · Basic auth +``` + +Text on a filled `accent`/`danger` node uses the `-white` classes. A node is `accent` **only** if it's the focal point — see the colour budget in `design-tokens.md`. + +### A multi-line list node (e.g. a gateway with examples) + +```xml + +Payment Gateway + +KNET ++ 40 more +``` + +### Solid arrow with a label chip + +```xml + + +REST calls +``` + +Size the chip to the text (~`7px × characters`) and centre it on the line's midpoint so the rule doesn't strike through the words. + +### Async / return arrow (dashed) + +```xml + +``` + +Use a gentle curve for long return paths so they sweep around the diagram instead of cutting through it. + +## Text legibility rules + +- **Centre** labels with `text-anchor="middle"` at the node's centre; title baseline ≈ `y + 30` of a 70-tall node, subtitle ≈ `y + 50`. +- Titles ~2–3 words, subtitles one short line. If a node needs a paragraph, it's two nodes. +- Never let text overflow — widen the node or shorten the text. SVG `` doesn't wrap. + +## Making it inline-ready, then delivering it + +After the light SVG is final: + +```bash +python .claude/skills/svg-diagram/scripts/inline-svg.py .svg +``` + +This prints the finished inline SVG: root class `ottu-dgm--`, ids suffixed, every selector scoped, and a `[data-theme='dark']` override block appended. Then embed it: + +```tsx +// src/diagrams/WebhookSigning.tsx +import React from "react"; +import Diagram from "@site/src/components/Diagram"; + +const SVG = String.raw`…inline-svg.py output…`; + +export default function WebhookSigning(): React.JSX.Element { + return ; +} +``` + +```mdx +import WebhookSigning from '@site/src/diagrams/WebhookSigning'; + + +``` + +`` renders the SVG inline (in the page DOM) so it gets Poppins and theme-switching. Pass an optional `caption` for a small line under the diagram. + +## Self-check before delivering + +- [ ] `python -c "import xml.dom.minidom,sys; xml.dom.minidom.parse(sys.argv[1])" ` parses — well-formed. +- [ ] `` and `` are present and descriptive; `role="img"` is set. +- [ ] Font is Poppins everywhere; the string `Inter` appears nowhere. +- [ ] Every selector is scoped under `.ottu-dgm--`, and the `)", re.DOTALL) +RULE_RE = re.compile(r"^(\s*)\.([\w-]+)(\s*\{.*\})\s*$") +ID_DEF_RE = re.compile(r'\bid="([^"]+)"') +ROOT_SVG_RE = re.compile(r"]*?>", re.DOTALL) + + +def uniquify_ids(svg: str, slug: str) -> str: + ids = set(ID_DEF_RE.findall(svg)) + for old in sorted(ids, key=len, reverse=True): # longest first, avoid partial hits + new = f"{old}-{slug}" + svg = re.sub(rf'\bid="{re.escape(old)}"', f'id="{new}"', svg) + svg = svg.replace(f"url(#{old})", f"url(#{new})") + svg = re.sub(rf'((?:xlink:)?href=")#{re.escape(old)}(")', rf"\1#{new}\2", svg) + + def fix_labelledby(m: re.Match) -> str: + toks = [f"{t}-{slug}" if t in ids else t for t in m.group(1).split()] + return f'aria-labelledby="{" ".join(toks)}"' + + return re.sub(r'aria-labelledby="([^"]+)"', fix_labelledby, svg) + + +def add_scope_class(svg: str, scope: str) -> str: + def repl(m: re.Match) -> str: + tag = m.group(0) + cm = re.search(r'\bclass="([^"]*)"', tag) + if cm: + return tag.replace(cm.group(0), f'class="{cm.group(1)} {scope}"') + return tag[:-1] + f' class="{scope}"' + tag[-1] + + return ROOT_SVG_RE.sub(repl, svg, count=1) + + +def scope_and_theme_style(inner: str, scope: str) -> tuple[str, list[str]]: + """Return (rescoped+dual-theme style inner, classes with no dark override).""" + light_lines: list[str] = [] + classes: list[str] = [] + for line in inner.splitlines(): + m = RULE_RE.match(line) + if not m: + light_lines.append(line) + continue + indent, name, body = m.groups() + light_lines.append(f"{indent}.{scope} .{name}{body}") + classes.append(name) + + dark_lines = [" /* dark theme — overrides only what changes */"] + for name in classes: + if name in DARK_OVERRIDES: + dark_lines.append( + f" [data-theme='dark'] .{scope} .{name} {{ {DARK_OVERRIDES[name]} }}" + ) + style = "\n".join(light_lines) + "\n\n" + "\n".join(dark_lines) + "\n " + unthemed = [n for n in dict.fromkeys(classes) + if n not in DARK_OVERRIDES and n not in THEME_INDEPENDENT] + return style, unthemed + + +def main(argv: list[str]) -> int: + if not (3 <= len(argv) <= 4): + print(__doc__) + return 2 + src = Path(argv[1]) + slug = argv[2] + if not re.fullmatch(r"[a-z0-9][a-z0-9-]*", slug): + print(f"error: slug must be kebab-case (got {slug!r})", file=sys.stderr) + return 1 + if not src.is_file(): + print(f"error: input not found: {src}", file=sys.stderr) + return 1 + + scope = f"ottu-dgm--{slug}" + svg = src.read_text(encoding="utf-8") + + if re.search(r"['\"]inter['\"]", svg, re.I): + print("⚠ input uses the Inter font — switch it to Poppins before inlining.", + file=sys.stderr) + + svg = uniquify_ids(svg, slug) + svg = add_scope_class(svg, scope) + + m = STYLE_RE.search(svg) + if not m: + print("error: no + + + + + OTTU PLATFORM + + + + Customer + + + + Merchant Frontend + Website or mobile app + + + + Merchant Backend + Your server + + + + Checkout SDK + Web · iOS · Android · Flutter + + + + REST API + Api-Key · Basic auth + + + + Orchestration Engine + Smart routing · Failover + + + + Webhooks + HMAC-SHA256 signed events + + + + Payment Gateway + + KNET + MPGS + Cybersource + Tabby · Tamara + STC Bank · Benefit + + 40 more gateways + + + + + enters card + + + + embeds + + + + REST calls + + + + + + + + routes + + + + HMAC events +`; + +export default function ArchitectureDiagram(): React.JSX.Element { + return ( + + ); +} diff --git a/src/diagrams/RecurringFlow.tsx b/src/diagrams/RecurringFlow.tsx new file mode 100644 index 00000000..7f7ebcfe --- /dev/null +++ b/src/diagrams/RecurringFlow.tsx @@ -0,0 +1,147 @@ +import React from "react"; +import Diagram from "@site/src/components/Diagram"; + +/** + * Recurring payments (auto-debit) flow: CIT setup vs MIT charge. + * + * Single inline, theme-aware SVG generated by the `svg-diagram` skill + * (scripts/inline-svg.py, slug "recurring-flow"). Scoped ` + + + + CIT · CUSTOMER PRESENT + MIT · NO CUSTOMER + + + + OTTU PLATFORM + + + + Checkout Page + Ottu or self-hosted + + + + Customer + + + + Merchant Backend + Your server + + + + Checkout API + Creates CIT & MIT sessions + + + + Ottu + Processes payment · webhooks + + + + Native Payments API + Charge saved token + + + + + + create session + + + + + redirect to checkout + + + + + enters card · pays + + + + + submit payment + + + + + Ottu webhook · token (async) + + + + + + session_id (MIT) + + + + + charge saved token · MIT + + + + + payment result (direct) +`; + +export default function RecurringFlow(): React.JSX.Element { + return ( + + ); +} diff --git a/src/diagrams/WalletFlowDiagram.tsx b/src/diagrams/WalletFlowDiagram.tsx new file mode 100644 index 00000000..819df17f --- /dev/null +++ b/src/diagrams/WalletFlowDiagram.tsx @@ -0,0 +1,131 @@ +import React from "react"; +import Diagram from "@site/src/components/Diagram"; + +/** + * Ottu wallet refund/reserve flow diagram. + * + * Single inline, theme-aware SVG generated by the `svg-diagram` skill + * (scripts/inline-svg.py, slug "wallet-flow"). Scoped ` + + + + + OTTU PLATFORM + + + + Customer + + + + Merchant Frontend + Embeds Checkout SDK + + + + Merchant Backend + Refund · Session create + + + + Checkout SDK + Reserves · Commits · Releases + + + + Ottu Connect + REST API · Operation routing + + + + Wallet Service + Ledger · Reservations · Balance + + + + Refund destination + "pg" (default) · "wallet" + + + + Payment Gateway + Charges remainder + when wallet + doesn't cover + Refund reverses here + when destination = "pg" + + + + + pays at checkout + + + + embeds + + + + refund · session + + + + reserve / commit + + + + credit / debit + + + + remainder + + + + balance shown +`; + +export default function WalletFlowDiagram(): React.JSX.Element { + return ( + + ); +} diff --git a/src/theme/ApiExplorer/Authorization/index.tsx b/src/theme/ApiExplorer/Authorization/index.tsx index ae6ddb08..86776a2b 100644 --- a/src/theme/ApiExplorer/Authorization/index.tsx +++ b/src/theme/ApiExplorer/Authorization/index.tsx @@ -12,7 +12,9 @@ import React, { Fragment, useEffect } from "react"; const DEFAULT_USERNAME = "demo_user"; const DEFAULT_PASSWORD = "WY4Q9I1d5kHH3nJ"; -const DEFAULT_API_KEY = "GYj5Na8H.29g9hqNjm11nORQMa2WiZwIBQQ49MdAL"; +// Public demo key on ksa.ottu.dev. Bare key only — the explorer prepends +// the "Api-Key " prefix when it builds the Authorization header. +const DEFAULT_API_KEY = "uUjUqczM.P5PqlXx8zyuFUQVk19PLxfHBZu8rG4Uy"; export default function Authorization(): React.JSX.Element | null { const data = useTypedSelector((state: any) => state.auth.data); @@ -203,7 +205,7 @@ export default function Authorization(): React.JSX.Element | null { if (a.type === "apiKey") { const placeholder = - a.name === "Authorization" ? "Api-Key " : `${a.name}`; + a.name === "Authorization" ? "your-api-key" : `${a.name}`; return ( { if (didInit.current) return; didInit.current = true; + if (exampleStr !== null && !hasExample) { + console.warn( + `[ParamSelectFormItem] Example value "${exampleStr}" for param "${param.name}" is not in enum options [${options.join(", ")}]. Pre-fill skipped.` + ); + } if (hasExample && (param.value === undefined || param.value === "")) { - const val = String(example); - dispatch(setParam({ ...param, value: val })); + dispatch(setParam({ ...param, value: exampleStr })); if (setValue) { - setValue(param.name, val, { + setValue(param.name, exampleStr, { shouldValidate: false, shouldDirty: false, shouldTouch: false, @@ -47,9 +54,6 @@ export default function ParamSelectFormItem({ param }: { param: any }) { }, []); const showErrorMessage = (errors as any)?.[param.name]; - const defaultValue = hasExample ? String(example) : "---"; - - const [localValue, setLocalValue] = useState(defaultValue); if (!control) { // Rendered outside FormProvider (e.g. params list panel) — uncontrolled fallback diff --git a/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem.tsx b/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem.tsx index 90337411..297884b0 100644 --- a/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem.tsx +++ b/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem.tsx @@ -21,10 +21,15 @@ export default function ParamTextFormItem({ param }: { param: any }) { const hasExample = example !== undefined && example !== null && example !== ""; - const encodeForParam = (val: string) => - param.in === "path" || param.in === "query" - ? val.replace(/\s/g, "%20") - : val; + const encodeForParam = (val: string) => { + if (param.in !== "path" && param.in !== "query") return val; + // encodeURIComponent is overly aggressive — restore characters that are + // safe and commonly used in real API values. + // %2F must stay encoded in path params (/ is a path separator). + // In query params it's safe to decode back to a literal /. + const decoded = encodeURIComponent(val).replace(/%2C/g, ",").replace(/%40/g, "@").replace(/%3A/g, ":"); + return param.in === "query" ? decoded.replace(/%2F/g, "/") : decoded; + }; // Seed redux + react-hook-form from the example on first mount only. useEffect(() => { diff --git a/src/utils/checkoutSdk.ts b/src/utils/checkoutSdk.ts index 515cf5fe..1c7f1f8d 100644 --- a/src/utils/checkoutSdk.ts +++ b/src/utils/checkoutSdk.ts @@ -5,7 +5,7 @@ * Used by: CheckoutDemo, PaymentJourney, RecurringDemo. */ -import { SANDBOX_MERCHANT_ID, SANDBOX_API_KEY } from "./sandbox"; +import { ACTIVE_CONNECT } from "./sandbox"; /** * Checkout SDK script URL. @@ -13,7 +13,7 @@ import { SANDBOX_MERCHANT_ID, SANDBOX_API_KEY } from "./sandbox"; * Switch to https://assets.ottu.net/checkout/v3/checkout.min.js when released. */ export const CHECKOUT_SDK_CDN_URL = - "https://150330.dd33t4o2i3w1b.amplifyapp.com/checkout/v3/checkout.min.js"; + "https://assets.ottu.dev/checkout/v3/checkout.min.js"; /** Default forms of payment shown in demos. */ export const CHECKOUT_SDK_FORMS_OF_PAYMENT = [ @@ -26,7 +26,6 @@ export const CHECKOUT_SDK_FORMS_OF_PAYMENT = [ "urPay", ]; - /** Full branded theme used in the CheckoutDemo on the SDK docs page. */ export const CHECKOUT_SDK_THEME: Record = { main: { padding: "0px", width: "100%" }, @@ -56,12 +55,14 @@ export const CHECKOUT_SDK_THEME: Record = { "font-size": "16px", "font-style": "normal", "font-weight": "500", - "background-color": "#fafafa", + "background-color": "#f1f3f5", color: "#B00020", "border-width": "0px", "text-decoration": "underline", }, - "terms-container": { margin: "0px 0px 0px 0px" }, + "terms-container": { + margin: "0px 0px 0px 0px", + }, "checkbox-label": { color: "#1A1A1A", "font-family": "Poppins", @@ -86,16 +87,25 @@ export const CHECKOUT_SDK_THEME: Record = { "font-size": "14px", "font-weight": "400", }, - "pci-logos": { gap: "12px", margin: "20px 0px 0px 0px" }, - "wallet-buttons": { margin: "12px 0px -6px 0px" }, + "pci-logos": { + gap: "12px", + margin: "20px 0px 0px 0px", + }, + "wallet-buttons": { + margin: "12px 0px -6px 0px", + }, methods: { border: "#DADADA", "border-style": "solid", "border-width": "1px", "border-radius": "8px", }, - "selected-method": { border: "#0053A4" }, - border: { display: "none" }, + "selected-method": { + border: "#0053A4", + }, + border: { + display: "none", + }, "amount-box": { padding: "16px 12px", margin: "0px 0px 0px 0px", @@ -108,7 +118,7 @@ export const CHECKOUT_SDK_THEME: Record = { "amount-label": { color: "#1A1A1A", "font-family": "Poppins", - "font-size": "20px", + "font-size": "16px", "font-weight": "600", }, amount: { @@ -120,10 +130,12 @@ export const CHECKOUT_SDK_THEME: Record = { "card-background": { "background-color": "#ffffff", "border-bottom-radius": "8px", - "border-color": "#0053A4", + "border-color": "transparent", border: "solid", }, - "card-input-border": { "border-radius": "8px" }, + "card-input-border": { + "border-radius": "8px", + }, "card-input-fields": { color: "#1A1A1A", "font-family": "Poppins", @@ -136,7 +148,9 @@ export const CHECKOUT_SDK_THEME: Record = { "font-family": "Poppins", "font-size": "16px", }, - "field-error-border": { "border-color": "#dc3545" }, + "field-error-border": { + "border-color": "#dc3545", + }, "error-message": { color: "#dc3545", "font-family": "Poppins", @@ -151,9 +165,16 @@ export const CHECKOUT_SDK_THEME: Record = { "background-color": "#FFFFFF", "box-shadow": "0 0 4px rgba(0, 83, 164, 0.4)", }, - "selected-checkbox": { "background-color": "#0053A4" }, + "selected-checkbox": { + "background-color": "#0053A4", + }, + responsive: { - 450: { "amount-box": { "justify-content": "space-between" } }, + 450: { + "amount-box": { + "justify-content": "space-between", + }, + }, }, }; @@ -305,9 +326,9 @@ export function initCheckout(options: { } (window as any).Checkout.init({ selector: options.selector, - merchant_id: SANDBOX_MERCHANT_ID, + merchant_id: ACTIVE_CONNECT.merchantId, session_id: options.sessionId, - apiKey: SANDBOX_API_KEY, + apiKey: ACTIVE_CONNECT.sdkApiKey, displayMode: options.displayMode ?? "column", ...(options.formsOfPayment && { formsOfPayment: options.formsOfPayment }), ...(options.setupPreload && { setupPreload: options.setupPreload }), diff --git a/src/utils/sandbox.ts b/src/utils/sandbox.ts index 1b57e633..d2bf9efa 100644 --- a/src/utils/sandbox.ts +++ b/src/utils/sandbox.ts @@ -1,13 +1,46 @@ /** - * Reusable sandbox session utility for interactive demos. + * Reusable Connect session utility for interactive demos. * - * Used by: CheckoutDemo, RecurringDemo, and future Native Payments / mobile SDK demos. - * Credentials are intentionally public — sandbox-only, already exposed in CodePen. + * Used by: CheckoutDemo, RecurringDemo, PaymentJourney, WalletDemo, and future + * Native Payments / mobile SDK demos. + * + * Credentials are intentionally public — sandbox-only merchants, no real money. */ -export const SANDBOX_MERCHANT_ID = "sandbox.ottu.net"; -export const SANDBOX_API_KEY = "13df331cb989d68313b9141e2094d3f042c6d157"; -const SANDBOX_AUTH_KEY = "Fxi63E9x.AiYMnCCXcBVr657gs4N3ex3MZdeAeWDy"; +export interface ConnectEnv { + merchantId: string; + connectBaseUrl: string; + /** Authorization: Api-Key <…> for /b/checkout, /b/pbl, etc. */ + connectApiKey: string; + /** apiKey passed to Checkout.init() — the SDK widget key. */ + sdkApiKey: string; +} + +export const SANDBOX: ConnectEnv = { + merchantId: "sandbox.ottu.net", + connectBaseUrl: "https://sandbox.ottu.net", + connectApiKey: "Fxi63E9x.AiYMnCCXcBVr657gs4N3ex3MZdeAeWDy", + sdkApiKey: "13df331cb989d68313b9141e2094d3f042c6d157", +}; + +export const KSA: ConnectEnv = { + merchantId: "ksa.ottu.dev", + connectBaseUrl: "https://ksa.ottu.dev", + connectApiKey: "uUjUqczM.P5PqlXx8zyuFUQVk19PLxfHBZu8rG4Uy", + sdkApiKey: "88a460b42a0f8bec4011da23ce1d547bd04e8afc", +}; + +// ⬇️ THE GLOBAL SWITCH — change this one line to retarget every demo on the site. +// Both branches (dev → docs.ottu.dev, main → docs.ottu.com) currently use KSA: +// it is the only environment that hosts the full public API surface + wallet, +// so every demo and every code sample (via OTTU_CONNECT_BASE_URL) resolves the +// host through here. +// +// Do NOT point main at SANDBOX — sandbox.ottu.net has no wallet PG, so the +// WalletDemo and every wallet code sample would break in production. Move to a +// per-branch ConnectEnv (or a build-time env override) only once a +// production-grade sandbox also hosts wallet. +export const ACTIVE_CONNECT: ConnectEnv = KSA; export interface CreateSessionOptions { pg_codes: string[]; @@ -61,11 +94,11 @@ export async function createSandboxSession( }; const response = await fetch( - `https://${SANDBOX_MERCHANT_ID}/b/checkout/v1/pymt-txn/`, + `${ACTIVE_CONNECT.connectBaseUrl}/b/checkout/v1/pymt-txn/`, { method: "POST", headers: { - Authorization: `Api-Key ${SANDBOX_AUTH_KEY}`, + Authorization: `Api-Key ${ACTIVE_CONNECT.connectApiKey}`, "Content-Type": "application/json", }, body: JSON.stringify(body), @@ -96,11 +129,11 @@ export async function callAutoDebit( token: string ): Promise { const response = await fetch( - `https://${SANDBOX_MERCHANT_ID}/b/pbl/v2/payment/auto-debit/`, + `${ACTIVE_CONNECT.connectBaseUrl}/b/pbl/v2/payment/auto-debit/`, { method: "POST", headers: { - Authorization: `Api-Key ${SANDBOX_AUTH_KEY}`, + Authorization: `Api-Key ${ACTIVE_CONNECT.connectApiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ session_id: sessionId, token }), @@ -128,6 +161,7 @@ export async function callPaymentMethods(options: { tags?: string[]; tokenizable?: boolean; auto_debit?: boolean; + payment_services?: string[]; }): Promise { const body: Record = { plugin: options.plugin ?? "payment_request", @@ -138,13 +172,14 @@ export async function callPaymentMethods(options: { if (options.tags) body.tags = options.tags; if (options.tokenizable != null) body.tokenizable = options.tokenizable; if (options.auto_debit != null) body.auto_debit = options.auto_debit; + if (options.payment_services) body.payment_services = options.payment_services; const response = await fetch( - `https://${SANDBOX_MERCHANT_ID}/b/pbl/v2/payment-methods/`, + `${ACTIVE_CONNECT.connectBaseUrl}/b/pbl/v2/payment-methods/`, { method: "POST", headers: { - Authorization: `Api-Key ${SANDBOX_AUTH_KEY}`, + Authorization: `Api-Key ${ACTIVE_CONNECT.connectApiKey}`, "Content-Type": "application/json", }, body: JSON.stringify(body), @@ -168,11 +203,11 @@ export async function callPaymentStatusQuery( sessionId: string ): Promise { const response = await fetch( - `https://${SANDBOX_MERCHANT_ID}/b/pbl/v2/inquiry/`, + `${ACTIVE_CONNECT.connectBaseUrl}/b/pbl/v2/inquiry/`, { method: "POST", headers: { - Authorization: `Api-Key ${SANDBOX_AUTH_KEY}`, + Authorization: `Api-Key ${ACTIVE_CONNECT.connectApiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ session_id: sessionId }), @@ -223,3 +258,10 @@ export function getWebhookRelayUrl(): string { export function extractPgCodes(pmResponse: any): string[] { return (pmResponse?.payment_methods ?? []).map((pg: any) => pg.code); } + +/** + * Generate a fresh demo customer_id (used by WalletDemo when seeding a wallet). + */ +export function generateDemoCustomerId(): string { + return `demo_${Math.random().toString(36).slice(2, 10)}`; +} diff --git a/src/utils/walletDemoConfig.ts b/src/utils/walletDemoConfig.ts new file mode 100644 index 00000000..c977e7ce --- /dev/null +++ b/src/utils/walletDemoConfig.ts @@ -0,0 +1,19 @@ +/** + * WalletDemo runtime knobs that are NOT about the merchant host — + * which currency to seed, how much to seed, how much to charge at checkout, + * and the Payment Methods filter that picks a wallet-capable gateway. + * + * The merchant host / Api-Key / SDK key all come from `ACTIVE_CONNECT` + * in `./sandbox` — flip that one global to retarget every demo on the site. + */ +export const WALLET_DEMO = { + currency: "KWD", + seedAmount: "10.000", + sessionAmount: "8.000", + pgFilter: { + plugin: "e_commerce", + type: "sandbox", + tags: ["demo"], + payment_services: ["wallet"], + }, +}; diff --git a/src/utils/walletSeed.ts b/src/utils/walletSeed.ts new file mode 100644 index 00000000..8899f851 --- /dev/null +++ b/src/utils/walletSeed.ts @@ -0,0 +1,58 @@ +export interface SeedWalletOptions { + customer_id: string; + currency: string; + amount: string; + pg_code: string; +} + +export interface SeedWalletResult { + customer_id: string; + balance: string; + currency: string; + account_uuid: string; + raw: unknown; +} + +/** + * Where the /seed-wallet endpoint lives. + * - Local dev (localhost): the mcp-server runs at :8090 via `npm run webhook`. + * - Production: DO App Platform ingress routes /seed-wallet on the same origin to the mcp service. + */ +function seedWalletUrl(): string { + if (typeof window === "undefined") return "/seed-wallet"; + const { hostname } = window.location; + if (hostname === "localhost" || hostname === "127.0.0.1") { + return "http://localhost:8090/"; + } + return "/seed-wallet"; +} + +/** + * Seed a wallet credit for the docs Live Demo by calling the mcp service's + * /seed-wallet route. The mcp service holds the Keycloak client secret and + * mints a Bearer token for the wallet API on behalf of the browser. + */ +export async function seedWalletViaBackend( + opts: SeedWalletOptions +): Promise { + const response = await fetch(seedWalletUrl(), { + method: "POST", + headers: { + "Content-Type": "application/json", + "x-ottu-demo": "seed-wallet", + }, + body: JSON.stringify(opts), + }); + const text = await response.text(); + if (!response.ok) { + throw new Error(`Wallet seed failed (${response.status}): ${text || response.statusText}`); + } + const data = JSON.parse(text); + return { + customer_id: opts.customer_id, + balance: data.balance, + currency: data.currency ?? opts.currency, + account_uuid: data.account_uuid, + raw: data, + }; +} diff --git a/static/Ottu_API.yaml b/static/Ottu_API.yaml index 744e4cca..d4a4d7a7 100644 --- a/static/Ottu_API.yaml +++ b/static/Ottu_API.yaml @@ -4,1611 +4,1146 @@ info: version: 1.0.0 description: Ottu API paths: - /b/api/v1/dashboard/refund-transactions/: + /b/api/v1/reports/files/: get: - operationId: list_refund_transactions - description: |2 - - ## Overview - - The Refund Transactions API provides a paginated list of all refund transactions - (both full and partial refunds) in the system. This endpoint is designed for merchants - and internal systems to track and manage refunds. + operationId: list_reports + description: |+ + Retrieve a paginated list of completed transaction reports for reconciliation, accounting, analytics, and compliance purposes. ## Authentication - This endpoint requires authentication using one of the following methods: - - **API Key**: Include the `Authorization` header with your private API key (e.g., `Api-Key your_key_here`) - - **Basic Auth**: Use Keycloak or standard Basic Authentication - - **JWT Token**: Use Keycloak JWT authentication - - - ## Ordering + - **API Key** (Recommended): `Api-Key: your_private_api_key` + - **Basic Auth**: User must have `report.view_report` permission - Use the `ordering` parameter to sort results: - - `created` - Oldest first - - `-created` - Newest first (default) - ## Pagination + ## Example Request - The response is paginated using LimitOffsetPagination: - - `limit` - Number of results per page - - `offset` - Number of results to skip + ```bash + curl -X GET 'https://your-domain.com/b/api/v1/reports/files/?created_after=2025-11-01&limit=50' \ + -H 'Api-Key: your_private_api_key_here' + ``` - Response includes: - - `count` - Total number of matching records - - `next` - URL for next page (null if no more pages) - - `previous` - URL for previous page (null if on first page) - - `results` - Array of refund transactions + ## Key Features - ## Example Requests + - Only returns finished reports (optimized queries) + - Includes `encrypted_id` for reference (prevents enumeration) + - Provides `download_action` with ready-to-use secure download URL + - Ordered by creation date (newest first) + - Merchant-isolated (each instance sees only their reports) - ### Get all refunds (default: newest first) - ``` - GET /checkout/api/intl/v1/refund-transactions - Authorization: Api-Key your_api_key_here - ``` + ## Response Fields - ### Get refunds for a specific order - ``` - GET /checkout/api/intl/v1/refund-transactions?order_no=ORDER-12345 - ``` + - `encrypted_id`: Encrypted report identifier for reference + - `download_action.url`: Pre-signed download URL with embedded token + - `download_action.method`: HTTP method to use (always `GET`) - ### Get pending refunds only - ``` - GET /checkout/api/intl/v1/refund-transactions?state=refund_queued - ``` + ## Integration Walkthrough - ### Get refunds in a date range - ``` - GET /checkout/api/intl/v1/refund-transactions?created_after=01/12/2025 00:00&created_before=31/12/2025 23:59 - ``` + **Step 1**: Call this endpoint to list available reports - ### Combine multiple filters with pagination - ``` - GET /checkout/api/intl/v1/refund-transactions?state=refunded¤cy_code=KWD&limit=10&offset=0&ordering=-created - ``` + **Step 2**: From the response, extract `download_action.url` for the desired report - ## Notes + **Step 3**: Make a GET request to that URL (same auth headers) to download the file - - The `order_no` filter searches by the **parent** transaction's order number, not the refund transaction itself - - The `product_type` filter uses the **parent** transaction's type - - Date filters use the format `DD/MM/YYYY HH:MM` (24-hour format) - - The `initiator` field returns an empty object `{}` for refunds not initiated by a specific user - summary: List Refund Transactions + summary: List Transaction Reports parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - - in: query - name: amount_max - schema: - type: string - description: Filter by transaction amount range. Use amount_min and amount_max - to specify the range (e.g., amount_min=100&amount_max=500). - - in: query - name: amount_min - schema: - type: string - description: Filter by transaction amount range. Use amount_min and amount_max - to specify the range (e.g., amount_min=100&amount_max=500). - - in: query - name: bulk - schema: - type: integer - description: Filter by bulk payment ID. Returns transactions belonging to - a specific bulk payment batch. - - in: query - name: created_after - schema: - type: string - format: date-time - description: Filter by transaction creation date. Use created_after and created_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: created_before - schema: - type: string - format: date-time - description: Filter by transaction creation date. Use created_after and created_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: currency_code - schema: - type: string - description: Filter by currency code (e.g., KWD, USD, EUR). Returns transactions - with the specified currency. - - name: cursor - required: false - in: query - description: The pagination cursor value. - schema: - type: string - - in: query - name: customer_birth_date_after - schema: - type: string - format: date-time - description: Filter by customer birth date. Use customer_birth_date_after - and customer_birth_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 - 15:09:24) or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: customer_birth_date_before - schema: - type: string - format: date-time - description: Filter by customer birth date. Use customer_birth_date_after - and customer_birth_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 - 15:09:24) or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: disclosed_to_merchant - schema: - type: boolean - description: Filter by disclosure status to merchant. true = disclosed, false - = not disclosed. - - in: query - name: due_date_after - schema: - type: string - format: date-time - description: Filter by last transaction due date date. Use due_date_after - and due_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) - or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: due_date_before - schema: - type: string - format: date-time - description: Filter by last transaction due date date. Use due_date_after - and due_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) - or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: email_seen - schema: - type: boolean - description: Filter by whether the email notification was opened by the customer. - true = email opened (email_seen_at is set), false = not opened. - - in: query - name: email_seen_at_after - schema: - type: string - format: date-time - description: Filter by email seen date. Use email_seen_at_after and email_seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: email_seen_at_before - schema: - type: string - format: date-time - description: Filter by email seen date. Use email_seen_at_after and email_seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: gateway_code - schema: - type: string - description: Filter by payment gateway code. Returns transactions processed - through the specified gateway. - - in: query - name: initiator - schema: - type: integer - description: Filter by initiator user ID. Returns transactions created by - the specified user. - - in: query - name: modified_after - schema: - type: string - format: date-time - description: Filter by last modification date. Use modified_after and modified_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: modified_before - schema: - type: string - format: date-time - description: Filter by last modification date. Use modified_after and modified_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: order_no - schema: - type: string - - name: per_page - required: false - in: query - description: Number of results to return per page. - schema: - type: integer - - in: query - name: product_type - schema: - type: string - - in: query - name: q - schema: - type: string - description: 'JSON-encoded search query for searching across configured search - fields. Format: {"encrypted_field_key": "search_value"}. Get available search - fields from OPTIONS response.' - - in: query - name: seen - schema: - type: boolean - description: Filter by whether the transaction has been viewed. true = viewed - (seen_at is set), false = not viewed. - - in: query - name: seen_at_after - schema: - type: string - format: date-time - description: Filter by seen at date. Use seen_at_after and seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: seen_at_before - schema: - type: string - format: date-time - description: Filter by seen at date. Use seen_at_after and seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: state - schema: - type: string - x-spec-enum-id: a4680147d8c166ee - enum: - - refund_queued - - refunded - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: query + name: created_after + schema: + type: string + format: date + description: Created after (inclusive) + - in: query + name: created_before + schema: + type: string + format: date + description: Created before (inclusive) + - in: query + name: interval + schema: + type: string + enum: + - daily + - monthly + - weekly + - yearly + description: |- + Report interval - * `refunded` - Refunded - * `refund_queued` - Refund Queued - - in: query - name: state_changed_at_after - schema: - type: string - format: date-time - description: Filter by when the transaction state last changed. Use state_changed_at_after - and state_changed_at_before with ISO 8601 format. - - in: query - name: state_changed_at_before - schema: - type: string - format: date-time - description: Filter by when the transaction state last changed. Use state_changed_at_after - and state_changed_at_before with ISO 8601 format. - - in: query - name: unit - schema: - type: number - description: Filter by unit ID. Returns transactions belonging to the specified - unit. + * `daily` - Daily + * `weekly` - Weekly + * `monthly` - Monthly + * `yearly` - Yearly + - name: limit + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: offset + required: false + in: query + description: The initial index from which to return the results. + schema: + type: integer + - in: query + name: source + schema: + type: string + enum: + - auto + - manual + description: |- + Report source + + * `auto` - Auto + * `manual` - Manual tags: - - Dashboard - - Refunds + - Reports API security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/PaginatedRefundTransactionList' - description: Paginated list of refund transactions - '401': + $ref: "#/components/schemas/PaginatedReportAPIListList" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/FieldErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/api/v1/dashboard/refund-transactions/export/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/api/v1/reports/files/{token}/download/: get: - operationId: export_refund_transactions - description: |2 + operationId: download_report + description: |+ + Download a report file using the secure token from the list endpoint. - ## Overview + ## How It Works - The Export Refund Transactions API generates a downloadable report (CSV or XLSX) of - refund transactions. This endpoint is designed for merchants and internal systems to - export refund data for reporting, reconciliation, and analysis purposes. + 1. Call `/b/api/v1/reports/files/` to list reports + 2. Each report includes a `download_action` object with a pre-built URL + 3. Use that URL directly - the token is already embedded in the path ## Authentication - This endpoint requires authentication using one of the following methods: - - **API Key**: Include the `Authorization` header with your private API key (e.g., `Api-Key your_key_here`) - - **Basic Auth**: Use Keycloak or standard Basic Authentication - - **JWT Token**: Use Keycloak JWT authentication + - **API Key** (Recommended): `Api-Key: your_private_api_key` + - **Basic Auth**: User must have `report.view_report` permission + + ## Example Flow + + ```bash + # Step 1: List reports + curl -X GET 'https://your-domain.com/b/api/v1/reports/files/' \ + -H 'Api-Key: your_private_api_key_here' + + # Response includes: + # { + # "encrypted_id": "abc123...", + # "download_action": { + # "method": "GET", + # "url": "https://your-domain.com/b/api/v1/reports/files//download/" + # } + # } + + # Step 2: Download using the URL from download_action + curl -X GET 'https://your-domain.com/b/api/v1/reports/files//download/' \ + -H 'Api-Key: your_private_api_key_here' \ + -o report.csv + ``` + + ## Security Features + + - **Token-based**: Download tokens are UUIDs cached in Redis + - **Time-limited**: Tokens expire (configurable TTL, default from settings) + - **User-bound**: Token is tied to the user who requested the list + - **Rate Limiting**: Downloads are rate-limited per user + - **Ownership Verification**: Server verifies user owns the report + + ## File Delivery - ## Query Parameters + - **S3 Storage**: Redirects (302) to a pre-signed S3 URL + - **Local Storage**: Returns file with `X-Sendfile` header for Apache - ### Export Options - - `file_format` - Export format (default: `csv`) - - `csv` - Comma-separated values - - `xlsx` - Microsoft Excel format - - `fields` - Comma-separated list of fields to include in export (optional, all fields if not specified) - - `language` - Language for export headers (default: `en`) + ## File Formats - ## Notes + - **CSV**: `text/csv` - UTF-8 encoded, comma-delimited + - **XLSX**: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - - The `order_no` filter searches by the **parent** transaction's order number - - The `product_type` filter uses the **parent** transaction's type - - Large exports may take some time to generate; the file URL will be available once complete - summary: Export Refund Transactions + summary: Download Transaction Report File parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: path + name: token + schema: + type: string + description: Secure download token (UUID) from the `download_action.url` field in the list response. Tokens are time-limited and bound to the authenticated user. + required: true tags: - - Dashboard - - Refunds - - Export + - Reports API security: - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '201': + "200": content: application/json: schema: - $ref: '#/components/schemas/Report' - description: Report generated successfully with download URL - '401': + type: string + format: binary + description: "Report file (CSV or XLSX). For S3: redirects to pre-signed URL." + "302": + description: Redirect to pre-signed S3 URL (when S3 storage is enabled) + "400": + description: Invalid token (unknown alias or malformed token) + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": + description: User is not authorized to download this file + "404": + description: Report or file not found + "410": + description: Download link has expired or is invalid + /b/checkout/api/sdk/v1/pre-payment-option-check/{session_id}/: + post: + operationId: get_pre_payment_option + description: This endpoint allows you to retrieve the pre payment options for specific user using tabby integrated API. + summary: Retrieve Pre Payment Check response. + parameters: + - in: path + name: session_id + schema: + type: string + pattern: ^[-\w]+$ + required: true + tags: + - PaymentMethods API + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PGCodeValidation" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/PGCodeValidation" + multipart/form-data: + schema: + $ref: "#/components/schemas/PGCodeValidation" + required: true + security: + - SSO_JWT_Auth: [] + - tokenAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] + responses: + "200": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/api/v1/dashboard/transaction/export: - get: - operationId: export_all_transactions - description: |2 - - ## Overview - - `BaseTxnExportView` is the base class for all transaction export endpoints in the dashboard. - It generates a downloadable report (CSV or XLSX) of payment transactions with support for - filtering, field selection, timezone adjustment, and multi-language headers. - - Each plugin (e.g. payment_request, e_commerce, bulk) subclasses this view and sets its - own `txn_type`. The export only includes **parent transactions** (child/refund transactions - are excluded). - - --- - - ## Authentication - - All export endpoints require authentication using one of: - - **JWT Bearer Token**: `Authorization: Bearer ` - - **Keycloak JWT**: same Bearer scheme, issued by Keycloak - - **API Key**: `Authorization: Api-Key ` - - --- - - ## HTTP Request Headers - - | Header | Required | Description | Example | - |--------|----------|-------------|---------| - | `Authorization` | Yes | Authentication credential | `Bearer eyJhbGci...` | - | `X-Timezone` | No | IANA timezone name for date display in the exported file. Overrides the `timezone` query param. | `X-Timezone: Asia/Kuwait` | - - --- - - ## Discovering Available Fields — OPTIONS Request - - Before exporting, call `OPTIONS` on the same endpoint to get all available export column - keys grouped by category, plus the list of valid timezones. - - ``` - OPTIONS /api/v1/dashboard//export/ - Authorization: Bearer - ``` - - Response structure: - ```json - { - "groups": [ - { - "label": "Transaction Info", - "headers": [ - { "key": "order_no", "label": "Order No", "description": "Merchant order reference" }, - { "key": "amount", "label": "Amount", "description": "Transaction amount" }, - { "key": "state", "label": "State", "description": "Current transaction state" } - ] - } - ], - "timezones": [ - { "value": "Asia/Kuwait", "label": "(UTC+03:00) Asia/Kuwait" }, - { "value": "America/New_York", "label": "(UTC-05:00) America/New_York" } - ] - } - ``` - - Use the `key` values from this response as the `fields` query parameter values. - - --- - - ## Response - - On success (`HTTP 201 Created`) the response is a report object, **not** the file itself. - The file is generated asynchronously and a download URL is returned. - - --- - - ## Examples - - ### Export all paid transactions for January 2025 as CSV - ``` - GET /api/v1/dashboard/payment-request/export/?state=paid&created_after=01/01/2025 00:00&created_before=31/01/2025 23:59 - Authorization: Bearer - ``` - - ### Export as XLSX with selected fields only - ``` - GET /api/v1/dashboard/payment-request/export/?file_format=xlsx&fields=order_no,amount,currency_code,state,created - Authorization: Bearer - ``` - - ### Export with dates displayed in Kuwait timezone - ``` - GET /api/v1/dashboard/payment-request/export/?timezone=Asia/Kuwait - Authorization: Bearer - X-Timezone: Asia/Kuwait - ``` - - ### Export with Arabic column headers - ``` - GET /api/v1/dashboard/payment-request/export/?language=ar - Authorization: Bearer - ``` - - ### Export with dynamic field search filter - ``` - GET /api/v1/dashboard/payment-request/export/?q={"encrypted_customer_phone":"IjA1MXh4eHh4eHh4Ig"} - Authorization: Bearer - ``` - - --- - - ## Notes - - - Only **parent** transactions are exported. Refunds and child transactions are excluded. - - The `file` URL in the response is **time-limited**. Re-request the report if the URL expires. - - The `status` field may be `pending` or `processing` immediately after the request if the - report is generated asynchronously. Poll the report list endpoint or wait for `completed`. - - When both `X-Timezone` header and `timezone` query param are provided, the **header takes priority**. - - The `q` parameter keys are **encrypted field keys** specific to each plugin's search - configuration — always retrieve them from the `OPTIONS` response, do not hardcode them. - summary: Export All Transactions + $ref: "#/components/schemas/PrePaymentCheckResponses" + description: "" + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/FieldErrors" + description: "" + "403": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/checkout/v1/pymt-txn/: + post: + operationId: create_payment_transaction_checkout + description: Create a new Payment Transaction + summary: Create a new Payment Transaction + parameters: + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Dashboard - - Export + - Checkout API + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CheckoutPOSTRequest" + examples: + LoyaltyEnabled(minimal): + value: + type: e_commerce + amount: "100.000" + currency_code: SAR + customer_id: CUST-123 + customer_phone: "+966500000000" + loyalty: + enabled: true + summary: Mark transaction as rewardable + description: Minimal payload — set `loyalty.enabled=true`. The customer earns points automatically if the chosen PGMID has a wallet service with reward capability configured (e.g. Qitaf for STC merchants on SAR transactions). + LoyaltyWithReference+Metadata: + value: + type: e_commerce + amount: "250.000" + currency_code: SAR + customer_id: CUST-123 + customer_phone: "+966500000000" + order_no: ORDER-2026-9182 + loyalty: + enabled: true + reference: LOY-CAMP-SPRING-9182 + metadata: + campaign_id: spring2026 + segment: vip + summary: Loyalty with merchant reference and metadata + description: Full loyalty payload. `reference` overrides the default (`order_no`) sent to the loyalty provider; `metadata` is forwarded opaquely so merchant-side analytics can correlate rewards back to a campaign. + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/CheckoutPOSTRequest" + multipart/form-data: + schema: + $ref: "#/components/schemas/CheckoutPOSTRequest" + required: true security: - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] - - SSO_JWT_Auth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '201': + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/Success" + description: "" + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/ClientErrors" + description: "" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/Report' - description: Report generated successfully with download URL - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "415": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/api/v1/plugins/payment_request/transaction: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "423": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/checkout/v1/pymt-txn/{session_id}/: get: - operationId: list_payment_request_transactions - description: |- - List payment request transactions with configurable filter support. - - ## Metadata (OPTIONS Request) - - Send an OPTIONS request to this endpoint to retrieve metadata including: - - - **filters_data**: Configurable filter fields with their types and options - - **export**: Available export formats - - **actions**: Available bulk actions - - **search_fields**: Available search fields - - ## Filter Types - - ### Dropdown Filters - Select from predefined options. The `options` array contains available values. - - **Available dropdown filters:** - - `state`: Transaction state (pending, paid, failed, etc.) - - `currency_code`: Currency (KWD, USD, EUR, etc.) - - `gateway_code`: Payment gateway - - `initiator`: User who created the transaction - - `product_type`: Product type (e_commerce, payment_request, etc.) - - `seen`: Whether transaction was viewed (Yes/No) - - `email_seen`: Whether email notification was opened (Yes/No) - - **Example request:** - ``` - GET /b/api/v1/plugins/payment_request/transaction/?state=pending¤cy_code=KWD - ``` - - ### DateTime Filters - Filter by date/time range using `_after` and `_before` suffixes. - - **Available datetime filters:** - - `created`: Transaction creation date - - `modified`: Last modification date - - `state_changed_at`: When state last changed - - **Example request:** - ``` - GET /b/api/v1/plugins/payment_request/transaction/?created_after=2024-01-01T00:00:00Z&created_before=2024-12-31T23:59:59Z - ``` - - ### Amount Range Filters - Filter by numeric range using `_min` and `_max` suffixes. - - **Example request:** - ``` - GET /b/api/v1/plugins/payment_request/transaction/?amount_min=100&amount_max=500 - ``` - - ## Filter Configuration - - Filters are configured via the SearchConfig admin panel. Each merchant can customize which filters are available and their display order. Only active filters are returned in the OPTIONS response. - - ## Boolean Virtual Fields - - Some filters like `seen` and `email_seen` are virtual fields that don't exist directly on the model but are computed from related fields (e.g., `seen_at` timestamp). These return boolean options (Yes/No) in the dropdown. - summary: List Payment Request Transactions (with Configurable Filters) + operationId: retrieve_payment_transaction_checkout + description: Retrieve an existing Payment Transaction by session_id + summary: Retrieve Payment Transaction parameters: - - in: query - name: amount_max - schema: - type: string - description: Filter by transaction amount range. Use amount_min and amount_max - to specify the range (e.g., amount_min=100&amount_max=500). - - in: query - name: amount_min - schema: - type: string - description: Filter by transaction amount range. Use amount_min and amount_max - to specify the range (e.g., amount_min=100&amount_max=500). - - in: query - name: bulk - schema: - type: integer - description: Filter by bulk payment ID. Returns transactions belonging to - a specific bulk payment batch. - - in: query - name: created_after - schema: - type: string - format: date-time - description: Filter by transaction creation date. Use created_after and created_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: created_before - schema: - type: string - format: date-time - description: Filter by transaction creation date. Use created_after and created_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: currency_code - schema: - type: string - description: Filter by currency code (e.g., KWD, USD, EUR). Returns transactions - with the specified currency. - - name: cursor - required: false - in: query - description: The pagination cursor value. - schema: - type: string - - in: query - name: customer_birth_date_after - schema: - type: string - format: date-time - description: Filter by customer birth date. Use customer_birth_date_after - and customer_birth_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 - 15:09:24) or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: customer_birth_date_before - schema: - type: string - format: date-time - description: Filter by customer birth date. Use customer_birth_date_after - and customer_birth_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 - 15:09:24) or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: disclosed_to_merchant - schema: - type: boolean - description: Filter by disclosure status to merchant. true = disclosed, false - = not disclosed. - - in: query - name: due_date_after - schema: - type: string - format: date-time - description: Filter by last transaction due date date. Use due_date_after - and due_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) - or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: due_date_before - schema: - type: string - format: date-time - description: Filter by last transaction due date date. Use due_date_after - and due_date_before with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) - or ISO 8601 format (e.g., 2024-01-01 00:00:00). - - in: query - name: email_seen - schema: - type: boolean - description: Filter by whether the email notification was opened by the customer. - true = email opened (email_seen_at is set), false = not opened. - - in: query - name: email_seen_at_after - schema: - type: string - format: date-time - description: Filter by email seen date. Use email_seen_at_after and email_seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: email_seen_at_before - schema: - type: string - format: date-time - description: Filter by email seen date. Use email_seen_at_after and email_seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: gateway_code - schema: - type: string - description: Filter by payment gateway code. Returns transactions processed - through the specified gateway. - - in: query - name: initiator - schema: - type: integer - description: Filter by initiator user ID. Returns transactions created by - the specified user. - - in: query - name: modified_after - schema: - type: string - format: date-time - description: Filter by last modification date. Use modified_after and modified_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: modified_before - schema: - type: string - format: date-time - description: Filter by last modification date. Use modified_after and modified_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: order_no - schema: - type: string - description: Filter by order number. Exact match on the merchant's order reference. - - name: per_page - required: false - in: query - description: Number of results to return per page. - schema: - type: integer - - in: query - name: product_type - schema: - type: string - description: Filter by product type (e.g., e_commerce, payment_request, bulk, - event). Returns transactions of the specified product type. - - in: query - name: q - schema: - type: string - description: 'JSON-encoded search query for searching across configured search - fields. Format: {"encrypted_field_key": "search_value"}. Get available search - fields from OPTIONS response.' - - in: query - name: seen - schema: - type: boolean - description: Filter by whether the transaction has been viewed. true = viewed - (seen_at is set), false = not viewed. - - in: query - name: seen_at_after - schema: - type: string - format: date-time - description: Filter by seen at date. Use seen_at_after and seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: seen_at_before - schema: - type: string - format: date-time - description: Filter by seen at date. Use seen_at_after and seen_at_before - with DD/MM/YYYY HH:MM:SS format (e.g., 20/11/2025 15:09:24) or ISO 8601 - format (e.g., 2024-01-01 00:00:00). - - in: query - name: state - schema: - type: string - x-spec-enum-id: a4680147d8c166ee - enum: - - all_unpaid - - attempted - - authorized - - canceled - - cod - - created - - expired - - failed - - invalided - - paid - - pending - - refund_queued - - refund_rejected - - refunded - - voided - description: |- - Filter by transaction state. Use 'all_unpaid' to get all unpaid transactions (pending, attempted, created, expired, failed). Other values filter by specific state. - - * `all_unpaid` - All Unpaid - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - * `refund_queued` - Refund Queued - * `refund_rejected` - Refund Rejected - * `voided` - Voided - - in: query - name: state_changed_at_after - schema: - type: string - format: date-time - description: Filter by when the transaction state last changed. Use state_changed_at_after - and state_changed_at_before with ISO 8601 format. - - in: query - name: state_changed_at_before - schema: - type: string - format: date-time - description: Filter by when the transaction state last changed. Use state_changed_at_after - and state_changed_at_before with ISO 8601 format. - - in: query - name: unit - schema: - type: number - description: Filter by unit ID. Returns transactions belonging to the specified - unit. + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: path + name: session_id + schema: + type: string + pattern: ^[-\w]+$ + required: true tags: - - Payment Filtering & Search + - Checkout API security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/PaginatedTransactionMetadataResponseList' - description: '' - '401': + $ref: "#/components/schemas/CheckoutGETResponse" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/api/v1/plugins/payment_request/transaction/{id}: - get: - operationId: api_v1_plugins_payment_request_transaction_retrieve - description: Create, view list or detail - payment requests + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + put: + operationId: full_update_payment_transaction_checkout + description: Update an existing Payment Transaction + summary: Update Payment Transaction parameters: - - in: path - name: id - schema: - type: integer - description: A unique integer value identifying this Payment transaction. - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: path + name: session_id + schema: + type: string + pattern: ^[-\w]+$ + required: true tags: - - api + - Checkout API + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Checkout" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/Checkout" + multipart/form-data: + schema: + $ref: "#/components/schemas/Checkout" + required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/ListingPymtTxn' - description: '' - /b/api/v1/publisher/compare/metrics/: - get: - operationId: compare_metrics - description: Retrieve metrics for txn comparison which is done by by comparing - metrics from ES. This API is being called by Satellite. - summary: Retrieve metrics for txn comparison + $ref: "#/components/schemas/Checkout" + description: "" + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/Client Errors" + description: "" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + patch: + operationId: partial_update_payment_transaction_checkout + description: Partially update an existing Payment Transaction + summary: Partially Update Payment Transaction parameters: - - in: header - name: Authorization - schema: - type: string - default: Bearer eyJhbG... - description: Bearer token to be provided for authentication. - required: true - - in: header - name: X-Service-ID - schema: - type: string - default: service.name.dev - description: Keycloak realm to be provided for authentication. - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: path + name: session_id + schema: + type: string + pattern: ^[-\w]+$ + required: true tags: - - Satellite API + - Checkout API + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PatchedCheckoutPATCHRequest" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/PatchedCheckoutPATCHRequest" + multipart/form-data: + schema: + $ref: "#/components/schemas/PatchedCheckoutPATCHRequest" security: - - SSO_JWT_Auth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - type: object - additionalProperties: {} - examples: - Metrics: - value: - created: - amount: 11.63 - count: 2 - paid: - amount: 94.0 - count: 23 - description: '' - '400': + $ref: "#/components/schemas/CheckoutPATCHResponse" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/api/v1/publisher/compare/timestamp/: - get: - operationId: compare_timestamp - description: Retrieve the `PaymentTransaction.created` value of the first instance. - This API is being called by Satellite. - summary: Retrieve `created` value of first txn + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/checkout/v1/upload-attachment/: + post: + operationId: upload_attachment + description: Upload a file, attach it to a transaction if `session_id` or `order_no` is provided and shorify if `shortify_attachment_url` is true. + summary: Attachment Upload parameters: - - in: header - name: Authorization - schema: - type: string - default: Bearer eyJhbG... - description: Bearer token to be provided for authentication. - required: true - - in: header - name: X-Service-ID - schema: - type: string - default: service.name.dev - description: Keycloak realm to be provided for authentication. - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Satellite API + - Checkout API + requestBody: + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/AttachmentUpload" + required: true security: - - SSO_JWT_Auth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': - content: - application/json: - schema: - type: object - additionalProperties: {} - examples: - Created: - value: - created: '2021-09-01' - description: '' - '401': + "200": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/AttachmentUploadSuccessSerializers" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/api/v1/reports/files/: - get: - operationId: list_reports - description: |+ - Retrieve a paginated list of completed transaction reports for reconciliation, accounting, analytics, and compliance purposes. - - ## Authentication - - - **API Key** (Recommended): `Api-Key: your_private_api_key` - - **Basic Auth**: User must have `report.view_report` permission - - ## Example Request + $ref: "#/components/schemas/AttachmentUploadClientErrors" + description: "" + /b/wallet/ottu/v1/accounts/: + post: + operationId: wallet_accounts + description: |- + Lists every wallet account that belongs to a customer — one account per currency. + + ### When to call this + - Showing the customer their wallet balances (e.g. "You have 50.000 KWD and 25.000 USD"). + - Checking whether a customer already has a wallet in a specific currency before initiating a payment or refund-to-wallet. + - Building a back-office tool that needs to inspect a customer's wallet portfolio. + + ### Request body + | field | required | description | + |---|---|---| + | `customer_id` | yes | The merchant's identifier for the customer (the same `customer_id` you send during checkout). | + | `currency` | no | ISO 4217 code (e.g. `KWD`). Restricts results to a single currency. | + | `status` | no | One of `active`, `suspended`, `closed`. Defaults to all statuses. | + | `pagination` | no | Cursor pagination object — `{ "cursor": , "direction": "forward"|"backward", "per_page": 1..50 }`. Defaults to `{ cursor: null, direction: "forward", per_page: 20 }`. | + + ### Pagination + The wallet uses **cursor-based pagination**, not page numbers. To fetch the next page, take the `next` object from the previous response and send it back as `pagination`: + ```json + // 1st page + { "customer_id": "cust-123" } + // response → "next": {"cursor": 42, "direction": "forward", "per_page": 20} - ```bash - curl -X GET 'https://your-domain.com/b/api/v1/reports/files/?created_after=2025-11-01&limit=50' \ - -H 'Api-Key: your_private_api_key_here' + // 2nd page + { "customer_id": "cust-123", "pagination": {"cursor": 42, "direction": "forward", "per_page": 20} } ``` + When there are no more pages, `next` is `null`. - ## Key Features - - - Only returns finished reports (optimized queries) - - Includes `encrypted_id` for reference (prevents enumeration) - - Provides `download_action` with ready-to-use secure download URL - - Ordered by creation date (newest first) - - Merchant-isolated (each instance sees only their reports) - - ## Response Fields - - - `encrypted_id`: Encrypted report identifier for reference - - `download_action.url`: Pre-signed download URL with embedded token - - `download_action.method`: HTTP method to use (always `GET`) - - ## Integration Walkthrough - - **Step 1**: Call this endpoint to list available reports - - **Step 2**: From the response, extract `download_action.url` for the desired report - - **Step 3**: Make a GET request to that URL (same auth headers) to download the file + ### Response + Each item in `results` includes the account `id` (UUID), `currency`, `status`, `balance`, `available_balance`, and timestamps. `available_balance` excludes funds held by active reservations and is what the customer can spend right now. - summary: List Transaction Reports + ### Common responses + - **200** — accounts returned. `count: 0` with empty `results` is valid (customer has no wallet yet). + - **400** — validation error or upstream wallet error (the wallet's `detail` is forwarded). + - **401** — missing or invalid API key. + - **503** — no wallet service is configured on this merchant. + summary: List wallet accounts for a customer parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + tags: + - Wallet + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/WalletAccountsRequest" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/WalletAccountsRequest" + multipart/form-data: + schema: + $ref: "#/components/schemas/WalletAccountsRequest" required: true - - in: query - name: created_after - schema: - type: string - format: date - description: Created after (inclusive) - - in: query - name: created_before - schema: - type: string - format: date - description: Created before (inclusive) - - in: query - name: interval - schema: - type: string - enum: - - daily - - monthly - - weekly - - yearly - description: |- - Report interval - - * `daily` - Daily - * `weekly` - Weekly - * `monthly` - Monthly - * `yearly` - Yearly - - name: limit - required: false - in: query - description: Number of results to return per page. - schema: - type: integer - - name: offset - required: false - in: query - description: The initial index from which to return the results. - schema: - type: integer - - in: query - name: source - schema: - type: string - enum: - - auto - - manual - description: |- - Report source - - * `auto` - Auto - * `manual` - Manual + security: + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/WalletAccountsResponse" + description: "" + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/WalletAccountsErrors" + description: "" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "503": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/wallet/ottu/v1/entries/: + post: + operationId: wallet_entries + description: |- + Returns the ledger entries (debits, credits, reservations, releases, refunds, etc.) for one of the customer's wallet accounts. + + ### When to call this + - Building a transaction history page in the customer-facing portal. + - Reconciling a single payment (`session_id` filter) — see exactly which `reserve` / `debit_payment` / `release` entries it produced. + - Auditing wallet activity over a date range, by gateway (`pg_code`), or by entry type. + + ### How account resolution works + You only pass `customer_id` and `currency`. Ottu resolves the matching wallet account internally and queries its ledger. If the customer has no account in that currency the call returns **400** with `{"detail": "No wallet account found for customer."}`. + + ### Request body + | field | required | description | + |---|---|---| + | `customer_id` | yes | The merchant's identifier for the customer. | + | `currency` | yes | ISO 4217 code that selects which wallet account to read from. | + | `entry_type` | no | Filter by type: `credit_refund`, `debit_payment`, `reserve`, `release`, `expire`, `reversal`, `credit_adjustment`, `debit_adjustment`. | + | `direction` | no | `credit` (money into the wallet) or `debit` (money out). | + | `status` | no | `pending`, `completed`, or `failed`. | + | `session_id` | no | Restrict to entries produced by a specific payment session. Useful for reconciliation. | + | `provider` / `pg_code` | no | Restrict to entries originated by a specific provider or payment gateway code. | + | `date_from` / `date_to` | no | ISO date range (entry `created_at`). Inclusive. | + | `pagination` | no | Same cursor-based pagination object as the accounts endpoint (`{ cursor, direction, per_page }`, max `per_page` is 50, default 20). | + + ### Response + Each entry includes its `entry_type`, `direction`, `amount`, `currency`, `status`, the originating `session_id` and `pg_code`, and `created_at`. Use the `next`/`previous` cursor objects to page through history. + + ### Common responses + - **200** — entries returned (possibly empty). + - **400** — validation error, missing wallet account for the requested currency, or upstream wallet error. + - **401** — missing or invalid API key. + - **503** — no wallet service is configured on this merchant. + summary: List ledger entries on a customer's wallet account + parameters: + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Reports API + - Wallet + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/WalletEntriesRequest" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/WalletEntriesRequest" + multipart/form-data: + schema: + $ref: "#/components/schemas/WalletEntriesRequest" + required: true security: - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/PaginatedReportAPIListList' - description: '' - '400': + $ref: "#/components/schemas/WalletEntriesResponse" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/FieldErrors' - description: '' - '401': + $ref: "#/components/schemas/WalletEntriesErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "503": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/api/v1/reports/files/{token}/download/: - get: - operationId: download_report - description: |+ - Download a report file using the secure token from the list endpoint. - - ## How It Works - - 1. Call `/b/api/v1/reports/files/` to list reports - 2. Each report includes a `download_action` object with a pre-built URL - 3. Use that URL directly - the token is already embedded in the path - - ## Authentication - - - **API Key** (Recommended): `Api-Key: your_private_api_key` - - **Basic Auth**: User must have `report.view_report` permission - - ## Example Flow - - ```bash - # Step 1: List reports - curl -X GET 'https://your-domain.com/b/api/v1/reports/files/' \ - -H 'Api-Key: your_private_api_key_here' - - # Response includes: - # { - # "encrypted_id": "abc123...", - # "download_action": { - # "method": "GET", - # "url": "https://your-domain.com/b/api/v1/reports/files//download/" - # } - # } - - # Step 2: Download using the URL from download_action - curl -X GET 'https://your-domain.com/b/api/v1/reports/files//download/' \ - -H 'Api-Key: your_private_api_key_here' \ - -o report.csv - ``` - - ## Security Features - - - **Token-based**: Download tokens are UUIDs cached in Redis - - **Time-limited**: Tokens expire (configurable TTL, default from settings) - - **User-bound**: Token is tied to the user who requested the list - - **Rate Limiting**: Downloads are rate-limited per user - - **Ownership Verification**: Server verifies user owns the report - - ## File Delivery - - - **S3 Storage**: Redirects (302) to a pre-signed S3 URL - - **Local Storage**: Returns file with `X-Sendfile` header for Apache - - ## File Formats - - - **CSV**: `text/csv` - UTF-8 encoded, comma-delimited - - **XLSX**: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - - summary: Download Transaction Report File + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/wallet/ottu/v1/operations/: + post: + operationId: wallet_operation_details + description: |- + Returns a single wallet **operation** — the atomic unit of work the wallet performs (a reservation, a refund, an express debit, an adjustment, a reversal). Each operation rolls up one or more ledger entries (see the entries endpoint) under one identifier. + + ### When to call this + - Investigating a specific wallet operation by id (e.g. from a webhook, log line, or another API response). + - Showing the customer or finance team a detailed breakdown of one wallet event. + - Reconciling: confirm an operation's final `status` and inspect its entries. + + ### Request body + | field | required | description | + |---|---|---| + | `operation_id` | yes | The wallet's numeric operation id (returned by reservation/refund/express-checkout flows). | + + ### Response + - `operation_type` — one of `refund`, `reservation`, `deduction`, `adjustment`, `reversal`. + - `status` — one of `pending`, `completed`, `expired`, `canceled`, `failed`, `reversed`, `requires_review`. + - `session_id` — the payment session that produced the operation. + - `entries` — the ledger entries created by this operation (each with `entry_type`, `direction`, `amount`, `currency`, `status`). + + ### Common responses + - **200** — operation found. + - **400** — validation error or upstream wallet error (e.g. operation not found is forwarded as-is). + - **401** — missing or invalid API key. + - **503** — no wallet service is configured on this merchant. + summary: Get a single wallet operation by id parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - - in: path - name: token - schema: - type: string - description: Secure download token (UUID) from the `download_action.url` field - in the list response. Tokens are time-limited and bound to the authenticated - user. - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Reports API + - Wallet + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/WalletOperationsRequest" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/WalletOperationsRequest" + multipart/form-data: + schema: + $ref: "#/components/schemas/WalletOperationsRequest" + required: true security: - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - type: string - format: binary - description: 'Report file (CSV or XLSX). For S3: redirects to pre-signed - URL.' - '302': - description: Redirect to pre-signed S3 URL (when S3 storage is enabled) - '400': - description: Invalid token (unknown alias or malformed token) - '401': + $ref: "#/components/schemas/WalletOperationResponse" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - description: User is not authorized to download this file - '404': - description: Report or file not found - '410': - description: Download link has expired or is invalid - /b/api/v1/unified-ui/invoice/: - get: - operationId: api_v1_unified_ui_invoice_list - description: Invoice details to be used for invoice detail page on the frontend - dashboard - summary: Retrieve a list of Invoices - parameters: - - name: cursor - required: false - in: query - description: The pagination cursor value. - schema: - type: string - - in: query - name: due_date_after - schema: - type: string - format: date - description: 'Range: due_date_after:YYYY-MM-DD, due_date_before:YYYY-MM-DD' - - in: query - name: due_date_before - schema: - type: string - format: date - description: 'Range: due_date_after:YYYY-MM-DD, due_date_before:YYYY-MM-DD' - - in: query - name: invoice_date_after - schema: - type: string - format: date - description: 'Range: invoice_date_after:YYYY-MM-DD, invoice_date_before:YYYY-MM-DD' - - in: query - name: invoice_date_before - schema: - type: string - format: date - description: 'Range: invoice_date_after:YYYY-MM-DD, invoice_date_before:YYYY-MM-DD' - - in: query - name: is_active - schema: - type: boolean - - name: per_page - required: false - in: query - description: Number of results to return per page. - schema: - type: integer - - in: query - name: status - schema: - type: string - x-spec-enum-id: c131c51a82b6f22a - enum: - - canceled - - overdue - - paid - - sent - description: |- - Current status of the invoice. Can be one of the following: `sent`, `paid`, `overdue`, `canceled`. - - * `sent` - Sent - * `paid` - Paid - * `overdue` - Overdue - * `canceled` - Canceled - tags: - - Unified UI - security: - - SSO_JWT_Auth: [] - responses: - '200': + $ref: "#/components/schemas/WalletOperationsErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/PaginatedUnifiedUIInvoiceList' - description: '' - /b/api/v1/unified-ui/invoice/{txn__session_id}/: - get: - operationId: api_v1_unified_ui_invoice_retrieve - description: This view is used to view the invoice for internal dashboard. - summary: Retrieve an Invoice item - parameters: - - in: path - name: txn__session_id - schema: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - required: true - tags: - - Unified UI - security: - - SSO_JWT_Auth: [] - responses: - '200': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "503": content: application/json: schema: - $ref: '#/components/schemas/UnifiedUIInvoice' - description: '' - /b/api/v1/unified-ui/payment/{type}/{session_id}/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/checkout/v1/wallet/payment-sessions/{session_id}/finalization-status/: get: - operationId: get_payment_details - description: Payment transaction details to be used for payment detail page - on the frontend dashboard - summary: Retrieve the payment transaction details + operationId: wallet_finalization_status + description: |- + Returns the current state of a payment session in a wallet-friendly shape. **Read-only** — calling this endpoint never changes any state. + + ### Who calls this + Primarily the wallet service itself: when a wallet reservation is approaching its expiry, the wallet calls this to decide whether to **commit** the reservation (payment succeeded) or **release** it (payment didn't go through). Merchants can also call it to poll a session's outcome. + + ### URL parameter + | param | description | + |---|---| + | `session_id` | The payment transaction's `session_id`. | + + ### Response + - `status` — one of: + - `SUCCEEDED` — paid / authorized / refunded (terminal positive). + - `FAILED` — failed / expired / invalidated (terminal negative). + - `CANCELLED` — explicitly cancelled or voided. + - `PENDING` — created / pending / attempted (still in progress). + - `UNKNOWN` — state is not mapped (defensive default). + - `payment_transaction_id` — same as the input `session_id`. + - `last_updated_at` — ISO 8601 timestamp of the last state change. Use this to detect stale or freshly updated records. + - `source` — always `inquiry` (this endpoint is the inquiry channel). + + ### Common responses + - **200** — status returned. + - **401** — missing or invalid API key. + - **404** — no payment transaction matches the given `session_id`. + summary: Get the finalization status of a payment session parameters: - - in: path - name: session_id - schema: - type: string - required: true - - in: path - name: type - schema: - type: string - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: path + name: session_id + schema: + type: string + required: true tags: - - Unified UI + - Wallet security: - - SSO_JWT_Auth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/Payment' - description: '' - '403': + $ref: "#/components/schemas/WalletFinalizationStatus" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/aba/submit/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/invoice/v1/invoice/: post: - operationId: aba_payway_sub_option_submit - description: Submits the selected ABA PayWay sub-option and returns the required - payload and target URL for initiating the payment process via form submission. - The request must include a valid `session_id`, `pg_code` and a `sub_option`. - summary: Submit ABAPayWay + operationId: create_invoice + description: Create a new Invoice + summary: Create a new Invoice + parameters: + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Checkout SDK + - Invoice API requestBody: content: application/json: schema: - $ref: '#/components/schemas/ABAPayWay' + $ref: "#/components/schemas/InvoicePOSTRequest" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/ABAPayWay' + $ref: "#/components/schemas/InvoicePOSTRequest" multipart/form-data: schema: - $ref: '#/components/schemas/ABAPayWay' + $ref: "#/components/schemas/InvoicePOSTRequest" required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "201": content: application/json: schema: - $ref: '#/components/schemas/ABAPayWaySubmitSDKSuccessCallback' - description: '' - '400': + $ref: "#/components/schemas/InvoicePOSTResponse" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/ABAPayWayFailureResponse' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/apay/pay/: + $ref: "#/components/schemas/InvoiceClientErrors" + description: "" + /b/pbl/v2/auto-debit/: post: - operationId: post_pay_apple_pay - description: Submit an Apple Pay payment once received the `token` from ApplePay. - summary: Submit an Apple Pay payment + operationId: auto_debit + description: |- + This endpoint will take a session id and check for it's related payment if it's possible to be auto charged or not.
if possible it will charge the payment and return the operation response.
📝 **NOTE** Optional fields may not be represented in response body. + + summary: Native Payment API(Auto Debit) + parameters: + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/PayApplePay' + $ref: "#/components/schemas/AutoDebit" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/PayApplePay' + $ref: "#/components/schemas/AutoDebit" multipart/form-data: schema: - $ref: '#/components/schemas/PayApplePay' + $ref: "#/components/schemas/AutoDebit" required: true security: - - Api-Key Authentication: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/DevicePayViewSuccessResponse' - description: '' - '400': + $ref: "#/components/schemas/SchemaWebhook" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/ApplePayRejectedResponse' - description: '' - '401': + $ref: "#/components/schemas/AutoDebitErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/apay/validate-session/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/card/: post: - operationId: post_validate_apple_pay_session - description: Validate session for device eligibility and payment request accuracy. - summary: Validate Apple Pay session + operationId: get_user_cards + description: |- + This endpoint retrieves a list of cards saved by the customer. The response includes details such as the card's masked number, card type, and expiration date. By using this endpoint, you can provide the customer with an overview of their saved cards for future payments. + + **Note**: if card is created via save_card operation, below details should be considered + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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. + summary: Retrieve a list of saved cards for the customer. + parameters: + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Checkout SDK + - User Cards requestBody: content: application/json: schema: - $ref: '#/components/schemas/PayApplePay' + $ref: "#/components/schemas/UserCards" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/PayApplePay' + $ref: "#/components/schemas/UserCards" multipart/form-data: schema: - $ref: '#/components/schemas/PayApplePay' + $ref: "#/components/schemas/UserCards" required: true security: - - Api-Key Authentication: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/ApplePaySuccessSessionValidationResponse' - description: '' - '400': + $ref: "#/components/schemas/Card" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/ApplePaySessionValidationErrorResponse' - description: '' - '401': + $ref: "#/components/schemas/CardErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/cancel/{session_id}/: - post: - operationId: sdk_cancel_operation - description: API endpoint to allow cancel operations for SDK. - summary: SDK Cancel Operation - parameters: - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true - tags: - - Checkout SDK - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SDKCancelOperation' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/SDKCancelOperation' - multipart/form-data: - schema: - $ref: '#/components/schemas/SDKCancelOperation' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - responses: - '200': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/SDKCancelOperationResponse' - description: '' - '400': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": content: application/json: schema: - $ref: '#/components/schemas/FieldErrors' - description: '' - '404': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "405": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "415": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/concur-payer-view/{session_id}/: - get: - operationId: concur_payer_sdk - description: When `setupPreload` object is used and the state of the transaction - is `created`, calling this endpoint will update the transaction state to `pending`. - summary: Concur Payer View + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/card/{token}/: + delete: + operationId: delete_user_cards + description: This endpoint allows you to delete a customer's saved card from the system. Provide the unique card identifier to remove the card from the customer's saved cards list. This action can help maintain up-to-date card information and ensure that customers do not accidentally use expired or unwanted cards for payments. + summary: Delete a saved card for the customer. parameters: - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true + - in: query + name: customer_id + schema: + type: string + description: Utilized to retrieve cards associated with a specific customer using their unique customer_id.. + required: true + - in: path + name: token + schema: + type: string + description: The unique token associated with the card, required for tokenized card payments. Use this value to securely process transactions. + required: true + - in: query + name: type + schema: + type: string + description: Choose between `sandbox` and `production`. Select sandbox to retrieve cards created for test Payment Gateway MIDs, or production to fetch real cards used in live transactions. + required: true tags: - - Checkout SDK + - User Cards security: - - SSO_BasicAuth: [] - - basicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "204": content: application/json: schema: {} @@ -1617,10627 +1152,3205 @@ paths: value: {} summary: No Content description: No Content - '400': + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/CardErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/csuc_sdk/pay/{session_id}/{pg_code}/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "415": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/cash-payment/: post: - operationId: csuc_payment_execution - description: "This endpoint executes a Click to Pay payment through Cybersource - Unified Checkout using the transient token generated by the frontend widget. - \n\n**Flow Summary**:\n1. **Initialize Base Handler**: Retrieves `PaymentTransaction` - by `session_id`\n - Validates that exactly one transaction exists (no duplicates)\n - \ - Raises error if transaction not found or multiple found\n2. **Initialize - Click to Pay Handler**: Validates transaction and creates payment attempt\n - \ - Checks transaction validity using `is_valid_for_payment()`\n - Creates - new payment attempt or retrieves latest on condition failure\n3. **Process - Payment**: Sends authorization request to Cybersource\n - Extracts `transient_token` - from `funding_source`\n - Builds payment payload with:\n * Client reference - information (order reference number)\n * Processing information (capture=True - for auto-capture, commerce_indicator='internet')\n * Order information - (amount, currency)\n * Token information (transient token JWT)\n - Calls - Cybersource Payments API for authorization\n4. **Handle Response**: Processes - payment gateway response\n - Saves transaction ID and decoded token to payment - attempt data\n - Updates payment attempt state based on response status\n - \ - Triggers payment state machine transitions\n5. **Generate Response**: - Prepares standardized SDK response\n - Generates redirect URL using `get_standard_redirect_url()`\n - \ - Returns success/failure response with transaction details\n\n\n**Payment - Processing Details**:\n- **Operation Type**: Determined by MID configuration - (CAPTURE or AUTH)\n- **Auto-Capture**: Enabled by default (`capture: True` - in processing_information)\n- **Commerce Indicator**: Set to 'internet' for - online transactions\n- **Decision Manager**: Enabled based on MID configuration - for fraud detection\n\n\n**Request Parameters**:\n- `pg_code`: Payment gateway - MID code (validated to support Click to Pay)\n- `session_id`: Payment transaction - session ID\n- `funding_source`: Contains the transient token JWT from Cybersource - widget\n\n\n**Response Handling**:\n- **Success (200)**: Payment authorized, - returns redirect URL and transaction details\n- **Failure**: Returns error - message with attempt details\n- Payment attempt state automatically updated - based on Cybersource response\n\n\n**Error Handling**:\n- Invalid or missing - `session_id`: Returns 400 with appropriate error\n- Multiple transactions - for same session: Returns 400 error\n- Transaction not valid for payment: - Returns 400 with validation error\n- Cybersource API errors: Returns 400 with - gateway error message\n- Payment attempt state conflicts handled by FSM (Finite - State Machine)\n\n\n**Security Considerations**:\n- Transient tokens are single-use - and expire quickly\n- Transaction IDs saved for audit and follow-up operations - (void, capture, refund)\n- All payment data encrypted and logged via `@log_io` - decorator\n- Silent signals prevent duplicate webhook notifications during - processing\n\n\n**Data Saved to Payment Attempt**:\n- `transaction_id`: Cybersource - transaction ID for subsequent operations\n- `transient_token`: The JWT token - used for payment (for audit)\n- `transient_decoded_token`: Decoded token payload - (for debugging)\n- `form_of_payment`: Gateway name (CSUC)\n" - summary: Execute CSUC Payment - parameters: - - in: path - name: pg_code - schema: - type: string - required: true - - in: path - name: session_id - schema: - type: string - required: true + operationId: cash_payment_acknowledgement + description: "**⚠️ DEPRECATED**: This endpoint (`cash-payment/`) is deprecated and will be removed in future releases.
Please migrate to the new endpoint at `payment/cash/` for acknowledging cash payments.

This endpoint handles cash payment acknowledgement requests.
📝 **NOTE**: Optional fields may not be represented in the response body." + summary: Cash Payment Acknowledgement (Deprecated) tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/CSUCPayment' - examples: - CSUCPaymentRequest: - value: - pg_code: CSUC_KWT_001 - session_id: abc123def456ghi789 - funding_source: - transient_token: eyJraWQiOiJ6dSIsImFsZyI6IlJTMjU2In0... - summary: CSUC Payment Request + $ref: "#/components/schemas/CashPayment" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/CSUCPayment' + $ref: "#/components/schemas/CashPayment" multipart/form-data: schema: - $ref: '#/components/schemas/CSUCPayment' + $ref: "#/components/schemas/CashPayment" required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/SchemaWebhook' - description: '' - '400': + $ref: "#/components/schemas/SchemaWebhook" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/CSUCPaymentFailureResponse' - description: '' - '401': + $ref: "#/components/schemas/CashAcknowledgementErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/csuc_sdk/submit/{session_id}/{pg_code}/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/inquiry/: post: - operationId: csuc_payment_config_generation - description: "This endpoint initializes the Cybersource Unified Checkout (CSUC) - payment flow by generating and returning the capture context token and associated - configuration. \n\n**Flow Summary**:\n1. **Validate Inputs**: The `pg_code` - and `session_id` are validated to ensure:\n - The MID exists and supports - Click to Pay payment method\n - The payment transaction exists and is valid - for payment\n2. **Retrieve Transaction**: Fetches the `PaymentTransaction` - using `session_id`\n3. **Create/Reuse Payment Attempt**: Either creates a - new payment attempt or reuses the latest one\n4. **Generate Capture Context**: - Calls Cybersource API to create a capture context JWT token containing:\n - \ - Allowed card networks and payment types\n - Client version and locale - settings\n - Billing, shipping, and email capture mandates\n - Transaction - amount and currency\n - Decision manager configuration\n5. **Parse Token**: - Decodes the JWT to extract SDK client configuration:\n - JavaScript SDK - URL and integrity hash\n - Payment form submission URL\n6. **Cache & Return**: - Caches the complete response (10 min TTL) and returns configuration\n\n\n**Capture - Context Caching**:\n- Capture contexts are cached using key: `{mid_code}_{session_id}_ctp_context`\n- - Cache TTL: 600 seconds (10 minutes)\n- Subsequent requests with same session - reuse cached context\n\n\n**Response Structure**:\n- `sdk_client`: Contains - the Cybersource JS SDK URL, SRI integrity hash, and CORS settings\n- `form_config`: - Specifies the payment execution endpoint URL and form parameters\n- `capture_context`: - JWT token to initialize the checkout widget\n\n\n**Typical Use Case**:\n- - Called by frontend before rendering the Cybersource payment widget\n- The - frontend loads the SDK from `sdk_client.src` with integrity verification\n- - The `capture_context` is passed to Cybersource's JavaScript SDK\n- After user - completes payment, the widget generates a transient token\n- Frontend submits - transient token to `form_config.action` URL\n\n\n**Integration Steps**:\n1. - Frontend calls this endpoint with `pg_code` and `session_id`\n2. Backend generates/retrieves - capture context from Cybersource\n3. Frontend dynamically loads the JS SDK - using `sdk_client` configuration\n4. Frontend initializes Cybersource widget - with `capture_context`\n5. User completes payment in Cybersource widget\n6. - Frontend receives transient token from widget\n7. Frontend POSTs transient - token to `form_config.action` URL\n" - summary: Initialize CSUC Payment Flow + operationId: inquiry + description: |- + The Check Status-Inquiry endpoint is part of our Payment Gateway API. It's designed for checking the status of a specific payment transaction. This endpoint is particularly useful when notifications about a transaction status change haven't been received. It acts as a manual check for confirming the payment status, mirroring the structure of a payment webhook notification. + + The Inquiry operation can only be triggered for payment transactions in the `pending`, `attempted`, `failed`, or `expired` states. If the transaction state is already `paid` or `authorized`, the response is returned immediately without re-confirming it with third-party Payment Gateways (PGs). However, if the system isn't up to date and the transaction state is still in one of the mentioned states, Ottu will trigger an API call to the PG to update the transaction state. If multiple payment options were attempted using different PGs, all PGs supporting payment status checks will be called, ensuring the merchant receives the most updated status of the payment. + + This endpoint uses a throttling mechanism to prevent potential system abuse. Throttling rules are as follows: + + 1. **Initial Grace Period (10 minutes):** If the Inquiry endpoint is called within 10 minutes from when the payment transaction is created, the request will be throttled. + + 2. **First Request:** Once the initial grace period has passed, the first request is allowed. Subsequent requests for the same transaction within the next 30 minutes will be throttled. + + 3. **Second Request:** After the end of the first throttle period, a second request is permitted. Further requests for the same transaction within another 30 minutes from the second request are throttled. + + 4. **Subsequent Requests:** If the number of requests for the same transaction exceeds three within the overall time frame, any further requests are denied. + + Note: The above rules are applied per transaction. Additionally, the endpoint allows a maximum of 30 requests per minute across all transactions. + + It's mandatory to provide at least one of the identifiers (`session_id` or `order_no`). + summary: Check Status-Inquiry parameters: - - in: path - name: pg_code - schema: - type: string - required: true - - in: path - name: session_id - schema: - type: string - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/SubmitClickToPay' + $ref: "#/components/schemas/Inquiry" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/SubmitClickToPay' + $ref: "#/components/schemas/Inquiry" multipart/form-data: schema: - $ref: '#/components/schemas/SubmitClickToPay' - required: true + $ref: "#/components/schemas/Inquiry" security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/CSUCSubmitSuccessResponse' - description: '' - '400': + $ref: "#/components/schemas/SchemaWebhook" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/CSUCSubmitFailureResponse' - description: '' - '401': + $ref: "#/components/schemas/InquiryErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/doku_sdk/submit/{session_id}/{pg_code}/: - post: - operationId: ctp_payment_config_generation - description: "This endpoint initializes the doku payment flow by provisioning - the required SDK configuration for the frontend to launch the appropriate - checkout widget. \nIt is used at the beginning of the payment journey to fetch - the necessary JS SDK URLs,\ncapture tokens, form attributes, and other metadata - specific to the payment provider.\n**Flow Summary**:\n1. **Validate Inputs**: - The `pg_code` and `session_id` are validated via the serializer.\n2. **Locate - Transaction**: Retrieves the payment transaction using the `session_id`.\n3. - **Setup Context**: Resolves the merchant identity and loads configuration.\n4. - **Provision SDK**: Calls the payment gateway's `get_vendor_sdk_config()` to - receive SDK metadata.\n5. **Respond**: Returns the configuration as a unified - structure to be consumed by the frontend.\n**Typical Use Case**:\n- Used by - the frontend to prepare a Click to Pay UI (e.g., DOKU, CSUC).\n- Useful requires - an initial context/token.\n" - summary: Submit Doku - parameters: - - in: path - name: pg_code - schema: - type: string - required: true - - in: path - name: session_id - schema: - type: string - required: true - tags: - - Checkout SDK - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SubmitClickToPay' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/SubmitClickToPay' - multipart/form-data: - schema: - $ref: '#/components/schemas/SubmitClickToPay' - required: true - security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] - responses: - '200': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/ClickToPaySubmitSuccessResponse' - description: '' - '400': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "404": content: application/json: schema: - $ref: '#/components/schemas/ClickToPaySubmitFailureResponse' - description: '' - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "415": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/geidea_sdk/submit/{session_id}/{pg_code}/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/message-notification/: post: - operationId: geidea_payment_config_generation - description: "This endpoint initializes the Geidea payment flow by provisioning - the required SDK configuration for the frontend to launch the appropriate - checkout widget. \nIt is used at the beginning of the payment journey to fetch - the necessary JS SDK URLs,\nsession ID, merchant public key, and other metadata - specific to Geidea.\n**Flow Summary**:\n1. **Validate Inputs**: The `pg_code` - and `session_id` are validated via the serializer.\n2. **Locate Transaction**: - Retrieves the payment transaction using the `session_id`.\n3. **Setup Context**: - Resolves the merchant identity and loads configuration.\n4. **Provision SDK**: - Calls the payment gateway's `get_vendor_sdk_config()` to receive SDK metadata.\n5. - **Respond**: Returns the configuration as a unified structure to be consumed - by the frontend.\n**Typical Use Case**:\n- Used by the frontend to prepare - a Geidea checkout UI.\n- Requires an initial context/token.\n" - summary: Submit Geidea + operationId: message_notifications + description: |+ + The Message Notifications API provides an interface to send proper notification for any given transaction based on the provided `session_id` or `order_no`. + + This API is useful when you need to manually trigger the notification process for a specific payment transaction, such as when a payment is successful but the notification has not been sent. + + Two key identifiers, `order_no` and `session_id`, can be used interchangeably to specify the payment transaction that the operation should be applied to. + + By providing any combination of `email`, `sms` or `whatsapp` in `channels`, if relative configurations are present and the transaction's notification field has the event inside the specified channel, the API will initiate the notification process. + + For every operation, the API provides a clear response containing information about the executed operation, a user-friendly message (`detail`), and the operation's result (`success` indicates a successful operation). + + summary: Message Notifications parameters: - - in: path - name: pg_code - schema: - type: string - required: true - - in: path - name: session_id - schema: - type: string - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Checkout SDK + - Payment Notifications requestBody: content: application/json: schema: - $ref: '#/components/schemas/SubmitClickToPay' + $ref: "#/components/schemas/MessageNotification" + examples: + SMS: + value: + session_id: + channels: + - sms + Email: + value: + order_no: + channels: + - email + summary: Email + WhatsApp&SMS: + value: + session_id: + channels: + - sms + - whatsapp + summary: WhatsApp & SMS Notifications application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/SubmitClickToPay' + $ref: "#/components/schemas/MessageNotification" multipart/form-data: schema: - $ref: '#/components/schemas/SubmitClickToPay' + $ref: "#/components/schemas/MessageNotification" required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_JWT_Auth: [] + - tokenAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/GeideaSubmitSuccessResponse' - description: '' - '400': + $ref: "#/components/schemas/PaymentNotificationResponses" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GeideaSubmitFailureResponse' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/gpay/pay/: - post: - operationId: post_pay_google_pay - description: Submit a Google Pay payment once received the `paymentData` from - GooglePay. - summary: Submit a Google Pay payment - tags: - - Checkout SDK - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PayGooglePay' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/PayGooglePay' - multipart/form-data: - schema: - $ref: '#/components/schemas/PayGooglePay' - required: true - security: - - Api-Key Authentication: [] - responses: - '200': + $ref: "#/components/schemas/PaymentNotificationErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/DevicePayView' - description: '' - '400': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/GooglePayPayRejectedResponse' - description: '' - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "405": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/pre-payment-option-check/{session_id}/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/notifications/send/{channel}/: post: - operationId: get_pre_payment_option - description: This endpoint allows you to retrieve the pre payment options for - specific user using tabby integrated API. - summary: Retrieve Pre Payment Check response. + operationId: send_specific_notification + description: |+ + This API endpoint sends notifications via the specified channel (email, SMS, or WhatsApp) for a given template. + + The template_id (provided in the request body) identifies the notification template to use. The notification channel is specified as part of the URL path (/notifications/send/{channel}/). This API allows you to manually trigger notifications for specific templates and channels. The available channels are email, SMS, and WhatsApp. The API will initiate the notification process If the specified channel is configured and the corresponding notification event exists for the given template. + + The API response includes details about the notification, a user-friendly message, and a channel indicator. A message indicates that the notification process was initiated successfully. + + summary: Channel Specific Notifications parameters: - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: path + name: channel + schema: + type: string + enum: + - email + - sms + - whatsapp + description: Specify the channel of notification to send. + required: true tags: - - PaymentMethods API + - Communication Notifications requestBody: content: application/json: schema: - $ref: '#/components/schemas/PGCodeValidation' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/PGCodeValidation' - multipart/form-data: - schema: - $ref: '#/components/schemas/PGCodeValidation' - required: true - security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + $ref: "#/components/schemas/ChannelSpecificNotification" + examples: + Email: + value: + template_id: communication-notification-email + language: en + context: + communication_message: Simple Message + extra_info: extra_info + to: initial_user@domain.com + cc: + - user@domain.com + - user2@domain.com + bcc: + - user3@domain.com + body: This is plain text body. + attachments: + - filename: Example_File.pdf + content: base64_encoded_file_content + content_type: application/pdf + - filename: Example_data.csv + content: base64_encoded_file_content + content_type: plain/text + summary: Email + SMS: + value: + channel: sms + template_id: communication-notification-sms + language: en + context: + communication_message: Simple Message + extra_info: extra_info + to: "+96599999999" + summary: SMS + WHATSAPP: + value: + channel: whatsapp + template_id: communication-notification-whatsapp + unit_config: unit-config-identifier + language: en + context: + communication_message: Simple Message + extra_info: extra_info + to: "+96599999999" + summary: WhatsApp + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/ChannelSpecificNotification" + multipart/form-data: + schema: + $ref: "#/components/schemas/ChannelSpecificNotification" + required: true + security: + - SSO_JWT_Auth: [] + - tokenAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/PrePaymentCheckResponses' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/FieldErrors' - description: '' - '403': + "200": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/pymt-txn/submit/{session_id}/: - get: - operationId: initiate_checkout_sdk - description: The payment details to be used for initiating a checkout process - using the Checkout SDK. When utilizing `setupPreload` and the transaction's - state is `created`, calling the Concur Payer View updates the transaction - state to `pending`. - summary: Retrieve init data - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true - tags: - - Checkout SDK - security: - - SSO_BasicAuth: [] - - basicAuth: [] - responses: - '200': + $ref: "#/components/schemas/ChannelNotificationResponses" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/CheckoutSDKResponse' - description: '' - '400': + $ref: "#/components/schemas/ChannelNotificationErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "405": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/stcpay/pay/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/operation/: post: - operationId: stc_pay_checkout_sdk_capture - description: " \n The Capture endpoint is responsible for processing - capture requests to STC Bank.\n It accepts the session ID and OTP - (One-Time Password) as input parameters.\n The endpoint performs - a capture request to STC Bank\n and handles the transaction state - based on the response from the payment gateway.\n " - summary: Submit STC Bank OTP + operationId: public_operations + description: |+ + The Payment Operations API provides an interface to manage your payment transactions beyond their initial creation. It allows for several operations including `refund`, `capture`, `void`, and others, directly syncing with the Payment Gateway (PG) for certain actions to ensure consistency across systems. + + Two key identifiers, `order_no` and `session_id`, can be used interchangeably to specify the payment transaction that the operation should be applied to. + + For operations such as `refund` and `capture`, you can optionally define the `amount` to be actioned. If not provided, the API will attempt to perform the operation on the full amount, or the remaining amount if previous operations were conducted. However, note that for `void`, the operation always applies to the full amount, ignoring the `amount` value if provided. + + This API also allows you to perform certain operations solely at the Ottu system level, providing increased control over your payment transactions. + + For every operation, the API provides a clear response containing information about the executed operation, a user-friendly message (`detail`), and the operation's result (`success` indicates a successful operation). + + summary: Operations + parameters: + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true + - in: header + name: Tracking-Key + schema: + type: string + default: "Tracking-Key: your_operation_tracking_key" + description: |+ + The Tracking-Key is a unique identifier provided by the merchant for each operation request. + + It is crucial for ensuring the distinctiveness of each operation. + + When initiating an operation, this key is stored alongside other transaction details in the database. + + It serves as a reference for future status queries. + + Enabling the retrieval of the latest status information for a specific operation. + + Ensure that each `Tracking-Key` is distinct to prevent ambiguities in operation tracking and status updates. + tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/SubmitSMSPaymentPaymentRequest' + $ref: "#/components/schemas/Operation" + examples: + Expire: + value: + session_id: + operation: expire + Refund: + value: + session_id: + operation: refund + amount: "100.000" + summary: Refund + WalletRefund: + value: + session_id: + operation: refund + amount: "100.000" + destination: wallet + summary: Wallet Refund + description: Credits the refund to the customer's wallet linked to the settling MID. + IFGRefund: + value: + session_id: + operation: refund + amount: "100.000" + extra: + orders: + - passengerDocumentNumber: "4862100022075" + amount: 1 + - passengerDocumentNumber: "4862100022076" + amount: 1 + - passengerDocumentNumber: "4862100022077" + amount: 0 + summary: IFG Partial Refund application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/SubmitSMSPaymentPaymentRequest' + $ref: "#/components/schemas/Operation" multipart/form-data: schema: - $ref: '#/components/schemas/SubmitSMSPaymentPaymentRequest' + $ref: "#/components/schemas/Operation" required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/PaymentOperationResponses" + description: "" + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/PaymentOperationErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/STCPayRejectedResponse' - description: '' - '401': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/stcpay/submit/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "405": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/payment-methods/: post: - operationId: stc_pay_checkout_sdk_authorize - description: "\n To initiate a payment using the SDK for STC Bank - Payment,\n you are required to submit the customer's phone number\n - \ and indicate whether to enable the option to save the card for - future use. \n " - summary: Submit STC Bank payment method + operationId: get_payment_methods + description: This endpoint allows you to retrieve the available payment methods for a specific plugin, operation and customer. You can specify the desired filter field to get a list of payment methods that are supported and accessible. + summary: Retrieve a list of payment methods based on filter values. tags: - - Checkout SDK + - PaymentMethods API requestBody: content: application/json: schema: - $ref: '#/components/schemas/SMSPaymentAuthorizePayment' + $ref: "#/components/schemas/PaymentMethodsRequest" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/SMSPaymentAuthorizePayment' + $ref: "#/components/schemas/PaymentMethodsRequest" multipart/form-data: schema: - $ref: '#/components/schemas/SMSPaymentAuthorizePayment' + $ref: "#/components/schemas/PaymentMethodsRequest" + required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/STCPaymentAuthorize' - description: '' - '401': + $ref: "#/components/schemas/PaymentMethodsResponse" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '400': + $ref: "#/components/schemas/FieldErrors" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/STCPayPaymentRejectedResponse' - description: '' - /b/checkout/api/sdk/v1/submit-token/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/payment/apple-pay/: post: - operationId: submit_token_payment_method - description: Use the Pay with Token Endpoint to process a payment with a saved - card token. - summary: Submit token payment method - parameters: - - in: header - name: Channel - schema: - type: string - description: Specifies the transaction channel through which the payment is - processed, such as `hosted` or `mobile_sdk`.Each channel may have specific - processing logic and security requirements. - required: true - - in: header - name: Merchant-Id - schema: - type: string - description: The Merchant ID is required for authentication purposes.It identifies - the requesting merchant and ensures that the request is authorized to access - the public key. - required: true + operationId: apple_native_payment + description: |- + Allows merchants to submit an Apple Pay payment directly via server-to-server integration. This endpoint requires private key authentication and expects a valid Apple Pay token structure in the request payload under `payload`. + + Typical use case: The merchant collects the Apple Pay token on their frontend and sends it to this endpoint along with session and amount information. + summary: Native Payment API(Apple Pay) tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/SubmitToken' + $ref: "#/components/schemas/ApplePayNativePayment" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/ApplePayNativePayment" + multipart/form-data: + schema: + $ref: "#/components/schemas/ApplePayNativePayment" required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/SDKSubmitTokenResponse' - description: '' - '400': + $ref: "#/components/schemas/SchemaWebhook" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/FieldErrors' - description: '' - '404': + $ref: "#/components/schemas/NativeApplePaymentErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/submit/{session_id}/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/payment/auto-debit/: post: - operationId: submit_redirect_payment_method - description: Submit the payment method customer has selected on the SDK and - in return get the PG url where the user can be redirected to perform the payment. - summary: Submit redirect payment method + operationId: auto_debit_2 + description: |- + This endpoint will take a session id and check for it's related payment if it's possible to be auto charged or not.
if possible it will charge the payment and return the operation response.
📝 **NOTE** Optional fields may not be represented in response body. + + summary: Native Payment API(Auto Debit) parameters: - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/CheckoutSubmit' + $ref: "#/components/schemas/AutoDebit" + application/x-www-form-urlencoded: + schema: + $ref: "#/components/schemas/AutoDebit" + multipart/form-data: + schema: + $ref: "#/components/schemas/AutoDebit" required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SDKSubmitRedirectResponse' - description: '' - '400': + "200": content: application/json: schema: - $ref: '#/components/schemas/FieldErrors' - description: '' - '404': + $ref: "#/components/schemas/SchemaWebhook" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '401': + $ref: "#/components/schemas/AutoDebitErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/urpay/pay/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/payment/cash/: post: - operationId: urpay_pay_checkout_sdk_capture - description: " \n The Capture endpoint is responsible for processing - capture requests to URPay pay.\n It accepts the session ID and - OTP (One-Time Password) as input parameters.\n The endpoint performs - a capture request to URPay pay\n and handles the transaction state - based on the response from the payment gateway.\n " - summary: Submit URPay Pay OTP + operationId: cash_payment_acknowledgement_2 + description: "**⚠️ DEPRECATED**: This endpoint (`cash-payment/`) is deprecated and will be removed in future releases.
Please migrate to the new endpoint at `payment/cash/` for acknowledging cash payments.

This endpoint handles cash payment acknowledgement requests.
📝 **NOTE**: Optional fields may not be represented in the response body." + summary: Cash Payment Acknowledgement (Deprecated) tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/SubmitSMSPaymentPaymentRequest' + $ref: "#/components/schemas/CashPayment" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/SubmitSMSPaymentPaymentRequest' + $ref: "#/components/schemas/CashPayment" multipart/form-data: schema: - $ref: '#/components/schemas/SubmitSMSPaymentPaymentRequest' + $ref: "#/components/schemas/CashPayment" required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] + - SSO_JWT_Auth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/URPayPayRejectedResponse' - description: '' - '401': + $ref: "#/components/schemas/SchemaWebhook" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/api/sdk/v1/urpay/submit/: + $ref: "#/components/schemas/CashAcknowledgementErrors" + description: "" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/payment/google-pay/: post: - operationId: urpay_pay_checkout_sdk_authorize - description: "\n To initiate a payment using the SDK for URPay pay - Payment,\n you are required to submit the customer's phone number\n - \ and indicate whether to enable the option to save the card for - future use. \n " - summary: Submit URPay Pay payment method + operationId: google_native_payment + description: |- + Allows merchants to submit an Google Pay payment directly via server-to-server integration. This endpoint requires private key authentication and expects a valid Google Pay token structure in the request payload under `payload`. + + Typical use case: The merchant collects the Google Pay token on their frontend and sends it to this endpoint along with session and amount information. + summary: Native Payment API(Google Pay) tags: - - Checkout SDK + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/SMSPaymentAuthorizePayment' + $ref: "#/components/schemas/GooglePayNativePayment" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/SMSPaymentAuthorizePayment' + $ref: "#/components/schemas/GooglePayNativePayment" multipart/form-data: schema: - $ref: '#/components/schemas/SMSPaymentAuthorizePayment' + $ref: "#/components/schemas/GooglePayNativePayment" + required: true security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/URPayPaymentAuthorize' - description: '' - '401': + $ref: "#/components/schemas/NativeGooglePaymentSuccess" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '400': + $ref: "#/components/schemas/NativeGooglePaymentErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/URPayPayPaymentRejectedResponse' - description: '' - /b/checkout/v1/pymt-txn/: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/payment/wallet/: post: - operationId: create_payment_transaction_checkout - description: Create a new Payment Transaction - summary: Create a new Payment Transaction - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true + operationId: wallet_native_payment + description: |- + Allows merchants to charge a customer's wallet balance directly via server-to-server integration. The wallet service is identified by `instrument_type=wallet` in the checkout transaction. + + The payment is processed using the customer's wallet account linked to the transaction's `customer_id`. No additional payload is required from the customer — the wallet service handles the debit internally. + summary: Native Payment API (Wallet) tags: - - Checkout API + - Payment Operations requestBody: content: application/json: schema: - $ref: '#/components/schemas/CheckoutPOSTRequest' + $ref: "#/components/schemas/WalletNativePayment" application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/CheckoutPOSTRequest' + $ref: "#/components/schemas/WalletNativePayment" multipart/form-data: schema: - $ref: '#/components/schemas/CheckoutPOSTRequest' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Success' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/ClientErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '415': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '423': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/v1/pymt-txn/{session_id}/: - get: - operationId: retrieve_payment_transaction_checkout - description: Retrieve an existing Payment Transaction by session_id - summary: Retrieve Payment Transaction - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. + $ref: "#/components/schemas/WalletNativePayment" required: true - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true - tags: - - Checkout API security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/CheckoutGETResponse' - description: '' - '401': + "200": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/SchemaWebhook" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': + $ref: "#/components/schemas/NativeWalletPaymentErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - put: - operationId: full_update_payment_transaction_checkout - description: Update an existing Payment Transaction - summary: Update Payment Transaction + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + /b/pbl/v2/send-notification/: + post: + operationId: send_notification + description: |+ + The Communication Notifications API provides an interface to send notification for any given mail template based on the provided `template_id` and `channel`. + + This API is useful when you need to manually trigger the notification process for a specific mail template. + + Two key identifiers, `template_id` and `channel` both are provided in the request body. + + If the specified channel is configured and the corresponding notification event exists for the given template. + + The API response includes details about the notification, a user-friendly message, and a channel indicator. A message indicates that the notification process was initiated successfully. + + summary: Notifications parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true + - in: header + name: Authorization + schema: + type: string + default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo + description: Private API key to be provided in the format `Api-Key `. + required: true tags: - - Checkout API + - Communication Notifications requestBody: content: application/json: schema: - $ref: '#/components/schemas/Checkout' + $ref: "#/components/schemas/Notification" + examples: + Email: + value: + channel: email + template_id: communication-notification-email + language: en + context: + communication_message: Simple Message + extra_info: extra_info + to: initial_user@domain.com + cc: + - user@domain.com + - user2@domain.com + bcc: + - user3@domain.com + body: This plain text body serves as a fallback in the event of template rendering exceptions. + attachments: + - filename: Example_File.pdf + content: base64_encoded_file_content + content_type: application/pdf + - filename: Example_data.csv + content: base64_encoded_file_content + content_type: plain/text + summary: Email + SMS: + value: + channel: sms + template_id: communication-notification-sms + language: en + context: + communication_message: Simple Message + extra_info: extra_info + to: "+96599999999" + summary: SMS + WHATSAPP: + value: + channel: whatsapp + template_id: communication-notification-whatsapp + unit_config: unit-config-identifier + language: en + context: + communication_message: Simple Message + extra_info: extra_info + to: "+96599999999" + summary: WhatsApp application/x-www-form-urlencoded: schema: - $ref: '#/components/schemas/Checkout' + $ref: "#/components/schemas/Notification" multipart/form-data: schema: - $ref: '#/components/schemas/Checkout' + $ref: "#/components/schemas/Notification" required: true security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] + - SSO_JWT_Auth: [] + - tokenAuth: [] + - basicAuth: [] + - SSO_BasicAuth: [] responses: - '200': + "200": content: application/json: schema: - $ref: '#/components/schemas/Checkout' - description: '' - '400': + $ref: "#/components/schemas/NotificationResponses" + description: "" + "400": content: application/json: schema: - $ref: '#/components/schemas/Client Errors' - description: '' - '401': + $ref: "#/components/schemas/NotificationErrors" + description: "" + "401": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "403": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': + $ref: "#/components/schemas/GenericErrorMessage" + description: "" + "405": content: application/json: schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - patch: - operationId: partial_update_payment_transaction_checkout - description: Partially update an existing Payment Transaction - summary: Partially Update Payment Transaction - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - - in: path - name: session_id - schema: - type: string - pattern: ^[-\w]+$ - required: true - tags: - - Checkout API - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchedCheckoutPATCHRequest' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/PatchedCheckoutPATCHRequest' - multipart/form-data: - schema: - $ref: '#/components/schemas/PatchedCheckoutPATCHRequest' - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/CheckoutPATCHResponse' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/checkout/v1/upload-attachment/: - post: - operationId: upload_attachment - description: Upload a file, attach it to a transaction if `session_id` or `order_no` - is provided and shorify if `shortify_attachment_url` is true. - summary: Attachment Upload - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - Checkout API - requestBody: - content: - multipart/form-data: - schema: - $ref: '#/components/schemas/AttachmentUpload' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/AttachmentUploadSuccessSerializers' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/AttachmentUploadClientErrors' - description: '' - /b/invoice/v1/invoice/: - post: - operationId: create_invoice - description: Create a new Invoice - summary: Create a new Invoice - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - Invoice API - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/InvoicePOSTRequest' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/InvoicePOSTRequest' - multipart/form-data: - schema: - $ref: '#/components/schemas/InvoicePOSTRequest' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/InvoicePOSTResponse' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/InvoiceClientErrors' - description: '' - /b/op/attempt/{session_id}: - post: - operationId: create_attempt_pymt_txn_for_ottu_pg - description: demo - summary: Fetch Ottu session data - parameters: - - in: path - name: session_id - schema: - type: string - required: true - tags: - - Ottu PG - security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] - - {} - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/OttuPGPymtTxn' - description: '' - /b/pbl/v2/auto-debit/: - post: - operationId: auto_debit - description: "This endpoint will take a session id and check for it's related - payment if it's possible to be auto charged or not.
if possible it - will charge the payment and return the operation response.
\U0001F4DD - **NOTE** Optional fields may not be represented in response body.\n " - summary: Native Payment API(Auto Debit) - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AutoDebit' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/AutoDebit' - multipart/form-data: - schema: - $ref: '#/components/schemas/AutoDebit' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SchemaWebhook' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/AutoDebitErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/card/: - post: - operationId: get_user_cards - description: "This endpoint retrieves a list of cards saved by the customer. - The response includes details such as the card's masked number, card type, - and expiration date. By using this endpoint, you can provide the customer - with an overview of their saved cards for future payments.\n\n**Note**: if - card is created via save_card operation, below details should be considered\n1. - The amount must be zero for the save card operation. \n2. The selected MID(pg_code) - must support tokenization to enable the save card operation. \n3. Please note - that the save card operation is considered successful without any funds being - charged.\n4. Once a card is created, Ottu will send a webhook containing the - card details to the merchant's webhook URL.\n5. 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." - summary: Retrieve a list of saved cards for the customer. - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - User Cards - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UserCards' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/UserCards' - multipart/form-data: - schema: - $ref: '#/components/schemas/UserCards' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Card' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/CardErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '415': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/card/{token}/: - delete: - operationId: delete_user_cards - description: This endpoint allows you to delete a customer's saved card from - the system. Provide the unique card identifier to remove the card from the - customer's saved cards list. This action can help maintain up-to-date card - information and ensure that customers do not accidentally use expired or unwanted - cards for payments. - summary: Delete a saved card for the customer. - parameters: - - in: query - name: customer_id - schema: - type: string - description: Utilized to retrieve cards associated with a specific customer - using their unique customer_id.. - required: true - - in: path - name: token - schema: - type: string - description: The unique token associated with the card, required for tokenized - card payments. Use this value to securely process transactions. - required: true - - in: query - name: type - schema: - type: string - description: Choose between `sandbox` and `production`. Select sandbox to - retrieve cards created for test Payment Gateway MIDs, or production to fetch - real cards used in live transactions. - required: true - tags: - - User Cards - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '204': - content: - application/json: - schema: {} - examples: - NoContent: - value: {} - summary: No Content - description: No Content - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/CardErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '415': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/cash-payment/: - post: - operationId: cash_payment_acknowledgement - description: "**⚠️ DEPRECATED**: This endpoint (`cash-payment/`) is deprecated - and will be removed in future releases.
Please migrate to the new endpoint - at `payment/cash/` for acknowledging cash payments.

This endpoint - handles cash payment acknowledgement requests.
\U0001F4DD **NOTE**: Optional - fields may not be represented in the response body." - summary: Cash Payment Acknowledgement (Deprecated) - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CashPayment' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/CashPayment' - multipart/form-data: - schema: - $ref: '#/components/schemas/CashPayment' - required: true - security: - - basicAuth: [] - - SSO_BasicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SchemaWebhook' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/CashAcknowledgementErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/inquiry/: - post: - operationId: inquiry - description: "The Check Status-Inquiry endpoint is part of our Payment Gateway - API. It's designed for checking the status of a specific payment transaction. - This endpoint is particularly useful when notifications about a transaction - status change haven't been received. It acts as a manual check for confirming - the payment status, mirroring the structure of a payment webhook notification. - \n\nThe Inquiry operation can only be triggered for payment transactions in - the `pending`, `attempted`, `failed`, or `expired` states. If the transaction - state is already `paid` or `authorized`, the response is returned immediately - without re-confirming it with third-party Payment Gateways (PGs). However, - if the system isn't up to date and the transaction state is still in one of - the mentioned states, Ottu will trigger an API call to the PG to update the - transaction state. If multiple payment options were attempted using different - PGs, all PGs supporting payment status checks will be called, ensuring the - merchant receives the most updated status of the payment. \n\nThis endpoint - uses a throttling mechanism to prevent potential system abuse. Throttling - rules are as follows:\n\n1. **Initial Grace Period (10 minutes):** If the - Inquiry endpoint is called within 10 minutes from when the payment transaction - is created, the request will be throttled.\n\n2. **First Request:** Once the - initial grace period has passed, the first request is allowed. Subsequent - requests for the same transaction within the next 30 minutes will be throttled.\n\n3. - **Second Request:** After the end of the first throttle period, a second request - is permitted. Further requests for the same transaction within another 30 - minutes from the second request are throttled.\n\n4. **Subsequent Requests:** - If the number of requests for the same transaction exceeds three within the - overall time frame, any further requests are denied.\n\nNote: The above rules - are applied per transaction. Additionally, the endpoint allows a maximum of - 30 requests per minute across all transactions.\n\nIt's mandatory to provide - at least one of the identifiers (`session_id` or `order_no`)." - summary: Check Status-Inquiry - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Inquiry' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/Inquiry' - multipart/form-data: - schema: - $ref: '#/components/schemas/Inquiry' - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SchemaWebhook' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/InquiryErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '415': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/message-notification/: - post: - operationId: message_notifications - description: "The Message Notifications API provides an interface to send proper - notification for any given transaction based on the provided `session_id` - or `order_no`.\n\nThis API is useful when you need to manually trigger the - notification process for a specific payment transaction, such as when a payment - is successful but the notification has not been sent.\n\nTwo key identifiers, - `order_no` and `session_id`, can be used interchangeably to specify the payment - transaction that the operation should be applied to.\n\nBy providing any combination - of `email`, `sms` or `whatsapp` in `channels`, if relative configurations - are present and the transaction's notification field has the event inside - the specified channel, the API will initiate the notification process. \n\nFor - every operation, the API provides a clear response containing information - about the executed operation, a user-friendly message (`detail`), and the - operation's result (`success` indicates a successful operation).\n\n" - summary: Message Notifications - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - Payment Notifications - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/MessageNotification' - examples: - SMS: - value: - session_id: - channels: - - sms - Email: - value: - order_no: - channels: - - email - summary: Email - WhatsApp&SMS: - value: - session_id: - channels: - - sms - - whatsapp - summary: WhatsApp & SMS Notifications - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/MessageNotification' - multipart/form-data: - schema: - $ref: '#/components/schemas/MessageNotification' - required: true - security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentNotificationResponses' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentNotificationErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/notifications/send/{channel}/: - post: - operationId: send_specific_notification - description: |+ - This API endpoint sends notifications via the specified channel (email, SMS, or WhatsApp) for a given template. - - The template_id (provided in the request body) identifies the notification template to use. The notification channel is specified as part of the URL path (/notifications/send/{channel}/). This API allows you to manually trigger notifications for specific templates and channels. The available channels are email, SMS, and WhatsApp. The API will initiate the notification process If the specified channel is configured and the corresponding notification event exists for the given template. - - The API response includes details about the notification, a user-friendly message, and a channel indicator. A message indicates that the notification process was initiated successfully. - - summary: Channel Specific Notifications - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - - in: path - name: channel - schema: - type: string - enum: - - email - - sms - - whatsapp - description: Specify the channel of notification to send. - required: true - tags: - - Communication Notifications - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ChannelSpecificNotification' - examples: - Email: - value: - template_id: communication-notification-email - language: en - context: - communication_message: Simple Message - extra_info: extra_info - to: initial_user@domain.com - cc: - - user@domain.com - - user2@domain.com - bcc: - - user3@domain.com - body: This is plain text body. - attachments: - - filename: Example_File.pdf - content: base64_encoded_file_content - content_type: application/pdf - - filename: Example_data.csv - content: base64_encoded_file_content - content_type: plain/text - summary: Email - SMS: - value: - channel: sms - template_id: communication-notification-sms - language: en - context: - communication_message: Simple Message - extra_info: extra_info - to: '+96599999999' - summary: SMS - WHATSAPP: - value: - channel: whatsapp - template_id: communication-notification-whatsapp - unit_config: unit-config-identifier - language: en - context: - communication_message: Simple Message - extra_info: extra_info - to: '+96599999999' - summary: WhatsApp - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/ChannelSpecificNotification' - multipart/form-data: - schema: - $ref: '#/components/schemas/ChannelSpecificNotification' - required: true - security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ChannelNotificationResponses' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/ChannelNotificationErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/operation/: - post: - operationId: public_operations - description: |+ - The Payment Operations API provides an interface to manage your payment transactions beyond their initial creation. It allows for several operations including `refund`, `capture`, `void`, and others, directly syncing with the Payment Gateway (PG) for certain actions to ensure consistency across systems. - - Two key identifiers, `order_no` and `session_id`, can be used interchangeably to specify the payment transaction that the operation should be applied to. - - For operations such as `refund` and `capture`, you can optionally define the `amount` to be actioned. If not provided, the API will attempt to perform the operation on the full amount, or the remaining amount if previous operations were conducted. However, note that for `void`, the operation always applies to the full amount, ignoring the `amount` value if provided. - - This API also allows you to perform certain operations solely at the Ottu system level, providing increased control over your payment transactions. - - For every operation, the API provides a clear response containing information about the executed operation, a user-friendly message (`detail`), and the operation's result (`success` indicates a successful operation). - - summary: Operations - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - - in: header - name: Tracking-Key - schema: - type: string - default: 'Tracking-Key: your_operation_tracking_key' - description: |+ - The Tracking-Key is a unique identifier provided by the merchant for each operation request. - - It is crucial for ensuring the distinctiveness of each operation. - - When initiating an operation, this key is stored alongside other transaction details in the database. - - It serves as a reference for future status queries. - - Enabling the retrieval of the latest status information for a specific operation. - - Ensure that each `Tracking-Key` is distinct to prevent ambiguities in operation tracking and status updates. - - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Operation' - examples: - Expire: - value: - session_id: - operation: expire - Refund: - value: - session_id: - operation: refund - amount: '100.000' - summary: Refund - IFGRefund: - value: - session_id: - operation: refund - amount: '100.000' - extra: - orders: - - passengerDocumentNumber: '4862100022075' - amount: 1 - - passengerDocumentNumber: '4862100022076' - amount: 1 - - passengerDocumentNumber: '4862100022077' - amount: 0 - summary: IFG Partial Refund - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/Operation' - multipart/form-data: - schema: - $ref: '#/components/schemas/Operation' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentOperationResponses' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentOperationErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/payment-methods/: - post: - operationId: get_payment_methods - description: This endpoint allows you to retrieve the available payment methods - for a specific plugin, operation and customer. You can specify the desired - filter field to get a list of payment methods that are supported and accessible. - summary: Retrieve a list of payment methods based on filter values. - tags: - - PaymentMethods API - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentMethodsRequest' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/PaymentMethodsRequest' - multipart/form-data: - schema: - $ref: '#/components/schemas/PaymentMethodsRequest' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/PaymentMethodsResponse' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/FieldErrors' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/payment/apple-pay/: - post: - operationId: apple_direct_payment - description: "Allows merchants to submit an Apple Pay payment directly via server-to-server - integration. This endpoint requires private key authentication and expects - a valid Apple Pay token structure in the request payload under `payload`. - \n\nTypical use case: The merchant collects the Apple Pay token on their frontend - and sends it to this endpoint along with session and amount information." - summary: Native Payment API(Apple Pay) - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ApplePayDirectPayment' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/ApplePayDirectPayment' - multipart/form-data: - schema: - $ref: '#/components/schemas/ApplePayDirectPayment' - required: true - security: - - basicAuth: [] - - SSO_BasicAuth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SchemaWebhook' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/DirectApplePaymentErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/payment/auto-debit/: - post: - operationId: auto_debit_2 - description: "This endpoint will take a session id and check for it's related - payment if it's possible to be auto charged or not.
if possible it - will charge the payment and return the operation response.
\U0001F4DD - **NOTE** Optional fields may not be represented in response body.\n " - summary: Native Payment API(Auto Debit) - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AutoDebit' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/AutoDebit' - multipart/form-data: - schema: - $ref: '#/components/schemas/AutoDebit' - required: true - security: - - SSO_BasicAuth: [] - - basicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SchemaWebhook' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/AutoDebitErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/payment/cash/: - post: - operationId: cash_payment_acknowledgement_2 - description: "**⚠️ DEPRECATED**: This endpoint (`cash-payment/`) is deprecated - and will be removed in future releases.
Please migrate to the new endpoint - at `payment/cash/` for acknowledging cash payments.

This endpoint - handles cash payment acknowledgement requests.
\U0001F4DD **NOTE**: Optional - fields may not be represented in the response body." - summary: Cash Payment Acknowledgement (Deprecated) - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CashPayment' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/CashPayment' - multipart/form-data: - schema: - $ref: '#/components/schemas/CashPayment' - required: true - security: - - basicAuth: [] - - SSO_BasicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SchemaWebhook' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/CashAcknowledgementErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/payment/google-pay/: - post: - operationId: google_direct_payment - description: "Allows merchants to submit an Google Pay payment directly via - server-to-server integration. This endpoint requires private key authentication - and expects a valid Google Pay token structure in the request payload under - `payload`. \n\nTypical use case: The merchant collects the Google Pay token - on their frontend and sends it to this endpoint along with session and amount - information." - summary: Native Payment API(Google Pay) - tags: - - Payment Operations - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/GooglePayDirectPayment' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/GooglePayDirectPayment' - multipart/form-data: - schema: - $ref: '#/components/schemas/GooglePayDirectPayment' - required: true - security: - - basicAuth: [] - - SSO_BasicAuth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/DirectGooglePaymentSuccess' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/DirectGooglePaymentErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/pbl/v2/send-notification/: - post: - operationId: send_notification - description: |+ - The Communication Notifications API provides an interface to send notification for any given mail template based on the provided `template_id` and `channel`. - - This API is useful when you need to manually trigger the notification process for a specific mail template. - - Two key identifiers, `template_id` and `channel` both are provided in the request body. - - If the specified channel is configured and the corresponding notification event exists for the given template. - - The API response includes details about the notification, a user-friendly message, and a channel indicator. A message indicates that the notification process was initiated successfully. - - summary: Notifications - parameters: - - in: header - name: Authorization - schema: - type: string - default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo - description: Private API key to be provided in the format `Api-Key `. - required: true - tags: - - Communication Notifications - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Notification' - examples: - Email: - value: - channel: email - template_id: communication-notification-email - language: en - context: - communication_message: Simple Message - extra_info: extra_info - to: initial_user@domain.com - cc: - - user@domain.com - - user2@domain.com - bcc: - - user3@domain.com - body: This plain text body serves as a fallback in the event of - template rendering exceptions. - attachments: - - filename: Example_File.pdf - content: base64_encoded_file_content - content_type: application/pdf - - filename: Example_data.csv - content: base64_encoded_file_content - content_type: plain/text - summary: Email - SMS: - value: - channel: sms - template_id: communication-notification-sms - language: en - context: - communication_message: Simple Message - extra_info: extra_info - to: '+96599999999' - summary: SMS - WHATSAPP: - value: - channel: whatsapp - template_id: communication-notification-whatsapp - unit_config: unit-config-identifier - language: en - context: - communication_message: Simple Message - extra_info: extra_info - to: '+96599999999' - summary: WhatsApp - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/Notification' - multipart/form-data: - schema: - $ref: '#/components/schemas/Notification' - required: true - security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationResponses' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - /b/utilities/secure-file/{token}/: - get: - operationId: secure_file_download - description: |- - Download sensitive files using temporary authenticated tokens. - - **How it works:** - 1. Backend generates a UUID token when file download is requested - 2. Token is stored in Redis with 15-minute TTL (configurable) - 3. Client receives download URL with token - 4. Client makes GET request with JWT authentication - 5. Server validates token, checks authorization, and serves file - - **Token expiration:** Tokens expire after 15 minutes (default). If you receive a 410 GONE response, refresh the resource to get a new download link. - - **File storage:** Works with both S3 (returns redirect to presigned URL) and local storage (returns file with X-Sendfile header for Apache). - - **Authorization:** Users can only download files they own, unless they are superusers. - summary: Secure file download - parameters: - - in: path - name: token - schema: - type: string - format: uuid - required: true - tags: - - Utilities - security: - - SSO_JWT_Auth: [] - - tokenAuth: [] - - basicAuth: [] - - SSO_BasicAuth: [] - responses: - '200': - content: - application/json: - schema: - description: File download successful. Returns binary file content - (local storage) or redirect (S3). - content: - application/octet-stream: - schema: - type: string - format: binary - description: '' - '302': - content: - application/json: - schema: - description: Redirect to S3 presigned URL (when ENABLE_S3=True) - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/UnauthorizedMessage' - description: '' - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '410': - content: - application/json: - schema: - $ref: '#/components/schemas/TokenExpiredMessage' - description: '' - /b/utilities/shorten-url/: - post: - operationId: shorten_url - description: This endpoint allows authenticated clients with valid URL shortener - credentials to generate a shortened version of a provided long URL. URL shortening - must be enabled in your Ottu Core instance configuration. Ensure the request - includes a valid private API key in the headers to authenticate the request. - summary: Shorten a URL using Ottu's core URL shortening service. - parameters: - - in: header - name: Authorization - schema: - type: string - default: Bearer eyJhbG... - description: Bearer token to be provided for authentication. - required: true - tags: - - Utilities - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/URLShortener' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/URLShortener' - multipart/form-data: - schema: - $ref: '#/components/schemas/URLShortener' - required: true - security: - - SSO_BasicAuth: [] - - SSO_JWT_Auth: [] - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ShortenedURL' - description: '' - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/ClientErrors' - description: '' - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' - '429': - content: - application/json: - schema: - $ref: '#/components/schemas/GenericErrorMessage' - description: '' -components: - schemas: - ABAPayWay: - type: object - description: Serializer for handling base implementation of ABA PayWay. - properties: - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - pg_code: - type: string - description: PG code of payment gateway which a customer selected to perform - the payment or authorization. - sub_option: - type: string - description: Represent the sub-option of the payment method selected by - the user from the available options provided by the PG. - required: - - pg_code - - session_id - - sub_option - ABAPayWayFailureResponse: - oneOf: - - $ref: '#/components/schemas/ABAPayWaySubmitSDKErrorCallback' - ABAPayWayFormData: - type: object - properties: - req_time: - type: string - description: Request timestamp in the format YYYYMMDDHHMMSS. - merchant_id: - type: string - description: Unique identifier for the merchant. - tran_id: - type: string - description: Unique transaction identifier. - amount: - type: string - description: Transaction amount as a string, e.g., '10.73'. - firstname: - type: string - description: Customer's first name. - lastname: - type: string - description: Customer's last name. - email: - type: string - format: email - description: Customer's email address. - phone: - type: string - description: Customer's phone number in international format. - type: - type: string - description: 'Type of transaction: `purchase` or `pre-auth`.' - payment_option: - type: string - description: Selected ABA PayWay payment option. - return_url: - type: string - format: uri - description: Webhook URL to post **only** the success response. - currency: - type: string - description: Currency code, e.g., 'USD' or 'KHR'. - lifetime: - type: integer - description: Lifetime of the payment session in minutes. - view_type: - type: string - description: 'View type for the payment interface: `popup`.' - payment_gate: - type: integer - description: Payment gate identifier, usually 0 for ABA PayWay to use their - checkout. - hash: - type: string - description: Security hash for ABA PayWay to validate the payload. - required: - - amount - - currency - - email - - firstname - - hash - - lastname - - lifetime - - merchant_id - - payment_gate - - payment_option - - phone - - req_time - - return_url - - tran_id - - type - - view_type - ABAPayWaySDK: - type: object - description: Base serializer for different Flex payment methods. - properties: - code: - type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: - type: string - description: The name of the payment method. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - amount: - type: string - description: The total amount to be charged, including fees. - currency_code: - type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: - type: string - description: The fee charged by the payment gateway. - fee_description: - type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - flow: - enum: - - aba_payway - type: string - description: '* `aba_payway` - ABA PayWay' - x-spec-enum-id: 589d7f78e5da99b5 - default: aba_payway - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - submit_url: - type: string - format: uri - description: The URL to which the SDK should submit a POST request, based - on the selected `flow` type. For `aba_payway`, this URL is used to submit - the selected value from `flex_options.payment_sub_options[index].value` - and receive a payload for HTML form generation. - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - payment_sub_options: - type: array - items: - $ref: '#/components/schemas/PaymentSubOptionSDK' - description: List of payment options for ABA PayWay. - required: - - amount - - billing - - code - - currency_code - - fee - - fee_description - - name - - type - ABAPayWaySubmitSDKErrorCallback: - type: object - properties: - message: - type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: - enum: - - aba_payway - type: string - x-spec-enum-id: 589d7f78e5da99b5 - readOnly: true - default: aba_payway - description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. - - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: - type: string - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: - type: string - description: The reference number. - status: - type: string - readOnly: true - default: error - description: The payment is errored. `errorCallback` must be triggered. - required: - - form_of_payment - - message - - session_id - - status - ABAPayWaySubmitSDKSuccessCallback: - type: object - description: Callback payload to be forwarder directly to `successCallback` - SDK method. - properties: - message: - type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: - enum: - - aba_payway - type: string - description: '* `aba_payway` - ABA PayWay' - x-spec-enum-id: 589d7f78e5da99b5 - readOnly: true - default: aba_payway - challenge_occurred: - type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - status: - type: string - readOnly: true - default: success - description: The payment is successful. `successCallback` must be triggered. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: - type: string - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. - form_url: - type: string - format: uri - description: The URL to which the SDK should POST to. - js_sdk_src: - type: string - format: uri - description: The URL of the JavaScript SDK to be loaded for the payment - process. - form_data: - allOf: - - $ref: '#/components/schemas/ABAPayWayFormData' - description: The form data to be submitted for the payment process. - ws_url: - type: string - format: uri - description: WebSocket URL for real-time updates during the payment process. - required: - - form_data - - form_of_payment - - form_url - - js_sdk_src - - message - - order_no - - reference_number - - session_id - - status - - ws_url - Action: - type: object - description: Schema for available transaction actions. - properties: - action: - type: string - description: Action identifier (e.g., 'disclose', 'inquiry', 'acknowledge') - label: - type: string - description: Human-readable label for the action - method: - enum: - - GET - - POST - - PUT - - PATCH - - DELETE - type: string - x-spec-enum-id: 867bf764d3b1eeaa - description: |- - HTTP method to use for this action - - * `GET` - GET - * `POST` - POST - * `PUT` - PUT - * `PATCH` - PATCH - * `DELETE` - DELETE - url: - type: string - format: uri - description: URL endpoint for the action - required: - - action - - label - - method - Address: - type: object - description: Nested serializer to save Address data into PaymentTransaction - properties: - line1: - type: string - maxLength: 128 - line2: - type: string - maxLength: 128 - city: - type: string - maxLength: 40 - state: - type: string - maxLength: 40 - country: - enum: - - AF - - AL - - DZ - - AS - - AD - - AO - - AI - - AQ - - AG - - AR - - AM - - AW - - AU - - AT - - AZ - - BS - - BH - - BD - - BB - - BY - - BE - - BZ - - BJ - - BM - - BT - - BO - - BQ - - BA - - BW - - BV - - BR - - IO - - BN - - BG - - BF - - BI - - CV - - KH - - CM - - CA - - KY - - CF - - TD - - CL - - CN - - CX - - CC - - CO - - KM - - CG - - CD - - CK - - CR - - HR - - CU - - CW - - CY - - CZ - - CI - - DK - - DJ - - DM - - DO - - EC - - EG - - SV - - GQ - - ER - - EE - - SZ - - ET - - FK - - FO - - FJ - - FI - - FR - - GF - - PF - - TF - - GA - - GM - - GE - - DE - - GH - - GI - - GR - - GL - - GD - - GP - - GU - - GT - - GG - - GN - - GW - - GY - - HT - - HM - - VA - - HN - - HK - - HU - - IS - - IN - - ID - - IR - - IQ - - IE - - IM - - IL - - IT - - JM - - JP - - JE - - JO - - KZ - - KE - - KI - - KP - - KR - - KW - - KG - - LA - - LV - - LB - - LS - - LR - - LY - - LI - - LT - - LU - - MO - - MG - - MW - - MY - - MV - - ML - - MT - - MH - - MQ - - MR - - MU - - YT - - MX - - FM - - MD - - MC - - MN - - ME - - MS - - MA - - MZ - - MM - - NA - - NR - - NP - - NL - - NC - - NZ - - NI - - NE - - NG - - NU - - NF - - MK - - MP - - 'NO' - - OM - - PK - - PW - - PS - - PA - - PG - - PY - - PE - - PH - - PN - - PL - - PT - - PR - - QA - - RO - - RU - - RW - - RE - - BL - - SH - - KN - - LC - - MF - - PM - - VC - - WS - - SM - - ST - - SA - - SN - - RS - - SC - - SL - - SG - - SX - - SK - - SI - - SB - - SO - - ZA - - GS - - SS - - ES - - LK - - SD - - SR - - SJ - - SE - - CH - - SY - - TW - - TJ - - TZ - - TH - - TL - - TG - - TK - - TO - - TT - - TN - - TM - - TC - - TV - - TR - - UG - - UA - - AE - - GB - - US - - UM - - UY - - UZ - - VU - - VE - - VN - - VG - - VI - - WF - - EH - - YE - - ZM - - ZW - - AX - type: string - description: |- - * `AF` - Afghanistan - * `AL` - Albania - * `DZ` - Algeria - * `AS` - American Samoa - * `AD` - Andorra - * `AO` - Angola - * `AI` - Anguilla - * `AQ` - Antarctica - * `AG` - Antigua and Barbuda - * `AR` - Argentina - * `AM` - Armenia - * `AW` - Aruba - * `AU` - Australia - * `AT` - Austria - * `AZ` - Azerbaijan - * `BS` - Bahamas - * `BH` - Bahrain - * `BD` - Bangladesh - * `BB` - Barbados - * `BY` - Belarus - * `BE` - Belgium - * `BZ` - Belize - * `BJ` - Benin - * `BM` - Bermuda - * `BT` - Bhutan - * `BO` - Bolivia, Plurinational State of - * `BQ` - Bonaire, Sint Eustatius and Saba - * `BA` - Bosnia and Herzegovina - * `BW` - Botswana - * `BV` - Bouvet Island - * `BR` - Brazil - * `IO` - British Indian Ocean Territory - * `BN` - Brunei Darussalam - * `BG` - Bulgaria - * `BF` - Burkina Faso - * `BI` - Burundi - * `CV` - Cabo Verde - * `KH` - Cambodia - * `CM` - Cameroon - * `CA` - Canada - * `KY` - Cayman Islands - * `CF` - Central African Republic - * `TD` - Chad - * `CL` - Chile - * `CN` - China - * `CX` - Christmas Island - * `CC` - Cocos (Keeling) Islands - * `CO` - Colombia - * `KM` - Comoros - * `CG` - Congo - * `CD` - Congo, The Democratic Republic of the - * `CK` - Cook Islands - * `CR` - Costa Rica - * `HR` - Croatia - * `CU` - Cuba - * `CW` - Curaçao - * `CY` - Cyprus - * `CZ` - Czechia - * `CI` - Côte d'Ivoire - * `DK` - Denmark - * `DJ` - Djibouti - * `DM` - Dominica - * `DO` - Dominican Republic - * `EC` - Ecuador - * `EG` - Egypt - * `SV` - El Salvador - * `GQ` - Equatorial Guinea - * `ER` - Eritrea - * `EE` - Estonia - * `SZ` - Eswatini - * `ET` - Ethiopia - * `FK` - Falkland Islands (Malvinas) - * `FO` - Faroe Islands - * `FJ` - Fiji - * `FI` - Finland - * `FR` - France - * `GF` - French Guiana - * `PF` - French Polynesia - * `TF` - French Southern Territories - * `GA` - Gabon - * `GM` - Gambia - * `GE` - Georgia - * `DE` - Germany - * `GH` - Ghana - * `GI` - Gibraltar - * `GR` - Greece - * `GL` - Greenland - * `GD` - Grenada - * `GP` - Guadeloupe - * `GU` - Guam - * `GT` - Guatemala - * `GG` - Guernsey - * `GN` - Guinea - * `GW` - Guinea-Bissau - * `GY` - Guyana - * `HT` - Haiti - * `HM` - Heard Island and McDonald Islands - * `VA` - Holy See (Vatican City State) - * `HN` - Honduras - * `HK` - Hong Kong - * `HU` - Hungary - * `IS` - Iceland - * `IN` - India - * `ID` - Indonesia - * `IR` - Iran, Islamic Republic of - * `IQ` - Iraq - * `IE` - Ireland - * `IM` - Isle of Man - * `IL` - Israel - * `IT` - Italy - * `JM` - Jamaica - * `JP` - Japan - * `JE` - Jersey - * `JO` - Jordan - * `KZ` - Kazakhstan - * `KE` - Kenya - * `KI` - Kiribati - * `KP` - Korea, Democratic People's Republic of - * `KR` - Korea, Republic of - * `KW` - Kuwait - * `KG` - Kyrgyzstan - * `LA` - Lao People's Democratic Republic - * `LV` - Latvia - * `LB` - Lebanon - * `LS` - Lesotho - * `LR` - Liberia - * `LY` - Libya - * `LI` - Liechtenstein - * `LT` - Lithuania - * `LU` - Luxembourg - * `MO` - Macao - * `MG` - Madagascar - * `MW` - Malawi - * `MY` - Malaysia - * `MV` - Maldives - * `ML` - Mali - * `MT` - Malta - * `MH` - Marshall Islands - * `MQ` - Martinique - * `MR` - Mauritania - * `MU` - Mauritius - * `YT` - Mayotte - * `MX` - Mexico - * `FM` - Micronesia, Federated States of - * `MD` - Moldova, Republic of - * `MC` - Monaco - * `MN` - Mongolia - * `ME` - Montenegro - * `MS` - Montserrat - * `MA` - Morocco - * `MZ` - Mozambique - * `MM` - Myanmar - * `NA` - Namibia - * `NR` - Nauru - * `NP` - Nepal - * `NL` - Netherlands - * `NC` - New Caledonia - * `NZ` - New Zealand - * `NI` - Nicaragua - * `NE` - Niger - * `NG` - Nigeria - * `NU` - Niue - * `NF` - Norfolk Island - * `MK` - North Macedonia - * `MP` - Northern Mariana Islands - * `NO` - Norway - * `OM` - Oman - * `PK` - Pakistan - * `PW` - Palau - * `PS` - Palestine, State of - * `PA` - Panama - * `PG` - Papua New Guinea - * `PY` - Paraguay - * `PE` - Peru - * `PH` - Philippines - * `PN` - Pitcairn - * `PL` - Poland - * `PT` - Portugal - * `PR` - Puerto Rico - * `QA` - Qatar - * `RO` - Romania - * `RU` - Russian Federation - * `RW` - Rwanda - * `RE` - Réunion - * `BL` - Saint Barthélemy - * `SH` - Saint Helena, Ascension and Tristan da Cunha - * `KN` - Saint Kitts and Nevis - * `LC` - Saint Lucia - * `MF` - Saint Martin (French part) - * `PM` - Saint Pierre and Miquelon - * `VC` - Saint Vincent and the Grenadines - * `WS` - Samoa - * `SM` - San Marino - * `ST` - Sao Tome and Principe - * `SA` - Saudi Arabia - * `SN` - Senegal - * `RS` - Serbia - * `SC` - Seychelles - * `SL` - Sierra Leone - * `SG` - Singapore - * `SX` - Sint Maarten (Dutch part) - * `SK` - Slovakia - * `SI` - Slovenia - * `SB` - Solomon Islands - * `SO` - Somalia - * `ZA` - South Africa - * `GS` - South Georgia and the South Sandwich Islands - * `SS` - South Sudan - * `ES` - Spain - * `LK` - Sri Lanka - * `SD` - Sudan - * `SR` - Suriname - * `SJ` - Svalbard and Jan Mayen - * `SE` - Sweden - * `CH` - Switzerland - * `SY` - Syrian Arab Republic - * `TW` - Taiwan, Province of China - * `TJ` - Tajikistan - * `TZ` - Tanzania, United Republic of - * `TH` - Thailand - * `TL` - Timor-Leste - * `TG` - Togo - * `TK` - Tokelau - * `TO` - Tonga - * `TT` - Trinidad and Tobago - * `TN` - Tunisia - * `TM` - Turkmenistan - * `TC` - Turks and Caicos Islands - * `TV` - Tuvalu - * `TR` - Türkiye - * `UG` - Uganda - * `UA` - Ukraine - * `AE` - United Arab Emirates - * `GB` - United Kingdom - * `US` - United States - * `UM` - United States Minor Outlying Islands - * `UY` - Uruguay - * `UZ` - Uzbekistan - * `VU` - Vanuatu - * `VE` - Venezuela, Bolivarian Republic of - * `VN` - Viet Nam - * `VG` - Virgin Islands, British - * `VI` - Virgin Islands, U.S. - * `WF` - Wallis and Futuna - * `EH` - Western Sahara - * `YE` - Yemen - * `ZM` - Zambia - * `ZW` - Zimbabwe - * `AX` - Åland Islands - x-spec-enum-id: 8067456ff4917829 - postal_code: - type: string - maxLength: 12 - required: - - city - - country - - line1 - Agreement: - type: object - description: |- - Serializer to hold the recurring data information. - This is required for being able to create recurring payments and the PGs - require this information. - properties: - id: - type: string - description: "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: - \n1. Recurring Payments: Periodic debits, e.g., gym memberships. \n2. - Installment Payments: Multiple charges for a single purchase over time. - \n3. Unscheduled: Future payments as required, e.g., account top-ups. - \n4. Industry Practice: Standard business practices related to an original - payment, e.g., hotel charges after checkout." - maxLength: 128 - amount_variability: - enum: - - fixed - - variable - type: string - x-spec-enum-id: 559f7896c94c0925 - description: |- - Indicates if all payments within the agreement use the same amount or if the amount differs between the payments. - - * `fixed` - Fixed - * `variable` - Variable - start_date: - type: string - format: date - description: Date on which the agreement with the payer to process payments - starts. - expiry_date: - type: string - format: date - description: Date on which your agreement with the payer to process payments - expires. - max_amount_per_cycle: - type: string - format: decimal - description: The maximum amount for a single payment in the series as agreed - with the payer. - cycle_interval_days: - type: integer - maximum: 366 - minimum: 1 - description: The minimum number of days between payments agreed with the - payer. - total_cycles: - type: integer - maximum: 999 - minimum: 1 - description: The number of merchant-initiated payments within the recurring - payment agreement. - frequency: - enum: - - irregular - - daily - - weekly - - semi_monthly - - monthly - - quarterly - - semi_annually - - yearly - - other - type: string - x-spec-enum-id: f7d3278be09218f0 - description: |- - The frequency of the payments within the series as agreed with the payer. - - * `irregular` - Irregular - * `daily` - Daily - * `weekly` - Weekly - * `semi_monthly` - Semi Monthly - * `monthly` - Monthly - * `quarterly` - Quarterly - * `semi_annually` - Semi Annually - * `yearly` - Yearly - * `other` - Other - type: - enum: - - event_based - - installment - - recurring - - unscheduled - - other - type: string - x-spec-enum-id: a78a057f002d8a8c - default: recurring - description: "The type of commercial agreement that the payer has with the - merchant.\n\n *Note*: For `unscheduled` agreements, the allowed values - should be configured as follows: \n\n `id` - Accepts any value. \n\n `frequency`. - \n\n `type`.\n\n This configuration ensures that only specific values - are permitted for each field when the `type` is `Unscheduled`.\n\n *Note*: - For `recurring` agreements, the following fields are mandatory as follows: - \n\n `amount_variability` \n\n `cycle_interval_days` \n\n `expiry_date` - \n\n ` `requency` \n\n `id` \n\n `total_cycles` \n\n This configuration - ensures that the required values are mandatory for each field when the - `type` is `Recurring`.\n\n* `event_based` - Event Based\n* `installment` - - Installment\n* `recurring` - Recurring\n* `unscheduled` - Unscheduled\n* - `other` - Other" - seller: - allOf: - - $ref: '#/components/schemas/AgreementSeller' - description: Details about the retailer, if the agreement is for installment - payments. - AgreementSeller: - type: object - properties: - name: - type: string - description: The retailer's trading name. - maxLength: 128 - short_name: - type: string - description: Abbreviation of the retailer's trading name, suitable for payer's - statement display. - maxLength: 64 - category_code: - type: string - description: A 4-digit code classifying the retailer's business by the type - of goods or services it offers. - maxLength: 64 - AmountDetails: - type: object - properties: - currency_code: - type: string - readOnly: true - amount: - type: string - description: 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 - maxLength: 120 - total: - type: string - readOnly: true - description: Denotes the comprehensive total of the payment transaction, - incorporating both the principal amount and any associated fees. - fee: - type: string - readOnly: true - description: 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. - exchange_rate: - type: string - description: The conversion rate used for currency conversion during payment. - This value reflects the rate locally calculated. - required: - - currency_code - - fee - - total - ApplePay: - type: object - description: Serializer for Apple Pay config, to be used in SDK clients like - web and mobile. - properties: - domain: - type: string - description: The domain of the merchant accepting the payment. - maxLength: 255 - merchant_id: - type: string - description: The ID of the merchant accepting the payment. - maxLength: 100 - code: - type: string - description: The payment service code. - maxLength: 100 - pattern: ^[-a-zA-Z0-9_]+$ - shop_name: - type: string - description: The name of the shop or store accepting the payment. - maxLength: 255 - amount: - type: string - description: The total amount of the payment, including any fees. - maxLength: 20 - fee: - type: string - description: The fee for the payment. - maxLength: 20 - fee_description: - type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - maxLength: 128 - currency_code: - type: string - description: The ISO 4217 currency code for the payment. - maxLength: 10 - country_code: - type: string - description: The ISO 3166-1 alpha-2 country code for the payment currency. - maxLength: 2 - validation_url: - type: string - format: uri - description: The URL to use for validating the payment session. - payment_url: - type: string - format: uri - description: The URL to use for submitting the payment. - session_id: - type: string - description: The ID of the payment session, if included. - maxLength: 100 - flow: - enum: - - apple_pay - type: string - x-spec-enum-id: 350daf15e49287c0 - description: |- - Using the payment_url, you can proceed for submitting the paymentOnce the payment session is validatedthis URL is used to initiate the actual payment process. - - * `apple_pay` - ApplePay - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - required: - - amount - - billing - - code - - country_code - - currency_code - - domain - - fee - - fee_description - - flow - - merchant_id - - payment_url - - shop_name - - validation_url - ApplePayDirectPayment: - type: object - properties: - payload: - $ref: '#/components/schemas/ApplePayToken' - pg_code: - type: - - string - - 'null' - description: The unique pg_code used for this payment instrument. - session_id: - type: string - description: A unique identifier for the payment transaction (session). - required: - - payload - - session_id - ApplePayHeaderSchema: - type: object - description: Apple Pay header containing encryption details - properties: - ephemeralPublicKey: - type: string - description: Ephemeral public key for encryption - publicKeyHash: - type: string - description: Hash of the merchant's public key - transactionId: - type: string - description: Unique transaction identifier - required: - - publicKeyHash - - transactionId - ApplePayInstrument: - type: object - description: Apple Pay payment instrument - properties: - instrument_type: - enum: - - apple_pay - type: string - x-spec-enum-id: 49c50763123c8d7e - default: apple_pay - description: |- - Payment type: Apple Pay - - * `apple_pay` - apple_pay - payload: - allOf: - - $ref: '#/components/schemas/ApplePayPayloadSchema' - description: Apple Pay payment token received from Apple Pay SDK. Pass the - complete token object exactly as received without modification. Includes - paymentData (encrypted), paymentMethod details, and transactionIdentifier. - required: - - payload - ApplePayPayloadSchema: - type: object - description: Complete Apple Pay token structure - properties: - paymentData: - allOf: - - $ref: '#/components/schemas/ApplePayPaymentDataSchema' - description: Encrypted payment data - paymentMethod: - allOf: - - $ref: '#/components/schemas/ApplePayPaymentMethodSchema' - description: Payment method information - transactionIdentifier: - type: string - description: Apple Pay transaction identifier - required: - - paymentData - - paymentMethod - - transactionIdentifier - ApplePayPaymentDataSchema: - type: object - description: Encrypted Apple Pay payment data - properties: - version: - type: string - description: Token version (e.g., 'EC_v1') - data: - type: string - description: Encrypted payment data - signature: - type: string - description: Signature of the payment data - header: - allOf: - - $ref: '#/components/schemas/ApplePayHeaderSchema' - description: Cryptographic header - required: - - data - - header - - signature - - version - ApplePayPaymentMethodSchema: - type: object - description: Apple Pay payment method details - properties: - displayName: - type: string - description: Display name (e.g., 'Visa 1234') - network: - type: string - description: Card network (e.g., 'Visa') - type: - type: string - description: Card type (e.g., 'debit') - required: - - displayName - - network - - type - ApplePayRejectedResponse: - oneOf: - - $ref: '#/components/schemas/DevicePayViewCancelResponse' - - $ref: '#/components/schemas/DevicePayViewErrorResponse' - ApplePaySessionValidationErrorResponse: - type: object - properties: - message: - type: string - default: Permission error while connecting to Apple servers. Contact the - website administrator. - callback_payload: - $ref: '#/components/schemas/SDKErrorCallback' - required: - - callback_payload - ApplePaySuccessSessionValidationResponse: - type: object - properties: - epochTimestamp: - type: integer - default: 1684246149600 - description: The current epoch timestamp in milliseconds. - expiresAt: - type: integer - default: 1684246149600 - description: The epoch timestamp in milliseconds when the session expires. - merchantSessionIdentifier: - type: string - default: SSHFE64C210A89B444EAC94C97DC8F491E9 - description: The merchant session identifier. - nonce: - type: string - default: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 - description: The nonce for the session. - merchantIdentifier: - type: string - default: 1D2C836E771FA6598F2CB6A8A85A - description: The merchant identifier. - domainName: - type: string - default: example.com - description: The domain name of the merchant. - displayName: - type: string - default: Example Store - description: The display name of the merchant. - signature: - type: string - default: 308006092a864886f70d010702a0803080020101310d300b06092a864886f70d010 - description: The signature for the session. - operationalAnalyticsIdentifier: - type: string - default: Apple Pay:1D2C836E771FA6598F2CB6A8A85A - description: The operational analytics identifier. - retries: - type: integer - default: 0 - description: The number of retries for the session. - pspId: - type: string - default: 1D2C836E771FA6598F2CB6A8A85A - description: The PSP identifier. - ApplePayToken: - type: object - properties: - paymentData: - allOf: - - $ref: '#/components/schemas/ApplePaymentData' - description: Encrypted Apple Pay payment data containing the payment amount, - merchant ID, and other transaction details. This payload is decrypted - by the payment gateway to complete the transaction. - paymentMethod: - allOf: - - $ref: '#/components/schemas/PaymentMethod' - description: Describes the payment method selected by the customer, including - card network (e.g., Visa), type (e.g., debit), and display name. - transactionIdentifier: - type: string - required: - - paymentData - - paymentMethod - - transactionIdentifier - ApplePayload: - type: object - properties: - token: - $ref: '#/components/schemas/ParentToken' - required: - - token - ApplePaymentData: - type: object - properties: - version: - type: string - data: - type: string - signature: - type: string - header: - allOf: - - $ref: '#/components/schemas/Header' - description: Cryptographic header used to decrypt the Apple Pay payment - data. Includes the public key hash, ephemeral public key, wrapped key, - and transaction ID. - required: - - data - - header - - signature - - version - Attachment: - type: object - properties: - content: - type: string - url: - type: string - format: uri - filename: - type: string - content_type: - type: string - size: - type: string - AttachmentUpload: - type: object - properties: - file: - type: string - format: uri - description: A writable field that accepts an attachment. - pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ - shortify_attachment_url: - type: boolean - default: false - description: If set to `true`, the URL of the uploaded attachment will be - shortened using a URL shortener service. if configured.This should be - used when sharing the attachment URL via SMS or WhatsApp. This will only - work with `session_id` or `order_no`. - order_no: - type: string - description: This is an optional identifier used to specify the payment - transaction upon which the operation should be performed. You can use - either the `order_no` or `session_id` field; at least one of these two - identifiers must be provided to select the payment transaction that should - be actioned. - maxLength: 128 - session_id: - type: string - description: Similar to `order_no`, `session_id` is an optional identifier - used to specify the payment transaction for the operation. You must provide - either `order_no` or `session_id` in order to select the appropriate payment - transaction. - maxLength: 128 - required: - - file - AttachmentUploadClientErrors: - oneOf: - - $ref: '#/components/schemas/AttachmentUploadFailureWithoutTXN' - - $ref: '#/components/schemas/AttachmentUploadFailureTXNNotFoundOrderNo' - - $ref: '#/components/schemas/AttachmentUploadFailureTXNNotFoundSessionID' - - $ref: '#/components/schemas/AttachmentUploadFailureTXNNotBoth' - - $ref: '#/components/schemas/AttachmentUploadFailureNoFile' - - $ref: '#/components/schemas/AttachmentUploadFailureWrongExtension' - AttachmentUploadFailureNoFile: - type: object - properties: - file: - type: string - description: No file was submitted. - required: - - file - AttachmentUploadFailureTXNNotBoth: - type: object - properties: - session_id: - type: string - description: Please provide only `order_no` or `session_id`, not both. - order_no: - type: string - description: Please provide only `order_no` or `session_id`, not both. - required: - - order_no - - session_id - AttachmentUploadFailureTXNNotFoundOrderNo: - type: object - properties: - order_no: - type: string - description: No PaymentTransaction found with `order_no` of foo. - required: - - order_no - AttachmentUploadFailureTXNNotFoundSessionID: - type: object - properties: - session_id: - type: string - description: No PaymentTransaction found with `session_id` of foo. - required: - - session_id - AttachmentUploadFailureWithoutTXN: - type: object - properties: - attachment_short_url: - type: string - description: You must provide either `session_id` or `order_no` to identify - the PaymentTransaction. - required: - - attachment_short_url - AttachmentUploadFailureWrongExtension: - type: object - properties: - file: - type: string - description: 'File extension ''zip'' is not allowed. Allowed extensions - are: pdf, jpeg, png, doc, docx, jpg, xls, xlsx, txt.' - required: - - file - AttachmentUploadSuccess: - type: object - properties: - file_url: - type: string - description: The Relative URL of the uploaded file in the storage. Duplicate - file names will have a random string attached to the end. - original_filename: - type: string - description: The original name of the uploaded file. - required: - - file_url - - original_filename - AttachmentUploadSuccessSerializers: - oneOf: - - $ref: '#/components/schemas/AttachmentUploadSuccess' - - $ref: '#/components/schemas/AttachmentUploadSuccessWithShortURL' - AttachmentUploadSuccessWithShortURL: - type: object - properties: - file_url: - type: string - description: The Relative URL of the uploaded file in the storage. Duplicate - file names will have a random string attached to the end. - original_filename: - type: string - description: The original name of the uploaded file. - attachment_short_url: - type: string - format: uri - description: The shortened URL of the file. Useful for SMS & WhatsApp. - required: - - attachment_short_url - - file_url - - original_filename - Attempt: - type: object - description: This Attempt models its used solely for PaymentTransaction detail - page - properties: - id: - type: integer - readOnly: true - state: - enum: - - pending - - success - - failed - - canceled - - error - - cod - type: string - x-spec-enum-id: 03c10fdf706d3f9a - description: |- - Represents the current status of a payment attempt. This means that it shows whether a payment is pending, has been successfully processed, has failed, has been canceled, or has encountered an error. Additionally, it also supports the Cash on Delivery payment method. - - * `pending` - Pending - * `success` - Success - * `failed` - Failed - * `canceled` - Canceled - * `error` - Error - * `cod` - Cash on Delivery - message: - type: - - string - - 'null' - description: Error message in case of failed payment - reference_number: - type: - - string - - 'null' - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. - maxLength: 64 - gateway_response: {} - amount: - type: string - maxLength: 120 - exchange_rate: - type: string - format: decimal - pattern: ^-?\d{0,9}(?:\.\d{0,6})?$ - description: The conversion rate used for currency conversion during payment. - This value reflects the rate locally calculated. - fee: - type: string - maxLength: 120 - total: - type: string - maxLength: 120 - created: - type: string - format: date-time - readOnly: true - modified: - type: string - format: date-time - readOnly: true - state_changed_at: - type: string - format: date-time - currency_code: - enum: - - AED - - AFN - - ALL - - AMD - - ANG - - AOA - - ARS - - AUD - - AWG - - AZN - - BAM - - BBD - - BDT - - BGN - - BHD - - BIF - - BMD - - BND - - BOB - - BOV - - BRL - - BSD - - BTN - - BWP - - BYN - - BZD - - CAD - - CDF - - CHE - - CHF - - CHW - - CLF - - CLP - - CNY - - COP - - COU - - CRC - - CUC - - CUP - - CVE - - CZK - - DJF - - DKK - - DOP - - DZD - - EGP - - ERN - - ETB - - EUR - - FJD - - FKP - - GBP - - GEL - - GHS - - GIP - - GMD - - GNF - - GTQ - - GYD - - HKD - - HNL - - HRK - - HTG - - HUF - - IDR - - ILS - - INR - - IQD - - IRR - - ISK - - JMD - - JOD - - JPY - - KES - - KGS - - KHR - - KMF - - KPW - - KRW - - KWD - - KYD - - KZT - - LAK - - LBP - - LKR - - LRD - - LSL - - LYD - - MAD - - MDL - - MGA - - MKD - - MMK - - MNT - - MOP - - MRU - - MUR - - MVR - - MWK - - MXN - - MXV - - MYR - - MZN - - NAD - - NGN - - NIO - - NOK - - NPR - - NZD - - OMR - - PAB - - PEN - - PGK - - PHP - - PKR - - PLN - - PYG - - QAR - - RON - - RSD - - RUB - - RWF - - SAR - - SBD - - SCR - - SDG - - SEK - - SGD - - SHP - - SLE - - SLL - - SOS - - SRD - - SSP - - STN - - SVC - - SYP - - SZL - - THB - - TJS - - TMT - - TND - - TOP - - TRY - - TTD - - TWD - - TZS - - UAH - - UGX - - USD - - USN - - UYI - - UYU - - UYW - - UZS - - VED - - VES - - VND - - VUV - - WST - - XAF - - XAG - - XAU - - XBA - - XBB - - XBC - - XBD - - XCD - - XDR - - XOF - - XPD - - XPF - - XPT - - XSU - - XTS - - XUA - - XXX - - YER - - ZAR - - ZMW - - ZWL - type: string - description: |- - * `AED` - AED - * `AFN` - AFN - * `ALL` - ALL - * `AMD` - AMD - * `ANG` - ANG - * `AOA` - AOA - * `ARS` - ARS - * `AUD` - AUD - * `AWG` - AWG - * `AZN` - AZN - * `BAM` - BAM - * `BBD` - BBD - * `BDT` - BDT - * `BGN` - BGN - * `BHD` - BHD - * `BIF` - BIF - * `BMD` - BMD - * `BND` - BND - * `BOB` - BOB - * `BOV` - BOV - * `BRL` - BRL - * `BSD` - BSD - * `BTN` - BTN - * `BWP` - BWP - * `BYN` - BYN - * `BZD` - BZD - * `CAD` - CAD - * `CDF` - CDF - * `CHE` - CHE - * `CHF` - CHF - * `CHW` - CHW - * `CLF` - CLF - * `CLP` - CLP - * `CNY` - CNY - * `COP` - COP - * `COU` - COU - * `CRC` - CRC - * `CUC` - CUC - * `CUP` - CUP - * `CVE` - CVE - * `CZK` - CZK - * `DJF` - DJF - * `DKK` - DKK - * `DOP` - DOP - * `DZD` - DZD - * `EGP` - EGP - * `ERN` - ERN - * `ETB` - ETB - * `EUR` - EUR - * `FJD` - FJD - * `FKP` - FKP - * `GBP` - GBP - * `GEL` - GEL - * `GHS` - GHS - * `GIP` - GIP - * `GMD` - GMD - * `GNF` - GNF - * `GTQ` - GTQ - * `GYD` - GYD - * `HKD` - HKD - * `HNL` - HNL - * `HRK` - HRK - * `HTG` - HTG - * `HUF` - HUF - * `IDR` - IDR - * `ILS` - ILS - * `INR` - INR - * `IQD` - IQD - * `IRR` - IRR - * `ISK` - ISK - * `JMD` - JMD - * `JOD` - JOD - * `JPY` - JPY - * `KES` - KES - * `KGS` - KGS - * `KHR` - KHR - * `KMF` - KMF - * `KPW` - KPW - * `KRW` - KRW - * `KWD` - KWD - * `KYD` - KYD - * `KZT` - KZT - * `LAK` - LAK - * `LBP` - LBP - * `LKR` - LKR - * `LRD` - LRD - * `LSL` - LSL - * `LYD` - LYD - * `MAD` - MAD - * `MDL` - MDL - * `MGA` - MGA - * `MKD` - MKD - * `MMK` - MMK - * `MNT` - MNT - * `MOP` - MOP - * `MRU` - MRU - * `MUR` - MUR - * `MVR` - MVR - * `MWK` - MWK - * `MXN` - MXN - * `MXV` - MXV - * `MYR` - MYR - * `MZN` - MZN - * `NAD` - NAD - * `NGN` - NGN - * `NIO` - NIO - * `NOK` - NOK - * `NPR` - NPR - * `NZD` - NZD - * `OMR` - OMR - * `PAB` - PAB - * `PEN` - PEN - * `PGK` - PGK - * `PHP` - PHP - * `PKR` - PKR - * `PLN` - PLN - * `PYG` - PYG - * `QAR` - QAR - * `RON` - RON - * `RSD` - RSD - * `RUB` - RUB - * `RWF` - RWF - * `SAR` - SAR - * `SBD` - SBD - * `SCR` - SCR - * `SDG` - SDG - * `SEK` - SEK - * `SGD` - SGD - * `SHP` - SHP - * `SLE` - SLE - * `SLL` - SLL - * `SOS` - SOS - * `SRD` - SRD - * `SSP` - SSP - * `STN` - STN - * `SVC` - SVC - * `SYP` - SYP - * `SZL` - SZL - * `THB` - THB - * `TJS` - TJS - * `TMT` - TMT - * `TND` - TND - * `TOP` - TOP - * `TRY` - TRY - * `TTD` - TTD - * `TWD` - TWD - * `TZS` - TZS - * `UAH` - UAH - * `UGX` - UGX - * `USD` - USD - * `USN` - USN - * `UYI` - UYI - * `UYU` - UYU - * `UYW` - UYW - * `UZS` - UZS - * `VED` - VED - * `VES` - VES - * `VND` - VND - * `VUV` - VUV - * `WST` - WST - * `XAF` - XAF - * `XAG` - XAG - * `XAU` - XAU - * `XBA` - XBA - * `XBB` - XBB - * `XBC` - XBC - * `XBD` - XBD - * `XCD` - XCD - * `XDR` - XDR - * `XOF` - XOF - * `XPD` - XPD - * `XPF` - XPF - * `XPT` - XPT - * `XSU` - XSU - * `XTS` - XTS - * `XUA` - XUA - * `XXX` - XXX - * `YER` - YER - * `ZAR` - ZAR - * `ZMW` - ZMW - * `ZWL` - ZWL - x-spec-enum-id: 1314c690acf1c093 - readOnly: true - disclosed_to_merchant: - type: boolean - title: Disclosed to merchant? - disclosed_data: - description: Webhooked data to merchant webhook URL. - disclosure_url_error: - title: Webhook URL error - description: Logs the error reason of merchant webhook url. - request_data: - description: Technical data of the request that user sent. - data: - description: Used to store useful information for internal purposes - required: - - created - - currency_code - - id - - modified - AutoDebit: - type: object - description: |- - Auto debit serializer should take session_id and consumer payment token - then validate if session id is valid - if session id is valid then validate if payment gateway supports auto debit - if payment gateway supports auto debit then validate if payment gateway has implemented auto debit - if payment gateway has implemented auto debit then charge the token and return charge response from client - auto_debit method which should be implemented in client - properties: - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - token: - type: string - description: Use this field to provide the unique identifier of a saved - customer card for processing a payment in the API request. - required: - - session_id - - token - AutoDebitErrors: - oneOf: - - $ref: '#/components/schemas/OperationErrorResponse' - - $ref: '#/components/schemas/FieldErrors' - BNPLPaymentSDK: - type: object - description: Serializer for BNPL (Buy Now, Pay Later) payment methods like Tamara - & Tabby. - properties: - code: - type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: - type: string - description: The name of the payment method. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - amount: - type: string - description: The total amount to be charged, including fees. - currency_code: - type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: - type: string - description: The fee charged by the payment gateway. - fee_description: - type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - icon: - type: string - format: uri - description: The svg URL of the icon for the payment method. - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - pg_icons: - allOf: - - $ref: '#/components/schemas/MIDIcon' - description: Represents list of mid icons configured for `pgmid` settings - flow: - enum: - - tamara - - tabby - - doku - - taly - type: string - description: |- - * `tamara` - Tamara - * `tabby` - Tabby - * `doku` - Doku - * `taly` - Taly - x-spec-enum-id: 79dbf4c0ffa64158 - redirect_url: - type: string - format: uri - description: 'This field is used for the `ottu_pg` payment flow. When `flow` - is `ottu_pg`, the payer will be directly redirected to this URL. This - field is only present when `flow` is `ottu_pg`. For web integrations: - Use `window.location.href = redirect_url` to redirect the payer to the - specified URL. For mobile SDK integrations: Open the `redirect_url` in - the webview. Upon redirecting to the provided URL, the webview should - be closed and the transaction refreshed using the `Checkout SDK / Retrieve - init data API`. Detect the URL redirection by listening to redirects in - the webview. When a redirect occurs to a URL containing the `merchant_id` - domain, close the webview and reload the SDK after calling the `Retrieve - init data API`.' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - can_save_card: - type: boolean - description: When true, display a checkbox in the SDK for card saving with - this payment method. When false, do not display the checkbox. - submit_url: - type: string - format: uri - description: 'When submitting information via POST, the appropriate URL - depends on the `flow` value:`redirect`: The URL is for submitting `payment_methods[index].code`.' - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - pre_payment_options_available: - type: boolean - description: Indicates whether pre-payment options have already been saved. - If True, the options are available; otherwise, they need to be fetched. - pre_payment_check_url: - type: string - format: uri - description: Merchant-associated endpoint URL for validating pre-payment - options. Frontend will send the payment gateway code to this URL to check - if the customer can proceed with this payment method. - pre_payment_options: - description: This field holds pre-payment options retrieved from BNPL providers. - The associated session details will only be saved to the transaction after - the frontend SDK validates the session using `pre_payment_check_url`. - required: - - amount - - billing - - can_save_card - - code - - currency_code - - fee - - fee_description - - flow - - icon - - icons - - name - - pre_payment_check_url - - pre_payment_options - - pre_payment_options_available - - type - BaseUser: - type: object - properties: - id: - type: integer - readOnly: true - first_name: - type: string - maxLength: 32 - last_name: - type: string - maxLength: 32 - username: - type: string - description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ - only. - pattern: ^[\w.@+-]+$ - maxLength: 150 - is_superuser: - type: boolean - title: Superuser status - description: Designates that this user has all permissions without explicitly - assigning them. - is_staff: - type: boolean - title: Staff status - description: Designates whether the user can log into this admin site. - email: - type: string - format: email - title: Email address - maxLength: 254 - required: - - email - - id - - username - Billing: - type: object - properties: - amount: - allOf: - - $ref: '#/components/schemas/BillingAmount' - description: The total transaction amount including fees - sub_total: - allOf: - - $ref: '#/components/schemas/BillingAmount' - description: The subtotal amount before fees - fee: - allOf: - - $ref: '#/components/schemas/BillingAmount' - description: The fee amount charged for the transaction - required: - - amount - - fee - - sub_total - BillingAmount: - type: object - properties: - display: - type: string - description: Formatted amount with currency symbol for display purposes - value: - type: string - description: The numeric value of the amount as a string - currency_code: - type: string - description: The ISO currency code for the amount - maxLength: 3 - label: - type: string - description: A descriptive label for the amount - required: - - currency_code - - display - - label - - value - BrandingItem: - type: object - properties: - text: - type: string - description: Display text, e.g. 'Have 30% off'. - color: - type: string - description: Hex color code for the text, e.g. '#FFFF00' or '#FFF'. - pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$ - font_weight: - type: integer - default: 700 - description: CSS font-weight value (e.g. 400 regular, 500 medium, 600 semibold, - 700 bold). Defaults to 700. - required: - - color - - text - BrandingOptions: - type: object - properties: - payment_methods: - type: object - additionalProperties: - $ref: '#/components/schemas/BrandingItem' - required: - - payment_methods - Bulk: - type: object - properties: - id: - type: integer - readOnly: true - name: - type: string - maxLength: 512 - required: - - id - CSUCPayment: - type: object - description: |- - Serializer for executing CSUC Click to Pay payments. - - This serializer is used when the user completes the payment flow - and submits their payment method through the Cybersource widget. - properties: - pg_code: - type: string - description: Payment Gateway code selected for Click to Pay. - session_id: - type: string - description: Session ID used to identify the transaction. - funding_source: - type: object - additionalProperties: {} - description: 'Payment source containing the transient token from Cybersource. - This token is generated by the Cybersource Unified Checkout widget after - the user completes payment method selection. Expected structure: {''transient_token'': - ''jwt_token_string''}' - required: - - funding_source - - pg_code - - session_id - CSUCPaymentFailureResponse: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - CSUCSDK: - type: object - description: Serializer for Click to Pay payment flow. - properties: - code: - type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: - type: string - description: The name of the payment method. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - amount: - type: string - description: The total amount to be charged, including fees. - currency_code: - type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: - type: string - description: The fee charged by the payment gateway. - fee_description: - type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - icon: - type: string - format: uri - description: The svg URL of the icon for the payment method. - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - pg_icons: - allOf: - - $ref: '#/components/schemas/MIDIcon' - description: Represents list of mid icons configured for `pgmid` settings - flow: - enum: - - csuc - type: string - description: '* `csuc` - csuc' - x-spec-enum-id: 255c519aa3651370 - default: csuc - redirect_url: - type: string - format: uri - description: 'This field is used for the `ottu_pg` payment flow. When `flow` - is `ottu_pg`, the payer will be directly redirected to this URL. This - field is only present when `flow` is `ottu_pg`. For web integrations: - Use `window.location.href = redirect_url` to redirect the payer to the - specified URL. For mobile SDK integrations: Open the `redirect_url` in - the webview. Upon redirecting to the provided URL, the webview should - be closed and the transaction refreshed using the `Checkout SDK / Retrieve - init data API`. Detect the URL redirection by listening to redirects in - the webview. When a redirect occurs to a URL containing the `merchant_id` - domain, close the webview and reload the SDK after calling the `Retrieve - init data API`.' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - can_save_card: - type: boolean - description: When true, display a checkbox in the SDK for card saving with - this payment method. When false, do not display the checkbox. - submit_url: - type: string - format: uri - description: URL that the frontend must call with POST request to get Click - to Pay configuration data for the selected payment gateway. For example, - when the user selects a gateway like DOKU or CSUC this endpoint should - be triggered to initialize the specific payment flow. The response will - contain gateway-specific configuration needed to proceed. Refer to the - 'Submit Doku' section in the documentation for more details. - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - required: - - amount - - billing - - can_save_card - - code - - currency_code - - fee - - fee_description - - icon - - icons - - name - - submit_url - - type - CSUCSDKResponse: - type: object - description: |- - Response serializer for CSUC (Cybersource Unified Checkout) SDK configuration. - - This response contains the complete configuration needed to initialize the - Cybersource Unified Checkout widget on the frontend, including SDK loading - information, form configuration, and the capture context JWT token. - properties: - sdk_client: - allOf: - - $ref: '#/components/schemas/SDKClientConfig' - description: Configuration for loading the Cybersource JavaScript SDK. Contains - the script URL, integrity hash for security, and CORS settings. - form_config: - allOf: - - $ref: '#/components/schemas/FormConfig' - description: Payment form configuration. Specifies where to submit the transient - token after the user completes payment in the Cybersource widget. - capture_context: - type: string - description: |- - JWT capture context token required to initialize the Cybersource Unified Checkout. This token contains encrypted payment configuration including: - - Allowed card networks (VISA, MASTERCARD, etc.) - - Allowed payment types (CLICKTOPAY, PANENTRY) - - Client version and locale settings - - Capture mandate (billing type, email/phone/shipping requests) - - Complete mandate (operation type: CAPTURE or AUTH, decision manager settings) - - Order information (amount and currency) - - Target origins for CORS - - Payment configurations for SRC (Secure Remote Commerce) providers - - The token is cached for 10 minutes to improve performance. - - For more information, see: https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-intro.html - required: - - capture_context - - form_config - - sdk_client - CSUCSubmitFailureResponse: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - CSUCSubmitSuccessResponse: - oneOf: - - $ref: '#/components/schemas/CSUCSDKResponse' - Card: - type: object - description: Represents token details, only if the user pays with a tokenized - card, Ottu will include the token details in the response. - properties: - brand: - type: - - string - - 'null' - description: The card brand (e.g., Visa, Mastercard) associated with the - card. Display this information for customer reference. - maxLength: 32 - customer_id: - type: string - description: The unique identifier for the customer who owns the card - maxLength: 36 - cvv_required: - type: boolean - description: 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_month: - type: string - description: The card's expiration month. Provide this information for transaction - processing and validation. - maxLength: 2 - expiry_year: - type: string - description: The card's expiration year. Provide this information for transaction - processing and validation. - maxLength: 2 - is_expired: - type: boolean - description: 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_preferred: - type: boolean - readOnly: true - description: ' 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_card: - type: - - string - - 'null' - description: The cardholder's name as it appears on the card. Display this - information for customer verification. - maxLength: 64 - number: - type: - - string - - 'null' - description: The masked card number to be displayed, ensuring customer privacy - and security while providing essential information. - maxLength: 19 - pg_code: - type: string - description: The `pg_code` associated with the card's creation. - pg_name: - enum: - - knet - - cybersource - - csuc - - checkoutcom - - migs - - dapi - - deema - - doku - - burgan - - paypal - - mpgs - - kpay - - enet - - omannet - - benefit - - benefit_pay - - blank - - cbk - - fss - - myfatoorah - - ngenius - - ifg - - ccavenues - - payu_india - - cod - - amazon_pay - - ottu_pg - - bookeey - - upg - - bambora - - hyperpay - - qpay - - smart_pay - - sohar - - nbo - - tabby - - tamara - - hesabe - - rajhi - - stc_pay - - stcbahrain - - urpay - - beyon_money - - upayments - - tap - - fawry - - fiserv - - geidea - - payon - - paymob - - moyasar - - abapayway - - skipcash - - taly - - tess - type: string - x-spec-enum-id: d824e9691fe4d7ec - description: |- - The payment `gateway` associated with the user's card. - - * `knet` - Knet - * `cybersource` - CyberSource - * `csuc` - Cybersource Unified Checkout - * `checkoutcom` - checkout.com - * `migs` - MiGS - * `dapi` - Dapi - * `deema` - Deema - * `doku` - Doku - * `burgan` - Burgan - * `paypal` - PayPal - * `mpgs` - MPGS - * `kpay` - KPay - * `enet` - Enet - * `omannet` - OmanNet - * `benefit` - Benefit - * `benefit_pay` - BenefitPay - * `blank` - Blank - * `cbk` - CBK - * `fss` - FSS - * `myfatoorah` - MyFatoorah - * `ngenius` - N-Genius - * `ifg` - IATA Financial Gateway - * `ccavenues` - Ccavenues - * `payu_india` - PayU India - * `cod` - Cash - * `amazon_pay` - Amazon Pay - * `ottu_pg` - Ottu PG - * `bookeey` - Bookeey - * `upg` - UPG - * `bambora` - Bambora - * `hyperpay` - HyperPay - * `qpay` - Qpay - * `smart_pay` - SmartPay - * `sohar` - SoharInternational - * `nbo` - NBO - * `tabby` - Tabby - * `tamara` - Tamara - * `hesabe` - Hesabe - * `rajhi` - Alrajhi Bank - * `stc_pay` - STC Bank - * `stcbahrain` - STC Bahrain - * `urpay` - URPay - * `beyon_money` - BeyonMoney - * `upayments` - UPayments - * `tap` - Tap Payments - * `fawry` - Fawry - * `fiserv` - Fiserv - * `geidea` - Geidea - * `payon` - PayOn - * `paymob` - PayMob - * `moyasar` - Moyasar - * `abapayway` - ABA PayWay - * `skipcash` - Skip Cash - * `taly` - Taly - * `tess` - Tess Payments - token: - type: string - description: The unique token associated with the card, required for tokenized - card payments. Use this value to securely process transactions. - maxLength: 50 - agreements: - description: List of agreements associated with this card. - required: - - agreements - - brand - - customer_id - - cvv_required - - expiry_month - - expiry_year - - is_expired - - is_preferred - - name_on_card - - number - - pg_code - - pg_name - - token - CardAcceptanceCriteria: - type: object - properties: - min_expiry_time: - type: integer - maximum: 365 - minimum: 1 - description: |- - 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. - CardErrors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/GenericErrorMessage' - CardSDK: - type: object - description: Serializer Card model for SDK - properties: - agreements: - description: List of agreements associated with this card. - customer_id: - type: string - description: The unique identifier for the customer who owns the card - maxLength: 36 - brand: - type: - - string - - 'null' - description: The card brand (e.g., Visa, Mastercard) associated with the - card. Display this information for customer reference. - maxLength: 32 - name_on_card: - type: - - string - - 'null' - description: The cardholder's name as it appears on the card. Display this - information for customer verification. - maxLength: 64 - number: - type: - - string - - 'null' - description: The masked card number to be displayed, ensuring customer privacy - and security while providing essential information. - maxLength: 19 - expiry_month: - type: string - description: The card's expiration month. Provide this information for transaction - processing and validation. - maxLength: 2 - expiry_year: - type: string - description: The card's expiration year. Provide this information for transaction - processing and validation. - maxLength: 2 - token: - type: string - description: The unique token associated with the card, required for tokenized - card payments. Use this value to securely process transactions. - maxLength: 50 - is_preferred: - type: boolean - readOnly: true - description: ' 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.' - is_expired: - type: boolean - description: 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. - pg_code: - type: string - description: The `pg_code` associated with the card's creation. - pg_name: - type: string - readOnly: true - description: Represents the display name of card associated payment gateway - cvv_required: - type: boolean - description: 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. - delete_url: - type: string - readOnly: true - description: Delete URL for this card. - submit_url: - type: string - readOnly: true - description: Submit URL for this card. - required: - - agreements - - brand - - customer_id - - cvv_required - - delete_url - - expiry_month - - expiry_year - - is_expired - - is_preferred - - name_on_card - - number - - pg_code - - pg_name - - submit_url - - token - CashAcknowledgementErrors: - oneOf: - - $ref: '#/components/schemas/OperationErrorResponse' - - $ref: '#/components/schemas/FieldErrors' - CashPayment: - type: object - description: |- - Serializer for acknowledging cash payments. - - Inherits from BaseTxnLookupSerializer, which provides the logic for retrieving - a PaymentTransaction object based on the provided session ID. - properties: - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - required: - - session_id - ChannelNotificationErrors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/NotificationFailure' - ChannelNotificationResponses: - oneOf: - - $ref: '#/components/schemas/NotificationSuccess' - ChannelSpecificNotification: - type: object - description: This serializer class is solely for API documentation purposes. - properties: - template_id: - type: string - description: This field is required. It specifies the template to be used - for the notification. - to: - type: string - description: Required for all notifications. Must be a valid email address - for email notifications, and a valid international phone number for SMS - and WhatsApp notifications. - unit_config: - type: integer - description: This field is optional for SMS and email notifications, but - it is mandatory for WhatsApp notifications. - language: - enum: - - en - - ar - type: string - x-spec-enum-id: ac1757d67890d125 - default: en - description: |- - Specifies the language for email, SMS, and WhatsApp notifications. The default language is English (en). - - * `en` - English - * `ar` - Arabic - cc: - type: array - items: - type: string - format: email - description: This field is optional. When provided, it specifies the list - of CC recipients for the email notification. - bcc: - type: array - items: - type: string - format: email - description: This field is optional. When provided, it specifies the list - of BCC recipients for the email notification. - subject: - type: string - description: This field is optional. Use this field to customize the email - subject if you don't want to use the one from the template. - body: - type: string - description: '{''This field is optional. If provided, it serves as a fallback - template in case the primary template fails to render. This has to be - a plain text body of the email.''}' - context: - description: This field is optional. If provided, the context data will - be passed to the template engine during rendering. - attachments: - type: array - items: - $ref: '#/components/schemas/Attachment' - description: This field is optional. Use this field to include file attachments - with your email notification. Provide the file data as a base64 encoded - string *or* a publicly accessible URL. - trace_id: - type: string - description: This field is optional. A unique identifier for tracking the - notification request. Useful for logging and debugging. - maxLength: 60 - tags: - type: array - items: - type: string - description: This field is optional. A list of metadata tags for analytics - or categorization purposes. - required: - - template_id - - to - Checkout: - type: object - description: |- - Serializer to work with PaymentTransaction instances. - - Also uses request data from other serializers to save into PaymentTransaction db table: - properties: - amount: - type: string - format: decimal - description: 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 - currency_code: - type: string - description: 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. - pg_codes: - type: array - items: - type: string - title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment or authorization. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - billing_address: - $ref: '#/components/schemas/Address' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingOptions' - writeOnly: true - description: |- - Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. - - font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. - shipping_address: - $ref: '#/components/schemas/ShippingAddress' - agreement: - allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - attachment: - type: string - format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' - attachment_short_url: - type: string - format: uri - readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. - attachment_upload_url: - type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. - pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ - billing: - type: string - readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. - card_acceptance_criteria: - allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' - description: |- - 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. - checkout_page_url: - type: string - format: uri - readOnly: true - description: Frontend Checkout Url. - maxLength: 2000 - checkout_short_url: - type: string - format: uri - readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. - checkout_url: - type: string - format: uri - readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. - customer_birthdate: - type: string - format: date - title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. - customer_email: - type: string - format: email - description: 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. - maxLength: 128 - customer_first_name: - type: string - description: 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. - maxLength: 64 - customer_id: - type: string - description: 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. - maxLength: 64 - customer_last_name: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 16 - customer_phone_2: - type: string - title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. - maxLength: 16 - due_datetime: - type: string - format: date-time - title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. - email_recipients: - type: array - items: - type: string - format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. - expiration_time: - type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. - generate_qr_code: - type: boolean - writeOnly: true - default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. - include_sdk_setup_preload: - type: boolean - writeOnly: true - default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. - initiator_id: - type: integer - title: initiator - description: 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 - language: - enum: - - en - - ar - type: string - x-spec-enum-id: ac1757d67890d125 - default: en - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - notifications: - allOf: - - $ref: '#/components/schemas/Notifications' - title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. - operation: - type: string - readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' - payment_methods: - allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' - readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. - payment_type: - enum: - - one_off - - auto_debit - - save_card - type: string - x-spec-enum-id: b2ae60f7918918e7 - default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - preload_checkout_page: - type: boolean - writeOnly: true - default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). - product_type: - type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. - maxLength: 128 - qr_code_url: - type: string - format: uri - readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. - redirect_url: - type: string - format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - maxLength: 2000 - sdk_setup_preload_payload: - allOf: - - $ref: '#/components/schemas/CheckoutSDK' - readOnly: true - default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. - session_id: - type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - settled_pg_code: - type: string - readOnly: true - title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. - shortify_attachment_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. - shortify_checkout_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. - state: - enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod - type: string - x-spec-enum-id: caee163196dbc11f - readOnly: true - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. - - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - unit_code: - type: string - writeOnly: true - title: Unit - description: The slug of the unit to be used for the transaction. - vendor_name: - type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - webhook_url: - type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 2000 - required: - - amount - - attachment_short_url - - billing - - checkout_page_url - - checkout_short_url - - checkout_url - - currency_code - - operation - - payment_methods - - pg_codes - - qr_code_url - - sdk_setup_preload_payload - - session_id - - settled_pg_code - - state - - type - CheckoutGETResponse: - type: object - description: |- - Serializer to work with PaymentTransaction instances. - - Also uses request data from other serializers to save into PaymentTransaction db table: - properties: - amount: - type: string - format: decimal - description: 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 - currency_code: - type: string - description: 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. - pg_codes: - type: array - items: - type: string - title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment or authorization. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - billing_address: - $ref: '#/components/schemas/Address' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingOptions' - writeOnly: true - description: |- - Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. - - font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. - shipping_address: - $ref: '#/components/schemas/ShippingAddress' - agreement: - allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - attachment: - type: string - format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' - attachment_short_url: - type: string - format: uri - readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. - attachment_upload_url: - type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. - pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ - billing: - type: string - readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. - card_acceptance_criteria: - allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' - description: |- - 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. - checkout_page_url: - type: string - format: uri - readOnly: true - description: Frontend Checkout Url. - maxLength: 2000 - checkout_short_url: - type: string - format: uri - readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. - checkout_url: - type: string - format: uri - readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. - customer_birthdate: - type: string - format: date - title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. - customer_email: - type: string - format: email - description: 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. - maxLength: 128 - customer_first_name: - type: string - description: 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. - maxLength: 64 - customer_id: - type: string - description: 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. - maxLength: 64 - customer_last_name: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 16 - customer_phone_2: - type: string - title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. - maxLength: 16 - due_datetime: - type: string - format: date-time - title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. - email_recipients: - type: array - items: - type: string - format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. - expiration_time: - type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. - generate_qr_code: - type: boolean - writeOnly: true - default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. - include_sdk_setup_preload: - type: boolean - writeOnly: true - default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. - initiator_id: - type: integer - title: initiator - description: 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 - language: - enum: - - en - - ar - type: string - x-spec-enum-id: ac1757d67890d125 - default: en - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - notifications: - allOf: - - $ref: '#/components/schemas/Notifications' - title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. - operation: - type: string - readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' - payment_methods: - allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' - readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. - payment_type: - enum: - - one_off - - auto_debit - - save_card - type: string - x-spec-enum-id: b2ae60f7918918e7 - default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - preload_checkout_page: - type: boolean - writeOnly: true - default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). - product_type: - type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. - maxLength: 128 - qr_code_url: - type: string - format: uri - readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. - redirect_url: - type: string - format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - maxLength: 2000 - sdk_setup_preload_payload: - allOf: - - $ref: '#/components/schemas/CheckoutSDK' - readOnly: true - default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. - session_id: - type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - settled_pg_code: - type: string - readOnly: true - title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. - shortify_attachment_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. - shortify_checkout_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. - state: - enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod - type: string - x-spec-enum-id: caee163196dbc11f - readOnly: true - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. - - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - unit_code: - type: string - writeOnly: true - title: Unit - description: The slug of the unit to be used for the transaction. - vendor_name: - type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - webhook_url: - type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 2000 - required: - - amount - - attachment_short_url - - billing - - checkout_page_url - - checkout_short_url - - checkout_url - - currency_code - - operation - - payment_methods - - pg_codes - - qr_code_url - - sdk_setup_preload_payload - - session_id - - settled_pg_code - - state - - type - CheckoutPATCHResponse: - type: object - description: |- - Serializer to work with PaymentTransaction instances. - - Also uses request data from other serializers to save into PaymentTransaction db table: - properties: - amount: - type: string - format: decimal - description: 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 - currency_code: - type: string - description: 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. - pg_codes: - type: array - items: - type: string - title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment or authorization. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - billing_address: - $ref: '#/components/schemas/Address' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingOptions' - writeOnly: true - description: |- - Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. - - font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. - shipping_address: - $ref: '#/components/schemas/ShippingAddress' - agreement: - allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - attachment: - type: string - format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' - attachment_short_url: - type: string - format: uri - readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. - attachment_upload_url: - type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. - pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ - billing: - type: string - readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. - card_acceptance_criteria: - allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' - description: |- - 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. - checkout_page_url: - type: string - format: uri - readOnly: true - description: Frontend Checkout Url. - maxLength: 2000 - checkout_short_url: - type: string - format: uri - readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. - checkout_url: - type: string - format: uri - readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. - customer_birthdate: - type: string - format: date - title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. - customer_email: - type: string - format: email - description: 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. - maxLength: 128 - customer_first_name: - type: string - description: 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. - maxLength: 64 - customer_id: - type: string - description: 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. - maxLength: 64 - customer_last_name: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 16 - customer_phone_2: - type: string - title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. - maxLength: 16 - due_datetime: - type: string - format: date-time - title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. - email_recipients: - type: array - items: - type: string - format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. - expiration_time: - type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. - generate_qr_code: - type: boolean - writeOnly: true - default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. - include_sdk_setup_preload: - type: boolean - writeOnly: true - default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. - initiator_id: - type: integer - title: initiator - description: 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 - language: - enum: - - en - - ar - type: string - x-spec-enum-id: ac1757d67890d125 - default: en - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - notifications: - allOf: - - $ref: '#/components/schemas/Notifications' - title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. - operation: - type: string - readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' - payment_methods: - allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' - readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. - payment_type: - enum: - - one_off - - auto_debit - - save_card - type: string - x-spec-enum-id: b2ae60f7918918e7 - default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - preload_checkout_page: - type: boolean - writeOnly: true - default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). - product_type: - type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. - maxLength: 128 - qr_code_url: - type: string - format: uri - readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. - redirect_url: - type: string - format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - maxLength: 2000 - sdk_setup_preload_payload: - allOf: - - $ref: '#/components/schemas/CheckoutSDK' - readOnly: true - default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. - session_id: - type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - settled_pg_code: - type: string - readOnly: true - title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. - shortify_attachment_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. - shortify_checkout_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. - state: - enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod - type: string - x-spec-enum-id: caee163196dbc11f - readOnly: true - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. - - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - unit_code: - type: string - writeOnly: true - title: Unit - description: The slug of the unit to be used for the transaction. - vendor_name: - type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - webhook_url: - type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 2000 - required: - - amount - - attachment_short_url - - billing - - checkout_page_url - - checkout_short_url - - checkout_url - - currency_code - - operation - - payment_methods - - pg_codes - - qr_code_url - - sdk_setup_preload_payload - - session_id - - settled_pg_code - - state - - type - CheckoutPOSTRequest: - type: object - description: |- - Serializer to work with PaymentTransaction instances. - - Also uses request data from other serializers to save into PaymentTransaction db table: - properties: - amount: - type: string - format: decimal - description: 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 - currency_code: - type: string - description: 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. - pg_codes: - type: array - items: - type: string - title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment or authorization. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - billing_address: - $ref: '#/components/schemas/Address' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingOptions' - writeOnly: true - description: |- - Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. - - font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. - shipping_address: - $ref: '#/components/schemas/ShippingAddress' - agreement: - allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - attachment: - type: string - format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' - attachment_short_url: - type: string - format: uri - readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. - attachment_upload_url: - type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. - pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ - billing: - type: string - readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. - card_acceptance_criteria: - allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' - description: |- - 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. - checkout_page_url: - type: string - format: uri - readOnly: true - description: Frontend Checkout Url. - maxLength: 2000 - checkout_short_url: - type: string - format: uri - readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. - checkout_url: - type: string - format: uri - readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. - customer_birthdate: - type: string - format: date - title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. - customer_email: - type: string - format: email - description: 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. - maxLength: 128 - customer_first_name: - type: string - description: 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. - maxLength: 64 - customer_id: - type: string - description: 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. - maxLength: 64 - customer_last_name: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 16 - customer_phone_2: - type: string - title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. - maxLength: 16 - due_datetime: - type: string - format: date-time - title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. - email_recipients: - type: array - items: - type: string - format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. - expiration_time: - type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. - generate_qr_code: - type: boolean - writeOnly: true - default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. - include_sdk_setup_preload: - type: boolean - writeOnly: true - default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. - initiator_id: - type: integer - title: initiator - description: 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 - language: - enum: - - en - - ar - type: string - x-spec-enum-id: ac1757d67890d125 - default: en - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - notifications: - allOf: - - $ref: '#/components/schemas/Notifications' - title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. - operation: - type: string - readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' - payment_methods: - allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' - readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. - payment_type: - enum: - - one_off - - auto_debit - - save_card - type: string - x-spec-enum-id: b2ae60f7918918e7 - default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - preload_checkout_page: - type: boolean - writeOnly: true - default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). - product_type: - type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. - maxLength: 128 - qr_code_url: - type: string - format: uri - readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. - redirect_url: - type: string - format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - maxLength: 2000 - sdk_setup_preload_payload: - allOf: - - $ref: '#/components/schemas/CheckoutSDK' - readOnly: true - default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. - session_id: - type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - settled_pg_code: - type: string - readOnly: true - title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. - shortify_attachment_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. - shortify_checkout_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. - state: - enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod - type: string - x-spec-enum-id: caee163196dbc11f - readOnly: true - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. - - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - unit_code: - type: string - writeOnly: true - title: Unit - description: The slug of the unit to be used for the transaction. - vendor_name: - type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - webhook_url: - type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 2000 - required: - - amount - - attachment_short_url - - billing - - checkout_page_url - - checkout_short_url - - checkout_url - - currency_code - - operation - - payment_methods - - pg_codes - - qr_code_url - - sdk_setup_preload_payload - - session_id - - settled_pg_code - - state - - type - CheckoutPOSTResponse: - type: object - description: |- - Serializer to work with PaymentTransaction instances. - - Also uses request data from other serializers to save into PaymentTransaction db table: - properties: - amount: - type: string - format: decimal - description: 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 - currency_code: - type: string - description: 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. - pg_codes: - type: array - items: - type: string - title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment or authorization. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - billing_address: - $ref: '#/components/schemas/Address' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingOptions' - writeOnly: true - description: |- - Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. - - font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. - shipping_address: - $ref: '#/components/schemas/ShippingAddress' - agreement: - allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - attachment: - type: string - format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' - attachment_short_url: - type: string - format: uri - readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. - attachment_upload_url: - type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. - pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ - billing: - type: string - readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. - card_acceptance_criteria: - allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' - description: |- - 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. - checkout_page_url: - type: string - format: uri - readOnly: true - description: Frontend Checkout Url. - maxLength: 2000 - checkout_short_url: - type: string - format: uri - readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. - checkout_url: - type: string - format: uri - readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. - customer_birthdate: - type: string - format: date - title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. - customer_email: - type: string - format: email - description: 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. - maxLength: 128 - customer_first_name: - type: string - description: 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. - maxLength: 64 - customer_id: - type: string - description: 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. - maxLength: 64 - customer_last_name: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 16 - customer_phone_2: - type: string - title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. - maxLength: 16 - due_datetime: - type: string - format: date-time - title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. - email_recipients: - type: array - items: - type: string - format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. - expiration_time: - type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. - generate_qr_code: - type: boolean - writeOnly: true - default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. - include_sdk_setup_preload: - type: boolean - writeOnly: true - default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. - initiator_id: - type: integer - title: initiator - description: 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 - language: - enum: - - en - - ar - type: string - x-spec-enum-id: ac1757d67890d125 - default: en - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - notifications: - allOf: - - $ref: '#/components/schemas/Notifications' - title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. - operation: - type: string - readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' - payment_methods: - allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' - readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. - payment_type: - enum: - - one_off - - auto_debit - - save_card - type: string - x-spec-enum-id: b2ae60f7918918e7 - default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - preload_checkout_page: - type: boolean - writeOnly: true - default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). - product_type: - type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. - maxLength: 128 - qr_code_url: - type: string - format: uri - readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. - redirect_url: - type: string - format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - maxLength: 2000 - sdk_setup_preload_payload: - allOf: - - $ref: '#/components/schemas/CheckoutSDK' - readOnly: true - default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. - session_id: - type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - settled_pg_code: - type: string - readOnly: true - title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. - shortify_attachment_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. - shortify_checkout_url: - type: boolean - writeOnly: true - default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. - state: - enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod - type: string - x-spec-enum-id: caee163196dbc11f - readOnly: true - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. - - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - unit_code: - type: string - writeOnly: true - title: Unit - description: The slug of the unit to be used for the transaction. - vendor_name: - type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - webhook_url: - type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 2000 - required: - - amount - - attachment_short_url - - billing - - checkout_page_url - - checkout_short_url - - checkout_url - - currency_code - - operation - - payment_methods - - pg_codes - - qr_code_url - - sdk_setup_preload_payload - - session_id - - settled_pg_code - - state - - type - CheckoutSDK: + $ref: "#/components/schemas/GenericErrorMessage" + description: "" +components: + schemas: + Address: type: object - description: |- - Serialize data for SDK init. - The SDK will use this data to initialize the payment process and - to display the payment methods. - properties: - amount: - type: string - format: decimal - description: 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 - billing: - type: string - readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. - cards: - type: array - items: - type: object - additionalProperties: {} - description: List of saved tokenized cards for customer payments, which - can be used for transactions. Render alongside `payment_methods` for customers - to choose from. - readOnly: true - customer_id: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 16 - currency_code: - type: string - description: 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. - expiration_time: - type: string - readOnly: true - description: 'The datetime when this payment transaction will expire. ' - language: - enum: - - en - - ar - type: string - x-spec-enum-id: ac1757d67890d125 - default: en - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - operation: + description: Nested serializer to save Address data into PaymentTransaction + properties: + line1: type: string - readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. - payment_type: - enum: - - one_off - - auto_debit - - save_card + maxLength: 128 + line2: type: string - x-spec-enum-id: b2ae60f7918918e7 - default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - payment_methods: - type: array - items: {} - description: "The provided documentation describes the `payment_methods` - field.\n\n Detailing the types of payment methods included and their functionality - \nas well as backward compatibility considerations for removed methods. - \n\nThe `payment_methods` field includes various payment options available - to customers\nexcluding device-specific methods like `apple_pay`, `google_pay`and - `flex_methods` represented in flex methods section\nit primarily supports - methods requiring a redirect flow\nwhere users complete transactions on - an external webpage.\n\n`Functionality`: users are redirected to an external - \nsite mostly to gateway payment page \nusing `redirect_url` where they - can complete the payment flow\n\n**The dynamic nature of the payment_methods**:`payment_methods` - type is an array of objects \nand it's type allows it to accommodate an - unlimited variety of payment options\nas each object represents a gateway - payment option but strictly associated to redirect payment flow\n\n**Backward - Compatibility Notice:**\n\n`stc_pay`: \nprevious Inclusion, `stc_pay` - was formerly listed within the `payment_methods` array\nit has been removed - in favor of a more streamlined integration within the SDK\nsimilar to - the approach for `payment_services`.\n\n**Backward Compatibility:** \n\nThe - SDK must still support STC Bank for applications relying on older API versions.\nAlthough - it will not appear in current and future versions\nthe SDK will manage - its inclusion internally\n\nto ensure a seamless transition and consistent - user experience\nacross different API versions, without disrupting existing - integrations.\n" - readOnly: true - payment_services: - type: array - items: {} - description: "Dedicated to singular, prominently featured payment options\n\nsuch - as `apple_pay`, `google_pay`, `samsung_pay`, `stc_pay`, etc.,\nthe `payment_services` - field presents these methods in a distinctive manner.\n\nUnlike `payment_methods`, - payment services are intended to be displayed uniquely,\nTypically represented - by dedicated buttons or interfaces within the payment page.\n\nThis ensures - that each payment service,\nidentifiable by its unique flow ie: (`apple_pay`, - `stc_pay`)\nis presented no more than once to the user\nmaintaining clarity - and simplicity in the payment selection process.\n\n**Backward Compatibility - Notice**:\nhistorically, the availability of (`apple_pay`, `google_pay`) - \nwas indicated through the `apple_pay_available` and `google_pay_available` - flags\nat the root level of the API response.\n\nWith the evolution of - the API, these flags have been deprecated, \nand the respective payment - methods have been integrated into the `payment_services` array.\n\nDespite - this restructuring, backward compatibility for these payment methods\nis - preserved in the SDK to accommodate previous API versions,\nensuring a - seamless transition for existing implementations.\n" - readOnly: true - flex_methods: - type: array - items: {} - description: | - The `flex_methods` field encompasses a comprehensive array - of payment options available to customers, - explicitly excluding device-specific methods such as `apple_pay` - `google_pay`, redirect flow `payment_methods` and tokenized card solutions - otherwise it represents the flexible payment methods ie:(`tamara`, `tabby`, `taly`) - payment options that necessitate dynamic flows - where SDK might need to fetch some `pre-payment-check` API calls then - users are guided to an external webpage to finalize their payment transactions. - - It's important to note that the flex_methods array is dynamic - and can accommodate an unlimited array of payment methods. - each method listed should be individually rendered within the user interface with a separated flow. - readOnly: true - sdk_studio: - type: object - additionalProperties: {} - description: Represents the configuration of SDK Studio configuration, which - includes the available payment methods and services sdk config required - by the frontend to initialize the payment SDK properly. - readOnly: true - response: - type: object - additionalProperties: {} - description: "**What is a payment gateway response?**\n\nA payment gateway - response is the feedback received\nfrom payment gateway after a user has - completed a payment\nthis response provides information on whether the - payment was successful or if it was canceled or failed.\n\n**When do we - receive the response?**\n\nWe receive the payment gateway response immediately - after the user has made a payment\nor after n of minutes defined for a - gateway inquiry request initiated by ottu core\nto fetch the transaction - status after the defined time for each gateway.\n\n**Which attempt do - we get the response for?**\n\nthe response we provide is from the most - recent payment attempt.\nthis ensures that the information reflects the - latest status of the transaction.\n\n**Structure of the response**: \n\nThe - response structure is managed by our SDK,\nwhich updates the payment details - and triggers one of three callbacks\nbased on the status provided in the - response:\n\n`successCallback`: Triggered if the response.status indicates - a successful payment.\n\n`cancelCallback`: Triggered if the response.status - indicates a canceled payment.\n\n`errorCallback`: Triggered if the response.status - indicates a error payment.\n\n" - readOnly: true + maxLength: 128 + city: + type: string + maxLength: 40 state: - enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod type: string - x-spec-enum-id: caee163196dbc11f - readOnly: true - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. - - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - type: + maxLength: 40 + country: enum: - - e_commerce - - payment_request + - AF + - AL + - DZ + - AS + - AD + - AO + - AI + - AQ + - AG + - AR + - AM + - AW + - AU + - AT + - AZ + - BS + - BH + - BD + - BB + - BY + - BE + - BZ + - BJ + - BM + - BT + - BO + - BQ + - BA + - BW + - BV + - BR + - IO + - BN + - BG + - BF + - BI + - CV + - KH + - CM + - CA + - KY + - CF + - TD + - CL + - CN + - CX + - CC + - CO + - KM + - CG + - CD + - CK + - CR + - HR + - CU + - CW + - CY + - CZ + - CI + - DK + - DJ + - DM + - DO + - EC + - EG + - SV + - GQ + - ER + - EE + - SZ + - ET + - FK + - FO + - FJ + - FI + - FR + - GF + - PF + - TF + - GA + - GM + - GE + - DE + - GH + - GI + - GR + - GL + - GD + - GP + - GU + - GT + - GG + - GN + - GW + - GY + - HT + - HM + - VA + - HN + - HK + - HU + - IS + - IN + - ID + - IR + - IQ + - IE + - IM + - IL + - IT + - JM + - JP + - JE + - JO + - KZ + - KE + - KI + - KP + - KR + - KW + - KG + - LA + - LV + - LB + - LS + - LR + - LY + - LI + - LT + - LU + - MO + - MG + - MW + - MY + - MV + - ML + - MT + - MH + - MQ + - MR + - MU + - YT + - MX + - FM + - MD + - MC + - MN + - ME + - MS + - MA + - MZ + - MM + - NA + - NR + - NP + - NL + - NC + - NZ + - NI + - NE + - NG + - NU + - NF + - MK + - MP + - "NO" + - OM + - PK + - PW + - PS + - PA + - PG + - PY + - PE + - PH + - PN + - PL + - PT + - PR + - QA + - RO + - RU + - RW + - RE + - BL + - SH + - KN + - LC + - MF + - PM + - VC + - WS + - SM + - ST + - SA + - SN + - RS + - SC + - SL + - SG + - SX + - SK + - SI + - SB + - SO + - ZA + - GS + - SS + - ES + - LK + - SD + - SR + - SJ + - SE + - CH + - SY + - TW + - TJ + - TZ + - TH + - TL + - TG + - TK + - TO + - TT + - TN + - TM + - TC + - TV + - TR + - UG + - UA + - AE + - GB + - US + - UM + - UY + - UZ + - VU + - VE + - VN + - VG + - VI + - WF + - EH + - YE + - ZM + - ZW + - AX type: string - x-spec-enum-id: ad398830c7970f0a description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - is_amount_editable: - type: boolean - readOnly: true - title: Editable amount - description: This field specifies whether the customer can modify the payment - amount and choose the amount he wishes to pay. - session_id: - type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - cancel_url: + * `AF` - Afghanistan + * `AL` - Albania + * `DZ` - Algeria + * `AS` - American Samoa + * `AD` - Andorra + * `AO` - Angola + * `AI` - Anguilla + * `AQ` - Antarctica + * `AG` - Antigua and Barbuda + * `AR` - Argentina + * `AM` - Armenia + * `AW` - Aruba + * `AU` - Australia + * `AT` - Austria + * `AZ` - Azerbaijan + * `BS` - Bahamas + * `BH` - Bahrain + * `BD` - Bangladesh + * `BB` - Barbados + * `BY` - Belarus + * `BE` - Belgium + * `BZ` - Belize + * `BJ` - Benin + * `BM` - Bermuda + * `BT` - Bhutan + * `BO` - Bolivia, Plurinational State of + * `BQ` - Bonaire, Sint Eustatius and Saba + * `BA` - Bosnia and Herzegovina + * `BW` - Botswana + * `BV` - Bouvet Island + * `BR` - Brazil + * `IO` - British Indian Ocean Territory + * `BN` - Brunei Darussalam + * `BG` - Bulgaria + * `BF` - Burkina Faso + * `BI` - Burundi + * `CV` - Cabo Verde + * `KH` - Cambodia + * `CM` - Cameroon + * `CA` - Canada + * `KY` - Cayman Islands + * `CF` - Central African Republic + * `TD` - Chad + * `CL` - Chile + * `CN` - China + * `CX` - Christmas Island + * `CC` - Cocos (Keeling) Islands + * `CO` - Colombia + * `KM` - Comoros + * `CG` - Congo + * `CD` - Congo, The Democratic Republic of the + * `CK` - Cook Islands + * `CR` - Costa Rica + * `HR` - Croatia + * `CU` - Cuba + * `CW` - Curaçao + * `CY` - Cyprus + * `CZ` - Czechia + * `CI` - Côte d'Ivoire + * `DK` - Denmark + * `DJ` - Djibouti + * `DM` - Dominica + * `DO` - Dominican Republic + * `EC` - Ecuador + * `EG` - Egypt + * `SV` - El Salvador + * `GQ` - Equatorial Guinea + * `ER` - Eritrea + * `EE` - Estonia + * `SZ` - Eswatini + * `ET` - Ethiopia + * `FK` - Falkland Islands (Malvinas) + * `FO` - Faroe Islands + * `FJ` - Fiji + * `FI` - Finland + * `FR` - France + * `GF` - French Guiana + * `PF` - French Polynesia + * `TF` - French Southern Territories + * `GA` - Gabon + * `GM` - Gambia + * `GE` - Georgia + * `DE` - Germany + * `GH` - Ghana + * `GI` - Gibraltar + * `GR` - Greece + * `GL` - Greenland + * `GD` - Grenada + * `GP` - Guadeloupe + * `GU` - Guam + * `GT` - Guatemala + * `GG` - Guernsey + * `GN` - Guinea + * `GW` - Guinea-Bissau + * `GY` - Guyana + * `HT` - Haiti + * `HM` - Heard Island and McDonald Islands + * `VA` - Holy See (Vatican City State) + * `HN` - Honduras + * `HK` - Hong Kong + * `HU` - Hungary + * `IS` - Iceland + * `IN` - India + * `ID` - Indonesia + * `IR` - Iran, Islamic Republic of + * `IQ` - Iraq + * `IE` - Ireland + * `IM` - Isle of Man + * `IL` - Israel + * `IT` - Italy + * `JM` - Jamaica + * `JP` - Japan + * `JE` - Jersey + * `JO` - Jordan + * `KZ` - Kazakhstan + * `KE` - Kenya + * `KI` - Kiribati + * `KP` - Korea, Democratic People's Republic of + * `KR` - Korea, Republic of + * `KW` - Kuwait + * `KG` - Kyrgyzstan + * `LA` - Lao People's Democratic Republic + * `LV` - Latvia + * `LB` - Lebanon + * `LS` - Lesotho + * `LR` - Liberia + * `LY` - Libya + * `LI` - Liechtenstein + * `LT` - Lithuania + * `LU` - Luxembourg + * `MO` - Macao + * `MG` - Madagascar + * `MW` - Malawi + * `MY` - Malaysia + * `MV` - Maldives + * `ML` - Mali + * `MT` - Malta + * `MH` - Marshall Islands + * `MQ` - Martinique + * `MR` - Mauritania + * `MU` - Mauritius + * `YT` - Mayotte + * `MX` - Mexico + * `FM` - Micronesia, Federated States of + * `MD` - Moldova, Republic of + * `MC` - Monaco + * `MN` - Mongolia + * `ME` - Montenegro + * `MS` - Montserrat + * `MA` - Morocco + * `MZ` - Mozambique + * `MM` - Myanmar + * `NA` - Namibia + * `NR` - Nauru + * `NP` - Nepal + * `NL` - Netherlands + * `NC` - New Caledonia + * `NZ` - New Zealand + * `NI` - Nicaragua + * `NE` - Niger + * `NG` - Nigeria + * `NU` - Niue + * `NF` - Norfolk Island + * `MK` - North Macedonia + * `MP` - Northern Mariana Islands + * `NO` - Norway + * `OM` - Oman + * `PK` - Pakistan + * `PW` - Palau + * `PS` - Palestine, State of + * `PA` - Panama + * `PG` - Papua New Guinea + * `PY` - Paraguay + * `PE` - Peru + * `PH` - Philippines + * `PN` - Pitcairn + * `PL` - Poland + * `PT` - Portugal + * `PR` - Puerto Rico + * `QA` - Qatar + * `RO` - Romania + * `RU` - Russian Federation + * `RW` - Rwanda + * `RE` - Réunion + * `BL` - Saint Barthélemy + * `SH` - Saint Helena, Ascension and Tristan da Cunha + * `KN` - Saint Kitts and Nevis + * `LC` - Saint Lucia + * `MF` - Saint Martin (French part) + * `PM` - Saint Pierre and Miquelon + * `VC` - Saint Vincent and the Grenadines + * `WS` - Samoa + * `SM` - San Marino + * `ST` - Sao Tome and Principe + * `SA` - Saudi Arabia + * `SN` - Senegal + * `RS` - Serbia + * `SC` - Seychelles + * `SL` - Sierra Leone + * `SG` - Singapore + * `SX` - Sint Maarten (Dutch part) + * `SK` - Slovakia + * `SI` - Slovenia + * `SB` - Solomon Islands + * `SO` - Somalia + * `ZA` - South Africa + * `GS` - South Georgia and the South Sandwich Islands + * `SS` - South Sudan + * `ES` - Spain + * `LK` - Sri Lanka + * `SD` - Sudan + * `SR` - Suriname + * `SJ` - Svalbard and Jan Mayen + * `SE` - Sweden + * `CH` - Switzerland + * `SY` - Syrian Arab Republic + * `TW` - Taiwan, Province of China + * `TJ` - Tajikistan + * `TZ` - Tanzania, United Republic of + * `TH` - Thailand + * `TL` - Timor-Leste + * `TG` - Togo + * `TK` - Tokelau + * `TO` - Tonga + * `TT` - Trinidad and Tobago + * `TN` - Tunisia + * `TM` - Turkmenistan + * `TC` - Turks and Caicos Islands + * `TV` - Tuvalu + * `TR` - Türkiye + * `UG` - Uganda + * `UA` - Ukraine + * `AE` - United Arab Emirates + * `GB` - United Kingdom + * `US` - United States + * `UM` - United States Minor Outlying Islands + * `UY` - Uruguay + * `UZ` - Uzbekistan + * `VU` - Vanuatu + * `VE` - Venezuela, Bolivarian Republic of + * `VN` - Viet Nam + * `VG` - Virgin Islands, British + * `VI` - Virgin Islands, U.S. + * `WF` - Wallis and Futuna + * `EH` - Western Sahara + * `YE` - Yemen + * `ZM` - Zambia + * `ZW` - Zimbabwe + * `AX` - Åland Islands + x-spec-enum-id: 8067456ff4917829 + postal_code: type: string - format: uri - readOnly: true - description: "This endpoint used to cancel the transaction using the merchant - cancellation flow, \nto ensure the transaction cannot be paid again \nand - trigger the webhook notification \n" + maxLength: 12 required: - - amount - - billing - - cancel_url - - cards - - currency_code - - expiration_time - - flex_methods - - is_amount_editable - - operation - - payment_methods - - payment_services - - response - - sdk_studio - - session_id - - state - - type - CheckoutSDKResponse: + - city + - country + - line1 + Agreement: type: object description: |- - Serialize data for SDK init. - The SDK will use this data to initialize the payment process and - to display the payment methods. + Serializer to hold the recurring data information. + This is required for being able to create recurring payments and the PGs + require this information. properties: - amount: - type: string - format: decimal - description: 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 - billing: - allOf: - - $ref: '#/components/schemas/Billing' - readOnly: true - description: Detailed billing information for the transaction including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - cards: - type: array - items: - $ref: '#/components/schemas/CardSDK' - description: List of saved tokenized cards for customer payments, which - can be used for transactions. Render alongside `payment_methods` for customers - to choose from. - customer_id: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 16 - currency_code: - type: string - description: 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. - expiration_time: + id: type: string - readOnly: true - description: 'The datetime when this payment transaction will expire. ' - language: + description: |- + 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: + 1. Recurring Payments: Periodic debits, e.g., gym memberships. + 2. Installment Payments: Multiple charges for a single purchase over time. + 3. Unscheduled: Future payments as required, e.g., account top-ups. + 4. Industry Practice: Standard business practices related to an original payment, e.g., hotel charges after checkout. + maxLength: 128 + amount_variability: enum: - - en - - ar + - fixed + - variable type: string - x-spec-enum-id: ac1757d67890d125 - default: en + x-spec-enum-id: 559f7896c94c0925 description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. + Indicates if all payments within the agreement use the same amount or if the amount differs between the payments. - * `en` - English - * `ar` - Arabic - operation: + * `fixed` - Fixed + * `variable` - Variable + start_date: type: string - readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. - payment_type: - enum: - - one_off - - auto_debit - - save_card + format: date + description: Date on which the agreement with the payer to process payments starts. + expiry_date: type: string - x-spec-enum-id: b2ae60f7918918e7 - default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - payment_methods: - type: array - items: - $ref: '#/components/schemas/PaymentMethods' - description: "The provided documentation describes the `payment_methods` - field.\n\n Detailing the types of payment methods included and their functionality - \nas well as backward compatibility considerations for removed methods. - \n\nThe `payment_methods` field includes various payment options available - to customers\nexcluding device-specific methods like `apple_pay`, `google_pay`and - `flex_methods` represented in flex methods section\nit primarily supports - methods requiring a redirect flow\nwhere users complete transactions on - an external webpage.\n\n`Functionality`: users are redirected to an external - \nsite mostly to gateway payment page \nusing `redirect_url` where they - can complete the payment flow\n\n**The dynamic nature of the payment_methods**:`payment_methods` - type is an array of objects \nand it's type allows it to accommodate an - unlimited variety of payment options\nas each object represents a gateway - payment option but strictly associated to redirect payment flow\n\n**Backward - Compatibility Notice:**\n\n`stc_pay`: \nprevious Inclusion, `stc_pay` - was formerly listed within the `payment_methods` array\nit has been removed - in favor of a more streamlined integration within the SDK\nsimilar to - the approach for `payment_services`.\n\n**Backward Compatibility:** \n\nThe - SDK must still support STC Bank for applications relying on older API versions.\nAlthough - it will not appear in current and future versions\nthe SDK will manage - its inclusion internally\n\nto ensure a seamless transition and consistent - user experience\nacross different API versions, without disrupting existing - integrations.\n" - payment_services: - type: array - items: - $ref: '#/components/schemas/PaymentServices' - description: "Dedicated to singular, prominently featured payment options\n\nsuch - as `apple_pay`, `google_pay`, `samsung_pay`, `stc_pay`, etc.,\nthe `payment_services` - field presents these methods in a distinctive manner.\n\nUnlike `payment_methods`, - payment services are intended to be displayed uniquely,\nTypically represented - by dedicated buttons or interfaces within the payment page.\n\nThis ensures - that each payment service,\nidentifiable by its unique flow ie: (`apple_pay`, - `stc_pay`)\nis presented no more than once to the user\nmaintaining clarity - and simplicity in the payment selection process.\n\n**Backward Compatibility - Notice**:\nhistorically, the availability of (`apple_pay`, `google_pay`) - \nwas indicated through the `apple_pay_available` and `google_pay_available` - flags\nat the root level of the API response.\n\nWith the evolution of - the API, these flags have been deprecated, \nand the respective payment - methods have been integrated into the `payment_services` array.\n\nDespite - this restructuring, backward compatibility for these payment methods\nis - preserved in the SDK to accommodate previous API versions,\nensuring a - seamless transition for existing implementations.\n" - flex_methods: - type: array - items: - $ref: '#/components/schemas/FlexMethods' - description: | - The `flex_methods` field encompasses a comprehensive array - of payment options available to customers, - explicitly excluding device-specific methods such as `apple_pay` - `google_pay`, redirect flow `payment_methods` and tokenized card solutions - otherwise it represents the flexible payment methods ie:(`tamara`, `tabby`, `taly`) - payment options that necessitate dynamic flows - where SDK might need to fetch some `pre-payment-check` API calls then - users are guided to an external webpage to finalize their payment transactions. - - It's important to note that the flex_methods array is dynamic - and can accommodate an unlimited array of payment methods. - each method listed should be individually rendered within the user interface with a separated flow. - sdk_studio: - type: object - additionalProperties: {} - description: Represents the configuration of SDK Studio configuration, which - includes the available payment methods and services sdk config required - by the frontend to initialize the payment SDK properly. - readOnly: true - response: - type: array - items: - $ref: '#/components/schemas/Response' - description: "**What is a payment gateway response?**\n\nA payment gateway - response is the feedback received\nfrom payment gateway after a user has - completed a payment\nthis response provides information on whether the - payment was successful or if it was canceled or failed.\n\n**When do we - receive the response?**\n\nWe receive the payment gateway response immediately - after the user has made a payment\nor after n of minutes defined for a - gateway inquiry request initiated by ottu core\nto fetch the transaction - status after the defined time for each gateway.\n\n**Which attempt do - we get the response for?**\n\nthe response we provide is from the most - recent payment attempt.\nthis ensures that the information reflects the - latest status of the transaction.\n\n**Structure of the response**: \n\nThe - response structure is managed by our SDK,\nwhich updates the payment details - and triggers one of three callbacks\nbased on the status provided in the - response:\n\n`successCallback`: Triggered if the response.status indicates - a successful payment.\n\n`cancelCallback`: Triggered if the response.status - indicates a canceled payment.\n\n`errorCallback`: Triggered if the response.status - indicates a error payment.\n\n" - state: + format: date + description: Date on which your agreement with the payer to process payments expires. + max_amount_per_cycle: + type: string + format: decimal + description: The maximum amount for a single payment in the series as agreed with the payer. + cycle_interval_days: + type: integer + maximum: 366 + minimum: 1 + description: The minimum number of days between payments agreed with the payer. + total_cycles: + type: integer + maximum: 999 + minimum: 1 + description: The number of merchant-initiated payments within the recurring payment agreement. + frequency: enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod + - irregular + - daily + - weekly + - semi_monthly + - monthly + - quarterly + - semi_annually + - yearly + - other type: string - x-spec-enum-id: caee163196dbc11f - readOnly: true + x-spec-enum-id: f7d3278be09218f0 description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. + The frequency of the payments within the series as agreed with the payer. - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery + * `irregular` - Irregular + * `daily` - Daily + * `weekly` - Weekly + * `semi_monthly` - Semi Monthly + * `monthly` - Monthly + * `quarterly` - Quarterly + * `semi_annually` - Semi Annually + * `yearly` - Yearly + * `other` - Other type: enum: - - e_commerce - - payment_request + - event_based + - installment + - recurring + - unscheduled + - other type: string - x-spec-enum-id: ad398830c7970f0a + x-spec-enum-id: a78a057f002d8a8c + default: recurring description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. + The type of commercial agreement that the payer has with the merchant. - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - is_amount_editable: - type: boolean - readOnly: true - title: Editable amount - description: This field specifies whether the customer can modify the payment - amount and choose the amount he wishes to pay. - session_id: + *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 + seller: + allOf: + - $ref: "#/components/schemas/AgreementSeller" + description: Details about the retailer, if the agreement is for installment payments. + AgreementSeller: + type: object + properties: + name: type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - cancel_url: + description: The retailer's trading name. + maxLength: 128 + short_name: type: string - format: uri - readOnly: true - description: "This endpoint used to cancel the transaction using the merchant - cancellation flow, \nto ensure the transaction cannot be paid again \nand - trigger the webhook notification \n" - required: - - amount - - billing - - cancel_url - - cards - - currency_code - - expiration_time - - flex_methods - - is_amount_editable - - language - - operation - - payment_methods - - payment_services - - response - - sdk_studio - - session_id - - state - - type - CheckoutSubmit: + description: Abbreviation of the retailer's trading name, suitable for payer's statement display. + maxLength: 64 + category_code: + type: string + description: A 4-digit code classifying the retailer's business by the type of goods or services it offers. + maxLength: 64 + AmountDetails: type: object - description: |- - This serializer is responsible for validating the data sent by the SDK - when the user submits the payment form and for creating the url. properties: - amount: - type: string - format: decimal - customer_additional_phone: + currency_code: type: string - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. - maxLength: 32 - pg_code: - enum: - - dummy + readOnly: true + amount: type: string - x-spec-enum-id: 5130c80a788d4b63 - description: |- - the unique identifier code (`payment_methods[index].code`) for the payment method that the customer has selected to proceed with the transaction. - - * `dummy` - Dummy - save_card: - type: boolean - default: false - description: If true, the card will be saved for future payments. This option - is only available if the payment gateway supports it. - status: - enum: - - success - - error - - failed + description: 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 + maxLength: 120 + total: type: string - x-spec-enum-id: e1fe233c555c1d4d readOnly: true - description: |- - The status of the payment operation.It can be one of the following values: `success`, `canceled`, `error` - - * `success` - Success - * `error` - Error - * `failed` - Failed - message: + description: Denotes the comprehensive total of the payment transaction, incorporating both the principal amount and any associated fees. + fee: type: string readOnly: true - description: The message to be displayed to the user. - redirect_url: + description: 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. + exchange_rate: type: string - format: uri - readOnly: true - description: This field provides the URL to which the customer should be - redirected in order to complete the payment process when they have selected - this specific payment method. The developer implementing the SDK must - ensure that the redirection process is smooth and secure, providing a - seamless experience for the customer while maintaining the integrity of - the payment process. - channel: + description: The conversion rate used for currency conversion during payment. This value reflects the rate locally calculated. + required: + - currency_code + - fee + - total + ApplePayHeaderSchema: + type: object + description: Apple Pay header containing encryption details + properties: + ephemeralPublicKey: + type: string + description: Ephemeral public key for encryption + publicKeyHash: + type: string + description: Hash of the merchant's public key + transactionId: + type: string + description: Unique transaction identifier + required: + - publicKeyHash + - transactionId + ApplePayInstrument: + type: object + description: Apple Pay payment instrument + properties: + instrument_type: enum: - - web_sdk - - mobile_sdk - - hosted - - api + - apple_pay type: string - x-spec-enum-id: 1fe0752a05a7277d - default: web_sdk + x-spec-enum-id: 49c50763123c8d7e + default: apple_pay description: |- - IMPORTANT: This field determines the channel through which the payment is being made and has a direct impact on the redirection behavior post-payment. - - For Web (`web_sdk`): - - The payer will be redirected to the payment details page where they can complete the payment process. Use the code: `window.location.href = redirect_url` and the browser will handle any further redirects. - - For Mobile SDK (`mobile_sdk`): - - The `redirect_url` should be opened in a webview. This is the page where the payer will enter their card details. - - After entering the card details, the payer will be redirected to the final payment details page within the webview. - - Detect the URL redirection by listening to redirects within the webview. When a redirect occurs to the URL `{merchant_id}/b/gw/mobile-sdk-redirect`, close the webview. This indicates that the payment process has completed. - - After closing the webview, reload the SDK and call the `Retrieve init data API` to display the payment from `response object` to the payer. - - Note: `merchant_id` is the same ID used to build the `Fetch retrieve data API` and is the parameter added in the CheckoutSDK.init method. + Payment type: Apple Pay - * `web_sdk` - Web Sdk - * `mobile_sdk` - Mobile Sdk - * `hosted` - Hosted - * `api` - Api + * `apple_pay` - apple_pay + payload: + allOf: + - $ref: "#/components/schemas/ApplePayPayloadSchema" + description: Apple Pay payment token received from Apple Pay SDK. Pass the complete token object exactly as received without modification. Includes paymentData (encrypted), paymentMethod details, and transactionIdentifier. required: - - message - - pg_code - - redirect_url - - status - CheckoutSubmitSuccessResponse: + - payload + ApplePayNativePayment: type: object properties: - status: - type: string - readOnly: true - default: success - description: 'The status of the payment operation.It can be one of the following - values: `success`, `canceled`, `error`' - message: - type: string - readOnly: true - description: The message to be displayed to the user. - redirect_url: + payload: + $ref: "#/components/schemas/ApplePayToken" + pg_code: + type: + - string + - "null" + description: The unique pg_code used for this payment instrument. + session_id: type: string - format: uri - description: This field provides the URL to which the customer should be - redirected in order to complete the payment process when they have selected - this specific payment method. The developer implementing the SDK must - ensure that the redirection process is smooth and secure, providing a - seamless experience for the customer while maintaining the integrity of - the payment process. + description: A unique identifier for the payment transaction (session). required: - - message - - redirect_url - - status - ChildPayment: + - payload + - session_id + ApplePayPayloadSchema: type: object + description: Complete Apple Pay token structure properties: - amount: + paymentData: + allOf: + - $ref: "#/components/schemas/ApplePayPaymentDataSchema" + description: Encrypted payment data + paymentMethod: + allOf: + - $ref: "#/components/schemas/ApplePayPaymentMethodSchema" + description: Payment method information + transactionIdentifier: type: string - readOnly: true - currency_code: + description: Apple Pay transaction identifier + required: + - paymentData + - paymentMethod + - transactionIdentifier + ApplePayPaymentDataSchema: + type: object + description: Encrypted Apple Pay payment data + properties: + version: type: string - description: 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. - maxLength: 3 - minLength: 3 - order_no: - type: - - string - - 'null' - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - session_id: + description: Token version (e.g., 'EC_v1') + data: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - state: - enum: - - paid - - refunded - - refund_queued - - refund_rejected - - voided + description: Encrypted payment data + signature: type: string - x-spec-enum-id: f7b1c95c3c2311ac - description: |- - 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 + description: Signature of the payment data + header: + allOf: + - $ref: "#/components/schemas/ApplePayHeaderSchema" + description: Cryptographic header required: - - amount - - currency_code - ChildPymtTxn: + - data + - header + - signature + - version + ApplePayPaymentMethodSchema: type: object + description: Apple Pay payment method details properties: - id: - type: integer - readOnly: true - amount: + displayName: type: string - description: 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 - maxLength: 24 - gateway_code: + description: Display name (e.g., 'Visa 1234') + network: type: string - description: Represents the payment gateway code that was used to perform - the payment or authorization. - maxLength: 16 - currency_code: - enum: - - AED - - AFN - - ALL - - AMD - - ANG - - AOA - - ARS - - AUD - - AWG - - AZN - - BAM - - BBD - - BDT - - BGN - - BHD - - BIF - - BMD - - BND - - BOB - - BOV - - BRL - - BSD - - BTN - - BWP - - BYN - - BZD - - CAD - - CDF - - CHE - - CHF - - CHW - - CLF - - CLP - - CNY - - COP - - COU - - CRC - - CUC - - CUP - - CVE - - CZK - - DJF - - DKK - - DOP - - DZD - - EGP - - ERN - - ETB - - EUR - - FJD - - FKP - - GBP - - GEL - - GHS - - GIP - - GMD - - GNF - - GTQ - - GYD - - HKD - - HNL - - HRK - - HTG - - HUF - - IDR - - ILS - - INR - - IQD - - IRR - - ISK - - JMD - - JOD - - JPY - - KES - - KGS - - KHR - - KMF - - KPW - - KRW - - KWD - - KYD - - KZT - - LAK - - LBP - - LKR - - LRD - - LSL - - LYD - - MAD - - MDL - - MGA - - MKD - - MMK - - MNT - - MOP - - MRU - - MUR - - MVR - - MWK - - MXN - - MXV - - MYR - - MZN - - NAD - - NGN - - NIO - - NOK - - NPR - - NZD - - OMR - - PAB - - PEN - - PGK - - PHP - - PKR - - PLN - - PYG - - QAR - - RON - - RSD - - RUB - - RWF - - SAR - - SBD - - SCR - - SDG - - SEK - - SGD - - SHP - - SLE - - SLL - - SOS - - SRD - - SSP - - STN - - SVC - - SYP - - SZL - - THB - - TJS - - TMT - - TND - - TOP - - TRY - - TTD - - TWD - - TZS - - UAH - - UGX - - USD - - USN - - UYI - - UYU - - UYW - - UZS - - VED - - VES - - VND - - VUV - - WST - - XAF - - XAG - - XAU - - XBA - - XBB - - XBC - - XBD - - XCD - - XDR - - XOF - - XPD - - XPF - - XPT - - XSU - - XTS - - XUA - - XXX - - YER - - ZAR - - ZMW - - ZWL - type: string - x-spec-enum-id: 1314c690acf1c093 - description: |- - 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. - - * `AED` - AED - * `AFN` - AFN - * `ALL` - ALL - * `AMD` - AMD - * `ANG` - ANG - * `AOA` - AOA - * `ARS` - ARS - * `AUD` - AUD - * `AWG` - AWG - * `AZN` - AZN - * `BAM` - BAM - * `BBD` - BBD - * `BDT` - BDT - * `BGN` - BGN - * `BHD` - BHD - * `BIF` - BIF - * `BMD` - BMD - * `BND` - BND - * `BOB` - BOB - * `BOV` - BOV - * `BRL` - BRL - * `BSD` - BSD - * `BTN` - BTN - * `BWP` - BWP - * `BYN` - BYN - * `BZD` - BZD - * `CAD` - CAD - * `CDF` - CDF - * `CHE` - CHE - * `CHF` - CHF - * `CHW` - CHW - * `CLF` - CLF - * `CLP` - CLP - * `CNY` - CNY - * `COP` - COP - * `COU` - COU - * `CRC` - CRC - * `CUC` - CUC - * `CUP` - CUP - * `CVE` - CVE - * `CZK` - CZK - * `DJF` - DJF - * `DKK` - DKK - * `DOP` - DOP - * `DZD` - DZD - * `EGP` - EGP - * `ERN` - ERN - * `ETB` - ETB - * `EUR` - EUR - * `FJD` - FJD - * `FKP` - FKP - * `GBP` - GBP - * `GEL` - GEL - * `GHS` - GHS - * `GIP` - GIP - * `GMD` - GMD - * `GNF` - GNF - * `GTQ` - GTQ - * `GYD` - GYD - * `HKD` - HKD - * `HNL` - HNL - * `HRK` - HRK - * `HTG` - HTG - * `HUF` - HUF - * `IDR` - IDR - * `ILS` - ILS - * `INR` - INR - * `IQD` - IQD - * `IRR` - IRR - * `ISK` - ISK - * `JMD` - JMD - * `JOD` - JOD - * `JPY` - JPY - * `KES` - KES - * `KGS` - KGS - * `KHR` - KHR - * `KMF` - KMF - * `KPW` - KPW - * `KRW` - KRW - * `KWD` - KWD - * `KYD` - KYD - * `KZT` - KZT - * `LAK` - LAK - * `LBP` - LBP - * `LKR` - LKR - * `LRD` - LRD - * `LSL` - LSL - * `LYD` - LYD - * `MAD` - MAD - * `MDL` - MDL - * `MGA` - MGA - * `MKD` - MKD - * `MMK` - MMK - * `MNT` - MNT - * `MOP` - MOP - * `MRU` - MRU - * `MUR` - MUR - * `MVR` - MVR - * `MWK` - MWK - * `MXN` - MXN - * `MXV` - MXV - * `MYR` - MYR - * `MZN` - MZN - * `NAD` - NAD - * `NGN` - NGN - * `NIO` - NIO - * `NOK` - NOK - * `NPR` - NPR - * `NZD` - NZD - * `OMR` - OMR - * `PAB` - PAB - * `PEN` - PEN - * `PGK` - PGK - * `PHP` - PHP - * `PKR` - PKR - * `PLN` - PLN - * `PYG` - PYG - * `QAR` - QAR - * `RON` - RON - * `RSD` - RSD - * `RUB` - RUB - * `RWF` - RWF - * `SAR` - SAR - * `SBD` - SBD - * `SCR` - SCR - * `SDG` - SDG - * `SEK` - SEK - * `SGD` - SGD - * `SHP` - SHP - * `SLE` - SLE - * `SLL` - SLL - * `SOS` - SOS - * `SRD` - SRD - * `SSP` - SSP - * `STN` - STN - * `SVC` - SVC - * `SYP` - SYP - * `SZL` - SZL - * `THB` - THB - * `TJS` - TJS - * `TMT` - TMT - * `TND` - TND - * `TOP` - TOP - * `TRY` - TRY - * `TTD` - TTD - * `TWD` - TWD - * `TZS` - TZS - * `UAH` - UAH - * `UGX` - UGX - * `USD` - USD - * `USN` - USN - * `UYI` - UYI - * `UYU` - UYU - * `UYW` - UYW - * `UZS` - UZS - * `VED` - VED - * `VES` - VES - * `VND` - VND - * `VUV` - VUV - * `WST` - WST - * `XAF` - XAF - * `XAG` - XAG - * `XAU` - XAU - * `XBA` - XBA - * `XBB` - XBB - * `XBC` - XBC - * `XBD` - XBD - * `XCD` - XCD - * `XDR` - XDR - * `XOF` - XOF - * `XPD` - XPD - * `XPF` - XPF - * `XPT` - XPT - * `XSU` - XSU - * `XTS` - XTS - * `XUA` - XUA - * `XXX` - XXX - * `YER` - YER - * `ZAR` - ZAR - * `ZMW` - ZMW - * `ZWL` - ZWL - language: - enum: - - en - - ar + description: Card network (e.g., 'Visa') + type: type: string - x-spec-enum-id: ac1757d67890d125 - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - customer_email: + description: Card type (e.g., 'debit') + required: + - displayName + - network + - type + ApplePayToken: + type: object + properties: + paymentData: + allOf: + - $ref: "#/components/schemas/ApplePaymentData" + description: Encrypted Apple Pay payment data containing the payment amount, merchant ID, and other transaction details. This payload is decrypted by the payment gateway to complete the transaction. + paymentMethod: + allOf: + - $ref: "#/components/schemas/PaymentMethod" + description: Describes the payment method selected by the customer, including card network (e.g., Visa), type (e.g., debit), and display name. + transactionIdentifier: type: string - description: 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. - maxLength: 128 - state: + required: + - paymentData + - paymentMethod + - transactionIdentifier + ApplePaymentData: + type: object + properties: + version: type: string - readOnly: true - created: + data: type: string - format: date-time - readOnly: true - unit: + signature: type: string - readOnly: true - fee: + header: + allOf: + - $ref: "#/components/schemas/Header" + description: Cryptographic header used to decrypt the Apple Pay payment data. Includes the public key hash, ephemeral public key, wrapped key, and transaction ID. + required: + - data + - header + - signature + - version + Attachment: + type: object + properties: + content: type: string - readOnly: true - state_changed_at: + url: type: string - readOnly: true - payment_date: + format: uri + filename: type: string - readOnly: true - vendor_name: + content_type: type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - track_id: + size: type: string - readOnly: true - gateway_name: + AttachmentUpload: + type: object + properties: + file: type: string - readOnly: true - initiator: - allOf: - - $ref: '#/components/schemas/BaseUser' - readOnly: true - auth_code: + format: uri + description: A writable field that accepts an attachment. + pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ + shortify_attachment_url: + type: boolean + default: false + description: If set to `true`, the URL of the uploaded attachment will be shortened using a URL shortener service. if configured.This should be used when sharing the attachment URL via SMS or WhatsApp. This will only work with `session_id` or `order_no`. + order_no: type: string - readOnly: true - card_type: + description: This is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the `order_no` or `session_id` field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned. + maxLength: 128 + session_id: type: string - readOnly: true - attachment_url: + description: Similar to `order_no`, `session_id` is an optional identifier used to specify the payment transaction for the operation. You must provide either `order_no` or `session_id` in order to select the appropriate payment transaction. + maxLength: 128 + required: + - file + AttachmentUploadClientErrors: + oneOf: + - $ref: "#/components/schemas/AttachmentUploadFailureWithoutTXN" + - $ref: "#/components/schemas/AttachmentUploadFailureTXNNotFoundOrderNo" + - $ref: "#/components/schemas/AttachmentUploadFailureTXNNotFoundSessionID" + - $ref: "#/components/schemas/AttachmentUploadFailureTXNNotBoth" + - $ref: "#/components/schemas/AttachmentUploadFailureNoFile" + - $ref: "#/components/schemas/AttachmentUploadFailureWrongExtension" + AttachmentUploadFailureNoFile: + type: object + properties: + file: type: string - readOnly: true - card_details: + description: No file was submitted. + required: + - file + AttachmentUploadFailureTXNNotBoth: + type: object + properties: + session_id: type: string - readOnly: true - card_holder: + description: Please provide only `order_no` or `session_id`, not both. + order_no: type: string - readOnly: true - cardholder_email: + description: Please provide only `order_no` or `session_id`, not both. + required: + - order_no + - session_id + AttachmentUploadFailureTXNNotFoundOrderNo: + type: object + properties: + order_no: type: string - readOnly: true - card_number: + description: No PaymentTransaction found with `order_no` of foo. + required: + - order_no + AttachmentUploadFailureTXNNotFoundSessionID: + type: object + properties: + session_id: type: string - readOnly: true - card_expiry: + description: No PaymentTransaction found with `session_id` of foo. + required: + - session_id + AttachmentUploadFailureWithoutTXN: + type: object + properties: + attachment_short_url: type: string - readOnly: true - type: - enum: - - e_commerce - - payment_request - - bulk - - catalogue - - customer_payment - - event - - food_ordering - - iata - - real_estate - type: string - x-spec-enum-id: b2b79580b4e2b976 - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - E-Commerce - * `payment_request` - Payment request - * `bulk` - Bulk Payment Request - * `catalogue` - Catalogue purchase - * `customer_payment` - Customer payment - * `event` - Event management and booking - * `food_ordering` - Food ordering - * `iata` - IATA - * `real_estate` - Real Estate + description: You must provide either `session_id` or `order_no` to identify the PaymentTransaction. required: - - amount - - attachment_url - - auth_code - - card_details - - card_expiry - - card_holder - - card_number - - card_type - - cardholder_email - - created - - currency_code - - fee - - gateway_name - - id - - initiator - - payment_date - - state - - state_changed_at - - track_id - - unit - ChildrenPayment: + - attachment_short_url + AttachmentUploadFailureWrongExtension: type: object properties: - id: - type: integer - readOnly: true - title: Internal ID - description: This field is an automatically generated internal identifier - for each payment transaction. This unique and sequential ID makes it easy - to reference and manage individual transactions within the system. - state: - enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod - - refund_queued - - refund_rejected - - voided - type: string - x-spec-enum-id: a4680147d8c166ee - description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. - - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized - * `paid` - Paid - * `failed` - Failed - * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - * `refund_queued` - Refund Queued - * `refund_rejected` - Refund Rejected - * `voided` - Voided - created: + file: type: string - format: date-time - readOnly: true - amount: + description: "File extension 'zip' is not allowed. Allowed extensions are: pdf, jpeg, png, doc, docx, jpg, xls, xlsx, txt." + required: + - file + AttachmentUploadSuccess: + type: object + properties: + file_url: type: string - description: 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 - maxLength: 24 - currency_code: - enum: - - AED - - AFN - - ALL - - AMD - - ANG - - AOA - - ARS - - AUD - - AWG - - AZN - - BAM - - BBD - - BDT - - BGN - - BHD - - BIF - - BMD - - BND - - BOB - - BOV - - BRL - - BSD - - BTN - - BWP - - BYN - - BZD - - CAD - - CDF - - CHE - - CHF - - CHW - - CLF - - CLP - - CNY - - COP - - COU - - CRC - - CUC - - CUP - - CVE - - CZK - - DJF - - DKK - - DOP - - DZD - - EGP - - ERN - - ETB - - EUR - - FJD - - FKP - - GBP - - GEL - - GHS - - GIP - - GMD - - GNF - - GTQ - - GYD - - HKD - - HNL - - HRK - - HTG - - HUF - - IDR - - ILS - - INR - - IQD - - IRR - - ISK - - JMD - - JOD - - JPY - - KES - - KGS - - KHR - - KMF - - KPW - - KRW - - KWD - - KYD - - KZT - - LAK - - LBP - - LKR - - LRD - - LSL - - LYD - - MAD - - MDL - - MGA - - MKD - - MMK - - MNT - - MOP - - MRU - - MUR - - MVR - - MWK - - MXN - - MXV - - MYR - - MZN - - NAD - - NGN - - NIO - - NOK - - NPR - - NZD - - OMR - - PAB - - PEN - - PGK - - PHP - - PKR - - PLN - - PYG - - QAR - - RON - - RSD - - RUB - - RWF - - SAR - - SBD - - SCR - - SDG - - SEK - - SGD - - SHP - - SLE - - SLL - - SOS - - SRD - - SSP - - STN - - SVC - - SYP - - SZL - - THB - - TJS - - TMT - - TND - - TOP - - TRY - - TTD - - TWD - - TZS - - UAH - - UGX - - USD - - USN - - UYI - - UYU - - UYW - - UZS - - VED - - VES - - VND - - VUV - - WST - - XAF - - XAG - - XAU - - XBA - - XBB - - XBC - - XBD - - XCD - - XDR - - XOF - - XPD - - XPF - - XPT - - XSU - - XTS - - XUA - - XXX - - YER - - ZAR - - ZMW - - ZWL - type: string - x-spec-enum-id: 1314c690acf1c093 - readOnly: true - description: |- - 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. - - * `AED` - AED - * `AFN` - AFN - * `ALL` - ALL - * `AMD` - AMD - * `ANG` - ANG - * `AOA` - AOA - * `ARS` - ARS - * `AUD` - AUD - * `AWG` - AWG - * `AZN` - AZN - * `BAM` - BAM - * `BBD` - BBD - * `BDT` - BDT - * `BGN` - BGN - * `BHD` - BHD - * `BIF` - BIF - * `BMD` - BMD - * `BND` - BND - * `BOB` - BOB - * `BOV` - BOV - * `BRL` - BRL - * `BSD` - BSD - * `BTN` - BTN - * `BWP` - BWP - * `BYN` - BYN - * `BZD` - BZD - * `CAD` - CAD - * `CDF` - CDF - * `CHE` - CHE - * `CHF` - CHF - * `CHW` - CHW - * `CLF` - CLF - * `CLP` - CLP - * `CNY` - CNY - * `COP` - COP - * `COU` - COU - * `CRC` - CRC - * `CUC` - CUC - * `CUP` - CUP - * `CVE` - CVE - * `CZK` - CZK - * `DJF` - DJF - * `DKK` - DKK - * `DOP` - DOP - * `DZD` - DZD - * `EGP` - EGP - * `ERN` - ERN - * `ETB` - ETB - * `EUR` - EUR - * `FJD` - FJD - * `FKP` - FKP - * `GBP` - GBP - * `GEL` - GEL - * `GHS` - GHS - * `GIP` - GIP - * `GMD` - GMD - * `GNF` - GNF - * `GTQ` - GTQ - * `GYD` - GYD - * `HKD` - HKD - * `HNL` - HNL - * `HRK` - HRK - * `HTG` - HTG - * `HUF` - HUF - * `IDR` - IDR - * `ILS` - ILS - * `INR` - INR - * `IQD` - IQD - * `IRR` - IRR - * `ISK` - ISK - * `JMD` - JMD - * `JOD` - JOD - * `JPY` - JPY - * `KES` - KES - * `KGS` - KGS - * `KHR` - KHR - * `KMF` - KMF - * `KPW` - KPW - * `KRW` - KRW - * `KWD` - KWD - * `KYD` - KYD - * `KZT` - KZT - * `LAK` - LAK - * `LBP` - LBP - * `LKR` - LKR - * `LRD` - LRD - * `LSL` - LSL - * `LYD` - LYD - * `MAD` - MAD - * `MDL` - MDL - * `MGA` - MGA - * `MKD` - MKD - * `MMK` - MMK - * `MNT` - MNT - * `MOP` - MOP - * `MRU` - MRU - * `MUR` - MUR - * `MVR` - MVR - * `MWK` - MWK - * `MXN` - MXN - * `MXV` - MXV - * `MYR` - MYR - * `MZN` - MZN - * `NAD` - NAD - * `NGN` - NGN - * `NIO` - NIO - * `NOK` - NOK - * `NPR` - NPR - * `NZD` - NZD - * `OMR` - OMR - * `PAB` - PAB - * `PEN` - PEN - * `PGK` - PGK - * `PHP` - PHP - * `PKR` - PKR - * `PLN` - PLN - * `PYG` - PYG - * `QAR` - QAR - * `RON` - RON - * `RSD` - RSD - * `RUB` - RUB - * `RWF` - RWF - * `SAR` - SAR - * `SBD` - SBD - * `SCR` - SCR - * `SDG` - SDG - * `SEK` - SEK - * `SGD` - SGD - * `SHP` - SHP - * `SLE` - SLE - * `SLL` - SLL - * `SOS` - SOS - * `SRD` - SRD - * `SSP` - SSP - * `STN` - STN - * `SVC` - SVC - * `SYP` - SYP - * `SZL` - SZL - * `THB` - THB - * `TJS` - TJS - * `TMT` - TMT - * `TND` - TND - * `TOP` - TOP - * `TRY` - TRY - * `TTD` - TTD - * `TWD` - TWD - * `TZS` - TZS - * `UAH` - UAH - * `UGX` - UGX - * `USD` - USD - * `USN` - USN - * `UYI` - UYI - * `UYU` - UYU - * `UYW` - UYW - * `UZS` - UZS - * `VED` - VED - * `VES` - VES - * `VND` - VND - * `VUV` - VUV - * `WST` - WST - * `XAF` - XAF - * `XAG` - XAG - * `XAU` - XAU - * `XBA` - XBA - * `XBB` - XBB - * `XBC` - XBC - * `XBD` - XBD - * `XCD` - XCD - * `XDR` - XDR - * `XOF` - XOF - * `XPD` - XPD - * `XPF` - XPF - * `XPT` - XPT - * `XSU` - XSU - * `XTS` - XTS - * `XUA` - XUA - * `XXX` - XXX - * `YER` - YER - * `ZAR` - ZAR - * `ZMW` - ZMW - * `ZWL` - ZWL - reference_number: - type: - - string - - 'null' - readOnly: true - description: An auto-generated internal identifier for this payment transaction. - While this field may be used for tracking and reporting purposes, it is - recommended to use the session_id field instead, as it provides the same - functionality and more. - session_id: + description: The Relative URL of the uploaded file in the storage. Duplicate file names will have a random string attached to the end. + original_filename: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - pg_response: - type: object - additionalProperties: {} - readOnly: true - disclosed_to_merchant: - type: boolean - readOnly: true - title: Disclosed to Merchant? - disclosed_data: - type: object - additionalProperties: {} - readOnly: true - webhook_url_error: - type: object - additionalProperties: {} - readOnly: true + description: The original name of the uploaded file. required: - - amount - - created - - currency_code - - disclosed_data - - disclosed_to_merchant - - id - - pg_response - - reference_number - - webhook_url_error - ClickToPaySubmitFailureResponse: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - ClickToPaySubmitSuccessResponse: - oneOf: - - $ref: '#/components/schemas/DokuSDKResponse' - Client Errors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/NestedFieldErrors' - ClientErrors: + - file_url + - original_filename + AttachmentUploadSuccessSerializers: oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/NestedFieldErrors' - - $ref: '#/components/schemas/GenericErrorMessage' - - $ref: '#/components/schemas/OperationErrorResponse' - Customer: + - $ref: "#/components/schemas/AttachmentUploadSuccess" + - $ref: "#/components/schemas/AttachmentUploadSuccessWithShortURL" + AttachmentUploadSuccessWithShortURL: type: object - description: Customer serializer for Ottu PG properties: - id: + file_url: type: string - maxLength: 50 - first_name: + description: The Relative URL of the uploaded file in the storage. Duplicate file names will have a random string attached to the end. + original_filename: type: string - maxLength: 50 - last_name: + description: The original name of the uploaded file. + attachment_short_url: type: string - maxLength: 50 - email: + format: uri + description: The shortened URL of the file. Useful for SMS & WhatsApp. + required: + - attachment_short_url + - file_url + - original_filename + AutoDebit: + type: object + description: |- + Auto debit serializer should take session_id and consumer payment token + then validate if session id is valid + if session id is valid then validate if payment gateway supports auto debit + if payment gateway supports auto debit then validate if payment gateway has implemented auto debit + if payment gateway has implemented auto debit then charge the token and return charge response from client + auto_debit method which should be implemented in client + properties: + session_id: type: string - format: email - phone: + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + maxLength: 128 + token: type: string - maxLength: 50 + description: Use this field to provide the unique identifier of a saved customer card for processing a payment in the API request. required: - - email - - first_name - - id - - last_name - - phone - CustomerBillingAddress: + - session_id + - token + AutoDebitErrors: + oneOf: + - $ref: "#/components/schemas/OperationErrorResponse" + - $ref: "#/components/schemas/FieldErrors" + BrandingItem: type: object properties: - line1: + text: type: string - title: Address Line 1 - line2: + description: Display text, e.g. 'Have 30% off'. + color: type: string - title: Address Line 2 - city: + description: Hex color code for the text, e.g. '#FFFF00' or '#FFF'. + pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$ + font_weight: + type: integer + default: 700 + description: CSS font-weight value (e.g. 400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700. + required: + - color + - text + BrandingOptions: + type: object + properties: + payment_methods: + type: object + additionalProperties: + $ref: "#/components/schemas/BrandingItem" + required: + - payment_methods + Card: + type: object + description: Represents token details, only if the user pays with a tokenized card, Ottu will include the token details in the response. + properties: + brand: + type: + - string + - "null" + description: The card brand (e.g., Visa, Mastercard) associated with the card. Display this information for customer reference. + maxLength: 32 + customer_id: type: string - state: + description: The unique identifier for the customer who owns the card + maxLength: 64 + cvv_required: + type: boolean + description: 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_month: type: string - country: + description: The card's expiration month. Provide this information for transaction processing and validation. + maxLength: 2 + expiry_year: type: string - postal_code: + description: The card's expiration year. Provide this information for transaction processing and validation. + maxLength: 2 + is_expired: + type: boolean + description: 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_preferred: + type: boolean + readOnly: true + description: " 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_card: + type: + - string + - "null" + description: The cardholder's name as it appears on the card. Display this information for customer verification. + maxLength: 64 + number: + type: + - string + - "null" + description: The masked card number to be displayed, ensuring customer privacy and security while providing essential information. + maxLength: 19 + pg_code: + type: string + description: The `pg_code` associated with the card's creation. + pg_name: + enum: + - knet + - cybersource + - csuc + - checkoutcom + - migs + - dapi + - deema + - doku + - burgan + - paypal + - mpgs + - kpay + - enet + - omannet + - benefit + - benefit_pay + - blank + - cbk + - fss + - myfatoorah + - ngenius + - ifg + - ccavenues + - payu_india + - cod + - amazon_pay + - ottu_pg + - bookeey + - upg + - bambora + - hyperpay + - qpay + - smart_pay + - sohar + - nbo + - tabby + - tamara + - hesabe + - rajhi + - stc_pay + - stcbahrain + - urpay + - beyon_money + - upayments + - tap + - fawry + - fiserv + - geidea + - payon + - paymob + - moyasar + - abapayway + - skipcash + - taly + - tess + - ottu_sandbox + type: string + x-spec-enum-id: dffcbd9ebd1f5a1c + description: |- + The payment `gateway` associated with the user's card. + + * `knet` - Knet + * `cybersource` - CyberSource + * `csuc` - Cybersource Unified Checkout + * `checkoutcom` - checkout.com + * `migs` - MiGS + * `dapi` - Dapi + * `deema` - Deema + * `doku` - Doku + * `burgan` - Burgan + * `paypal` - PayPal + * `mpgs` - MPGS + * `kpay` - KPay + * `enet` - Enet + * `omannet` - OmanNet + * `benefit` - Benefit + * `benefit_pay` - BenefitPay + * `blank` - Blank + * `cbk` - CBK + * `fss` - FSS + * `myfatoorah` - MyFatoorah + * `ngenius` - N-Genius + * `ifg` - IATA Financial Gateway + * `ccavenues` - Ccavenues + * `payu_india` - PayU India + * `cod` - Cash + * `amazon_pay` - Amazon Pay + * `ottu_pg` - Ottu PG + * `bookeey` - Bookeey + * `upg` - UPG + * `bambora` - Bambora + * `hyperpay` - HyperPay + * `qpay` - Qpay + * `smart_pay` - SmartPay + * `sohar` - SoharInternational + * `nbo` - NBO + * `tabby` - Tabby + * `tamara` - Tamara + * `hesabe` - Hesabe + * `rajhi` - Alrajhi Bank + * `stc_pay` - STC Pay + * `stcbahrain` - STC Bahrain + * `urpay` - URPay + * `beyon_money` - BeyonMoney + * `upayments` - UPayments + * `tap` - Tap Payments + * `fawry` - Fawry + * `fiserv` - Fiserv + * `geidea` - Geidea + * `payon` - PayOn + * `paymob` - PayMob + * `moyasar` - Moyasar + * `abapayway` - ABA PayWay + * `skipcash` - Skip Cash + * `taly` - Taly + * `tess` - Tess Payments + * `ottu_sandbox` - Ottu Sandbox + token: type: string + description: The unique token associated with the card, required for tokenized card payments. Use this value to securely process transactions. + maxLength: 50 + agreements: + description: List of agreements associated with this card. required: - - city - - country - - line1 - - line2 - - postal_code - - state - DevicePayView: + - agreements + - brand + - customer_id + - cvv_required + - expiry_month + - expiry_year + - is_expired + - is_preferred + - name_on_card + - number + - pg_code + - pg_name + - token + CardAcceptanceCriteria: + type: object + properties: + min_expiry_time: + type: integer + maximum: 365 + minimum: 1 + description: |- + 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. + CardErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/GenericErrorMessage" + CashAcknowledgementErrors: oneOf: - - $ref: '#/components/schemas/DevicePayViewSuccessResponse' - - $ref: '#/components/schemas/IFrame3DSResponse' - DevicePayViewCancelResponse: + - $ref: "#/components/schemas/OperationErrorResponse" + - $ref: "#/components/schemas/FieldErrors" + CashPayment: type: object description: |- - Serializer for the response of the PayView of the payment services like - Apple Pay, Google Pay, etc. + Serializer for acknowledging cash payments. + + Inherits from BaseTxnLookupSerializer, which provides the logic for retrieving + a PaymentTransaction object based on the provided session ID. properties: - approved: - type: boolean - default: false - description: Whether the payment was approved or not. For legacy purposes - only, use `callback_payload` instead. - message: + session_id: type: string - description: Informative message. For legacy purposes only, use `callback_payload` - instead. - callback_payload: - allOf: - - $ref: '#/components/schemas/SDKCancelCallback' - description: This payload must be forwarded as is to `cancelCallback` method. + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + maxLength: 128 required: - - callback_payload - - message - DevicePayViewErrorResponse: + - session_id + ChannelNotificationErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/NotificationFailure" + ChannelNotificationResponses: + oneOf: + - $ref: "#/components/schemas/NotificationSuccess" + ChannelSpecificNotification: type: object - description: |- - Serializer for the response of the PayView of the payment services like - Apple Pay, Google Pay, etc. + description: This serializer class is solely for API documentation purposes. properties: - approved: - type: boolean - default: false - description: Whether the payment was approved or not. For legacy purposes - only, use `callback_payload` instead. - message: + template_id: type: string - description: Informative message. For legacy purposes only, use `callback_payload` - instead. - callback_payload: - allOf: - - $ref: '#/components/schemas/SDKErrorCallback' - description: This payload must be forwarded as is to `errorCallback` method. + description: This field is required. It specifies the template to be used for the notification. + to: + type: string + description: Required for all notifications. Must be a valid email address for email notifications, and a valid international phone number for SMS and WhatsApp notifications. + unit_config: + type: integer + description: This field is optional for SMS and email notifications, but it is mandatory for WhatsApp notifications. + language: + enum: + - en + - ar + type: string + x-spec-enum-id: ac1757d67890d125 + default: en + description: |- + Specifies the language for email, SMS, and WhatsApp notifications. The default language is English (en). + + * `en` - English + * `ar` - Arabic + cc: + type: array + items: + type: string + format: email + description: This field is optional. When provided, it specifies the list of CC recipients for the email notification. + bcc: + type: array + items: + type: string + format: email + description: This field is optional. When provided, it specifies the list of BCC recipients for the email notification. + subject: + type: string + description: This field is optional. Use this field to customize the email subject if you don't want to use the one from the template. + body: + type: string + description: "{'This field is optional. If provided, it serves as a fallback template in case the primary template fails to render. This has to be a plain text body of the email.'}" + context: + description: This field is optional. If provided, the context data will be passed to the template engine during rendering. + attachments: + type: array + items: + $ref: "#/components/schemas/Attachment" + description: This field is optional. Use this field to include file attachments with your email notification. Provide the file data as a base64 encoded string *or* a publicly accessible URL. + trace_id: + type: string + description: This field is optional. A unique identifier for tracking the notification request. Useful for logging and debugging. + maxLength: 60 + tags: + type: array + items: + type: string + description: This field is optional. A list of metadata tags for analytics or categorization purposes. required: - - callback_payload - - message - DevicePayViewSuccessResponse: + - template_id + - to + Checkout: type: object description: |- - Serializer for the response of the PayView of the payment services like - Apple Pay, Google Pay, etc. + Serializer to work with PaymentTransaction instances. - The responses are aligned for all payment services. + Also uses request data from other serializers to save into PaymentTransaction db table: properties: - approved: - type: boolean - default: true - description: Whether the payment was approved or not. For legacy purposes - only, use `callback_payload` instead. - message: + amount: type: string - description: Informative message. For legacy purposes only, use `callback_payload` - instead. - redirect_url: + format: decimal + description: 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 + currency_code: type: string - format: uri - description: The URL where the customer should be redirected to after the - payment. For legacy purposes only, use `callback_payload` instead. - callback_payload: - allOf: - - $ref: '#/components/schemas/SDKSuccessCallback' - description: This payload must be forwarder as is to `successCallback` method. - required: - - callback_payload - - message - DirectApplePaymentErrors: - oneOf: - - $ref: '#/components/schemas/OperationErrorResponse' - - $ref: '#/components/schemas/FieldErrors' - DirectGooglePaymentErrors: - oneOf: - - $ref: '#/components/schemas/OperationErrorResponse' - - $ref: '#/components/schemas/FieldErrors' - DirectGooglePaymentSuccess: - oneOf: - - $ref: '#/components/schemas/SchemaWebhook' - - $ref: '#/components/schemas/IFrame3DSResponse' - - $ref: '#/components/schemas/Redirect3DSResponse' - DirectPaymentResponse: - type: object - properties: - pg_params: + description: 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. + pg_codes: + type: array + items: + type: string + title: Gateway + description: The list of payment gateway codes from which a customer can select to perform the payment or authorization. + type: + enum: + - e_commerce + - payment_request + type: string + x-spec-enum-id: ad398830c7970f0a + description: |- + The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. + + * `e_commerce` - Ecommerce + * `payment_request` - Payment Request + billing_address: + $ref: "#/components/schemas/Address" + branding_options: allOf: - - $ref: '#/components/schemas/PGParams' - readOnly: true - description: "The `pg_params` field contains the details received \nfrom - the payment gateway callback these details are \nprovided to us by the - gateway after a user has completed \na payment transaction additionally, - `pg_params` \ncan include information obtained from an inquiry \nrequest - made to the payment gateway status check API. \n" + - $ref: "#/components/schemas/BrandingOptions" + writeOnly: true + description: |- + Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. + + font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" + description: |- + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. + shipping_address: + $ref: "#/components/schemas/ShippingAddress" agreement: allOf: - - $ref: '#/components/schemas/Agreement' - readOnly: true - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - amount: + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. + attachment: type: string + format: uri + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " + attachment_short_url: + type: string + format: uri readOnly: true - description: 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: - allOf: - - $ref: '#/components/schemas/AmountDetails' + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. + attachment_upload_url: + type: string + description: A writable field that accepts an attachment that has already been uploaded to the server. + pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ + billing: + type: string readOnly: true - description: 'A comprehensive set of amount details includes: Currency Code, - Amount, Total, Fee.' - capture_delivery_address: - type: boolean - description: By enabling this, you will ask for user's address. If enabled, - capture delivery coordinates should also be active. - capture_delivery_location: - type: boolean - title: Capture delivery coordinates - description: 'By enabling this, you will ask for user''s delivery location - on a map. ' + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. card_acceptance_criteria: allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' - readOnly: true + - $ref: "#/components/schemas/CardAcceptanceCriteria" description: |- 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. - currency_code: - type: string - description: 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. - maxLength: 3 - minLength: 3 - customer_address_city: - type: string - description: The city of the customer's billing address. This field may - be used to send the billing address to the payment gateway. - maxLength: 40 - customer_address_country: + checkout_page_url: type: string - description: 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. - maxLength: 2 - minLength: 2 - customer_address_line1: + format: uri + readOnly: true + description: Frontend Checkout Url. + maxLength: 2000 + checkout_short_url: type: string - title: Customer address line 1 - description: 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_line2: + format: uri + readOnly: true + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. + checkout_url: type: string - title: Customer address line 2 - description: 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. + format: uri + readOnly: true + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. customer_birthdate: - type: - - string - - 'null' - format: date - description: The customer's date of birth in ISO format (YYYY-MM-DD). - customer_address_postal_code: - type: string - description: The postal code of the customer's billing address. This field - may be used to send the billing address to the payment gateway. - maxLength: 12 - customer_address_state: type: string - description: The state or region of the customer's billing address. This - field may be used to send the billing address to the payment gateway. - maxLength: 40 + format: date + title: Customer Date of Birth + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. customer_email: type: string - description: 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. + format: email + description: 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. maxLength: 128 customer_first_name: type: string - description: 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. + description: 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. maxLength: 64 customer_id: type: string - description: 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. + description: 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. maxLength: 64 customer_last_name: type: string - description: 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. + description: 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. maxLength: 64 customer_phone: type: string - description: 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. - maxLength: 32 - extra: - description: The extra information for the payment details, which the merchant - has sent it in key value form. - fee: - type: string - description: 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. - readOnly: true - gateway_account: - type: string - readOnly: true - description: This code corresponds to the payment gateway and plays an essential - role in facilitating payment transactions. - gateway_name: - type: string - readOnly: true - description: The name of the payment gateway service being utilized. - gateway_response: - type: object - additionalProperties: {} - description: This field stores the processed response received from the - payment gateway and forwarded to Ottu. - readOnly: true - initiator: - allOf: - - $ref: '#/components/schemas/InitiatorUser' - description: 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 - is_sandbox: - type: boolean - title: Is Sandbox? - description: Indicates whether the operation was performed in a test environment - or not. - message: - type: string - readOnly: true - description: 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_no: - type: - - string - - 'null' - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - paid_amount: - oneOf: - - type: number - format: double - - type: string - description: 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. - readOnly: true - payment_type: - enum: - - one_off - - auto_debit - - save_card - type: string - x-spec-enum-id: b2ae60f7918918e7 - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - reference_number: - type: string - readOnly: true - refunded_amount: - type: number - format: double - description: The total refunded amount for the payment transaction. - remaining_amount: - type: number - format: double - description: The residual amount due. Together with the editable amount, - it indicates the outstanding balance of a transaction awaiting settlement. - readOnly: true - result: - enum: - - pending - - success - - failed - - canceled - - error - - cod - type: string - description: Indicates the outcome of the operation. `success` denotes a - successful operation. - x-spec-enum-id: 03c10fdf706d3f9a - readOnly: true - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - settled_amount: - type: number - format: double - description: The amount that has been paid or authorized in its original - currency, excluding any fees. - readOnly: true - signature: - type: string - readOnly: true - description: '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.' - state: + description: 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. + maxLength: 16 + customer_phone_2: type: string - readOnly: true - token: - allOf: - - $ref: '#/components/schemas/Card' - description: |- - Please note that if card is created via checkout save_card payment type - - It means card is created via successful operation without any funds charged. - - For more details check Checkout API `payment_type` field documentation details - transaction_log_id: - type: - - integer - - 'null' - maximum: 2147483647 - minimum: 0 - description: 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. - timestamp_utc: + title: Customer additional phone + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. + maxLength: 16 + due_datetime: type: string format: date-time - readOnly: true - description: 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. - transactions: + title: Due date and time + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. + email_recipients: type: array items: - $ref: '#/components/schemas/ChildPayment' - description: A list of dictionaries is generated, each containing a concise - summary of each child payment transaction that has been created. - voided_amount: - type: number - format: double - description: The total voided amount for the payment transaction. - required: - - agreement - - amount - - amount_details - - card_acceptance_criteria - - currency_code - - customer_address_country - - fee - - gateway_account - - gateway_name - - gateway_response - - message - - paid_amount - - pg_params - - reference_number - - remaining_amount - - result - - settled_amount - - signature - - state - - timestamp_utc - DokuSDK: - type: object - description: Serializer for Click to Pay payment flow. - properties: - code: - type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: + type: string + format: email + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. + expiration_time: type: string - description: The name of the payment method. - type: + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. + generate_qr_code: + type: boolean + writeOnly: true + default: false + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. + include_sdk_setup_preload: + type: boolean + writeOnly: true + default: false + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. + initiator_id: + type: integer + title: initiator + description: 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 + language: enum: - - e_commerce - - payment_request + - en + - ar type: string - x-spec-enum-id: ad398830c7970f0a + x-spec-enum-id: ac1757d67890d125 + default: en description: |- - The type of the payment transaction. + This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - amount: - type: string - description: The total amount to be charged, including fees. - currency_code: - type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: - type: string - description: The fee charged by the payment gateway. - fee_description: + * `en` - English + * `ar` - Arabic + notifications: + allOf: + - $ref: "#/components/schemas/Notifications" + title: Notification settings + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. + operation: type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - icon: + readOnly: true + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. + order_no: type: string - format: uri - description: The svg URL of the icon for the payment method. - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - pg_icons: + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + maxLength: 128 + payment_instrument: + $ref: "#/components/schemas/PaymentInstrument" + payment_methods: allOf: - - $ref: '#/components/schemas/MIDIcon' - description: Represents list of mid icons configured for `pgmid` settings - flow: + - $ref: "#/components/schemas/PaymentMethodsForRedirect" + readOnly: true + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. + payment_type: enum: - - doku + - one_off + - auto_debit + - save_card type: string - description: '* `doku` - Doku' - x-spec-enum-id: caab68c0e0a434b4 - default: doku - redirect_url: - type: string - format: uri - description: 'This field is used for the `ottu_pg` payment flow. When `flow` - is `ottu_pg`, the payer will be directly redirected to this URL. This - field is only present when `flow` is `ottu_pg`. For web integrations: - Use `window.location.href = redirect_url` to redirect the payer to the - specified URL. For mobile SDK integrations: Open the `redirect_url` in - the webview. Upon redirecting to the provided URL, the webview should - be closed and the transaction refreshed using the `Checkout SDK / Retrieve - init data API`. Detect the URL redirection by listening to redirects in - the webview. When a redirect occurs to a URL containing the `merchant_id` - domain, close the webview and reload the SDK after calling the `Retrieve - init data API`.' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - can_save_card: + x-spec-enum-id: b2ae60f7918918e7 + default: one_off + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 + preload_checkout_page: type: boolean - description: When true, display a checkbox in the SDK for card saving with - this payment method. When false, do not display the checkbox. - submit_url: - type: string - format: uri - description: URL that the frontend must call with POST request to get Click - to Pay configuration data for the selected payment gateway. For example, - when the user selects a gateway like DOKU or CSUC this endpoint should - be triggered to initialize the specific payment flow. The response will - contain gateway-specific configuration needed to proceed. Refer to the - 'Submit Doku' section in the documentation for more details. - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - required: - - amount - - billing - - can_save_card - - code - - currency_code - - fee - - fee_description - - icon - - icons - - name - - submit_url - - type - DokuSDKResponse: - type: object - properties: - js_sdk_src: + writeOnly: true + default: false + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). + product_type: type: string - format: uri - description: URL of doku JavaScript SDK required to initiate the payment - flow for more info please review these docshttps://developers.doku.com/accept-payment/doku-checkout/integration-guide/frontend-integration - payment_url: + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. + maxLength: 128 + qr_code_url: type: string format: uri - description: Payment URL needed to initialize doku payment iframe. - reference_number: - type: string - description: The reference number associated with the payment. - ws_url: + readOnly: true + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. + redirect_url: type: string format: uri - description: The WebSocket URL for real-time communication during callback - process. - required: - - js_sdk_src - - payment_url - - reference_number - - ws_url - ExternalOperation: - type: object - properties: - amount: - type: string + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. + maxLength: 2000 + sdk_setup_preload_payload: + allOf: + - $ref: "#/components/schemas/CheckoutSDK" readOnly: true - description: The specific amount for which the operation was performed. + default: false + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. session_id: type: string - description: The session ID of the parent transaction will be included in - the webhook payload. This session ID is crucial for associating the webhook - event with the original transaction, allowing for accurate tracking and - processing. readOnly: true - order_no: + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + settled_pg_code: type: string - description: The 'order_no' field indicates the unique order number of the - parent transaction. This identifier is crucial for tracking and managing - the related order within its entire lifecycle. readOnly: true - initiator: - allOf: - - $ref: '#/components/schemas/InitiatorUser' - description: If the operation was performed using Basic Auth (and not an - API Key), this field contains the details of the `initiator` who started - the operation. - is_sandbox: + title: Final Payment Gateway + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. + shortify_attachment_url: type: boolean - title: Is Sandbox? - description: Indicates whether the operation was performed in a test environment - or not. - operation: - enum: - - capture - - refund - - void - type: string - description: Identifies the operation that was executed. - x-spec-enum-id: 6fdf34a272fc404b - readOnly: true - pg_code: - type: string - description: Represents the `pg_code` of the Payment Gateway settings which - was used to perform the operation. - pg_response: - type: object - additionalProperties: {} - readOnly: true - description: Contains the raw response from the payment gateway (PG) for - the operation (`pg_response`). It will always be a valid JSON. - reference_number: - type: string - readOnly: true - description: A unique reference_number assigned by Ottu for the performed - operation. It's also sent to the PG and can be used as a reconciliation - parameter. - source: - enum: - - input - - pg - type: string - description: Can have one of two values - `input` or `pg`. If `input`, it - means the operation was performed in an API call triggered by the merchant. - If `pg`, it means the operation was done on the PG management dashboard, - and the PG notified Ottu via webhook. The `pg` value will always be notified - to the webhook, never in an API call. - x-spec-enum-id: 11ceda8d7147f99f - readOnly: true - success: + writeOnly: true + default: false + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. + shortify_checkout_url: type: boolean - readOnly: true - description: Indicates whether the operation was successful or not (`success=True` - or `success=False`). - result: + writeOnly: true + default: false + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. + state: enum: - - success - - failed + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod type: string - description: The result of the operation - whether it was successful or - not. - x-spec-enum-id: ce10c9ef1792a8ae + x-spec-enum-id: caee163196dbc11f readOnly: true - signature: + description: |- + The current state of the payment transaction, it helps to understand the progress of the payment. + + * `created` - Created + * `pending` - Pending + * `attempted` - Attempted + * `authorized` - Authorized + * `paid` - Paid + * `failed` - Failed + * `canceled` - Canceled + * `expired` - Expired + * `invalided` - Invalided + * `refunded` - Refunded + * `cod` - Cash on Delivery + unit_code: type: string - readOnly: true - description: '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.' - timestamp_utc: + writeOnly: true + title: Unit + description: The slug of the unit to be used for the transaction. + vendor_name: type: string - format: date-time - description: Specifies the time when the operation was performed, in the - UTC timezone. - txn: - allOf: - - $ref: '#/components/schemas/ChildPayment' - readOnly: true - description: Every operation results in the creation of a payment transaction - (`txn`), which is a child of the payment transaction against which the - operation is performed. This child transaction holds all the details of - the operation. - pg_params: - allOf: - - $ref: '#/components/schemas/PGParams' - readOnly: true - description: "The `pg_params` field contains the details received \nfrom - the payment gateway callback these details are \nprovided to us by the - gateway after a user has completed \na payment transaction additionally, - `pg_params` \ncan include information obtained from an inquiry \nrequest - made to the payment gateway status check API. \n" - extra: - description: The extra information for the payment details, which the merchant - has sent it in key value form. + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. + maxLength: 64 + webhook_url: + type: string + format: uri + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " + maxLength: 2000 required: - - amount - - operation - - order_no - - pg_params - - pg_response - - reference_number - - result - - session_id - - signature - - source - - success - - timestamp_utc - - txn - ExtraInner: + - amount + - attachment_short_url + - billing + - checkout_page_url + - checkout_short_url + - checkout_url + - currency_code + - operation + - payment_methods + - pg_codes + - qr_code_url + - sdk_setup_preload_payload + - session_id + - settled_pg_code + - state + - type + CheckoutGETResponse: type: object description: |- - Serializer for extra data aka dynamic fields. - Extra data can accept any value by default. However, - if the merchant wants to enforce a specific type, they can - use the plugins.Field class to do so. All CUSTOM fields are - validated inside extra field. - - Implementation: - - requires to have a config property in the parent - serializer which has to return a PluginConfig instance, - to which fields are attached. + Serializer to work with PaymentTransaction instances. + + Also uses request data from other serializers to save into PaymentTransaction db table: properties: - policy_type: - enum: - - fire - - liability - - excess - - marine - - '' - type: string - description: |- - * `fire` - Fire - * `liability` - Liability - * `excess` - Excess - * `marine` - Marine - x-spec-enum-id: 6ca3b5a451a7ec73 - remarks: - type: string - invoice_no: + amount: type: string - title: invoice no. - booking_reference: + format: decimal + description: 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 + currency_code: type: string - title: Internal Order ID - FieldErrors: - type: object - properties: - field_name: + description: 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. + pg_codes: type: array items: type: string - default: This field is required. - FilterField: - type: object - description: |- - Schema for individual filter field configuration. - - Each filter field represents a configurable filter that can be applied - to the transaction list. The filter type determines how the filter - should be rendered in the UI and how the query parameters should be - formatted. - properties: - key: - type: string - description: |- - The query parameter key for this filter. Use this as the parameter name when making GET requests. - - **Usage by filter type:** - - `dropdown`: Use as-is (e.g., `?state=pending`) - - `datetime`/`date`: Append `_after` or `_before` (e.g., `?created_after=2024-01-01T00:00:00Z&created_before=2024-12-31T23:59:59Z`) - - `amount_range`: Append `_min` or `_max` (e.g., `?amount_min=100&amount_max=500`) - label: - type: string - description: Human-readable label for the filter (English) - label_ar: - type: string - description: Human-readable label for the filter (Arabic) + title: Gateway + description: The list of payment gateway codes from which a customer can select to perform the payment or authorization. type: enum: - - dropdown - - datetime - - date - - amount_range + - e_commerce + - payment_request type: string - x-spec-enum-id: 284ffa996a0cdac0 + x-spec-enum-id: ad398830c7970f0a description: |- - Filter type determining the UI component and query format: - - - **dropdown**: Select from predefined options. Returns `options` array with available values. - - **datetime**: Date and time range picker. Use `{key}_after` and `{key}_before` query params with ISO 8601 format. - - **date**: Date-only range picker. Use `{key}_after` and `{key}_before` query params with YYYY-MM-DD format. - - **amount_range**: Numeric range input. Returns `min_amount` and `max_amount` bounds. Use `{key}_min` and `{key}_max` query params. - - * `dropdown` - dropdown - * `datetime` - datetime - * `date` - date - * `amount_range` - amount_range - options: - type: array - items: - $ref: '#/components/schemas/FilterOption' - description: Available options for dropdown filters. Only present when `type='dropdown'`. - Each option contains a `value` (to send as query param) and `display_name` - (for UI display). - min_amount: - type: string - format: decimal - pattern: ^-?\d{0,17}(?:\.\d{0,3})?$ - description: Minimum allowed value for amount_range filters. Only present - when `type='amount_range'`. Client should validate input is >= this value. - max_amount: - type: string - format: decimal - pattern: ^-?\d{0,17}(?:\.\d{0,3})?$ - description: Maximum allowed value for amount_range filters. Only present - when `type='amount_range'`. Client should validate input is <= this value. - required: - - key - - label - - label_ar - - type - FilterOption: - type: object - description: Schema for individual filter option in dropdown filters. - properties: - value: - type: string - description: The value to pass as the filter parameter - display_name: - type: string - description: Human-readable label for the option - display_name_en: - type: string - description: English label (for multilingual options like unit) - display_name_ar: - type: string - description: Arabic label (for multilingual options like unit) - required: - - display_name - - value - FlexMethods: - oneOf: - - $ref: '#/components/schemas/BNPLPaymentSDK' - - $ref: '#/components/schemas/DokuSDK' - - $ref: '#/components/schemas/CSUCSDK' - - $ref: '#/components/schemas/ABAPayWaySDK' - FormConfig: - type: object - description: Configuration for the payment form that submits the transient token. - properties: - action: + The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. + + * `e_commerce` - Ecommerce + * `payment_request` - Payment Request + billing_address: + $ref: "#/components/schemas/Address" + branding_options: + allOf: + - $ref: "#/components/schemas/BrandingOptions" + writeOnly: true + description: |- + Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. + + font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" + description: |- + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. + shipping_address: + $ref: "#/components/schemas/ShippingAddress" + agreement: + allOf: + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. + attachment: type: string format: uri - description: 'Form submission URL where the transient token will be posted. - This points to the payment execution endpoint for this session. Example: - https://example.com/checkout/api/sdk/v1/csuc_sdk/pay/{session_id}/{pg_code}/' - method: - type: string - description: HTTP method for form submission. Always 'POST' for payment - processing. - form_id: - type: string - description: Recommended HTML form ID attribute for the payment form. Useful - for frontend JavaScript to target the correct form element. - required: - - action - - form_id - - method - GeideaSDKResponse: - type: object - properties: - session_id: - type: string - description: The Geidea checkout session ID returned from create session - API. - sdk_url: + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " + attachment_short_url: type: string format: uri - description: URL of Geidea JavaScript SDK required to initiate the payment - flow. - merchant_public_key: + readOnly: true + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. + attachment_upload_url: type: string - description: The merchant public key (merchant ID) for SDK initialization. - environment: - enum: - - test - - prod + description: A writable field that accepts an attachment that has already been uploaded to the server. + pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ + billing: type: string - x-spec-enum-id: 62f4ef67396c3252 + readOnly: true + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. + card_acceptance_criteria: + allOf: + - $ref: "#/components/schemas/CardAcceptanceCriteria" description: |- - The environment mode: 'test' for sandbox or 'prod' for production. + 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. - * `test` - test - * `prod` - prod - language: + **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. + checkout_page_url: type: string - description: The language code for the checkout UI (e.g., 'en', 'ar'). - reference_number: + format: uri + readOnly: true + description: Frontend Checkout Url. + maxLength: 2000 + checkout_short_url: type: string - description: The reference number associated with the payment. - required: - - environment - - language - - merchant_public_key - - reference_number - - sdk_url - - session_id - GeideaSubmitFailureResponse: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - GeideaSubmitSuccessResponse: - oneOf: - - $ref: '#/components/schemas/GeideaSDKResponse' - GenericErrorMessage: - type: object - properties: - detail: + format: uri + readOnly: true + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. + checkout_url: type: string - required: - - detail - GooglePay: - type: object - description: Base serializer for payment configuration, to be used in SDK clients - like web and mobile. - properties: - code: + format: uri + readOnly: true + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. + customer_birthdate: type: string - description: The payment service code. - pattern: ^[-a-zA-Z0-9_]+$ - environment: - enum: - - TEST - - PRODUCTION + format: date + title: Customer Date of Birth + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. + customer_email: type: string - x-spec-enum-id: e84d62d46874224c - description: |- - This field specifies the environment to use for the payment, either 'TEST' or 'PRODUCTION'. In the TEST environment, transactions are not processed and can be used to test the integration. In the PRODUCTION environment, transactions are processed and real money is involved - - * `TEST` - TEST - * `PRODUCTION` - PRODUCTION - gateway: - type: - - string - - 'null' - description: This field specifies the name of the payment gateway to use. - Payment gateways are third-party services that facilitate payment transactions - between merchants and customers. If this field is not provided, the default - payment gateway configured on the backend will be used. - maxLength: 24 - gateway_merchant_id: - type: string - description: This field specifies the merchant ID for the payment gateway. - This ID is used by the payment gateway to identify the merchant and route - the payment transaction to the correct account. If you are unsure what - value to use for this field, please consult the documentation provided - by your payment gateway provider. - maxLength: 256 - merchant_id: - type: string - description: This field specifies the ID of the merchant accepting the payment. - This ID is used by Google Pay to identify the merchant and associate the - payment transaction with the correct merchant account. - maxLength: 100 - merchant_name: - type: string - description: This field specifies the name of the merchant accepting the - payment. This name will be displayed to the user during the payment process - and on their payment confirmation - maxLength: 25 - total_price: - type: string - description: This field specifies the total price for the payment, including - any fees. The price should be formatted as a string with the decimal point - as a period, e.g. '10.99'. - maxLength: 20 - currency_code: + format: email + description: 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. + maxLength: 128 + customer_first_name: + type: string + description: 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. + maxLength: 64 + customer_id: type: string - description: This field specifies the ISO 4217 currency code for the payment. - This code is used to specify the currency of the payment transaction. - If you are unsure what value to use for this field, please consult the - documentation provided by your payment gateway provider. - maxLength: 10 - country_code: + description: 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. + maxLength: 64 + customer_last_name: type: string - description: This field specifies the ISO 3166-1 alpha-2 country code for - the payment currency. This code is used to specify the country of the - payment transaction. If you are unsure what value to use for this field, - please consult the documentation provided by your payment gateway provider. - maxLength: 2 - fee: + description: 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. + maxLength: 64 + customer_phone: type: string - description: The fee for the payment. - maxLength: 20 - fee_description: + description: 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. + maxLength: 16 + customer_phone_2: type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - maxLength: 128 - payment_url: + title: Customer additional phone + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. + maxLength: 16 + due_datetime: type: string - format: uri - description: The URL to use for submitting the payment. - flow: + format: date-time + title: Due date and time + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. + email_recipients: + type: array + items: + type: string + format: email + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. + expiration_time: + type: string + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. + generate_qr_code: + type: boolean + writeOnly: true + default: false + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. + include_sdk_setup_preload: + type: boolean + writeOnly: true + default: false + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. + initiator_id: + type: integer + title: initiator + description: 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 + language: enum: - - google_pay + - en + - ar type: string - x-spec-enum-id: 914df0a2f2bada0b + x-spec-enum-id: ac1757d67890d125 + default: en description: |- - Using the payment_url, you can proceed for submitting the paymentOnce the payment session is validatedthis URL is used to initiate the actual payment process. + This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - * `google_pay` - GooglePay - billing: + * `en` - English + * `ar` - Arabic + notifications: allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - required: - - billing - - code - - country_code - - currency_code - - environment - - fee - - fee_description - - flow - - gateway - - gateway_merchant_id - - merchant_id - - merchant_name - - payment_url - - total_price - GooglePayDirectPayment: - type: object - properties: - payload: - $ref: '#/components/schemas/GooglePayPaymentData' - pg_code: - type: - - string - - 'null' - description: The unique pg_code used for this payment instrument. - session_id: - type: string - description: A unique identifier for the payment transaction (session). - required: - - payload - - session_id - GooglePayInfoSchema: - type: object - description: Google Pay card information - properties: - cardNetwork: + - $ref: "#/components/schemas/Notifications" + title: Notification settings + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. + operation: type: string - description: Card network (e.g., 'VISA') - cardDetails: + readOnly: true + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. + order_no: type: string - description: Last 4 digits of card - required: - - cardDetails - - cardNetwork - GooglePayInstrument: - type: object - description: Google Pay payment instrument - properties: - instrument_type: + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + maxLength: 128 + payment_instrument: + $ref: "#/components/schemas/PaymentInstrument" + payment_methods: + allOf: + - $ref: "#/components/schemas/PaymentMethodsForRedirect" + readOnly: true + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. + payment_type: enum: - - google_pay + - one_off + - auto_debit + - save_card type: string - x-spec-enum-id: 394f64ef0358d4b7 - default: google_pay + x-spec-enum-id: b2ae60f7918918e7 + default: one_off description: |- - Payment type: Google Pay + 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. - * `google_pay` - google_pay - payload: - allOf: - - $ref: '#/components/schemas/GooglePayPayloadSchema' - description: Google Pay payment data received from Google Pay SDK. Pass - the complete paymentData object exactly as received without modification. - Includes apiVersion, paymentMethodData with tokenization data. - required: - - payload - GooglePayPayRejectedResponse: - oneOf: - - $ref: '#/components/schemas/DevicePayViewCancelResponse' - - $ref: '#/components/schemas/DevicePayViewErrorResponse' - GooglePayPayloadSchema: - type: object - description: Complete Google Pay payment data structure - properties: - apiVersion: - type: integer - description: Google Pay API version (e.g., 2) - apiVersionMinor: - type: integer - description: API minor version (e.g., 0) - paymentMethodData: - allOf: - - $ref: '#/components/schemas/GooglePayPaymentMethodDataSchema' - description: Payment method and tokenization data - required: - - apiVersion - - apiVersionMinor - - paymentMethodData - GooglePayPaymentData: - type: object - description: |- - Serializer for Google Pay payment, which is used to validate - the payment data sent from the SDK client. + Choose `save_card` if you want to perform a card tokenization operation. - OrderSerializer must be added also in the mixin classes - for minimal amount validation + NOTE: If `auto_debit` is selected: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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. - This deserialize the data sent from the SDK client, namely the - paymentData https://developers.google.com/pay/api/web/reference/response-objects#PaymentData + NOTE: If `save_card` is selected: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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. - { - "apiVersion": 2, - "apiVersionMinor": 0, - "paymentMethodData": { - "type": "CARD", - "description": "Visa 1234", - "info": { - "cardNetwork": "VISA", - "cardDetails": "1234", - "billingAddress": { - "name": "John Smith", - "phoneNumber": "+16505551234", - "postalAddress": { - "addressLines": ["1234 Main Street"], - "locality": "Mountain View", - "administrativeArea": "CA", - "postalCode": "94043", - "countryCode": "US", - }, - }, - }, - "tokenizationData": { - "type": "PAYMENT_GATEWAY", - "token": "dummy_payment_token", - }, - }, - "email": "customer@example.com", - "shippingAddress": { - "name": "John Smith", - "phoneNumber": "+16505551234", - "postalAddress": { - "addressLines": ["1234 Main Street"], - "locality": "Mountain View", - "administrativeArea": "CA", - "postalCode": "94043", - "countryCode": "US", - }, - }, - } - properties: - apiVersion: - type: integer - description: The version of the Google Pay API used to process the payment. - apiVersionMinor: - type: integer - description: The minor version of the Google Pay API used to process the - payment. - paymentMethodData: - allOf: - - $ref: '#/components/schemas/PaymentMethodData' - description: The payment method data. - email: + * `one_off` - One Off + * `auto_debit` - Auto Debit + * `save_card` - Save Card + preload_checkout_page: + type: boolean + writeOnly: true + default: false + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). + product_type: type: string - format: email - description: The email address of the customer. - shippingAddress: - type: object - additionalProperties: {} - description: The shipping address of the customer. - required: - - apiVersion - - apiVersionMinor - - paymentMethodData - GooglePayPaymentMethodDataSchema: - type: object - description: Google Pay payment method data - properties: - type: + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. + maxLength: 128 + qr_code_url: type: string - description: Payment method type (e.g., 'CARD') - description: + format: uri + readOnly: true + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. + redirect_url: type: string - description: Payment method description - info: - allOf: - - $ref: '#/components/schemas/GooglePayInfoSchema' - description: Card information - tokenizationData: + format: uri + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. + maxLength: 2000 + sdk_setup_preload_payload: allOf: - - $ref: '#/components/schemas/GooglePayTokenizationDataSchema' - description: Tokenization data with encrypted token - required: - - description - - info - - tokenizationData - - type - GooglePayTokenizationDataSchema: - type: object - description: Google Pay tokenization data - properties: - type: + - $ref: "#/components/schemas/CheckoutSDK" + readOnly: true + default: false + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. + session_id: type: string - description: Tokenization type (e.g., 'PAYMENT_GATEWAY') - token: + readOnly: true + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + settled_pg_code: type: string - description: Encrypted payment token - required: - - token - - type - Header: - type: object - properties: - ephemeralPublicKey: + readOnly: true + title: Final Payment Gateway + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. + shortify_attachment_url: + type: boolean + writeOnly: true + default: false + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. + shortify_checkout_url: + type: boolean + writeOnly: true + default: false + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. + state: + enum: + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod type: string - wrappedKey: + x-spec-enum-id: caee163196dbc11f + readOnly: true + description: |- + The current state of the payment transaction, it helps to understand the progress of the payment. + + * `created` - Created + * `pending` - Pending + * `attempted` - Attempted + * `authorized` - Authorized + * `paid` - Paid + * `failed` - Failed + * `canceled` - Canceled + * `expired` - Expired + * `invalided` - Invalided + * `refunded` - Refunded + * `cod` - Cash on Delivery + unit_code: type: string - publicKeyHash: + writeOnly: true + title: Unit + description: The slug of the unit to be used for the transaction. + vendor_name: type: string - transactionId: + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. + maxLength: 64 + webhook_url: type: string + format: uri + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " + maxLength: 2000 required: - - publicKeyHash - - transactionId - IATARecord: + - amount + - attachment_short_url + - billing + - checkout_page_url + - checkout_short_url + - checkout_url + - currency_code + - operation + - payment_methods + - pg_codes + - qr_code_url + - sdk_setup_preload_payload + - session_id + - settled_pg_code + - state + - type + CheckoutPATCHResponse: type: object + description: |- + Serializer to work with PaymentTransaction instances. + + Also uses request data from other serializers to save into PaymentTransaction db table: properties: - id: - type: integer - readOnly: true + amount: + type: string + format: decimal + description: 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 + currency_code: + type: string + description: 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. + pg_codes: + type: array + items: + type: string + title: Gateway + description: The list of payment gateway codes from which a customer can select to perform the payment or authorization. type: enum: - - token - - order - - auth_cancel - - order_cancel - - order_exchange - - order_refund - - ticket - - exchanged_ticket - - tdnr_status - - get_auth - - agent_lookup - - check_status - - payment_authorize + - e_commerce + - payment_request type: string + x-spec-enum-id: ad398830c7970f0a description: |- - * `token` - token - * `order` - order - * `auth_cancel` - auth_cancel - * `order_cancel` - order_cancel - * `order_exchange` - order_exchange - * `order_refund` - order_refund - * `ticket` - ticket - * `exchanged_ticket` - exchanged_ticket - * `tdnr_status` - tdnr_status - * `get_auth` - get_auth - * `agent_lookup` - agent_lookup - * `check_status` - check_status - * `payment_authorize` - payment_authorize - x-spec-enum-id: 7cdec242e8189509 - request_data: - type: object - additionalProperties: {} - response_data: - type: object - additionalProperties: {} - error: - type: - - string - - 'null' - maxLength: 127 - created: - type: string - format: date-time - readOnly: true - modified: + The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. + + * `e_commerce` - Ecommerce + * `payment_request` - Payment Request + billing_address: + $ref: "#/components/schemas/Address" + branding_options: + allOf: + - $ref: "#/components/schemas/BrandingOptions" + writeOnly: true + description: |- + Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. + + font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" + description: |- + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. + shipping_address: + $ref: "#/components/schemas/ShippingAddress" + agreement: + allOf: + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. + attachment: type: string - format: date-time - readOnly: true - required: - - created - - id - - modified - - request_data - - response_data - - type - IFrame3DSResponse: - type: object - properties: - status: + format: uri + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " + attachment_short_url: type: string + format: uri readOnly: true - default: 3DS - description: The payment is in 3DSecure process. Indicates a 3D Secure verification - is required. html must be displayed to the customer in the iframe. - reference_number: + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. + attachment_upload_url: type: string - readOnly: true - description: This is a unique value associated with each payment transaction - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). allowing for multiple reference - numbers per session_id. - form_of_payment: - enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + description: A writable field that accepts an attachment that has already been uploaded to the server. + pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ + billing: type: string - x-spec-enum-id: d21d329ca6d31930 readOnly: true + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. + card_acceptance_criteria: + allOf: + - $ref: "#/components/schemas/CardAcceptanceCriteria" description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + 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. - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean - default: true - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - method: - type: string - readOnly: true - default: iframe - description: The method of 3D Secure verification. - html: - type: string - readOnly: true - description: The HTML code to be displayed in the iframe. - ws_url: + **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. + checkout_page_url: type: string format: uri readOnly: true - description: The WebSocket URL for real-time communication during the 3D - Secure process. - required: - - form_of_payment - - html - - method - - reference_number - - status - - ws_url - Icons: - type: object - properties: - webp: + description: Frontend Checkout Url. + maxLength: 2000 + checkout_short_url: type: string format: uri - description: The webp URL of the icon for the payment method. - svg: + readOnly: true + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. + checkout_url: type: string format: uri - description: The svg URL of the icon for the payment method. - required: - - svg - - webp - Initiator: - type: object - properties: - id: - type: integer readOnly: true - username: + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. + customer_birthdate: type: string - description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ - only. - pattern: ^[\w.@+-]+$ - maxLength: 150 - email: + format: date + title: Customer Date of Birth + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. + customer_email: type: string format: email - title: Email address - maxLength: 254 - phone: - type: string - title: Phone number + description: 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. maxLength: 128 - required: - - email - - id - - username - InitiatorUser: - type: object - properties: - id: - type: integer - readOnly: true - first_name: + customer_first_name: type: string - maxLength: 32 - last_name: + description: 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. + maxLength: 64 + customer_id: type: string - maxLength: 32 - username: + description: 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. + maxLength: 64 + customer_last_name: type: string - description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ - only. - pattern: ^[\w.@+-]+$ - maxLength: 150 - email: + description: 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. + maxLength: 64 + customer_phone: type: string - format: email - title: Email address - maxLength: 254 - phone: + description: 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. + maxLength: 16 + customer_phone_2: type: string - title: Phone number - maxLength: 128 - required: - - email - - id - - username - Inquiry: - type: object - description: This serializer is used to validate the lookup fields for the inquiry - operation. - properties: - order_no: + title: Customer additional phone + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. + maxLength: 16 + due_datetime: type: string - description: This is an optional identifier used to specify the payment - transaction upon which the operation should be performed. You can use - either the `order_no` or `session_id` field; at least one of these two - identifiers must be provided to select the payment transaction that should - be actioned. - maxLength: 128 - session_id: + format: date-time + title: Due date and time + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. + email_recipients: + type: array + items: + type: string + format: email + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. + expiration_time: type: string - description: Similar to `order_no`, `session_id` is an optional identifier - used to specify the payment transaction for the operation. You must provide - either `order_no` or `session_id` in order to select the appropriate payment - transaction. - maxLength: 128 - notify_webhook_url: + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. + generate_qr_code: type: boolean + writeOnly: true default: false - description: A boolean value indicating whether or not to notify the webhook_url - about the status of the payment. When set to true, the system will send - a notification to the webhook_url specified during the creation of the - payment via the Checkout API. This is particularly useful for merchants - who have an acknowledgement mechanism in place and want to trigger it - to confirm the payment/order on their system. - webhook_url: - type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 200 - InquiryErrors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/InquiryFailure' - InquiryFailure: - type: object - properties: - detail: - type: string - description: Provides a message associated with the operation, suitable - for displaying to the end user. - result: - enum: - - failed - type: string - description: '* `failed` - Failed' - x-spec-enum-id: 8b493f06ef915a3f - required: - - detail - - result - InternalOperation: - type: object - properties: - detail: - type: string - description: Provides a message associated with the operation, suitable - for displaying to the end user. - operation: - enum: - - refund - - void - - capture - - delete - - cancel - - expire - type: string - x-spec-enum-id: ba0e384393b3f117 - description: |- - Specifies the executed operation. It can be either `delete`, `cancel`, or `expire`. - - * `refund` - Refund - * `void` - Void - * `capture` - Capture - * `delete` - Delete - * `cancel` - Cancel - * `expire` - Expire - result: + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. + include_sdk_setup_preload: + type: boolean + writeOnly: true + default: false + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. + initiator_id: + type: integer + title: initiator + description: 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 + language: enum: - - success - - failed + - en + - ar type: string - x-spec-enum-id: 74cb1d0c38c4dfc9 + x-spec-enum-id: ac1757d67890d125 + default: en description: |- - Indicates the outcome of the operation. `success` denotes a successful operation. - - * `success` - Success - * `failed` - Failed - required: - - detail - - operation - - result - InvoiceClientErrors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/NestedFieldErrors' - - $ref: '#/components/schemas/GenericErrorMessage' - InvoiceItem: - type: object - description: |- - Serializer to use for `InvoiceItem` instances. - - The unit_price, quantity, description and sku fields are required. - The rest are optional. + This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - The class includes a method to calculate the discount on the invoice and another to calculate the total values. - properties: - id: - type: integer + * `en` - English + * `ar` - Arabic + notifications: + allOf: + - $ref: "#/components/schemas/Notifications" + title: Notification settings + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. + operation: + type: string readOnly: true - invoice: - type: - - integer - - 'null' - description: Associated invoice. - sku: + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. + order_no: type: string - description: Unique identifier for the invoice item. - maxLength: 255 - description: + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + maxLength: 128 + payment_instrument: + $ref: "#/components/schemas/PaymentInstrument" + payment_methods: + allOf: + - $ref: "#/components/schemas/PaymentMethodsForRedirect" + readOnly: true + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. + payment_type: + enum: + - one_off + - auto_debit + - save_card type: string - description: Product name or a brief description of the item. - maxLength: 255 - quantity: + x-spec-enum-id: b2ae60f7918918e7 + default: one_off + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 + preload_checkout_page: + type: boolean + writeOnly: true + default: false + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). + product_type: type: string - format: decimal - description: Number of units of the product. - unit_price: + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. + maxLength: 128 + qr_code_url: type: string - format: decimal - description: Price per unit of the product, excluding tax. - tax_rate: + format: uri + readOnly: true + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. + redirect_url: type: string - format: decimal - description: Tax rate applied to the invoice item. - tax_amount: + format: uri + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. + maxLength: 2000 + sdk_setup_preload_payload: + allOf: + - $ref: "#/components/schemas/CheckoutSDK" + readOnly: true + default: false + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. + session_id: type: string - format: decimal - description: Total tax amount for the invoice item. - discount_percentage: + readOnly: true + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + settled_pg_code: type: string - format: decimal - description: Percentage-based discount applied to the invoice item. The - calculated discount cannot exceed theitem's total value, including tax. - discount_amount: + readOnly: true + title: Final Payment Gateway + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. + shortify_attachment_url: + type: boolean + writeOnly: true + default: false + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. + shortify_checkout_url: + type: boolean + writeOnly: true + default: false + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. + state: + enum: + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod type: string - format: decimal - description: Fixed amount discount applied to the invoice item. The discount - cannot exceed the item's total value, including tax. - total_excl_tax: + x-spec-enum-id: caee163196dbc11f + readOnly: true + description: |- + The current state of the payment transaction, it helps to understand the progress of the payment. + + * `created` - Created + * `pending` - Pending + * `attempted` - Attempted + * `authorized` - Authorized + * `paid` - Paid + * `failed` - Failed + * `canceled` - Canceled + * `expired` - Expired + * `invalided` - Invalided + * `refunded` - Refunded + * `cod` - Cash on Delivery + unit_code: type: string - format: decimal - description: Total value of the invoice item, excluding tax. This is calculated - as (unit_price * quantity) - discount. - total_incl_tax: + writeOnly: true + title: Unit + description: The slug of the unit to be used for the transaction. + vendor_name: type: string - format: decimal - description: Total value of the invoice item, including tax. This is calculated - as (unit_price * quantity) - discount + applicable tax. - currency_code: + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. + maxLength: 64 + webhook_url: type: string - description: 'For internal purposes: it''ll be overridden by the main currency_code' + format: uri + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " + maxLength: 2000 required: - - currency_code - - description - - id - - quantity - - sku - - unit_price - InvoicePOSTRequest: + - amount + - attachment_short_url + - billing + - checkout_page_url + - checkout_short_url + - checkout_url + - currency_code + - operation + - payment_methods + - pg_codes + - qr_code_url + - sdk_setup_preload_payload + - session_id + - settled_pg_code + - state + - type + CheckoutPOSTRequest: type: object description: |- - Serializer class for `Invoice` instances, inheriting from `BaseInvoiceSerializer` and - `CheckoutSerializer`. It provides methods for creating invoices, invoice items, and transactions. + Serializer to work with PaymentTransaction instances. + + Also uses request data from other serializers to save into PaymentTransaction db table: properties: - currency_code: - type: string - description: 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. - due_date: + amount: type: string - format: date - description: The date by which the customer is expected to make payment - for the invoice. - invoice_items: - type: array - items: - $ref: '#/components/schemas/InvoiceItem' - description: The list of items for the invoice. - invoice_number: + format: decimal + description: 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 + currency_code: type: string - description: A unique identifier for the invoice, typically used for tracking - and referencing purposes. - maxLength: 255 + description: 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. pg_codes: type: array items: type: string title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment + description: The list of payment gateway codes from which a customer can select to perform the payment or authorization. type: enum: - - e_commerce - - payment_request + - e_commerce + - payment_request type: string x-spec-enum-id: ad398830c7970f0a description: |- @@ -12246,68 +4359,59 @@ components: * `e_commerce` - Ecommerce * `payment_request` - Payment Request billing_address: - $ref: '#/components/schemas/Address' + $ref: "#/components/schemas/Address" branding_options: allOf: - - $ref: '#/components/schemas/BrandingOptions' + - $ref: "#/components/schemas/BrandingOptions" writeOnly: true description: |- Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" + description: |- + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. shipping_address: - $ref: '#/components/schemas/ShippingAddress' + $ref: "#/components/schemas/ShippingAddress" agreement: allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - amount: - type: string - format: decimal - description: 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 + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. attachment: type: string format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " attachment_short_url: type: string format: uri readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. attachment_upload_url: type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. + description: A writable field that accepts an attachment that has already been uploaded to the server. pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ billing: type: string readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. card_acceptance_criteria: allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' + - $ref: "#/components/schemas/CardAcceptanceCriteria" description: |- 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. @@ -12324,145 +4428,75 @@ components: type: string format: uri readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. checkout_url: type: string format: uri readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. - company_name: - type: string - description: The company name is used for invoice API. - maxLength: 64 + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. customer_birthdate: type: string format: date title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. customer_email: type: string format: email - description: 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. + description: 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. maxLength: 128 customer_first_name: type: string - description: 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. + description: 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. maxLength: 64 customer_id: type: string - description: 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. + description: 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. maxLength: 64 customer_last_name: type: string - description: 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. + description: 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. maxLength: 64 customer_phone: type: string - description: 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. + description: 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. maxLength: 16 customer_phone_2: type: string title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. maxLength: 16 - discount_amount: - type: string - format: decimal - description: The fixed amount discount applied to the full invoice amount, - including taxes. If set, the discount_percentage field will be set to - null. Both discount_amount and discount_percentage cannot be set simultaneously. - The discount cannot be higher than the `total_excl_tax` field. - discount_percentage: - type: string - format: decimal - description: The percentage-based discount applied to the full invoice amount, - including taxes. If set, the discount_amount field will be automatically - calculated. Both discount_amount and discount_percentage cannot be set - simultaneously. The discount cannot be higher than the `total_excl_tax` - field. due_datetime: type: string format: date-time title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. email_recipients: type: array items: type: string format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. expiration_time: type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. generate_qr_code: type: boolean writeOnly: true default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. include_sdk_setup_preload: type: boolean writeOnly: true default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. initiator_id: type: integer title: initiator - description: 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 - invoice_id: - type: integer - readOnly: true + description: 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 language: enum: - - en - - ar + - en + - ar type: string x-spec-enum-id: ac1757d67890d125 default: en @@ -12473,165 +4507,109 @@ components: * `ar` - Arabic notifications: allOf: - - $ref: '#/components/schemas/Notifications' + - $ref: "#/components/schemas/Notifications" title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. operation: type: string readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. order_no: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. maxLength: 128 payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' + $ref: "#/components/schemas/PaymentInstrument" payment_methods: allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' + - $ref: "#/components/schemas/PaymentMethodsForRedirect" readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. payment_type: enum: - - one_off - - auto_debit - - save_card + - one_off + - auto_debit + - save_card type: string x-spec-enum-id: b2ae60f7918918e7 default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 preload_checkout_page: type: boolean writeOnly: true default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). product_type: type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. maxLength: 128 qr_code_url: type: string format: uri readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. redirect_url: type: string format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. maxLength: 2000 sdk_setup_preload_payload: allOf: - - $ref: '#/components/schemas/CheckoutSDK' + - $ref: "#/components/schemas/CheckoutSDK" readOnly: true default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. session_id: type: string readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. settled_pg_code: type: string readOnly: true title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. - shipping_excl_tax: - type: string - format: decimal - title: Shipping Excl. Tax - description: The cost of shipping for the invoice, excluding taxes. - shipping_incl_tax: - type: string - format: decimal - title: Shipping Incl. Tax - description: The cost of shipping for the invoice, including all applicable - taxes. - shipping_method: - type: string - description: The method or service used for shipping the items associated - with the invoice. - shipping_tax_rate: - type: string - format: decimal - description: 'The tax rate applied to the shipping cost, expressed as a - percentage. ' + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. shortify_attachment_url: type: boolean writeOnly: true default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. shortify_checkout_url: type: boolean writeOnly: true default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. state: enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod type: string x-spec-enum-id: caee163196dbc11f readOnly: true @@ -12649,45 +4627,6 @@ components: * `invalided` - Invalided * `refunded` - Refunded * `cod` - Cash on Delivery - status: - enum: - - sent - - paid - - overdue - - canceled - type: string - x-spec-enum-id: c131c51a82b6f22a - readOnly: true - description: |- - Current status of the invoice. Can be one of the following: `sent`, `paid`, `overdue`, `canceled`. - - * `sent` - Sent - * `paid` - Paid - * `overdue` - Overdue - * `canceled` - Canceled - subtotal: - type: string - format: decimal - description: Sum of total_incl_tax's of all invoice items. - tax_amount: - type: string - format: decimal - description: The total amount of tax applied to the invoice. - tax_rate: - type: string - format: decimal - title: Tax - description: The tax rate applied to the invoice, expressed as a percentage. - total_excl_tax: - type: string - format: decimal - title: Total Excl. Tax - description: The total amount of the invoice, excluding taxes. - total_incl_tax: - type: string - format: decimal - title: Total Incl. Tax - description: The total amount of the invoice, including all applicable taxes. unit_code: type: string writeOnly: true @@ -12695,75 +4634,54 @@ components: description: The slug of the unit to be used for the transaction. vendor_name: type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. maxLength: 64 webhook_url: type: string format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " maxLength: 2000 required: - - attachment_short_url - - billing - - checkout_page_url - - checkout_short_url - - checkout_url - - currency_code - - due_date - - invoice_id - - invoice_items - - invoice_number - - operation - - payment_methods - - pg_codes - - qr_code_url - - sdk_setup_preload_payload - - session_id - - settled_pg_code - - state - - status - - type - InvoicePOSTResponse: + - amount + - attachment_short_url + - billing + - checkout_page_url + - checkout_short_url + - checkout_url + - currency_code + - operation + - payment_methods + - pg_codes + - qr_code_url + - sdk_setup_preload_payload + - session_id + - settled_pg_code + - state + - type + CheckoutPOSTResponse: type: object description: |- - Serializer class for `Invoice` instances, inheriting from `BaseInvoiceSerializer` and - `CheckoutSerializer`. It provides methods for creating invoices, invoice items, and transactions. + Serializer to work with PaymentTransaction instances. + + Also uses request data from other serializers to save into PaymentTransaction db table: properties: - currency_code: - type: string - description: 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. - due_date: + amount: type: string - format: date - description: The date by which the customer is expected to make payment - for the invoice. - invoice_items: - type: array - items: - $ref: '#/components/schemas/InvoiceItem' - description: The list of items for the invoice. - invoice_number: + format: decimal + description: 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 + currency_code: type: string - description: A unique identifier for the invoice, typically used for tracking - and referencing purposes. - maxLength: 255 + description: 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. pg_codes: type: array items: type: string title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment + description: The list of payment gateway codes from which a customer can select to perform the payment or authorization. type: enum: - - e_commerce - - payment_request + - e_commerce + - payment_request type: string x-spec-enum-id: ad398830c7970f0a description: |- @@ -12772,68 +4690,59 @@ components: * `e_commerce` - Ecommerce * `payment_request` - Payment Request billing_address: - $ref: '#/components/schemas/Address' + $ref: "#/components/schemas/Address" branding_options: allOf: - - $ref: '#/components/schemas/BrandingOptions' + - $ref: "#/components/schemas/BrandingOptions" writeOnly: true description: |- Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" + description: |- + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. shipping_address: - $ref: '#/components/schemas/ShippingAddress' + $ref: "#/components/schemas/ShippingAddress" agreement: allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - amount: - type: string - format: decimal - description: 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 + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. attachment: type: string format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " attachment_short_url: type: string format: uri readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. attachment_upload_url: type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. + description: A writable field that accepts an attachment that has already been uploaded to the server. pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ billing: type: string readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. card_acceptance_criteria: allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' + - $ref: "#/components/schemas/CardAcceptanceCriteria" description: |- 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. @@ -12850,145 +4759,75 @@ components: type: string format: uri readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. checkout_url: type: string - format: uri - readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. - company_name: - type: string - description: The company name is used for invoice API. - maxLength: 64 + format: uri + readOnly: true + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. customer_birthdate: type: string format: date title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. customer_email: type: string format: email - description: 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. + description: 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. maxLength: 128 customer_first_name: type: string - description: 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. + description: 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. maxLength: 64 customer_id: type: string - description: 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. + description: 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. maxLength: 64 customer_last_name: type: string - description: 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. + description: 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. maxLength: 64 customer_phone: type: string - description: 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. + description: 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. maxLength: 16 customer_phone_2: type: string title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. maxLength: 16 - discount_amount: - type: string - format: decimal - description: The fixed amount discount applied to the full invoice amount, - including taxes. If set, the discount_percentage field will be set to - null. Both discount_amount and discount_percentage cannot be set simultaneously. - The discount cannot be higher than the `total_excl_tax` field. - discount_percentage: - type: string - format: decimal - description: The percentage-based discount applied to the full invoice amount, - including taxes. If set, the discount_amount field will be automatically - calculated. Both discount_amount and discount_percentage cannot be set - simultaneously. The discount cannot be higher than the `total_excl_tax` - field. due_datetime: type: string format: date-time title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. email_recipients: type: array items: type: string format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. expiration_time: type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. generate_qr_code: type: boolean writeOnly: true default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. include_sdk_setup_preload: type: boolean writeOnly: true default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. initiator_id: type: integer title: initiator - description: 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 - invoice_id: - type: integer - readOnly: true + description: 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 language: enum: - - en - - ar + - en + - ar type: string x-spec-enum-id: ac1757d67890d125 default: en @@ -12999,165 +4838,109 @@ components: * `ar` - Arabic notifications: allOf: - - $ref: '#/components/schemas/Notifications' + - $ref: "#/components/schemas/Notifications" title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. operation: type: string readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. order_no: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. maxLength: 128 payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' + $ref: "#/components/schemas/PaymentInstrument" payment_methods: allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' + - $ref: "#/components/schemas/PaymentMethodsForRedirect" readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. payment_type: enum: - - one_off - - auto_debit - - save_card + - one_off + - auto_debit + - save_card type: string x-spec-enum-id: b2ae60f7918918e7 default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 preload_checkout_page: type: boolean writeOnly: true default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). product_type: type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. maxLength: 128 qr_code_url: type: string format: uri readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. redirect_url: type: string format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. maxLength: 2000 sdk_setup_preload_payload: allOf: - - $ref: '#/components/schemas/CheckoutSDK' + - $ref: "#/components/schemas/CheckoutSDK" readOnly: true default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. session_id: type: string readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. settled_pg_code: type: string readOnly: true title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. - shipping_excl_tax: - type: string - format: decimal - title: Shipping Excl. Tax - description: The cost of shipping for the invoice, excluding taxes. - shipping_incl_tax: - type: string - format: decimal - title: Shipping Incl. Tax - description: The cost of shipping for the invoice, including all applicable - taxes. - shipping_method: - type: string - description: The method or service used for shipping the items associated - with the invoice. - shipping_tax_rate: - type: string - format: decimal - description: 'The tax rate applied to the shipping cost, expressed as a - percentage. ' + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. shortify_attachment_url: type: boolean writeOnly: true default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. shortify_checkout_url: type: boolean writeOnly: true default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. state: enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod type: string x-spec-enum-id: caee163196dbc11f readOnly: true @@ -13175,1799 +4958,1691 @@ components: * `invalided` - Invalided * `refunded` - Refunded * `cod` - Cash on Delivery - status: + unit_code: + type: string + writeOnly: true + title: Unit + description: The slug of the unit to be used for the transaction. + vendor_name: + type: string + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. + maxLength: 64 + webhook_url: + type: string + format: uri + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " + maxLength: 2000 + required: + - amount + - attachment_short_url + - billing + - checkout_page_url + - checkout_short_url + - checkout_url + - currency_code + - operation + - payment_methods + - pg_codes + - qr_code_url + - sdk_setup_preload_payload + - session_id + - settled_pg_code + - state + - type + CheckoutSDK: + type: object + description: |- + Serialize data for SDK init. + The SDK will use this data to initialize the payment process and + to display the payment methods. + properties: + amount: + type: string + format: decimal + description: 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 + billing: + type: string + readOnly: true + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. + cards: + type: array + items: + type: object + additionalProperties: {} + description: List of saved tokenized cards for customer payments, which can be used for transactions. Render alongside `payment_methods` for customers to choose from. + readOnly: true + customer_id: + type: string + description: 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. + maxLength: 64 + customer_phone: + type: string + description: 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. + maxLength: 16 + currency_code: + type: string + description: 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. + expiration_time: + type: string + readOnly: true + description: "The datetime when this payment transaction will expire. " + language: enum: - - sent - - paid - - overdue - - canceled + - en + - ar + type: string + x-spec-enum-id: ac1757d67890d125 + default: en + description: |- + This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. + + * `en` - English + * `ar` - Arabic + operation: type: string - x-spec-enum-id: c131c51a82b6f22a readOnly: true + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. + payment_type: + enum: + - one_off + - auto_debit + - save_card + type: string + x-spec-enum-id: b2ae60f7918918e7 + default: one_off description: |- - Current status of the invoice. Can be one of the following: `sent`, `paid`, `overdue`, `canceled`. + 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. - * `sent` - Sent + Choose `save_card` if you want to perform a card tokenization operation. + + NOTE: If `auto_debit` is selected: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 + payment_methods: + type: array + items: {} + description: | + The provided documentation describes the `payment_methods` field. + + Detailing the types of payment methods included and their functionality + as well as backward compatibility considerations for removed methods. + + The `payment_methods` field includes various payment options available to customers + excluding device-specific methods like `apple_pay`, `google_pay`and `flex_methods` represented in flex methods section + it primarily supports methods requiring a redirect flow + where users complete transactions on an external webpage. + + `Functionality`: users are redirected to an external + site mostly to gateway payment page + using `redirect_url` where they can complete the payment flow + + **The dynamic nature of the payment_methods**:`payment_methods` type is an array of objects + and it's type allows it to accommodate an unlimited variety of payment options + as each object represents a gateway payment option but strictly associated to redirect payment flow + + **Backward Compatibility Notice:** + + `stc_pay`: + previous Inclusion, `stc_pay` was formerly listed within the `payment_methods` array + it has been removed in favor of a more streamlined integration within the SDK + similar to the approach for `payment_services`. + + **Backward Compatibility:** + + The SDK must still support STC Pay for applications relying on older API versions. + Although it will not appear in current and future versions + the SDK will manage its inclusion internally + + to ensure a seamless transition and consistent user experience + across different API versions, without disrupting existing integrations. + readOnly: true + payment_services: + type: array + items: {} + description: | + Dedicated to singular, prominently featured payment options + + such as `apple_pay`, `google_pay`, `samsung_pay`, `stc_pay`, etc., + the `payment_services` field presents these methods in a distinctive manner. + + Unlike `payment_methods`, payment services are intended to be displayed uniquely, + Typically represented by dedicated buttons or interfaces within the payment page. + + This ensures that each payment service, + identifiable by its unique flow ie: (`apple_pay`, `stc_pay`) + is presented no more than once to the user + maintaining clarity and simplicity in the payment selection process. + + **Backward Compatibility Notice**: + historically, the availability of (`apple_pay`, `google_pay`) + was indicated through the `apple_pay_available` and `google_pay_available` flags + at the root level of the API response. + + With the evolution of the API, these flags have been deprecated, + and the respective payment methods have been integrated into the `payment_services` array. + + Despite this restructuring, backward compatibility for these payment methods + is preserved in the SDK to accommodate previous API versions, + ensuring a seamless transition for existing implementations. + readOnly: true + flex_methods: + type: array + items: {} + description: | + The `flex_methods` field encompasses a comprehensive array + of payment options available to customers, + explicitly excluding device-specific methods such as `apple_pay` + `google_pay`, redirect flow `payment_methods` and tokenized card solutions + otherwise it represents the flexible payment methods ie:(`tamara`, `tabby`, `taly`) + payment options that necessitate dynamic flows + where SDK might need to fetch some `pre-payment-check` API calls then + users are guided to an external webpage to finalize their payment transactions. + + It's important to note that the flex_methods array is dynamic + and can accommodate an unlimited array of payment methods. + each method listed should be individually rendered within the user interface with a separated flow. + readOnly: true + sdk_studio: + type: object + additionalProperties: {} + description: Represents the configuration of SDK Studio configuration, which includes the available payment methods and services sdk config required by the frontend to initialize the payment SDK properly. + readOnly: true + response: + type: object + additionalProperties: {} + description: |+ + **What is a payment gateway response?** + + A payment gateway response is the feedback received + from payment gateway after a user has completed a payment + this response provides information on whether the payment was successful or if it was canceled or failed. + + **When do we receive the response?** + + We receive the payment gateway response immediately after the user has made a payment + or after n of minutes defined for a gateway inquiry request initiated by ottu core + to fetch the transaction status after the defined time for each gateway. + + **Which attempt do we get the response for?** + + the response we provide is from the most recent payment attempt. + this ensures that the information reflects the latest status of the transaction. + + **Structure of the response**: + + The response structure is managed by our SDK, + which updates the payment details and triggers one of three callbacks + based on the status provided in the response: + + `successCallback`: Triggered if the response.status indicates a successful payment. + + `cancelCallback`: Triggered if the response.status indicates a canceled payment. + + `errorCallback`: Triggered if the response.status indicates a error payment. + + readOnly: true + state: + enum: + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod + type: string + x-spec-enum-id: caee163196dbc11f + readOnly: true + description: |- + The current state of the payment transaction, it helps to understand the progress of the payment. + + * `created` - Created + * `pending` - Pending + * `attempted` - Attempted + * `authorized` - Authorized * `paid` - Paid - * `overdue` - Overdue + * `failed` - Failed * `canceled` - Canceled - subtotal: + * `expired` - Expired + * `invalided` - Invalided + * `refunded` - Refunded + * `cod` - Cash on Delivery + type: + enum: + - e_commerce + - payment_request type: string - format: decimal - description: Sum of total_incl_tax's of all invoice items. - tax_amount: + x-spec-enum-id: ad398830c7970f0a + description: |- + The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. + + * `e_commerce` - Ecommerce + * `payment_request` - Payment Request + is_amount_editable: + type: boolean + readOnly: true + title: Editable amount + description: This field specifies whether the customer can modify the payment amount and choose the amount he wishes to pay. + session_id: type: string - format: decimal - description: The total amount of tax applied to the invoice. - tax_rate: + readOnly: true + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + cancel_url: + type: string + format: uri + readOnly: true + description: | + This endpoint used to cancel the transaction using the merchant cancellation flow, + to ensure the transaction cannot be paid again + and trigger the webhook notification + required: + - amount + - billing + - cancel_url + - cards + - currency_code + - expiration_time + - flex_methods + - is_amount_editable + - operation + - payment_methods + - payment_services + - response + - sdk_studio + - session_id + - state + - type + ChildPayment: + type: object + properties: + amount: + type: string + readOnly: true + currency_code: + type: string + description: 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. + maxLength: 3 + minLength: 3 + order_no: + type: + - string + - "null" + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + maxLength: 128 + session_id: + type: string + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + maxLength: 128 + state: + enum: + - paid + - refunded + - refund_queued + - refund_rejected + - voided + type: string + x-spec-enum-id: f7b1c95c3c2311ac + description: |- + 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 + required: + - amount + - currency_code + Client Errors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/NestedFieldErrors" + ClientErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/NestedFieldErrors" + - $ref: "#/components/schemas/GenericErrorMessage" + - $ref: "#/components/schemas/OperationErrorResponse" + CustomerWalletTransaction: + type: object + description: |- + One wallet leg in `customer_wallet_transactions`. + + A txn that uses multiple wallets (Ottu + Qitaf stacked, etc.) emits one + record per provider. Single-wallet txns emit a one-element list. + properties: + provider_code: type: string - format: decimal - title: Tax - description: The tax rate applied to the invoice, expressed as a percentage. - total_excl_tax: + description: Stable identifier of the wallet provider that handled this leg (e.g. `wallet_ottu`, `wallet_qitaf`). Empty for legacy native payments where the provider wasn't recorded on the attempt. + amount: type: string - format: decimal - title: Total Excl. Tax - description: The total amount of the invoice, excluding taxes. - total_incl_tax: + description: Amount charged from this wallet. + currency: type: string - format: decimal - title: Total Incl. Tax - description: The total amount of the invoice, including all applicable taxes. - unit_code: + description: ISO 4217 currency code. + operation_id: type: string - writeOnly: true - title: Unit - description: The slug of the unit to be used for the transaction. - vendor_name: + description: Wallet service operation ID (opaque per provider). + wallet_response: + allOf: + - $ref: "#/components/schemas/WalletServiceResponse" + description: Full response returned by the wallet service for this leg. + created_at: type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - webhook_url: + format: date-time + description: Wallet transaction creation timestamp. + modified_at: type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 2000 - required: - - attachment_short_url - - billing - - checkout_page_url - - checkout_short_url - - checkout_url - - currency_code - - due_date - - invoice_id - - invoice_items - - invoice_number - - operation - - payment_methods - - pg_codes - - qr_code_url - - sdk_setup_preload_payload - - session_id - - settled_pg_code - - state - - status - - type - ListingPymtTxn: + format: date-time + description: Wallet transaction last modification timestamp. + DirectPaymentResponse: type: object properties: - id: - type: integer + pg_params: + allOf: + - $ref: "#/components/schemas/PGParams" readOnly: true - state: - type: string + description: | + The `pg_params` field contains the details received + from the payment gateway callback these details are + provided to us by the gateway after a user has completed + a payment transaction additionally, `pg_params` + can include information obtained from an inquiry + request made to the payment gateway status check API. + agreement: + allOf: + - $ref: "#/components/schemas/Agreement" readOnly: true + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. amount: type: string - description: 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 - maxLength: 24 - currency_code: - enum: - - AED - - AFN - - ALL - - AMD - - ANG - - AOA - - ARS - - AUD - - AWG - - AZN - - BAM - - BBD - - BDT - - BGN - - BHD - - BIF - - BMD - - BND - - BOB - - BOV - - BRL - - BSD - - BTN - - BWP - - BYN - - BZD - - CAD - - CDF - - CHE - - CHF - - CHW - - CLF - - CLP - - CNY - - COP - - COU - - CRC - - CUC - - CUP - - CVE - - CZK - - DJF - - DKK - - DOP - - DZD - - EGP - - ERN - - ETB - - EUR - - FJD - - FKP - - GBP - - GEL - - GHS - - GIP - - GMD - - GNF - - GTQ - - GYD - - HKD - - HNL - - HRK - - HTG - - HUF - - IDR - - ILS - - INR - - IQD - - IRR - - ISK - - JMD - - JOD - - JPY - - KES - - KGS - - KHR - - KMF - - KPW - - KRW - - KWD - - KYD - - KZT - - LAK - - LBP - - LKR - - LRD - - LSL - - LYD - - MAD - - MDL - - MGA - - MKD - - MMK - - MNT - - MOP - - MRU - - MUR - - MVR - - MWK - - MXN - - MXV - - MYR - - MZN - - NAD - - NGN - - NIO - - NOK - - NPR - - NZD - - OMR - - PAB - - PEN - - PGK - - PHP - - PKR - - PLN - - PYG - - QAR - - RON - - RSD - - RUB - - RWF - - SAR - - SBD - - SCR - - SDG - - SEK - - SGD - - SHP - - SLE - - SLL - - SOS - - SRD - - SSP - - STN - - SVC - - SYP - - SZL - - THB - - TJS - - TMT - - TND - - TOP - - TRY - - TTD - - TWD - - TZS - - UAH - - UGX - - USD - - USN - - UYI - - UYU - - UYW - - UZS - - VED - - VES - - VND - - VUV - - WST - - XAF - - XAG - - XAU - - XBA - - XBB - - XBC - - XBD - - XCD - - XDR - - XOF - - XPD - - XPF - - XPT - - XSU - - XTS - - XUA - - XXX - - YER - - ZAR - - ZMW - - ZWL - type: string - x-spec-enum-id: 1314c690acf1c093 + readOnly: true + description: 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: + allOf: + - $ref: "#/components/schemas/AmountDetails" + readOnly: true + description: "A comprehensive set of amount details includes: Currency Code, Amount, Total, Fee." + capture_delivery_address: + type: boolean + description: By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active. + capture_delivery_location: + type: boolean + title: Capture delivery coordinates + description: "By enabling this, you will ask for user's delivery location on a map. " + card_acceptance_criteria: + allOf: + - $ref: "#/components/schemas/CardAcceptanceCriteria" + readOnly: true description: |- - 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. - - * `AED` - AED - * `AFN` - AFN - * `ALL` - ALL - * `AMD` - AMD - * `ANG` - ANG - * `AOA` - AOA - * `ARS` - ARS - * `AUD` - AUD - * `AWG` - AWG - * `AZN` - AZN - * `BAM` - BAM - * `BBD` - BBD - * `BDT` - BDT - * `BGN` - BGN - * `BHD` - BHD - * `BIF` - BIF - * `BMD` - BMD - * `BND` - BND - * `BOB` - BOB - * `BOV` - BOV - * `BRL` - BRL - * `BSD` - BSD - * `BTN` - BTN - * `BWP` - BWP - * `BYN` - BYN - * `BZD` - BZD - * `CAD` - CAD - * `CDF` - CDF - * `CHE` - CHE - * `CHF` - CHF - * `CHW` - CHW - * `CLF` - CLF - * `CLP` - CLP - * `CNY` - CNY - * `COP` - COP - * `COU` - COU - * `CRC` - CRC - * `CUC` - CUC - * `CUP` - CUP - * `CVE` - CVE - * `CZK` - CZK - * `DJF` - DJF - * `DKK` - DKK - * `DOP` - DOP - * `DZD` - DZD - * `EGP` - EGP - * `ERN` - ERN - * `ETB` - ETB - * `EUR` - EUR - * `FJD` - FJD - * `FKP` - FKP - * `GBP` - GBP - * `GEL` - GEL - * `GHS` - GHS - * `GIP` - GIP - * `GMD` - GMD - * `GNF` - GNF - * `GTQ` - GTQ - * `GYD` - GYD - * `HKD` - HKD - * `HNL` - HNL - * `HRK` - HRK - * `HTG` - HTG - * `HUF` - HUF - * `IDR` - IDR - * `ILS` - ILS - * `INR` - INR - * `IQD` - IQD - * `IRR` - IRR - * `ISK` - ISK - * `JMD` - JMD - * `JOD` - JOD - * `JPY` - JPY - * `KES` - KES - * `KGS` - KGS - * `KHR` - KHR - * `KMF` - KMF - * `KPW` - KPW - * `KRW` - KRW - * `KWD` - KWD - * `KYD` - KYD - * `KZT` - KZT - * `LAK` - LAK - * `LBP` - LBP - * `LKR` - LKR - * `LRD` - LRD - * `LSL` - LSL - * `LYD` - LYD - * `MAD` - MAD - * `MDL` - MDL - * `MGA` - MGA - * `MKD` - MKD - * `MMK` - MMK - * `MNT` - MNT - * `MOP` - MOP - * `MRU` - MRU - * `MUR` - MUR - * `MVR` - MVR - * `MWK` - MWK - * `MXN` - MXN - * `MXV` - MXV - * `MYR` - MYR - * `MZN` - MZN - * `NAD` - NAD - * `NGN` - NGN - * `NIO` - NIO - * `NOK` - NOK - * `NPR` - NPR - * `NZD` - NZD - * `OMR` - OMR - * `PAB` - PAB - * `PEN` - PEN - * `PGK` - PGK - * `PHP` - PHP - * `PKR` - PKR - * `PLN` - PLN - * `PYG` - PYG - * `QAR` - QAR - * `RON` - RON - * `RSD` - RSD - * `RUB` - RUB - * `RWF` - RWF - * `SAR` - SAR - * `SBD` - SBD - * `SCR` - SCR - * `SDG` - SDG - * `SEK` - SEK - * `SGD` - SGD - * `SHP` - SHP - * `SLE` - SLE - * `SLL` - SLL - * `SOS` - SOS - * `SRD` - SRD - * `SSP` - SSP - * `STN` - STN - * `SVC` - SVC - * `SYP` - SYP - * `SZL` - SZL - * `THB` - THB - * `TJS` - TJS - * `TMT` - TMT - * `TND` - TND - * `TOP` - TOP - * `TRY` - TRY - * `TTD` - TTD - * `TWD` - TWD - * `TZS` - TZS - * `UAH` - UAH - * `UGX` - UGX - * `USD` - USD - * `USN` - USN - * `UYI` - UYI - * `UYU` - UYU - * `UYW` - UYW - * `UZS` - UZS - * `VED` - VED - * `VES` - VES - * `VND` - VND - * `VUV` - VUV - * `WST` - WST - * `XAF` - XAF - * `XAG` - XAG - * `XAU` - XAU - * `XBA` - XBA - * `XBB` - XBB - * `XBC` - XBC - * `XBD` - XBD - * `XCD` - XCD - * `XDR` - XDR - * `XOF` - XOF - * `XPD` - XPD - * `XPF` - XPF - * `XPT` - XPT - * `XSU` - XSU - * `XTS` - XTS - * `XUA` - XUA - * `XXX` - XXX - * `YER` - YER - * `ZAR` - ZAR - * `ZMW` - ZMW - * `ZWL` - ZWL - gateway_name: + 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. + currency_code: type: string - readOnly: true - card_type: + description: 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. + maxLength: 3 + minLength: 3 + customer_address_city: type: string - readOnly: true - attachment_url: + description: The city of the customer's billing address. This field may be used to send the billing address to the payment gateway. + maxLength: 40 + customer_address_country: type: string - readOnly: true - card_details: + description: 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. + maxLength: 2 + minLength: 2 + customer_address_line1: type: string - readOnly: true - card_holder: + title: Customer address line 1 + description: 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_line2: type: string - readOnly: true - card_expiry: + title: Customer address line 2 + description: 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_birthdate: + type: + - string + - "null" + format: date + description: The customer's date of birth in ISO format (YYYY-MM-DD). + customer_address_postal_code: type: string - readOnly: true - card_expiry_month: + description: The postal code of the customer's billing address. This field may be used to send the billing address to the payment gateway. + maxLength: 12 + customer_address_state: type: string - readOnly: true - card_expiry_year: + description: The state or region of the customer's billing address. This field may be used to send the billing address to the payment gateway. + maxLength: 40 + customer_email: type: string - readOnly: true - full_card_expiry: + description: 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. + maxLength: 128 + customer_first_name: type: string - readOnly: true - card_number: + description: 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. + maxLength: 64 + customer_id: + type: string + description: 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. + maxLength: 64 + customer_last_name: + type: string + description: 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. + maxLength: 64 + customer_phone: type: string + description: 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. + maxLength: 32 + customer_wallet_transactions: + type: array + items: + $ref: "#/components/schemas/CustomerWalletTransaction" readOnly: true - card_issuer: + description: List of wallet legs that contributed to this payment — one entry per wallet provider (Ottu, Qitaf, …). Multi-wallet stacking emits multiple entries; full or single-wallet payments emit a one-element list. Omitted entirely (key absent) when no wallet was involved. + extra: + description: The extra information for the payment details, which the merchant has sent it in key value form. + fee: type: string + description: 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. readOnly: true - cardholder_email: + gateway_account: type: string readOnly: true - auth_code: + description: This code corresponds to the payment gateway and plays an essential role in facilitating payment transactions. + gateway_name: type: string readOnly: true - track_id: + description: The name of the payment gateway service being utilized. + gateway_response: + type: object + additionalProperties: {} + description: This field stores the processed response received from the payment gateway and forwarded to Ottu. + readOnly: true + initiator: + allOf: + - $ref: "#/components/schemas/InitiatorUser" + description: 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 + is_sandbox: + type: boolean + title: Is Sandbox? + description: Indicates whether the operation was performed in a test environment or not. + message: type: string readOnly: true - ref: + description: 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_no: + type: + - string + - "null" + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + maxLength: 128 + paid_amount: + oneOf: + - type: number + format: double + - type: string + description: 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. + readOnly: true + payment_type: + enum: + - one_off + - auto_debit + - save_card + type: string + x-spec-enum-id: b2ae60f7918918e7 + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 + reference_number: type: string readOnly: true + refunded_amount: + type: number + format: double + description: The total refunded amount for the payment transaction. + remaining_amount: + type: number + format: double + description: The residual amount due. Together with the editable amount, it indicates the outstanding balance of a transaction awaiting settlement. + readOnly: true result: + enum: + - pending + - success + - failed + - canceled + - error + - cod type: string + description: Indicates the outcome of the operation. `success` denotes a successful operation. + x-spec-enum-id: 03c10fdf706d3f9a readOnly: true - post_date: + session_id: type: string + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + maxLength: 128 + settled_amount: + type: number + format: double + description: The amount that has been paid or authorized in its original currency, excluding any fees. readOnly: true - transaction_id: + signature: type: string readOnly: true - payment_id: + description: "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." + state: type: string readOnly: true - pg_message: + token: + allOf: + - $ref: "#/components/schemas/Card" + description: |- + Please note that if card is created via checkout save_card payment type + + It means card is created via successful operation without any funds charged. + + For more details check Checkout API `payment_type` field documentation details + transaction_log_id: + type: + - integer + - "null" + maximum: 2147483647 + minimum: 0 + description: 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. + timestamp_utc: type: string + format: date-time readOnly: true - receipt_no: + description: 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. + transactions: + type: array + items: + $ref: "#/components/schemas/ChildPayment" + description: A list of dictionaries is generated, each containing a concise summary of each child payment transaction that has been created. + voided_amount: + type: number + format: double + description: The total voided amount for the payment transaction. + required: + - agreement + - amount + - amount_details + - card_acceptance_criteria + - currency_code + - customer_address_country + - fee + - gateway_account + - gateway_name + - gateway_response + - message + - paid_amount + - pg_params + - reference_number + - remaining_amount + - result + - settled_amount + - signature + - state + - timestamp_utc + ExternalOperation: + type: object + properties: + amount: type: string readOnly: true - transaction_no: + description: The specific amount for which the operation was performed. + session_id: type: string + description: The session ID of the parent transaction will be included in the webhook payload. This session ID is crucial for associating the webhook event with the original transaction, allowing for accurate tracking and processing. readOnly: true - decision: + order_no: type: string + description: The 'order_no' field indicates the unique order number of the parent transaction. This identifier is crucial for tracking and managing the related order within its entire lifecycle. readOnly: true - dcc_payer_amount: + initiator: + allOf: + - $ref: "#/components/schemas/InitiatorUser" + description: If the operation was performed using Basic Auth (and not an API Key), this field contains the details of the `initiator` who started the operation. + is_sandbox: + type: boolean + title: Is Sandbox? + description: Indicates whether the operation was performed in a test environment or not. + operation: + enum: + - capture + - refund + - void type: string + description: Identifies the operation that was executed. + x-spec-enum-id: 6fdf34a272fc404b readOnly: true - dcc_payer_currency: + pg_code: type: string + description: Represents the `pg_code` of the Payment Gateway settings which was used to perform the operation. + pg_response: + type: object + additionalProperties: {} readOnly: true - dcc_payer_exchange_rate: + description: Contains the raw response from the payment gateway (PG) for the operation (`pg_response`). It will always be a valid JSON. + reference_number: type: string readOnly: true - rrn: + description: A unique reference_number assigned by Ottu for the performed operation. It's also sent to the PG and can be used as a reconciliation parameter. + source: + enum: + - input + - pg type: string + description: Can have one of two values - `input` or `pg`. If `input`, it means the operation was performed in an API call triggered by the merchant. If `pg`, it means the operation was done on the PG management dashboard, and the PG notified Ottu via webhook. The `pg` value will always be notified to the webhook, never in an API call. + x-spec-enum-id: 11ceda8d7147f99f readOnly: true - initiator: - allOf: - - $ref: '#/components/schemas/BaseUser' + success: + type: boolean readOnly: true - session_id: + description: Indicates whether the operation was successful or not (`success=True` or `success=False`). + result: + enum: + - success + - failed type: string + description: The result of the operation - whether it was successful or not. + x-spec-enum-id: ce10c9ef1792a8ae readOnly: true - customer_email: - type: string - description: 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. - maxLength: 128 - created: + signature: type: string - format: date-time readOnly: true - payment_date: + description: "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." + timestamp_utc: type: string + format: date-time + description: Specifies the time when the operation was performed, in the UTC timezone. + txn: + allOf: + - $ref: "#/components/schemas/ChildPayment" readOnly: true - state_changed_at: - type: string + description: Every operation results in the creation of a payment transaction (`txn`), which is a child of the payment transaction against which the operation is performed. This child transaction holds all the details of the operation. + pg_params: + allOf: + - $ref: "#/components/schemas/PGParams" readOnly: true - txns: + description: | + The `pg_params` field contains the details received + from the payment gateway callback these details are + provided to us by the gateway after a user has completed + a payment transaction additionally, `pg_params` + can include information obtained from an inquiry + request made to the payment gateway status check API. + extra: + description: The extra information for the payment details, which the merchant has sent it in key value form. + required: + - amount + - operation + - order_no + - pg_params + - pg_response + - reference_number + - result + - session_id + - signature + - source + - success + - timestamp_utc + - txn + FieldErrors: + type: object + properties: + field_name: type: array items: - $ref: '#/components/schemas/ChildPymtTxn' - readOnly: true - fee: - type: string - readOnly: true - type: - enum: - - e_commerce - - payment_request - - bulk - - catalogue - - customer_payment - - event - - food_ordering - - iata - - real_estate - type: string - x-spec-enum-id: b2b79580b4e2b976 - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - E-Commerce - * `payment_request` - Payment request - * `bulk` - Bulk Payment Request - * `catalogue` - Catalogue purchase - * `customer_payment` - Customer payment - * `event` - Event management and booking - * `food_ordering` - Food ordering - * `iata` - IATA - * `real_estate` - Real Estate - required: - - amount - - attachment_url - - auth_code - - card_details - - card_expiry - - card_expiry_month - - card_expiry_year - - card_holder - - card_issuer - - card_number - - card_type - - cardholder_email - - created - - currency_code - - dcc_payer_amount - - dcc_payer_currency - - dcc_payer_exchange_rate - - decision - - fee - - full_card_expiry - - gateway_name - - id - - initiator - - payment_date - - payment_id - - pg_message - - post_date - - receipt_no - - ref - - result - - rrn - - session_id - - state - - state_changed_at - - track_id - - transaction_id - - transaction_no - - txns - LogEntry: + type: string + default: This field is required. + GenericErrorMessage: type: object properties: - id: - type: integer - readOnly: true - action: - enum: - - 0 - - 1 - - 2 - - 3 - type: integer - description: |- - * `0` - create - * `1` - update - * `2` - delete - * `3` - access - x-spec-enum-id: f07ca4f574297d89 - minimum: 0 - maximum: 32767 - changes: - type: object - additionalProperties: {} - remote_addr: - type: - - string - - 'null' - title: Remote address - timestamp: + detail: type: string - format: date-time - readOnly: true - additional_data: - oneOf: - - {} - - type: 'null' - actor: - $ref: '#/components/schemas/Initiator' required: - - action - - actor - - changes - - id - - timestamp - MIDIcon: + - detail + GooglePayInfoSchema: type: object - description: Serializer for PG logo with custom logo URL resolution. + description: Google Pay card information properties: - svg: - type: - - string - - 'null' - format: uri - readOnly: true - description: '`Optional` field. Upload a logo in SVG format only. If provided - and no WebP image is uploaded, a WebP version will be automatically generated. - Only .svg files are accepted. Do not upload any other format.' - webp: + cardNetwork: type: string - readOnly: true - description: '`Mandatory` field. This must be provided either by uploading - a WebP image directly, or it will be auto-generated from the SVG file - (if provided). This field does not accept SVG files — only raster images - like PNG or JPEG that will be converted to WebP.' - label: + description: Card network (e.g., 'VISA') + cardDetails: type: string - description: The display name of the logo (translatable in EN and AR). - maxLength: 255 + description: Last 4 digits of card required: - - label - - svg - - webp - MailLog: + - cardDetails + - cardNetwork + GooglePayInstrument: type: object + description: Google Pay payment instrument properties: - id: - type: integer - readOnly: true - created: - type: string - format: date-time - readOnly: true - is_sent: - type: boolean - event_type: + instrument_type: enum: - - created - - paid - - canceled - - failed - - expired - - authorized - - voided - - refunded - - captured - - email_notification - - sms_notification - - whatsapp_notification - - '' - - null - type: - - string - - 'null' + - google_pay + type: string + x-spec-enum-id: 394f64ef0358d4b7 + default: google_pay description: |- - * `created` - Created - * `paid` - Paid - * `canceled` - Canceled - * `failed` - Failed - * `expired` - Expired - * `authorized` - Authorized - * `voided` - Voided - * `refunded` - Refunded - * `captured` - Captured - * `email_notification` - Email Notification - * `sms_notification` - SMS Notification - * `whatsapp_notification` - WhatsApp Notification - x-spec-enum-id: 60c1e510575d4f45 - forced: - type: boolean - provider: + Payment type: Google Pay + + * `google_pay` - google_pay + payload: + allOf: + - $ref: "#/components/schemas/GooglePayPayloadSchema" + description: Google Pay payment data received from Google Pay SDK. Pass the complete paymentData object exactly as received without modification. Includes apiVersion, paymentMethodData with tokenization data. + required: + - payload + GooglePayNativePayment: + type: object + properties: + payload: + $ref: "#/components/schemas/GooglePayPaymentData" + pg_code: type: - - string - - 'null' - readOnly: true - backend: + - string + - "null" + description: The unique pg_code used for this payment instrument. + session_id: type: string - readOnly: true - mail_logs: - type: array - items: - $ref: '#/components/schemas/MailLogEmail' + description: A unique identifier for the payment transaction (session). required: - - backend - - created - - id - - mail_logs - - provider - MailLogEmail: + - payload + - session_id + GooglePayPayloadSchema: type: object + description: Complete Google Pay payment data structure properties: - id: + apiVersion: type: integer - readOnly: true - email: - type: string - title: Recipient - maxLength: 350 - mail_type: - enum: - - cc - - bcc - - to - type: string - description: |- - * `cc` - CC - * `bcc` - BCC - * `to` - TO - x-spec-enum-id: f10013e327f82fe5 + description: Google Pay API version (e.g., 2) + apiVersionMinor: + type: integer + description: API minor version (e.g., 0) + paymentMethodData: + allOf: + - $ref: "#/components/schemas/GooglePayPaymentMethodDataSchema" + description: Payment method and tokenization data required: - - email - - id - - mail_type - MessageNotification: + - apiVersion + - apiVersionMinor + - paymentMethodData + GooglePayPaymentData: type: object - description: This serializer is used to validate the lookup fields for the inquiry - operation. + description: |- + Serializer for Google Pay payment, which is used to validate + the payment data sent from the SDK client. + + OrderSerializer must be added also in the mixin classes + for minimal amount validation + + This deserialize the data sent from the SDK client, namely the + paymentData https://developers.google.com/pay/api/web/reference/response-objects#PaymentData + + { + "apiVersion": 2, + "apiVersionMinor": 0, + "paymentMethodData": { + "type": "CARD", + "description": "Visa 1234", + "info": { + "cardNetwork": "VISA", + "cardDetails": "1234", + "billingAddress": { + "name": "John Smith", + "phoneNumber": "+16505551234", + "postalAddress": { + "addressLines": ["1234 Main Street"], + "locality": "Mountain View", + "administrativeArea": "CA", + "postalCode": "94043", + "countryCode": "US", + }, + }, + }, + "tokenizationData": { + "type": "PAYMENT_GATEWAY", + "token": "dummy_payment_token", + }, + }, + "email": "customer@example.com", + "shippingAddress": { + "name": "John Smith", + "phoneNumber": "+16505551234", + "postalAddress": { + "addressLines": ["1234 Main Street"], + "locality": "Mountain View", + "administrativeArea": "CA", + "postalCode": "94043", + "countryCode": "US", + }, + }, + } properties: - order_no: - type: string - description: This is an optional identifier used to specify the payment - transaction upon which the operation should be performed. You can use - either the `order_no` or `session_id` field; at least one of these two - identifiers must be provided to select the payment transaction that should - be actioned. - maxLength: 128 - session_id: + apiVersion: + type: integer + description: The version of the Google Pay API used to process the payment. + apiVersionMinor: + type: integer + description: The minor version of the Google Pay API used to process the payment. + paymentMethodData: + allOf: + - $ref: "#/components/schemas/PaymentMethodData" + description: The payment method data. + email: type: string - description: Similar to `order_no`, `session_id` is an optional identifier - used to specify the payment transaction for the operation. You must provide - either `order_no` or `session_id` in order to select the appropriate payment - transaction. - maxLength: 128 - channels: - type: array - items: - enum: - - sms - - email - - whatsapp - type: string - description: |- - * `sms` - sms - * `email` - email - * `whatsapp` - whatsapps - x-spec-enum-id: 62ab5ae1260bf392 - description: This field refers to the channels that are desired to be triggered - on the payment. The options are `sms`, `email`, `whatsapp`. + format: email + description: The email address of the customer. + shippingAddress: + type: object + additionalProperties: {} + description: The shipping address of the customer. required: - - channels - MessageNotificationFailure: + - apiVersion + - apiVersionMinor + - paymentMethodData + GooglePayPaymentMethodDataSchema: type: object - description: This serializer is used to validate the lookup fields for the inquiry - operation. + description: Google Pay payment method data properties: - order_no: - type: string - description: This is an optional identifier used to specify the payment - transaction upon which the operation should be performed. You can use - either the `order_no` or `session_id` field; at least one of these two - identifiers must be provided to select the payment transaction that should - be actioned. - maxLength: 128 - session_id: - type: string - description: Similar to `order_no`, `session_id` is an optional identifier - used to specify the payment transaction for the operation. You must provide - either `order_no` or `session_id` in order to select the appropriate payment - transaction. - maxLength: 128 - channels: - enum: - - sms - - email - - whatsapp + type: type: string - description: |- - * `sms` - sms - * `email` - email - * `whatsapp` - whatsapps - x-spec-enum-id: 62ab5ae1260bf392 - result: - enum: - - failed + description: Payment method type (e.g., 'CARD') + description: type: string - description: '* `failed` - Failed' - x-spec-enum-id: 8b493f06ef915a3f + description: Payment method description + info: + allOf: + - $ref: "#/components/schemas/GooglePayInfoSchema" + description: Card information + tokenizationData: + allOf: + - $ref: "#/components/schemas/GooglePayTokenizationDataSchema" + description: Tokenization data with encrypted token required: - - channels - - result - MessageNotificationSuccess: + - description + - info + - tokenizationData + - type + GooglePayTokenizationDataSchema: type: object + description: Google Pay tokenization data properties: - message: + type: type: string - default: Customer notified. - Nested: - type: object - properties: - field_name: - type: array - items: - type: string - default: To use sms notifications provide the `customer_phone` field. + description: Tokenization type (e.g., 'PAYMENT_GATEWAY') + token: + type: string + description: Encrypted payment token required: - - field_name - NestedFieldErrors: + - token + - type + Header: type: object properties: - field_name: - $ref: '#/components/schemas/Nested' + ephemeralPublicKey: + type: string + wrappedKey: + type: string + publicKeyHash: + type: string + transactionId: + type: string required: - - field_name - Notification: + - publicKeyHash + - transactionId + IFrame3DSResponse: type: object properties: - channel: - enum: - - email - - sms - - whatsapp - type: string - x-spec-enum-id: 26d97252a367d950 - description: |- - Specify the channel to trigger the notification: sms, email, or WhatsApp. Valid options are: `email`, `sms`, and `whatsapp`. - - * `email` - Email - * `sms` - SMS - * `whatsapp` - WhatsApp - template_id: + status: type: string - description: This field is required. It specifies the template to be used - for the notification. - to: + readOnly: true + default: 3DS + description: The payment is in 3DSecure process. Indicates a 3D Secure verification is required. html must be displayed to the customer in the iframe. + reference_number: type: string - description: Required for all notifications. Must be a valid email address - for email notifications, and a valid international phone number for SMS - and WhatsApp notifications. - unit_config: - type: integer - description: This field is optional for SMS and email notifications, but - it is mandatory for WhatsApp notifications. - language: + readOnly: true + description: This is a unique value associated with each payment transaction made by a customer. It serves as the unique identifier for the payment when sent to the Payment Gateway (PG). allowing for multiple reference numbers per session_id. + form_of_payment: enum: - - en - - ar + - apple_pay + - google_pay + - token_pay + - stc_pay + - urpay + - redirect + - samsung_pay + - doku + - aba_payway type: string - x-spec-enum-id: ac1757d67890d125 - default: en + x-spec-enum-id: d21d329ca6d31930 + readOnly: true description: |- - Specifies the language for email, SMS, and WhatsApp notifications. The default language is English (en). - - * `en` - English - * `ar` - Arabic - cc: - type: array - items: - type: string - format: email - description: This field is optional. When provided, it specifies the list - of CC recipients for the email notification. - bcc: - type: array - items: - type: string - format: email - description: This field is optional. When provided, it specifies the list - of BCC recipients for the email notification. - subject: + Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + + * `apple_pay` - Apple Pay + * `google_pay` - Google Pay + * `token_pay` - Token Pay + * `stc_pay` - STC Pay + * `urpay` - URPay + * `redirect` - Redirect + * `samsung_pay` - Samsung Pay + * `doku` - Doku + * `aba_payway` - ABA PayWay + challenge_occurred: + type: boolean + default: true + description: This flag indicates if an additional verification, such as 3DS, OTP, PIN, etc., was initiated during the payment process. Use this flag in cancelCallback and errorCallback to control the presentation of error messages, especially for on-site payments undergoing a challenge flow. For example, after a failed 3DS verification, it's useful to show a custom popup informing the user of the payment failure. However, it's crucial to note that not all on-site failed payments need custom error messaging. In cases like GooglePay or ApplePay, error messages are inherently handled by the Payment Sheet, which remains open for the user to retry, making this distinction vital. + method: type: string - description: This field is optional. Use this field to customize the email - subject if you don't want to use the one from the template. - body: + readOnly: true + default: iframe + description: The method of 3D Secure verification. + html: type: string - description: '{''This field is optional. If provided, it serves as a fallback - template in case the primary template fails to render. This has to be - a plain text body of the email.''}' - context: - description: This field is optional. If provided, the context data will - be passed to the template engine during rendering. - attachments: - type: array - items: - $ref: '#/components/schemas/Attachment' - description: This field is optional. Use this field to include file attachments - with your email notification. Provide the file data as a base64 encoded - string *or* a publicly accessible URL. - trace_id: + readOnly: true + description: The HTML code to be displayed in the iframe. + ws_url: type: string - description: This field is optional. A unique identifier for tracking the - notification request. Useful for logging and debugging. - maxLength: 60 - tags: - type: array - items: - type: string - description: This field is optional. A list of metadata tags for analytics - or categorization purposes. + format: uri + readOnly: true + description: The WebSocket URL for real-time communication during the 3D Secure process. required: - - channel - - template_id - - to - NotificationErrors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/NotificationFailure' - NotificationFailure: + - form_of_payment + - html + - method + - reference_number + - status + - ws_url + Icons: type: object properties: - detail: + webp: type: string - result: + format: uri + description: The webp URL of the icon for the payment method. + svg: type: string - default: failed + format: uri + description: The svg URL of the icon for the payment method. required: - - detail - NotificationResponses: - oneOf: - - $ref: '#/components/schemas/NotificationSuccess' - NotificationSet: + - svg + - webp + InitiatorUser: type: object properties: id: type: integer readOnly: true - name: + first_name: type: string - maxLength: 24 - pattern: ^[-a-zA-Z0-9_]+$ - required: - - id - - name - NotificationSuccess: - type: object - properties: - message: + maxLength: 32 + last_name: type: string - default: Notification sent. - result: + maxLength: 32 + username: type: string - default: success - Notifications: - type: object - properties: + description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only. + pattern: ^[\w.@+-]+$ + maxLength: 150 email: - type: array - items: - enum: - - created - - paid - - canceled - - failed - - expired - - authorized - - voided - - refunded - - captured - type: string - description: |- - * `created` - Created - * `paid` - Paid - * `canceled` - Canceled - * `failed` - Failed - * `expired` - Expired - * `authorized` - Authorized - * `voided` - Voided - * `refunded` - Refunded - * `captured` - Captured - x-spec-enum-id: a9456842df943874 - sms: - type: array - items: - enum: - - created - - paid - - canceled - - failed - - expired - - authorized - - voided - - refunded - - captured - type: string - description: |- - * `created` - Created - * `paid` - Paid - * `canceled` - Canceled - * `failed` - Failed - * `expired` - Expired - * `authorized` - Authorized - * `voided` - Voided - * `refunded` - Refunded - * `captured` - Captured - x-spec-enum-id: a9456842df943874 - whatsapp: - type: array - items: - enum: - - created - - paid - - canceled - - failed - - expired - - authorized - type: string - description: |- - * `created` - Created - * `paid` - Paid - * `canceled` - Canceled - * `failed` - Failed - * `expired` - Expired - * `authorized` - Authorized - x-spec-enum-id: 43293338bc4fdb1a - Operation: + type: string + format: email + title: Email address + maxLength: 254 + phone: + type: string + title: Phone number + maxLength: 128 + required: + - email + - id + - username + Inquiry: type: object - description: |- - Fetch the payment txn based on the order no or session id - also, if the payment txn is not in the accepted state for the - input operation, raise an error + description: This serializer is used to validate the lookup fields for the inquiry operation. properties: order_no: type: string - description: This is an optional identifier used to specify the payment - transaction upon which the operation should be performed. You can use - either the `order_no` or `session_id` field; at least one of these two - identifiers must be provided to select the payment transaction that should - be actioned. + description: This is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the `order_no` or `session_id` field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned. maxLength: 128 session_id: type: string - description: Similar to `order_no`, `session_id` is an optional identifier - used to specify the payment transaction for the operation. You must provide - either `order_no` or `session_id` in order to select the appropriate payment - transaction. + description: Similar to `order_no`, `session_id` is an optional identifier used to specify the payment transaction for the operation. You must provide either `order_no` or `session_id` in order to select the appropriate payment transaction. maxLength: 128 - operation: - enum: - - delete - - cancel - - expire - - refund - - capture - - void + notify_webhook_url: + type: boolean + default: false + description: A boolean value indicating whether or not to notify the webhook_url about the status of the payment. When set to true, the system will send a notification to the webhook_url specified during the creation of the payment via the Checkout API. This is particularly useful for merchants who have an acknowledgement mechanism in place and want to trigger it to confirm the payment/order on their system. + webhook_url: type: string - description: |- - * `delete` - delete - * `cancel` - cancel - * `expire` - expire - * `refund` - refund - * `capture` - capture - * `void` - void - x-spec-enum-id: 943f8b45fb88fe59 - amount: + format: uri + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " + maxLength: 200 + InquiryErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/InquiryFailure" + InquiryFailure: + type: object + properties: + detail: type: string - format: decimal - pattern: ^-?\d{0,13}(?:\.\d{0,3})?$ - description: This field is optional and used to specify the amount you want - to action for `refund` and `capture` operations. If not specified, Ottu - will attempt to perform the operation on the full amount, or the remaining - amount if previous operations have been performed. Keep in mind that `void` - operations always concern the full amount; the `amount` field is not considered - in this case. The `amount` field can be sent for all operations, but it - will only be taken into account for `refund` and `capture` operations. - extra: - type: object - additionalProperties: {} - description: "This field is optional and used to specify additional parameters - for the operation. \n\n**IFG**: \n\nFull Refund Details\n\nFor - full refund you don't need to use extra key.\n\nPartial Refund Details\n\nFor - operations involving partial refunds, the extra field allows specifying - individual ticket orders along with their corresponding refund amounts.\n\nThis - capability ensures precise control over the refund amounts for each ticket - within an order.\n\nKey Points\n\n`passengerDocumentNumber`: It - is imperative to include the document number for each ticket involved - in the refund operation. This ensures that the refund is accurately applied - to the correct tickets within an order.\n\n`amount`: Alongside each ticket - document number, specify the desired refund amount for that ticket and - make sure the type of amount is `INT`.\n\n`Excluding Tickets`: If certain - tickets within an order should not be refunded, you can specify a refund - amount of zero for those tickets. This approach allows for selective refunding - within a single order.\n\n`Important Note`\n\nAll tickets intended for - refund must be explicitly listed in the refund order details, with their - respective refund amounts clearly defined. This requirement ensures comprehensive - and error-free processing of partial refunds.\n\nExample\n\ncheck - in Request samples there is an example showcasing how to structure the - extra field for a partial refund request, including specifying refund - amounts for tickets" + description: Provides a message associated with the operation, suitable for displaying to the end user. + result: + enum: + - failed + type: string + description: "* `failed` - Failed" + x-spec-enum-id: 8b493f06ef915a3f required: - - operation - OperationErrorResponse: + - detail + - result + InternalOperation: type: object properties: detail: type: string - description: A human-readable description providing details about the failure. - maxLength: 255 + description: Provides a message associated with the operation, suitable for displaying to the end user. + operation: + enum: + - refund + - void + - capture + - delete + - cancel + - expire + type: string + x-spec-enum-id: ba0e384393b3f117 + description: |- + Specifies the executed operation. It can be either `delete`, `cancel`, or `expire`. + + * `refund` - Refund + * `void` - Void + * `capture` - Capture + * `delete` - Delete + * `cancel` - Cancel + * `expire` - Expire result: + enum: + - success + - failed type: string - default: failed - description: Indicates the outcome of the operation. Typically set to 'failed' - for error responses. - OperationFailure: + x-spec-enum-id: 74cb1d0c38c4dfc9 + description: |- + Indicates the outcome of the operation. `success` denotes a successful operation. + + * `success` - Success + * `failed` - Failed + required: + - detail + - operation + - result + InvoiceClientErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/NestedFieldErrors" + - $ref: "#/components/schemas/GenericErrorMessage" + InvoiceItem: type: object + description: |- + Serializer to use for `InvoiceItem` instances. + + The unit_price, quantity, description and sku fields are required. + The rest are optional. + + The class includes a method to calculate the discount on the invoice and another to calculate the total values. properties: - detail: + id: + type: integer + readOnly: true + invoice: + type: + - integer + - "null" + description: Associated invoice. + sku: + type: string + description: Unique identifier for the invoice item. + maxLength: 255 + description: + type: string + description: Product name or a brief description of the item. + maxLength: 255 + quantity: + type: string + format: decimal + description: Number of units of the product. + unit_price: + type: string + format: decimal + description: Price per unit of the product, excluding tax. + tax_rate: + type: string + format: decimal + description: Tax rate applied to the invoice item. + tax_amount: + type: string + format: decimal + description: Total tax amount for the invoice item. + discount_percentage: + type: string + format: decimal + description: Percentage-based discount applied to the invoice item. The calculated discount cannot exceed theitem's total value, including tax. + discount_amount: type: string - description: Provides a message associated with the operation, suitable - for displaying to the end user. - operation: - enum: - - delete - - cancel - - expire - - refund - - capture - - void - - operation_tracking + format: decimal + description: Fixed amount discount applied to the invoice item. The discount cannot exceed the item's total value, including tax. + total_excl_tax: type: string - description: |- - * `delete` - delete - * `cancel` - cancel - * `expire` - expire - * `refund` - refund - * `capture` - capture - * `void` - void - * `operation_tracking` - operation_tracking - x-spec-enum-id: 789f76f0e432d492 - result: - enum: - - failed + format: decimal + description: Total value of the invoice item, excluding tax. This is calculated as (unit_price * quantity) - discount. + total_incl_tax: type: string - description: '* `failed` - Failed' - x-spec-enum-id: 8b493f06ef915a3f + format: decimal + description: Total value of the invoice item, including tax. This is calculated as (unit_price * quantity) - discount + applicable tax. + currency_code: + type: string + description: "For internal purposes: it'll be overridden by the main currency_code" required: - - detail - - operation - - result - OttuPG: + - currency_code + - description + - id + - quantity + - sku + - unit_price + InvoicePOSTRequest: type: object + description: |- + Serializer class for `Invoice` instances, inheriting from `BaseInvoiceSerializer` and + `CheckoutSerializer`. It provides methods for creating invoices, invoice items, and transactions. properties: - code: + currency_code: type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: + description: 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. + due_date: type: string - description: The name of the payment method. + format: date + description: The date by which the customer is expected to make payment for the invoice. + invoice_items: + type: array + items: + $ref: "#/components/schemas/InvoiceItem" + description: The list of items for the invoice. + invoice_number: + type: string + description: A unique identifier for the invoice, typically used for tracking and referencing purposes. + maxLength: 255 + pg_codes: + type: array + items: + type: string + title: Gateway + description: The list of payment gateway codes from which a customer can select to perform the payment type: enum: - - e_commerce - - payment_request + - e_commerce + - payment_request type: string x-spec-enum-id: ad398830c7970f0a description: |- - The type of the payment transaction. + The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. * `e_commerce` - Ecommerce * `payment_request` - Payment Request + billing_address: + $ref: "#/components/schemas/Address" + branding_options: + allOf: + - $ref: "#/components/schemas/BrandingOptions" + writeOnly: true + description: |- + Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. + + font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" + description: |- + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. + shipping_address: + $ref: "#/components/schemas/ShippingAddress" + agreement: + allOf: + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. amount: type: string - description: The total amount to be charged, including fees. - currency_code: + format: decimal + description: 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 + attachment: type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: + format: uri + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " + attachment_short_url: type: string - description: The fee charged by the payment gateway. - fee_description: + format: uri + readOnly: true + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. + attachment_upload_url: type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - icon: + description: A writable field that accepts an attachment that has already been uploaded to the server. + pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ + billing: type: string - format: uri - description: The svg URL of the icon for the payment method. - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - pg_icons: + readOnly: true + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. + card_acceptance_criteria: allOf: - - $ref: '#/components/schemas/MIDIcon' - description: Represents list of mid icons configured for `pgmid` settings - flow: - type: string - default: ottu_pg - description: |+ - The flow type of the payment method. - - `ottu_pg`: - - **Web SDK**: Directly redirect the payer to the provided `redirect_url` using: `window.location.href = redirect_url`. - - **Mobile SDK**: Open the `redirect_url` directly in a webview. Ensure you append the query string `channel=mobile_sdk` to the end of the URL, taking care with the concatenation if the `redirect_url` already contains other query parameters. + - $ref: "#/components/schemas/CardAcceptanceCriteria" + description: |- + 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. - Common Webview Closing Method (for both `redirect` and `ottu_pg` in Mobile SDK): - Detect the URL redirection by listening to redirects within the webview. When a redirect occurs to the URL `{merchant_id}/b/gw/mobile-sdk-redirect`, close the webview. This indicates that the payment process has completed. After closing the webview, reload the SDK and call the `Retrieve init data API` to display the payment result to the payer. Note: `merchant_id` is the same ID used to build the `Fetch retrieve data API` and is the parameter added in the CheckoutSDK.init method. + **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. - redirect_url: + **Note**: The `card_acceptance_criteria` field is applicable only for direct payments and not for hosted session payments. + checkout_page_url: type: string format: uri - description: 'This field is used for the `ottu_pg` payment flow. When `flow` - is `ottu_pg`, the payer will be directly redirected to this URL. This - field is only present when `flow` is `ottu_pg`. For web integrations: - Use `window.location.href = redirect_url` to redirect the payer to the - specified URL. For mobile SDK integrations: Open the `redirect_url` in - the webview. Upon redirecting to the provided URL, the webview should - be closed and the transaction refreshed using the `Checkout SDK / Retrieve - init data API`. Detect the URL redirection by listening to redirects in - the webview. When a redirect occurs to a URL containing the `merchant_id` - domain, close the webview and reload the SDK after calling the `Retrieve - init data API`.' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - can_save_card: - type: boolean - description: When true, display a checkbox in the SDK for card saving with - this payment method. When false, do not display the checkbox. - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - trandata: - type: string - description: Encrypted transactional data that must be submitted alongside - the CHD (Cardholder Data) when performing a direct payment or saving a - card. This data contains metadata about the payment and enables quick - basic validation without requiring additional calls to the microservice. - direct_payment_url: + readOnly: true + description: Frontend Checkout Url. + maxLength: 2000 + checkout_short_url: type: string format: uri - description: The URL where the encrypted CHD (Cardholder Data) and `trandata` - must be submitted for a direct payment. Before submitting the data, fetch - the RSA public key from the `enc_key_url` and encrypt the CHD. If the - `payment_type` is `one_off`, use this URL. Refer to the OttuPG service - API documentation for details about the encryption process and payload - structure. - direct_save_card_url: + readOnly: true + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. + checkout_url: type: string format: uri - description: The URL where the encrypted CHD (Cardholder Data) and `trandata` - must be submitted for saving a card. Before submission, fetch the RSA - public key from the `enc_key_url` and encrypt the CHD. Use this URL when - the `payment_type` is `save_card`. Refer to the OttuPG service API documentation - for more details on encryption and payload requirements. - enc_key_url: + readOnly: true + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. + company_name: type: string - format: uri - description: The URL to fetch the RSA public key required for encrypting - the CHD (Cardholder Data) before submission to the `direct_payment_url` - or `direct_save_card_url`. Ensure the key is fetched and applied correctly - before encryption and submission. Refer to the OttuPG service API documentation - for detailed encryption instructions. - cvv_required: - type: boolean - default: true - description: 'Controls whether the CVV field is required or optional for - client-side validation. The CVV field should always be displayed to the - user. When `true`, the SDK must enforce client-side validation to ensure - the CVV field is filled before form submission. When `false`, the CVV - field is optional on the client side and the form can be submitted without - it. Note: The backend may still reject the payment and require CVV based - on certain criteria (e.g., card type, card network rules), even when this - flag is `false`. This is expected behavior and the SDK should handle such - backend validation errors appropriately.' - required: - - amount - - billing - - can_save_card - - code - - currency_code - - direct_payment_url - - direct_save_card_url - - enc_key_url - - fee - - fee_description - - icon - - icons - - name - - trandata - - type - OttuPGPymtTxn: - type: object - properties: - session_id: + description: The company name is used for invoice API. + maxLength: 64 + customer_birthdate: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - payment_type: - enum: - - one_off - - auto_debit - - save_card + format: date + title: Customer Date of Birth + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. + customer_email: type: string - x-spec-enum-id: b2ae60f7918918e7 - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" - amount: + format: email + description: 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. + maxLength: 128 + customer_first_name: type: string - readOnly: true - currency: + description: 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. + maxLength: 64 + customer_id: type: string - readOnly: true - description: Currency code for the transaction. - pg_code: + description: 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. + maxLength: 64 + customer_last_name: type: string - readOnly: true - description: PG code to be used for this transaction. A payment transaction - can have onlye one OttuPG code. - operation: - enum: - - purchase - - authorize + description: 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. + maxLength: 64 + customer_phone: type: string - description: |- - * `purchase` - Purchase - * `authorize` - Authorize - x-spec-enum-id: fef9cc64394d1c3e - readOnly: true - language: - enum: - - en - - ar + description: 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. + maxLength: 16 + customer_phone_2: type: string - x-spec-enum-id: ac1757d67890d125 - description: |- - This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. - - * `en` - English - * `ar` - Arabic - reference_number: + title: Customer additional phone + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. + maxLength: 16 + discount_amount: type: string - readOnly: true - callback_url: + format: decimal + description: The fixed amount discount applied to the full invoice amount, including taxes. If set, the discount_percentage field will be set to null. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the `total_excl_tax` field. + discount_percentage: type: string - format: uri - readOnly: true - description: Callback URL to be used by Ottu PG to send payment status updates. - customer: - allOf: - - $ref: '#/components/schemas/Customer' - readOnly: true - shipping_address: - allOf: - - $ref: '#/components/schemas/ShippingAddress' - readOnly: true - billing_address: - allOf: - - $ref: '#/components/schemas/Address' - readOnly: true - order_no: - type: - - string - - 'null' - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - redirect_url: + format: decimal + description: The percentage-based discount applied to the full invoice amount, including taxes. If set, the discount_amount field will be automatically calculated. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the `total_excl_tax` field. + due_datetime: type: string - format: uri - readOnly: true - agreement: - allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - card_acceptance_criteria: - allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' - description: |- - 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. - required: - - amount - - billing_address - - callback_url - - currency - - customer - - operation - - pg_code - - redirect_url - - reference_number - - shipping_address - PGCodeValidation: - type: object - properties: - pg_code: + format: date-time + title: Due date and time + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. + email_recipients: + type: array + items: + type: string + format: email + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. + expiration_time: type: string - maxLength: 50 - required: - - pg_code - PGParams: - type: object - description: Serializer for PaymentTransaction with dynamically generated fields. - properties: - auth_code: {} - card_type: {} - card_holder: {} - cardholder_email: {} - card_expiry_month: {} - card_expiry_year: {} - full_card_expiry: {} - card_number: {} - card_issuer: {} - ref: {} - result: {} - track_id: {} - post_date: {} - transaction_id: {} - payment_id: {} - pg_message: {} - receipt_no: {} - transaction_no: {} - decision: {} - card_expiry: {} - card_details: {} - dcc_payer_amount: {} - dcc_payer_currency: {} - dcc_payer_exchange_rate: {} - rrn: {} - PGPaymentMethods: - type: object - properties: - code: + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. + generate_qr_code: + type: boolean + writeOnly: true + default: false + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. + include_sdk_setup_preload: + type: boolean + writeOnly: true + default: false + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. + initiator_id: + type: integer + title: initiator + description: 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 + invoice_id: + type: integer + readOnly: true + language: + enum: + - en + - ar + type: string + x-spec-enum-id: ac1757d67890d125 + default: en + description: |- + This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. + + * `en` - English + * `ar` - Arabic + notifications: + allOf: + - $ref: "#/components/schemas/Notifications" + title: Notification settings + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. + operation: type: string readOnly: true - description: Indicates the unique code associated with the payment gateway. - This pivotal identifier facilitates transaction initiation through both - the dashboard and API. - name: + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. + order_no: type: string + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + maxLength: 128 + payment_instrument: + $ref: "#/components/schemas/PaymentInstrument" + payment_methods: + allOf: + - $ref: "#/components/schemas/PaymentMethodsForRedirect" readOnly: true - description: Represents the payment gateway internal name defined in Ottu. - is_sandbox: + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. + payment_type: + enum: + - one_off + - auto_debit + - save_card + type: string + x-spec-enum-id: b2ae60f7918918e7 + default: one_off + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 + preload_checkout_page: type: boolean - readOnly: true - description: Indicates whether this payment gateway operates in a sandbox - or production environment. - logo: + writeOnly: true + default: false + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). + product_type: + type: string + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. + maxLength: 128 + qr_code_url: type: string format: uri - wallets: - type: array - items: {} readOnly: true - default: - - ApplePay - - GooglePay - description: Denotes a list of payment services linked with this payment - gateway, such as `GooglePay` and `ApplePay` - default_currency: + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. + redirect_url: type: string + format: uri + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. + maxLength: 2000 + sdk_setup_preload_payload: + allOf: + - $ref: "#/components/schemas/CheckoutSDK" readOnly: true - default: KWD - description: Specifies the default currency code for the payment gateway, - formatted according to ISO 4217. - accepted_currencies: - type: array - items: {} + default: false + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. + session_id: + type: string readOnly: true - default: - - KWD - - USD - description: Indicates a list of default accepted currencies for the payment - gateway, each formatted in accordance with ISO 4217 standards. - operation: + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + settled_pg_code: type: string - description: 'Specifies the processing operation type for the payment method: - either ''authorize'' or ''purchase''. When set to `authorize`, successful - transactions using this payment method will transition to the `authorize` - state. Similarly, if set to `purchase`, they will follow the purchase - flow.' - operations: - type: array - items: {} - default: - - refund - - void readOnly: true - description: Specifies the payment operations that are available for this - payment gateway. - is_tokenizable: + title: Final Payment Gateway + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. + shipping_excl_tax: + type: string + format: decimal + title: Shipping Excl. Tax + description: The cost of shipping for the invoice, excluding taxes. + shipping_incl_tax: + type: string + format: decimal + title: Shipping Incl. Tax + description: The cost of shipping for the invoice, including all applicable taxes. + shipping_method: + type: string + description: The method or service used for shipping the items associated with the invoice. + shipping_tax_rate: + type: string + format: decimal + description: "The tax rate applied to the shipping cost, expressed as a percentage. " + shortify_attachment_url: type: boolean - description: This flag indicates whether tokenization is enabled for this - payment gateway. When set to true, it allows for the secure storage of - payment details, enabling future transactions without the need for re-entering - payment information. - auto_debit_enabled: + writeOnly: true + default: false + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. + shortify_checkout_url: type: boolean - description: This flag indicates whether auto-debit operation enabled or - not. - tags: - type: array - items: - enum: - - e_commerce - - crm - - pos - - invoicing - - subscriptions - - marketplace - - mobile_app - - ticket_booking - - donations - - government - - education - - healthcare - - insurance - - logistics - - hospitality - - real_estate - - retail - - telecom - - utilities - - demo - type: string - description: |- - * `e_commerce` - e_commerce - * `crm` - crm - * `pos` - pos - * `invoicing` - invoicing - * `subscriptions` - subscriptions - * `marketplace` - marketplace - * `mobile_app` - mobile_app - * `ticket_booking` - ticket_booking - * `donations` - donations - * `government` - government - * `education` - education - * `healthcare` - healthcare - * `insurance` - insurance - * `logistics` - logistics - * `hospitality` - hospitality - * `real_estate` - real_estate - * `retail` - retail - * `telecom` - telecom - * `utilities` - utilities - * `demo` - demo - x-spec-enum-id: b366021a7a7a68c9 + writeOnly: true + default: false + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. + state: + enum: + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod + type: string + x-spec-enum-id: caee163196dbc11f readOnly: true - description: Business vertical tags assigned to this payment method. - required: - - accepted_currencies - - auto_debit_enabled - - code - - default_currency - - is_sandbox - - is_tokenizable - - logo - - name - - operation - - operations - - tags - - wallets - PaginatedRefundTransactionList: - type: object - properties: - count: - type: integer - nullable: false - previous: + description: |- + The current state of the payment transaction, it helps to understand the progress of the payment. + + * `created` - Created + * `pending` - Pending + * `attempted` - Attempted + * `authorized` - Authorized + * `paid` - Paid + * `failed` - Failed + * `canceled` - Canceled + * `expired` - Expired + * `invalided` - Invalided + * `refunded` - Refunded + * `cod` - Cash on Delivery + status: + enum: + - sent + - paid + - overdue + - canceled type: string - nullable: true - next: + x-spec-enum-id: c131c51a82b6f22a + readOnly: true + description: |- + Current status of the invoice. Can be one of the following: `sent`, `paid`, `overdue`, `canceled`. + + * `sent` - Sent + * `paid` - Paid + * `overdue` - Overdue + * `canceled` - Canceled + subtotal: type: string - nullable: true - results: - type: array - items: - $ref: '#/components/schemas/RefundTransaction' - PaginatedReportAPIListList: - type: object - required: - - count - - results - properties: - count: - type: integer - example: 123 - next: + format: decimal + description: Sum of total_incl_tax's of all invoice items. + tax_amount: type: string - nullable: true - format: uri - example: http://api.example.org/accounts/?offset=400&limit=100 - previous: + format: decimal + description: The total amount of tax applied to the invoice. + tax_rate: type: string - nullable: true - format: uri - example: http://api.example.org/accounts/?offset=200&limit=100 - results: - type: array - items: - $ref: '#/components/schemas/ReportAPIList' - PaginatedTransactionMetadataResponseList: - type: object - properties: - count: - type: integer - nullable: false - previous: + format: decimal + title: Tax + description: The tax rate applied to the invoice, expressed as a percentage. + total_excl_tax: type: string - nullable: true - next: + format: decimal + title: Total Excl. Tax + description: The total amount of the invoice, excluding taxes. + total_incl_tax: type: string - nullable: true - results: - type: array - items: - $ref: '#/components/schemas/TransactionMetadataResponse' - PaginatedUnifiedUIInvoiceList: - type: object - properties: - count: - type: integer - nullable: false - previous: + format: decimal + title: Total Incl. Tax + description: The total amount of the invoice, including all applicable taxes. + unit_code: type: string - nullable: true - next: + writeOnly: true + title: Unit + description: The slug of the unit to be used for the transaction. + vendor_name: type: string - nullable: true - results: - type: array - items: - $ref: '#/components/schemas/UnifiedUIInvoice' - ParentToken: - type: object - properties: - token: - allOf: - - $ref: '#/components/schemas/ApplePayToken' - description: Contains the core Apple Pay token details used for processing - the payment. Includes the encrypted payment data, payment method metadata, - and the transaction identifier. + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. + maxLength: 64 + webhook_url: + type: string + format: uri + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " + maxLength: 2000 required: - - token - PatchedCheckoutPATCHRequest: + - attachment_short_url + - billing + - checkout_page_url + - checkout_short_url + - checkout_url + - currency_code + - due_date + - invoice_id + - invoice_items + - invoice_number + - operation + - payment_methods + - pg_codes + - qr_code_url + - sdk_setup_preload_payload + - session_id + - settled_pg_code + - state + - status + - type + InvoicePOSTResponse: type: object description: |- - Serializer to work with PaymentTransaction instances. - - Also uses request data from other serializers to save into PaymentTransaction db table: + Serializer class for `Invoice` instances, inheriting from `BaseInvoiceSerializer` and + `CheckoutSerializer`. It provides methods for creating invoices, invoice items, and transactions. properties: - amount: - type: string - format: decimal - description: 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 currency_code: type: string - description: 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. + description: 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. + due_date: + type: string + format: date + description: The date by which the customer is expected to make payment for the invoice. + invoice_items: + type: array + items: + $ref: "#/components/schemas/InvoiceItem" + description: The list of items for the invoice. + invoice_number: + type: string + description: A unique identifier for the invoice, typically used for tracking and referencing purposes. + maxLength: 255 pg_codes: type: array items: type: string title: Gateway - description: The list of payment gateway codes from which a customer can - select to perform the payment or authorization. + description: The list of payment gateway codes from which a customer can select to perform the payment type: enum: - - e_commerce - - payment_request + - e_commerce + - payment_request type: string x-spec-enum-id: ad398830c7970f0a description: |- @@ -14976,62 +6651,63 @@ components: * `e_commerce` - Ecommerce * `payment_request` - Payment Request billing_address: - $ref: '#/components/schemas/Address' + $ref: "#/components/schemas/Address" branding_options: allOf: - - $ref: '#/components/schemas/BrandingOptions' + - $ref: "#/components/schemas/BrandingOptions" writeOnly: true description: |- Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" + description: |- + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. shipping_address: - $ref: '#/components/schemas/ShippingAddress' + $ref: "#/components/schemas/ShippingAddress" agreement: allOf: - - $ref: '#/components/schemas/Agreement' - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. + amount: + type: string + format: decimal + description: 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 attachment: type: string format: uri - description: 'A writable field that accepts an attachment file to be included - in email notifications sent to the customer regarding their payment, and - also be available for download on the checkout page. This field may be - used to provide the customer with additional information or documentation - related to their purchase. The value of this field should be a file object. - Upon successful submission, the API will return the URL for downloading - the attached file. ' + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " attachment_short_url: type: string format: uri readOnly: true - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. attachment_upload_url: type: string - description: A writable field that accepts an attachment that has already - been uploaded to the server. + description: A writable field that accepts an attachment that has already been uploaded to the server. pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ billing: type: string readOnly: true - description: Detailed billing information including formatted amounts for - display and raw values for processing. Contains both the total transaction - amount and any applicable fees with their respective currency codes and - labels. + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. card_acceptance_criteria: allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' + - $ref: "#/components/schemas/CardAcceptanceCriteria" description: |- 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. @@ -15048,123 +6724,90 @@ components: type: string format: uri readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. This field is only available - if the `shortify_checkout_url` field is set to True. + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. checkout_url: type: string format: uri readOnly: true - description: URL that directs the customer to the Ottu Checkout Page where - they can see the payment details and available payment methods for the - transaction. If you need to share the payment link over SMS or WhatsApp, - use `checkout_short_url` instead. + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. + company_name: + type: string + description: The company name is used for invoice API. + maxLength: 64 customer_birthdate: type: string format: date title: Customer Date of Birth - description: Customer's date of birth in YYYY-MM-DD format.This field can - be used for age verification or compliance purposes during payment processing. + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. customer_email: type: string format: email - description: 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. + description: 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. maxLength: 128 customer_first_name: type: string - description: 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. + description: 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. maxLength: 64 customer_id: type: string - description: 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. + description: 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. maxLength: 64 customer_last_name: type: string - description: 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. + description: 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. maxLength: 64 customer_phone: type: string - description: 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. + description: 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. maxLength: 16 customer_phone_2: type: string title: Customer additional phone - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. maxLength: 16 + discount_amount: + type: string + format: decimal + description: The fixed amount discount applied to the full invoice amount, including taxes. If set, the discount_percentage field will be set to null. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the `total_excl_tax` field. + discount_percentage: + type: string + format: decimal + description: The percentage-based discount applied to the full invoice amount, including taxes. If set, the discount_amount field will be automatically calculated. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the `total_excl_tax` field. due_datetime: type: string format: date-time title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. email_recipients: type: array items: type: string format: email - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. expiration_time: type: string - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - extra: - allOf: - - $ref: '#/components/schemas/ExtraInner' - description: The extra information for the payment details, which the merchant - has sent it in key value form. + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. generate_qr_code: type: boolean writeOnly: true default: false - description: If set to true, the `qr_code_url` field will be present in - the response. Upon scanning it, the customer will be redirected to the - checkout_url, which is the Ottu Checkout page. + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. include_sdk_setup_preload: type: boolean writeOnly: true default: false - description: Set this to true to include the 'sdk_setup_preload_payload' - payload in the API response. This payload is only generated and added - when this parameter is explicitly set to true. By default, it is false - and the 'sdk_setup_preload_payload' payload will not be included. + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. initiator_id: type: integer title: initiator - description: 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 + description: 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 + invoice_id: + type: integer + readOnly: true language: enum: - - en - - ar + - en + - ar type: string x-spec-enum-id: ac1757d67890d125 default: en @@ -15175,145 +6818,126 @@ components: * `ar` - Arabic notifications: allOf: - - $ref: '#/components/schemas/Notifications' + - $ref: "#/components/schemas/Notifications" title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. operation: type: string readOnly: true - description: Specifies the type of operation to be performed by the payment - gateway. If set to `purchase`, the payment source will be directly charged. - If set to `authorize`, the payment source will only be authorized and - the actual charge will be made at a later time. + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. order_no: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. maxLength: 128 payment_instrument: - $ref: '#/components/schemas/PaymentInstrument' + $ref: "#/components/schemas/PaymentInstrument" payment_methods: allOf: - - $ref: '#/components/schemas/PaymentMethodsForRedirect' + - $ref: "#/components/schemas/PaymentMethodsForRedirect" readOnly: true - description: An array containing all the payment methods derived from the - `pg_codes` input. Each object in the array contains information about - a single payment gateway, including its icon and the `redirect_url` that - will redirect the customer to the payment gateway's payment page. + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. payment_type: enum: - - one_off - - auto_debit - - save_card + - one_off + - auto_debit + - save_card type: string x-spec-enum-id: b2ae60f7918918e7 default: one_off - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 preload_checkout_page: type: boolean writeOnly: true default: false - description: Pre-populate checkout page cache on transaction creation (POST - only). Improves performance when clients immediately poll for the checkout - page after creation. Ignored on updates (PATCH/PUT) - cache is automatically - invalidated on any update. The cache expires based on the transaction's - expiration time (max 1 hour). + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). product_type: type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. maxLength: 128 qr_code_url: type: string format: uri readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. redirect_url: type: string format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. maxLength: 2000 sdk_setup_preload_payload: allOf: - - $ref: '#/components/schemas/CheckoutSDK' + - $ref: "#/components/schemas/CheckoutSDK" readOnly: true default: false - description: A JSON object containing preloaded data required to initialize - the checkout interface.This includes essential details such as customer - information, available payment methods.and specific transaction details, - all formatted according to the Checkout SDK's initialization specifications.This - field streamlines the checkout process by providing necessary information - upfront.enhancing user experience and efficiency. + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. session_id: type: string readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. settled_pg_code: type: string readOnly: true title: Final Payment Gateway - description: The code of the payment gateway used for completing the transaction. - This field indicates the specific gateway that processed and settled the - payment, providing clarity on which payment service was ultimately utilized - for this transaction. + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. + shipping_excl_tax: + type: string + format: decimal + title: Shipping Excl. Tax + description: The cost of shipping for the invoice, excluding taxes. + shipping_incl_tax: + type: string + format: decimal + title: Shipping Incl. Tax + description: The cost of shipping for the invoice, including all applicable taxes. + shipping_method: + type: string + description: The method or service used for shipping the items associated with the invoice. + shipping_tax_rate: + type: string + format: decimal + description: "The tax rate applied to the shipping cost, expressed as a percentage. " shortify_attachment_url: type: boolean writeOnly: true default: false - description: If set to True, the URL of the uploaded attachment will be - shortened using a URL shortener service. This should be used when sharing - the attachment URL via SMS or WhatsApp. + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. shortify_checkout_url: type: boolean writeOnly: true default: false - description: If set to True, the checkout URL will be shortened using a - URL shortener service. This should be used when sharing the payment URL - via SMS or WhatsApp. + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. state: enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod type: string x-spec-enum-id: caee163196dbc11f readOnly: true @@ -15331,2316 +6955,1093 @@ components: * `invalided` - Invalided * `refunded` - Refunded * `cod` - Cash on Delivery - unit_code: - type: string - writeOnly: true - title: Unit - description: The slug of the unit to be used for the transaction. - vendor_name: - type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - webhook_url: - type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - maxLength: 2000 - PayApplePay: - type: object - description: Handles the incoming Apple Pay payment request - properties: - code: - type: string - description: The unique code identifying the payment gateway configuration - (PGMID) to be used for processing this payment. - amount: - type: string - description: 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 and paid via device payment. - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - apple_pay_payload: - allOf: - - $ref: '#/components/schemas/ApplePayload' - description: The Apple Pay payment payload containing the encrypted token - data returned by Apple. This includes the payment method, transaction - identifier, encrypted payment data, and cryptographic headers. - required: - - amount - - apple_pay_payload - - code - - session_id - PayGooglePay: - type: object - description: Handle incoming payment data from Google Pay SDK client. - properties: - code: - type: string - description: The unique code identifying the payment gateway configuration - (PGMID) to be used for processing this payment. - amount: - type: string - description: 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 and paid via device payment. - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - google_pay_payload: - allOf: - - $ref: '#/components/schemas/GooglePayPaymentData' - description: GooglePay payment data received from GooglePay. - required: - - amount - - code - - google_pay_payload - - session_id - Payment: - type: object - description: |- - This Payment models its used solely for PaymentTransaction detail page. - Cannot be instantiated without an instance of PaymentTransaction. - properties: - payment_url: - type: string - format: url - readOnly: true - id: - type: integer - readOnly: true - title: Internal ID - description: This field is an automatically generated internal identifier - for each payment transaction. This unique and sequential ID makes it easy - to reference and manage individual transactions within the system. - state: + status: enum: - - created - - pending - - attempted - - authorized - - paid - - failed - - canceled - - expired - - invalided - - refunded - - cod - - refund_queued - - refund_rejected - - voided - type: string - x-spec-enum-id: a4680147d8c166ee + - sent + - paid + - overdue + - canceled + type: string + x-spec-enum-id: c131c51a82b6f22a readOnly: true description: |- - The current state of the payment transaction, it helps to understand the progress of the payment. + Current status of the invoice. Can be one of the following: `sent`, `paid`, `overdue`, `canceled`. - * `created` - Created - * `pending` - Pending - * `attempted` - Attempted - * `authorized` - Authorized + * `sent` - Sent * `paid` - Paid - * `failed` - Failed + * `overdue` - Overdue * `canceled` - Canceled - * `expired` - Expired - * `invalided` - Invalided - * `refunded` - Refunded - * `cod` - Cash on Delivery - * `refund_queued` - Refund Queued - * `refund_rejected` - Refund Rejected - * `voided` - Voided - type: - enum: - - e_commerce - - payment_request - - bulk - - catalogue - - customer_payment - - event - - food_ordering - - iata - - real_estate - type: string - x-spec-enum-id: b2b79580b4e2b976 - readOnly: true - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - E-Commerce - * `payment_request` - Payment request - * `bulk` - Bulk Payment Request - * `catalogue` - Catalogue purchase - * `customer_payment` - Customer payment - * `event` - Event management and booking - * `food_ordering` - Food ordering - * `iata` - IATA - * `real_estate` - Real Estate - amount: - type: string - description: 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 - maxLength: 24 - currency_code: - enum: - - AED - - AFN - - ALL - - AMD - - ANG - - AOA - - ARS - - AUD - - AWG - - AZN - - BAM - - BBD - - BDT - - BGN - - BHD - - BIF - - BMD - - BND - - BOB - - BOV - - BRL - - BSD - - BTN - - BWP - - BYN - - BZD - - CAD - - CDF - - CHE - - CHF - - CHW - - CLF - - CLP - - CNY - - COP - - COU - - CRC - - CUC - - CUP - - CVE - - CZK - - DJF - - DKK - - DOP - - DZD - - EGP - - ERN - - ETB - - EUR - - FJD - - FKP - - GBP - - GEL - - GHS - - GIP - - GMD - - GNF - - GTQ - - GYD - - HKD - - HNL - - HRK - - HTG - - HUF - - IDR - - ILS - - INR - - IQD - - IRR - - ISK - - JMD - - JOD - - JPY - - KES - - KGS - - KHR - - KMF - - KPW - - KRW - - KWD - - KYD - - KZT - - LAK - - LBP - - LKR - - LRD - - LSL - - LYD - - MAD - - MDL - - MGA - - MKD - - MMK - - MNT - - MOP - - MRU - - MUR - - MVR - - MWK - - MXN - - MXV - - MYR - - MZN - - NAD - - NGN - - NIO - - NOK - - NPR - - NZD - - OMR - - PAB - - PEN - - PGK - - PHP - - PKR - - PLN - - PYG - - QAR - - RON - - RSD - - RUB - - RWF - - SAR - - SBD - - SCR - - SDG - - SEK - - SGD - - SHP - - SLE - - SLL - - SOS - - SRD - - SSP - - STN - - SVC - - SYP - - SZL - - THB - - TJS - - TMT - - TND - - TOP - - TRY - - TTD - - TWD - - TZS - - UAH - - UGX - - USD - - USN - - UYI - - UYU - - UYW - - UZS - - VED - - VES - - VND - - VUV - - WST - - XAF - - XAG - - XAU - - XBA - - XBB - - XBC - - XBD - - XCD - - XDR - - XOF - - XPD - - XPF - - XPT - - XSU - - XTS - - XUA - - XXX - - YER - - ZAR - - ZMW - - ZWL - type: string - x-spec-enum-id: 1314c690acf1c093 - description: |- - 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. - - * `AED` - AED - * `AFN` - AFN - * `ALL` - ALL - * `AMD` - AMD - * `ANG` - ANG - * `AOA` - AOA - * `ARS` - ARS - * `AUD` - AUD - * `AWG` - AWG - * `AZN` - AZN - * `BAM` - BAM - * `BBD` - BBD - * `BDT` - BDT - * `BGN` - BGN - * `BHD` - BHD - * `BIF` - BIF - * `BMD` - BMD - * `BND` - BND - * `BOB` - BOB - * `BOV` - BOV - * `BRL` - BRL - * `BSD` - BSD - * `BTN` - BTN - * `BWP` - BWP - * `BYN` - BYN - * `BZD` - BZD - * `CAD` - CAD - * `CDF` - CDF - * `CHE` - CHE - * `CHF` - CHF - * `CHW` - CHW - * `CLF` - CLF - * `CLP` - CLP - * `CNY` - CNY - * `COP` - COP - * `COU` - COU - * `CRC` - CRC - * `CUC` - CUC - * `CUP` - CUP - * `CVE` - CVE - * `CZK` - CZK - * `DJF` - DJF - * `DKK` - DKK - * `DOP` - DOP - * `DZD` - DZD - * `EGP` - EGP - * `ERN` - ERN - * `ETB` - ETB - * `EUR` - EUR - * `FJD` - FJD - * `FKP` - FKP - * `GBP` - GBP - * `GEL` - GEL - * `GHS` - GHS - * `GIP` - GIP - * `GMD` - GMD - * `GNF` - GNF - * `GTQ` - GTQ - * `GYD` - GYD - * `HKD` - HKD - * `HNL` - HNL - * `HRK` - HRK - * `HTG` - HTG - * `HUF` - HUF - * `IDR` - IDR - * `ILS` - ILS - * `INR` - INR - * `IQD` - IQD - * `IRR` - IRR - * `ISK` - ISK - * `JMD` - JMD - * `JOD` - JOD - * `JPY` - JPY - * `KES` - KES - * `KGS` - KGS - * `KHR` - KHR - * `KMF` - KMF - * `KPW` - KPW - * `KRW` - KRW - * `KWD` - KWD - * `KYD` - KYD - * `KZT` - KZT - * `LAK` - LAK - * `LBP` - LBP - * `LKR` - LKR - * `LRD` - LRD - * `LSL` - LSL - * `LYD` - LYD - * `MAD` - MAD - * `MDL` - MDL - * `MGA` - MGA - * `MKD` - MKD - * `MMK` - MMK - * `MNT` - MNT - * `MOP` - MOP - * `MRU` - MRU - * `MUR` - MUR - * `MVR` - MVR - * `MWK` - MWK - * `MXN` - MXN - * `MXV` - MXV - * `MYR` - MYR - * `MZN` - MZN - * `NAD` - NAD - * `NGN` - NGN - * `NIO` - NIO - * `NOK` - NOK - * `NPR` - NPR - * `NZD` - NZD - * `OMR` - OMR - * `PAB` - PAB - * `PEN` - PEN - * `PGK` - PGK - * `PHP` - PHP - * `PKR` - PKR - * `PLN` - PLN - * `PYG` - PYG - * `QAR` - QAR - * `RON` - RON - * `RSD` - RSD - * `RUB` - RUB - * `RWF` - RWF - * `SAR` - SAR - * `SBD` - SBD - * `SCR` - SCR - * `SDG` - SDG - * `SEK` - SEK - * `SGD` - SGD - * `SHP` - SHP - * `SLE` - SLE - * `SLL` - SLL - * `SOS` - SOS - * `SRD` - SRD - * `SSP` - SSP - * `STN` - STN - * `SVC` - SVC - * `SYP` - SYP - * `SZL` - SZL - * `THB` - THB - * `TJS` - TJS - * `TMT` - TMT - * `TND` - TND - * `TOP` - TOP - * `TRY` - TRY - * `TTD` - TTD - * `TWD` - TWD - * `TZS` - TZS - * `UAH` - UAH - * `UGX` - UGX - * `USD` - USD - * `USN` - USN - * `UYI` - UYI - * `UYU` - UYU - * `UYW` - UYW - * `UZS` - UZS - * `VED` - VED - * `VES` - VES - * `VND` - VND - * `VUV` - VUV - * `WST` - WST - * `XAF` - XAF - * `XAG` - XAG - * `XAU` - XAU - * `XBA` - XBA - * `XBB` - XBB - * `XBC` - XBC - * `XBD` - XBD - * `XCD` - XCD - * `XDR` - XDR - * `XOF` - XOF - * `XPD` - XPD - * `XPF` - XPF - * `XPT` - XPT - * `XSU` - XSU - * `XTS` - XTS - * `XUA` - XUA - * `XXX` - XXX - * `YER` - YER - * `ZAR` - ZAR - * `ZMW` - ZMW - * `ZWL` - ZWL - non_default_customer_email: - type: string - format: email - readOnly: true - title: Customer email - description: The email address of the customer. - non_master_unit_config: - type: string - readOnly: true - title: Unit - extra: - $ref: '#/components/schemas/ExtraInner' - order_no: - type: - - string - - 'null' - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - maxLength: 128 - customer_first_name: - type: string - description: 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. - maxLength: 64 - customer_last_name: - type: string - description: 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. - maxLength: 64 - customer_phone: - type: string - description: 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. - maxLength: 32 - customer_billing_address: - allOf: - - $ref: '#/components/schemas/CustomerBillingAddress' - readOnly: true - description: Represents the billing address of the customer, which will - be used for the payment transaction. This information might be used by - the payment gateway to verify the identity of the customer. It can be - displayed on the payment page, invoice, receipt, email, etc. - email_recipients: - type: string - description: A comma-separated list of email addresses for internal recipients - who will receive customer emails. These recipients will be included in - email notifications sent to the customer regarding their payment. - vendor_name: - type: string - description: The name of the vendor or merchant associated with this payment. - This field may be used for accounting and reporting purposes. - maxLength: 64 - due_date: - type: - - string - - 'null' - format: date - product_type: - type: string - description: The type of product or service being purchased. This field - may be used for tracking and reporting purposes. - maxLength: 128 - attachment: - type: - - string - - 'null' - format: uri - description: An optional attachment that will be included in email notifications - sent to the customer regarding their payment, and also be available for - download on the checkout page. This field may be used to provide the customer - with additional information or documentation related to their purchase. - attachment_short_url: - type: string - format: uri - description: A short URL that links to the attachment associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access the attachment. - maxLength: 2000 - qr_code_url: - type: string - format: uri - readOnly: true - description: A QR code that, when scanned, redirects to the checkout page - for this payment. This QR code may be displayed on invoices, receipts, - or other documents to allow customers to easily access the checkout page - and make a payment. This parameter is only present when `generate_qr_code` - is set to true. - session_id: - type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - created: - type: string - format: date-time - readOnly: true - modified: - type: string - format: date-time - readOnly: true - state_changed_at: - type: string - format: date-time - readOnly: true - description: A timestamp indicating when the state of this payment transaction - was last updated. This field may be used to track changes in the state - of the payment transaction over time. - invalidation_reason: - type: string - readOnly: true - description: If the payment transaction was invalidated, this field contains - the reason for it. - initiator: - allOf: - - $ref: '#/components/schemas/Initiator' - readOnly: true - shortify_checkout_url: - type: boolean - default: false - description: If enabled, the checkout URL will be shortened using the configured - URL shortener. - short_url: - type: string - format: uri - readOnly: true - description: A short URL link that, when opened, redirects to the checkout - page for this payment. This URL may be shared with the customer to allow - them to easily access and complete the payment. - maxLength: 200 - unit_config: - allOf: - - $ref: '#/components/schemas/Unit' - title: Unit - notifications: - title: Notification settings - description: A JSON field that contains the notification settings for this - payment transaction, including SMS and email notifications, as well as - the events for which they will be sent (e.g., 'created', 'paid', 'refund', - 'canceled', etc.). This field may be used to configure and customize the - notifications sent to customers and internal recipients throughout the - payment process. - gateway_code: + subtotal: type: string - readOnly: true - description: Represents the payment gateway code that was used to perform - the payment or authorization. - maxLength: 16 - pg_codes: - title: Payment Gateway Codes - description: The list of payment gateway codes from which a customer can - select to perform the payment or authorization. - payment_service: + format: decimal + description: Sum of total_incl_tax's of all invoice items. + tax_amount: type: string - readOnly: true - description: The payment service the customer has used to make the payment, - such as Apple Pay, Samsung Pay, Google Pay, or another payment service. - This field may be used to track the payment method used by the customer - and to help with accounting and reporting. - maxLength: 32 - service_code: + format: decimal + description: The total amount of tax applied to the invoice. + tax_rate: type: string - readOnly: true - title: Payment service code - description: The service code is used to identify the payment service that - was used to perform the payment or authorization. - maxLength: 16 - operation: - enum: - - purchase - - authorize + format: decimal + title: Tax + description: The tax rate applied to the invoice, expressed as a percentage. + total_excl_tax: type: string - x-spec-enum-id: fef9cc64394d1c3e - readOnly: true - description: |- - Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. - - * `purchase` - Purchase - * `authorize` - Authorize - is_sandbox: - type: boolean - readOnly: true - title: Is Sandbox? - description: Indicates whether the operation was performed in a test environment - or not. - is_amount_editable: - type: boolean - readOnly: true - title: Editable amount - description: This field specifies whether the customer can modify the payment - amount and choose the amount he wishes to pay. - settled_amount: - type: number - format: double - description: The paid or authorized amount in the original currency, excluding - any fees or charges. - readOnly: true - paid_amount: - oneOf: - - type: number - format: double - - type: string - description: Total paid amount in the original currency, with fee. This - calculation might be the result of currency exchange if it was paid in - different currency. - readOnly: true - fee: + format: decimal + title: Total Excl. Tax + description: The total amount of the invoice, excluding taxes. + total_incl_tax: type: string - description: Fee represents the amount paid by the customer in the currency - they used for the payment. This currency may differ from the currency - of the transaction. - readOnly: true - refunded_amount: - type: number - format: double - description: The total amount which has been refunded back to the customer - in the original currency, including any fees or charges that were applied - to the transaction. - readOnly: true - voided_amount: - type: number - format: double - description: The total amount which has been voided back to the customer - in the original currency, including any fees or charges that were applied - to the transaction. - readOnly: true - delivery_fee: + format: decimal + title: Total Incl. Tax + description: The total amount of the invoice, including all applicable taxes. + unit_code: type: string - readOnly: true - description: This field represents the delivery fee for the order. It is - applicable only for catalogue transactions. - maxLength: 120 - webhook_url: + writeOnly: true + title: Unit + description: The slug of the unit to be used for the transaction. + vendor_name: type: string - format: uri - description: 'URL where the payment result will be sent via a POST request - after the customer has completed the payment session. The payment result - will be included in the request body. ' - redirect_url: + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. + maxLength: 64 + webhook_url: type: string format: uri - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " maxLength: 2000 - capture_delivery_location: - type: boolean - title: Capture delivery coordinates - description: 'By enabling this, you will ask for user''s delivery location - on a map. ' - capture_delivery_address: + required: + - attachment_short_url + - billing + - checkout_page_url + - checkout_short_url + - checkout_url + - currency_code + - due_date + - invoice_id + - invoice_items + - invoice_number + - operation + - payment_methods + - pg_codes + - qr_code_url + - sdk_setup_preload_payload + - session_id + - settled_pg_code + - state + - status + - type + Loyalty: + type: object + properties: + enabled: type: boolean - description: By enabling this, you will ask for user's address. If enabled, - capture delivery coordinates should also be active. - agreement: - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." - customer_email: - type: string - description: 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. - maxLength: 128 - customer_additional_phone: - type: string - description: The customer's additional phone number, if any. This field - can be updated by the customer on the payment page or in the Checkout - SDK. - maxLength: 32 - customer_shipping_address: - title: Shipping address - description: The shipping address of the customer where the product or service - will be delivered to. This information might be used for fraud prevention - and it can be displayed on the invoice, receipt, email and other communication - sent to the customer. - card_acceptance_criteria: description: |- - 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. + Required. Set to `true` to mark this transaction as eligible for loyalty rewards. When `true` AND the pg_code used to settle the transaction is linked to an active wallet service whose provider declares the `POST_PURCHASE_REWARD` capability (currently STC Qitaf), the customer earns points on payment success. - **Note**: The `card_acceptance_criteria` field is applicable only for direct payments and not for hosted session payments. - seen_at: - type: - - string - - 'null' - format: date-time - readOnly: true - description: A timestamp indicating when the payment link associated with - this payment was seen or opened by the customer or any other guest user. - This field may be used to track when payment links have been accessed. - email_seen_at: - type: - - string - - 'null' - format: date-time - readOnly: true - description: A timestamp indicating when the email notification associated - with this payment was seen or opened by the customer or any other guest - user. This field may be used to track when email notifications have been - viewed. - due_datetime: - type: - - string - - 'null' - format: date-time - title: Due date and time - description: The date and time by which the payment is due. This field may - be used to help remind the customer to complete the payment before the - due date. - notification_set: - allOf: - - $ref: '#/components/schemas/NotificationSet' - readOnly: true - expiration_time: - type: - - string - - 'null' - description: If defined, any payment transactions created more than the - specified period of time ago will be invalidated or expired if the customer - attempts to complete them. By default, this expiration period is set to - 24 hours from the time of transaction creation. This feature helps ensure - that payment transactions are processed promptly. - shortify_attachment_url: - type: boolean - default: false - description: If enabled, the attachment URL will be shortened using the - configured URL shortener. - receipt_short_url: + Setting `false` (or omitting the entire `loyalty` object) disables rewards for this transaction even if a wallet service is configured. + reference: type: string + description: Optional merchant-side loyalty reference (campaign ID, program code, etc.). Forwarded to the loyalty provider as the external reference for this reward operation. Defaults to the transaction's `order_no` when omitted. + maxLength: 128 + metadata: + type: object + additionalProperties: {} + description: Optional opaque key/value pairs forwarded to the loyalty provider as additional context. Treated as a black box by Ottu — useful for attaching merchant-specific tags such as campaign IDs, segment codes, or audit references. + required: + - enabled + MIDIcon: + type: object + description: Serializer for PG logo with custom logo URL resolution. + properties: + svg: + type: + - string + - "null" format: uri readOnly: true - description: A short URL that links to the receipt associated with this - payment. This URL may be included in email/sms notifications sent to the - customer regarding their payment or displayed on the checkout page to - allow the customer to easily access their receipt. - maxLength: 2000 - invoice_pdf_url: + description: "`Optional` field. Upload a logo in SVG format only. If provided and no WebP image is uploaded, a WebP version will be automatically generated. Only .svg files are accepted. Do not upload any other format." + webp: type: string - format: uri - readOnly: true - data: - readOnly: true - description: Used to store useful information for internal purposes - bulk: - allOf: - - $ref: '#/components/schemas/Bulk' - readOnly: true - transaction_log_id: - type: - - integer - - 'null' - maximum: 2147483647 - minimum: 0 - readOnly: true - description: 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. - txns: - type: array - items: - $ref: '#/components/schemas/ChildrenPayment' - readOnly: true - title: Child Transactions - attempts: - type: array - items: - $ref: '#/components/schemas/Attempt' - readOnly: true - notification_triggers: - type: array - items: - $ref: '#/components/schemas/MailLog' - readOnly: true - title: Mail logs - log_entries: - allOf: - - $ref: '#/components/schemas/LogEntry' - readOnly: true - iata_records: - allOf: - - $ref: '#/components/schemas/IATARecord' readOnly: true + description: "`Mandatory` field. This must be provided either by uploading a WebP image directly, or it will be auto-generated from the SVG file (if provided). This field does not accept SVG files — only raster images like PNG or JPEG that will be converted to WebP." + label: + type: string + description: The display name of the logo (translatable in EN and AR). + maxLength: 255 required: - - amount - - attempts - - bulk - - created - - currency_code - - customer_billing_address - - data - - delivery_fee - - email_seen_at - - fee - - gateway_code - - iata_records - - id - - initiator - - invalidation_reason - - invoice_pdf_url - - is_amount_editable - - is_sandbox - - log_entries - - modified - - non_default_customer_email - - non_master_unit_config - - notification_set - - notification_triggers - - operation - - paid_amount - - payment_service - - payment_url - - qr_code_url - - receipt_short_url - - refunded_amount - - seen_at - - service_code - - session_id - - settled_amount - - short_url - - state - - state_changed_at - - transaction_log_id - - txns - - type - - unit_config - - voided_amount - PaymentGatewayInfo: + - label + - svg + - webp + MessageNotification: type: object - description: Information about the payment gateway, accompanied by the response - received from the payment gateway. + description: This serializer is used to validate the lookup fields for the inquiry operation. properties: - pg_code: + order_no: type: string - description: The unique identifier, or `pg_code`, for the payment gateway - that was used to process the payment. This value corresponds to the specific - payment method utilized by the customer, such as `credit-card`. - pg_name: + description: This is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the `order_no` or `session_id` field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned. + maxLength: 128 + session_id: type: string - description: The name of the payment gateway, represented in all lowercase - letters, that was used to perform the payment. This could be one of several - values, such as `kpay` (for KNET), `mpgs`, or `cybersource`. These identifiers - provide a human-readable way to understand the payment mechanism that - was utilized. - pg_response: - type: object - additionalProperties: {} - description: The raw response data that was received directly from the payment - gateway after the transaction attempt. This typically includes transaction - status, transaction identifier, and potentially error messages or additional - data provided by the gateway. + description: Similar to `order_no`, `session_id` is an optional identifier used to specify the payment transaction for the operation. You must provide either `order_no` or `session_id` in order to select the appropriate payment transaction. + maxLength: 128 + channels: + type: array + items: + enum: + - sms + - email + - whatsapp + type: string + description: |- + * `sms` - sms + * `email` - email + * `whatsapp` - whatsapps + x-spec-enum-id: 62ab5ae1260bf392 + description: This field refers to the channels that are desired to be triggered on the payment. The options are `sms`, `email`, `whatsapp`. required: - - pg_code - - pg_name - - pg_response - PaymentInstrument: - oneOf: - - $ref: '#/components/schemas/ApplePayInstrument' - - $ref: '#/components/schemas/GooglePayInstrument' - - $ref: '#/components/schemas/TokenPayInstrument' - - $ref: '#/components/schemas/SamsungPayInstrument' - PaymentLabel: + - channels + MessageNotificationFailure: type: object + description: This serializer is used to validate the lookup fields for the inquiry operation. properties: - payment_type: + order_no: type: string - instalment: - type: integer - description_en: + description: This is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the `order_no` or `session_id` field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned. + maxLength: 128 + session_id: type: string - description_ar: + description: Similar to `order_no`, `session_id` is an optional identifier used to specify the payment transaction for the operation. You must provide either `order_no` or `session_id` in order to select the appropriate payment transaction. + maxLength: 128 + channels: + enum: + - sms + - email + - whatsapp + type: string + description: |- + * `sms` - sms + * `email` - email + * `whatsapp` - whatsapps + x-spec-enum-id: 62ab5ae1260bf392 + result: + enum: + - failed type: string + description: "* `failed` - Failed" + x-spec-enum-id: 8b493f06ef915a3f required: - - description_ar - - description_en - - instalment - - payment_type - PaymentMethod: + - channels + - result + MessageNotificationSuccess: type: object properties: - displayName: - type: string - network: - type: string - type: + message: type: string - required: - - displayName - - network - - type - PaymentMethodData: + default: Customer notified. + NativeApplePaymentErrors: + oneOf: + - $ref: "#/components/schemas/OperationErrorResponse" + - $ref: "#/components/schemas/FieldErrors" + NativeGooglePaymentErrors: + oneOf: + - $ref: "#/components/schemas/OperationErrorResponse" + - $ref: "#/components/schemas/FieldErrors" + NativeGooglePaymentSuccess: + oneOf: + - $ref: "#/components/schemas/SchemaWebhook" + - $ref: "#/components/schemas/IFrame3DSResponse" + - $ref: "#/components/schemas/Redirect3DSResponse" + NativeWalletPaymentErrors: + oneOf: + - $ref: "#/components/schemas/OperationErrorResponse" + - $ref: "#/components/schemas/FieldErrors" + Nested: type: object - description: https://developers.google.com/pay/api/web/reference/response-objects#PaymentMethodData properties: - type: - type: string - description: The type of payment method data. - description: - type: string - description: The description of the payment method. - info: - type: object - additionalProperties: {} - description: The payment method info. - tokenizationData: - type: object - additionalProperties: {} - description: The tokenization data. + field_name: + type: array + items: + type: string + default: To use sms notifications provide the `customer_phone` field. required: - - description - - info - - tokenizationData - - type - PaymentMethods: - oneOf: - - $ref: '#/components/schemas/Redirect' - - $ref: '#/components/schemas/OttuPG' - PaymentMethodsForRedirect: + - field_name + NestedFieldErrors: type: object properties: - code: - type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: - type: string - description: The name of the payment method. - type: - enum: - - e_commerce - - payment_request - type: string - x-spec-enum-id: ad398830c7970f0a - description: |- - The type of the payment transaction. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - amount: - type: string - description: The total amount to be charged, including fees. - currency_code: - type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: - type: string - description: The fee charged by the payment gateway. - fee_description: - type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - icon: - type: string - format: uri - description: The svg URL of the icon for the payment method. - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - pg_icons: - allOf: - - $ref: '#/components/schemas/MIDIcon' - description: Represents list of mid icons configured for `pgmid` settings - flow: - type: string - default: redirect - description: The flow type of the payment method. - redirect_url: - type: - - string - - 'null' - format: uri - description: The URL where the customer should be redirected to perform - the payment. - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. + field_name: + $ref: "#/components/schemas/Nested" required: - - amount - - code - - currency_code - - fee - - fee_description - - icon - - icons - - name - - type - PaymentMethodsRequest: + - field_name + Notification: type: object properties: - plugin: - type: string - description: Payment methods will be curated based on their compatibility - with the specified plugin. - maxLength: 50 - currencies: - type: array - items: {} - description: 'Specify the three-letter ISO 4217 codes representing the desired - currencies. Examples include USD for United States Dollar, EUR for Euro, - and GBP for British Pound Sterling. Example: [''KWD'',''USD'']' - customer_id: - type: string - description: If provided, `customer_payment_methods` will be filtered to - show only those payment methods that have been successfully used with - a paid payment attempts by this customer in the past. - maxLength: 64 - operation: + channel: enum: - - purchase - - authorize + - email + - sms + - whatsapp type: string - x-spec-enum-id: 4e59e52f76e448b3 - description: |- - When specified, the available payment methods will be refined based on their compatibility with the indicated operation. - - * `purchase` - purchase - * `authorize` - authorize - tokenizable: - type: boolean - description: If defined, payment methods will be filtered based on supporting - tokenization and auto-debit action. - auto_debit: - type: boolean - description: If defined, payment methods will be filtered based on supporting - tokenization and auto-debit action. - pg_names: - type: array - items: {} + x-spec-enum-id: 26d97252a367d950 description: |- - When provided, the payment methods will be narrowed down to those that support the specified payment gateway name. Example: ['kpay','mpgs'] + Specify the channel to trigger the notification: sms, email, or WhatsApp. Valid options are: `email`, `sms`, and `whatsapp`. - Available Values:
  • `abapayway` - ABA PayWay

  • `rajhi` - Alrajhi Bank

  • `amazon_pay` - Amazon Pay

  • `bambora` - Bambora

  • `benefit` - Benefit

  • `benefit_pay` - BenefitPay

  • `beyon_money` - BeyonMoney

  • `bookeey` - Bookeey

  • `burgan` - Burgan

  • `cod` - Cash

  • `cbk` - CBK

  • `ccavenues` - Ccavenues

  • `checkoutcom` - checkout.com

  • `cybersource` - CyberSource

  • `csuc` - Cybersource Unified Checkout

  • `dapi` - Dapi

  • `deema` - Deema

  • `doku` - Doku

  • `enet` - Enet

  • `fawry` - Fawry

  • `fiserv` - Fiserv

  • `fss` - FSS

  • `geidea` - Geidea

  • `hesabe` - Hesabe

  • `hyperpay` - HyperPay

  • `kpay` - KNET

  • `moyasar` - Moyasar

  • `mpgs` - MPGS

  • `myfatoorah` - MyFatoorah

  • `ngenius` - N-Genius

  • `nbo` - NBO

  • `omannet` - OmanNet

  • `ottu_pg` - Ottu PG

  • `paymob` - PayMob

  • `payon` - PayOn

  • `paypal` - PayPal

  • `payu_india` - PayU India

  • `qpay` - Qpay

  • `skipcash` - Skip Cash

  • `smart_pay` - SmartPay

  • `sohar` - SoharInternational

  • `stcbahrain` - STC Bahrain

  • `stc_pay` - STC Bank

  • `tabby` - Tabby

  • `taly` - Taly

  • `tamara` - Tamara

  • `tap` - Tap Payments

  • `tess` - Tess Payments

  • `upayments` - UPayments

  • `upg` - UPG

  • `urpay` - URPay
    • - type: + * `email` - Email + * `sms` - SMS + * `whatsapp` - WhatsApp + template_id: + type: string + description: This field is required. It specifies the template to be used for the notification. + to: + type: string + description: Required for all notifications. Must be a valid email address for email notifications, and a valid international phone number for SMS and WhatsApp notifications. + unit_config: + type: integer + description: This field is optional for SMS and email notifications, but it is mandatory for WhatsApp notifications. + language: enum: - - sandbox - - production + - en + - ar type: string - x-spec-enum-id: 1e8a9859ef5c2b8e + x-spec-enum-id: ac1757d67890d125 + default: en description: |- - When specified, the available payment methods will be refined based on their type determining if type is sandbox or production. + Specifies the language for email, SMS, and WhatsApp notifications. The default language is English (en). - * `sandbox` - sandbox - * `production` - production - tags: + * `en` - English + * `ar` - Arabic + cc: type: array items: - enum: - - e_commerce - - crm - - pos - - invoicing - - subscriptions - - marketplace - - mobile_app - - ticket_booking - - donations - - government - - education - - healthcare - - insurance - - logistics - - hospitality - - real_estate - - retail - - telecom - - utilities - - demo type: string - description: |- - * `e_commerce` - e_commerce - * `crm` - crm - * `pos` - pos - * `invoicing` - invoicing - * `subscriptions` - subscriptions - * `marketplace` - marketplace - * `mobile_app` - mobile_app - * `ticket_booking` - ticket_booking - * `donations` - donations - * `government` - government - * `education` - education - * `healthcare` - healthcare - * `insurance` - insurance - * `logistics` - logistics - * `hospitality` - hospitality - * `real_estate` - real_estate - * `retail` - retail - * `telecom` - telecom - * `utilities` - utilities - * `demo` - demo - x-spec-enum-id: b366021a7a7a68c9 - description: 'When provided, the payment methods will be filtered to those - matching any of the specified business vertical tags (OR logic). Example: - [''e_commerce'', ''pos'']' - required: - - plugin - PaymentMethodsResponse: - type: object - properties: - customer_payment_methods: + format: email + description: This field is optional. When provided, it specifies the list of CC recipients for the email notification. + bcc: type: array - items: {} - description: Denotes a collection of payment gateways which used by user - in successful payment attempts. - payment_methods: + items: + type: string + format: email + description: This field is optional. When provided, it specifies the list of BCC recipients for the email notification. + subject: + type: string + description: This field is optional. Use this field to customize the email subject if you don't want to use the one from the template. + body: + type: string + description: "{'This field is optional. If provided, it serves as a fallback template in case the primary template fails to render. This has to be a plain text body of the email.'}" + context: + description: This field is optional. If provided, the context data will be passed to the template engine during rendering. + attachments: type: array items: - $ref: '#/components/schemas/PGPaymentMethods' - description: Provides a comprehensive overview of the available payment - gateways, delineated as distinct payment methods. - PaymentNotificationErrors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/MessageNotificationFailure' - PaymentNotificationResponses: - oneOf: - - $ref: '#/components/schemas/MessageNotificationSuccess' - PaymentOperationErrors: - oneOf: - - $ref: '#/components/schemas/FieldErrors' - - $ref: '#/components/schemas/OperationFailure' - PaymentOperationResponses: - oneOf: - - $ref: '#/components/schemas/InternalOperation' - - $ref: '#/components/schemas/ExternalOperation' - PaymentServices: + $ref: "#/components/schemas/Attachment" + description: This field is optional. Use this field to include file attachments with your email notification. Provide the file data as a base64 encoded string *or* a publicly accessible URL. + trace_id: + type: string + description: This field is optional. A unique identifier for tracking the notification request. Useful for logging and debugging. + maxLength: 60 + tags: + type: array + items: + type: string + description: This field is optional. A list of metadata tags for analytics or categorization purposes. + required: + - channel + - template_id + - to + NotificationErrors: oneOf: - - $ref: '#/components/schemas/ApplePay' - - $ref: '#/components/schemas/GooglePay' - - $ref: '#/components/schemas/STCPay' - - $ref: '#/components/schemas/URPay' - - $ref: '#/components/schemas/SamsungPay' - PaymentSubOptionSDK: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/NotificationFailure" + NotificationFailure: type: object - description: Serializer for payment sub-options in the SDK. properties: - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - title: + detail: type: string - description: The title of the payment method. - maxLength: 100 - value: + result: type: string - description: The value associated with the payment method. - maxLength: 100 + default: failed required: - - icons - - title - - value - PrePaymentCheckResponses: + - detail + NotificationResponses: oneOf: - - $ref: '#/components/schemas/TabbyPrePaymentCheck' - - $ref: '#/components/schemas/TamaraPrePaymentCheck' - - $ref: '#/components/schemas/TalyPrePaymentCheck' - Redirect: + - $ref: "#/components/schemas/NotificationSuccess" + NotificationSuccess: type: object properties: - code: + message: type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: + default: Notification sent. + result: type: string - description: The name of the payment method. - type: + default: success + Notifications: + type: object + properties: + email: + type: array + items: + enum: + - created + - paid + - canceled + - failed + - expired + - authorized + - voided + - refunded + - captured + type: string + description: |- + * `created` - Created + * `paid` - Paid + * `canceled` - Canceled + * `failed` - Failed + * `expired` - Expired + * `authorized` - Authorized + * `voided` - Voided + * `refunded` - Refunded + * `captured` - Captured + x-spec-enum-id: a9456842df943874 + sms: + type: array + items: + enum: + - created + - paid + - canceled + - failed + - expired + - authorized + - voided + - refunded + - captured + type: string + description: |- + * `created` - Created + * `paid` - Paid + * `canceled` - Canceled + * `failed` - Failed + * `expired` - Expired + * `authorized` - Authorized + * `voided` - Voided + * `refunded` - Refunded + * `captured` - Captured + x-spec-enum-id: a9456842df943874 + whatsapp: + type: array + items: + enum: + - created + - paid + - canceled + - failed + - expired + - authorized + type: string + description: |- + * `created` - Created + * `paid` - Paid + * `canceled` - Canceled + * `failed` - Failed + * `expired` - Expired + * `authorized` - Authorized + x-spec-enum-id: 43293338bc4fdb1a + Operation: + type: object + description: |- + Fetch the payment txn based on the order no or session id + also, if the payment txn is not in the accepted state for the + input operation, raise an error + properties: + order_no: + type: string + description: This is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the `order_no` or `session_id` field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned. + maxLength: 128 + session_id: + type: string + description: Similar to `order_no`, `session_id` is an optional identifier used to specify the payment transaction for the operation. You must provide either `order_no` or `session_id` in order to select the appropriate payment transaction. + maxLength: 128 + operation: enum: - - e_commerce - - payment_request + - delete + - cancel + - expire + - refund + - capture + - void type: string - x-spec-enum-id: ad398830c7970f0a description: |- - The type of the payment transaction. - - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request + * `delete` - delete + * `cancel` - cancel + * `expire` - expire + * `refund` - refund + * `capture` - capture + * `void` - void + x-spec-enum-id: 943f8b45fb88fe59 amount: type: string - description: The total amount to be charged, including fees. - currency_code: - type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: - type: string - description: The fee charged by the payment gateway. - fee_description: - type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - icon: - type: string - format: uri - description: The svg URL of the icon for the payment method. - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - pg_icons: - allOf: - - $ref: '#/components/schemas/MIDIcon' - description: Represents list of mid icons configured for `pgmid` settings - flow: - enum: - - redirect - type: string - x-spec-enum-id: ac32c30ac744401d + format: decimal + pattern: ^-?\d{0,13}(?:\.\d{0,3})?$ + description: This field is optional and used to specify the amount you want to action for `refund` and `capture` operations. If not specified, Ottu will attempt to perform the operation on the full amount, or the remaining amount if previous operations have been performed. Keep in mind that `void` operations always concern the full amount; the `amount` field is not considered in this case. The `amount` field can be sent for all operations, but it will only be taken into account for `refund` and `capture` operations. + extra: + type: object + additionalProperties: {} description: |- - The flow type of the payment method. + This field is optional and used to specify additional parameters for the operation. - 1. `redirect`: - - **Web SDK**: After submitting the payload as per `Submit redirect payment method API`, you will receive a `redirect_url`. Redirect the payer to this URL using: `window.location.href = redirect_url`. - - **Mobile SDK**: After submitting the payload, open the received `redirect_url` in a webview. + **IFG**: - = redirect_url`. - - **Mobile SDK**: Open the `redirect_url` directly in a webview. Ensure you append the query string `channel=mobile_sdk` to the end of the URL, taking care with the concatenation if the `redirect_url` already contains other query parameters. + Full Refund Details - Common Webview Closing Method (for both `redirect` and `ottu_pg` in Mobile SDK): - Detect the URL redirection by listening to redirects within the webview. When a redirect occurs to the URL `{merchant_id}/b/gw/mobile-sdk-redirect`, close the webview. This indicates that the payment process has completed. After closing the webview, reload the SDK and call the `Retrieve init data API` to display the payment result from `response object` to the payer. Note: `merchant_id` is the same ID used to build the `Fetch retrieve data API` and is the parameter added in the CheckoutSDK.init method. + For full refund you don't need to use extra key. + Partial Refund Details + For operations involving partial refunds, the extra field allows specifying individual ticket orders along with their corresponding refund amounts. - * `redirect` - Redirect - redirect_url: - type: string - format: uri - description: 'This field is used for the `ottu_pg` payment flow. When `flow` - is `ottu_pg`, the payer will be directly redirected to this URL. This - field is only present when `flow` is `ottu_pg`. For web integrations: - Use `window.location.href = redirect_url` to redirect the payer to the - specified URL. For mobile SDK integrations: Open the `redirect_url` in - the webview. Upon redirecting to the provided URL, the webview should - be closed and the transaction refreshed using the `Checkout SDK / Retrieve - init data API`. Detect the URL redirection by listening to redirects in - the webview. When a redirect occurs to a URL containing the `merchant_id` - domain, close the webview and reload the SDK after calling the `Retrieve - init data API`.' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - can_save_card: - type: boolean - description: When true, display a checkbox in the SDK for card saving with - this payment method. When false, do not display the checkbox. - submit_url: - type: string - format: uri - description: 'When submitting information via POST, the appropriate URL - depends on the `flow` value:`redirect`: The URL is for submitting `payment_methods[index].code`.' - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - required: - - amount - - billing - - can_save_card - - code - - currency_code - - fee - - fee_description - - flow - - icon - - icons - - name - - type - Redirect3DSResponse: - type: object - properties: - status: - type: string - readOnly: true - default: 3DS - description: The payment is in 3DSecure process. Indicates a 3D Secure verification - is required. html must be displayed to the customer in the iframe. - reference_number: - type: string - readOnly: true - description: This is a unique value associated with each payment transaction - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). allowing for multiple reference - numbers per session_id. - form_of_payment: - enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway - type: string - x-spec-enum-id: d21d329ca6d31930 - readOnly: true - description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + This capability ensures precise control over the refund amounts for each ticket within an order. - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean - default: true - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - method: - type: string - readOnly: true - default: redirect - description: The method of 3D Secure verification. - redirect_url: - type: string - format: uri - readOnly: true - description: |- - The URL where the payer shall be redirected for 3D Secure verification. + Key Points - **Platform-specific behavior based on the `channel` HTTP header:** + `passengerDocumentNumber`: It is imperative to include the document number for each ticket involved in the refund operation. This ensures that the refund is accurately applied to the correct tickets within an order. - ### For Web (`web_sdk`): - The payer will be redirected to the payment details page where they can complete the payment process. + `amount`: Alongside each ticket document number, specify the desired refund amount for that ticket and make sure the type of amount is `INT`. - Use the following JavaScript code: - ```javascript - window.location.href = redirect_url; - ``` - The browser will handle all subsequent redirects automatically. + `Excluding Tickets`: If certain tickets within an order should not be refunded, you can specify a refund amount of zero for those tickets. This approach allows for selective refunding within a single order. - ### For Mobile SDK (`mobile_sdk`): - The `redirect_url` should be opened in a WebView. This is the page where the payer will enter their card details. + `Important Note` - - After card details are entered, the payer is redirected to the final payment details page within the WebView. - - You must detect URL changes within the WebView. When a redirect occurs to the URL pattern: - `{merchant_id}/b/gw/mobile-sdk-redirect`, close the WebView. - - This URL indicates the end of the payment process. It will appear as a blank page and should not be shown to the user. - - After closing the WebView, reload the SDK and call the Retrieve Init Data API to present the payment result to the payer. + All tickets intended for refund must be explicitly listed in the refund order details, with their respective refund amounts clearly defined. This requirement ensures comprehensive and error-free processing of partial refunds. - **Important:** - Ensure the `channel` HTTP header is set correctly (`web_sdk` or `mobile_sdk`) to enable the appropriate behavior. Incorrect or missing `channel` headers may result in improper handling of the redirection flow. - order_no: - type: string - readOnly: true - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - session_id: + Example + + check in Request samples there is an example showcasing how to structure the extra field for a partial refund request, including specifying refund amounts for tickets + destination: + enum: + - pg + - wallet type: string - readOnly: true - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. + x-spec-enum-id: a8d72362952c1daf + default: pg + description: |- + Specifies where the refund should be credited. Use `pg` (default) to refund via the original payment gateway, or `wallet` to credit the amount to the customer's wallet balance. The `wallet` option is only available for `refund` operations and requires that the payment method has an active wallet service and the transaction has a `customer_id`. + + * `pg` - pg + * `wallet` - wallet required: - - form_of_payment - - method - - order_no - - redirect_url - - reference_number - - session_id - - status - RefundTransaction: + - operation + OperationErrorResponse: type: object properties: - id: - type: integer - readOnly: true - type: - enum: - - e_commerce - - payment_request - - bulk - - catalogue - - customer_payment - - event - - food_ordering - - iata - - real_estate - type: string - x-spec-enum-id: b2b79580b4e2b976 - description: |- - The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. - - * `e_commerce` - E-Commerce - * `payment_request` - Payment request - * `bulk` - Bulk Payment Request - * `catalogue` - Catalogue purchase - * `customer_payment` - Customer payment - * `event` - Event management and booking - * `food_ordering` - Food ordering - * `iata` - IATA - * `real_estate` - Real Estate - amount: - type: string - readOnly: true - description: The refunded amount for this transaction. - currency_code: + detail: type: string - description: The currency code of the refunded amount (e.g., KWD, USD). - created: + description: A human-readable description providing details about the failure. + maxLength: 255 + result: type: string - format: date-time - description: Date and time when the refund was initiated. - modified: + default: failed + description: Indicates the outcome of the operation. Typically set to 'failed' for error responses. + failed_provider: type: string - format: date-time - description: Date and time when the refund was modified. - state: + description: Wallet cohort errors only. The `provider_code` of the wallet leg whose commit/release failed and triggered the saga rollback. + pg_response: + description: Wallet cohort errors only. Raw response from the failing wallet service so the frontend can surface the upstream error code. + rollback: + description: "Wallet cohort errors only. Compensation report — `{refunded: [...], released: [...], compensation_failures: [...]}` — tells the frontend exactly which legs were reversed." + OperationFailure: + type: object + properties: + detail: type: string - description: Current state of the refund transaction (e.g., refunded, refund_queued, - refund_rejected). - gateway_code: + description: Provides a message associated with the operation, suitable for displaying to the end user. + operation: + enum: + - delete + - cancel + - expire + - refund + - capture + - void + - operation_tracking type: string - readOnly: true - description: The payment gateway code used to process the refund. - track_id: + description: |- + * `delete` - delete + * `cancel` - cancel + * `expire` - expire + * `refund` - refund + * `capture` - capture + * `void` - void + * `operation_tracking` - operation_tracking + x-spec-enum-id: 789f76f0e432d492 + result: + enum: + - failed type: string - readOnly: true - description: Gateway tracking ID returned from the payment gateway. - auth_code: + description: "* `failed` - Failed" + x-spec-enum-id: 8b493f06ef915a3f + required: + - detail + - operation + - result + PGCodeValidation: + type: object + properties: + pg_code: type: string - readOnly: true - description: Authorization code returned from the payment gateway. - product_type: + maxLength: 50 + required: + - pg_code + PGParams: + type: object + description: Serializer for PaymentTransaction with dynamically generated fields. + properties: + auth_code: {} + card_type: {} + card_holder: {} + cardholder_email: {} + card_expiry_month: {} + card_expiry_year: {} + full_card_expiry: {} + card_number: {} + card_issuer: {} + ref: {} + result: {} + track_id: {} + post_date: {} + transaction_id: {} + payment_id: {} + pg_message: {} + receipt_no: {} + transaction_no: {} + decision: {} + card_expiry: {} + card_details: {} + dcc_payer_amount: {} + dcc_payer_currency: {} + dcc_payer_exchange_rate: {} + rrn: {} + PGPaymentMethods: + type: object + properties: + code: type: string readOnly: true - description: Type of the original transaction (e.g., Payment Request, E-Commerce, - Customer Payment, Bulk). - reference_number: - type: string - description: Reference number of this refund transaction. - order_no: + description: Indicates the unique code associated with the payment gateway. This pivotal identifier facilitates transaction initiation through both the dashboard and API. + name: type: string readOnly: true - description: Order number of the original parent transaction. - parent_session_id: - type: string + description: Represents the payment gateway internal name defined in Ottu. + is_sandbox: + type: boolean readOnly: true - description: Session ID of the original parent transaction. - session_id: + description: Indicates whether this payment gateway operates in a sandbox or production environment. + logo: type: string - description: Session ID of this refund transaction. - initiator: - type: object - additionalProperties: {} - readOnly: true - description: User who initiated the refund operation. - required: - - amount - - auth_code - - created - - currency_code - - gateway_code - - id - - initiator - - modified - - order_no - - parent_session_id - - product_type - - reference_number - - session_id - - state - - track_id - Report: - type: object - properties: - id: - type: integer + format: uri + wallets: + type: array + items: {} readOnly: true - status: - type: string + default: + - ApplePay + - GooglePay + description: Denotes a list of payment services linked with this payment gateway, such as `GooglePay` and `ApplePay` + payment_services: + type: array + items: + $ref: "#/components/schemas/PaymentServiceListing" readOnly: true - type: - type: string - file: + description: Active payment services linked to this payment gateway — device payment services (Apple Pay, Google Pay, Samsung Pay, ...) and wallet providers (Ottu, Qitaf, ...). Each entry exposes the service `code` and `name`. + default_currency: type: string readOnly: true - size: - type: integer + default: KWD + description: Specifies the default currency code for the payment gateway, formatted according to ISO 4217. + accepted_currencies: + type: array + items: {} readOnly: true - file_format: - type: string - maxLength: 10 - records_amount: - type: integer - maximum: 2147483647 - minimum: 0 - period: - type: string - maxLength: 256 - created_at: - type: string - format: date-time - exported_at: - type: string - format: date-time - available_until: + default: + - KWD + - USD + description: Indicates a list of default accepted currencies for the payment gateway, each formatted in accordance with ISO 4217 standards. + operation: type: string - format: date-time + description: "Specifies the processing operation type for the payment method: either 'authorize' or 'purchase'. When set to `authorize`, successful transactions using this payment method will transition to the `authorize` state. Similarly, if set to `purchase`, they will follow the purchase flow." + operations: + type: array + items: {} + default: + - refund + - void readOnly: true - username: - type: string + description: Specifies the payment operations that are available for this payment gateway. + is_tokenizable: + type: boolean + description: This flag indicates whether tokenization is enabled for this payment gateway. When set to true, it allows for the secure storage of payment details, enabling future transactions without the need for re-entering payment information. + auto_debit_enabled: + type: boolean + description: This flag indicates whether auto-debit operation enabled or not. + tags: + type: array + items: + enum: + - e_commerce + - crm + - pos + - invoicing + - subscriptions + - marketplace + - mobile_app + - ticket_booking + - donations + - government + - education + - healthcare + - insurance + - logistics + - hospitality + - real_estate + - retail + - telecom + - utilities + - demo + - test + type: string + description: |- + * `e_commerce` - e_commerce + * `crm` - crm + * `pos` - pos + * `invoicing` - invoicing + * `subscriptions` - subscriptions + * `marketplace` - marketplace + * `mobile_app` - mobile_app + * `ticket_booking` - ticket_booking + * `donations` - donations + * `government` - government + * `education` - education + * `healthcare` - healthcare + * `insurance` - insurance + * `logistics` - logistics + * `hospitality` - hospitality + * `real_estate` - real_estate + * `retail` - retail + * `telecom` - telecom + * `utilities` - utilities + * `demo` - demo + * `test` - test + x-spec-enum-id: 397e40e715a6be71 readOnly: true - report_type: - type: string + description: Business vertical tags assigned to this payment method. required: - - available_until - - created_at - - exported_at - - file - - id - - period - - report_type - - size - - status - - type - - username - ReportAPIList: + - accepted_currencies + - auto_debit_enabled + - code + - default_currency + - is_sandbox + - is_tokenizable + - logo + - name + - operation + - operations + - payment_services + - tags + - wallets + PaginatedReportAPIListList: type: object + required: + - count + - results properties: - encrypted_id: - type: string - readOnly: true - report_name: + count: + type: integer + example: 123 + next: type: string - readOnly: true - interval: + nullable: true + format: uri + example: http://api.example.org/accounts/?offset=400&limit=100 + previous: type: string - readOnly: true - source: + nullable: true + format: uri + example: http://api.example.org/accounts/?offset=200&limit=100 + results: + type: array + items: + $ref: "#/components/schemas/ReportAPIList" + PatchedCheckoutPATCHRequest: + type: object + description: |- + Serializer to work with PaymentTransaction instances. + + Also uses request data from other serializers to save into PaymentTransaction db table: + properties: + amount: type: string - readOnly: true - file_format: + format: decimal + description: 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 + currency_code: type: string - maxLength: 10 - records_amount: - type: integer - maximum: 2147483647 - minimum: 0 - status: + description: 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. + pg_codes: + type: array + items: + type: string + title: Gateway + description: The list of payment gateway codes from which a customer can select to perform the payment or authorization. + type: enum: - - in_progress - - finished - - expired + - e_commerce + - payment_request type: string + x-spec-enum-id: ad398830c7970f0a + description: |- + The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. + + * `e_commerce` - Ecommerce + * `payment_request` - Payment Request + billing_address: + $ref: "#/components/schemas/Address" + branding_options: + allOf: + - $ref: "#/components/schemas/BrandingOptions" + writeOnly: true + description: |- + Per-payment-method branding customization provided by the merchant. Use payment_methods.{pg_code} to supply display data for each gateway. Only pg_codes present in payment_methods will have 'branding_options' included in their sdk_setup_preload_payload.payment_methods entry. + + font_weight follows CSS conventions (400 regular, 500 medium, 600 semibold, 700 bold). Defaults to 700 when omitted. + loyalty: + oneOf: + - $ref: "#/components/schemas/Loyalty" + - type: "null" description: |- - * `in_progress` - In Progress - * `finished` - Finished - * `expired` - Expired - x-spec-enum-id: 915999f8860a5adb - generated_at: - type: string - format: date-time - created_at: + Merchant-provided loyalty intent for this transaction. When `enabled=true` AND the pg_code used to pay is linked to an active wallet service with reward capability (e.g. STC Qitaf), the customer earns loyalty points on payment success. + + **How it works** + + 1. Merchant sets `loyalty.enabled=true` on checkout creation. + 2. Customer completes payment via any PGMID configured on this merchant. + 3. If that PGMID has an active wallet service with the `POST_PURCHASE_REWARD` capability, an asynchronous reward job fires after the transaction enters `PAID` state. + 4. The reward operation is stored on the transaction and automatically reversed (proportionally on partial refunds) if the transaction is later refunded. + + **Provider selection is implicit** — Ottu picks the right loyalty backend based on the PGMID's wallet-service configuration, so merchants do not need to know which loyalty program runs at the gateway level. Adding new loyalty providers (e.g. Mada Loyalty) requires no payload change. + shipping_address: + $ref: "#/components/schemas/ShippingAddress" + agreement: + allOf: + - $ref: "#/components/schemas/Agreement" + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. + attachment: type: string - format: date-time - readOnly: true - download_action: + format: uri + description: "A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. " + attachment_short_url: type: string + format: uri readOnly: true - required: - - created_at - - download_action - - encrypted_id - - generated_at - - interval - - report_name - - source - Response: - oneOf: - - $ref: '#/components/schemas/SDKSuccessCallback' - - $ref: '#/components/schemas/SDKCancelCallback' - - $ref: '#/components/schemas/SDKErrorCallback' - SDKCancelCallback: - type: object - properties: - message: + description: A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment. + attachment_upload_url: type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: - enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + description: A writable field that accepts an attachment that has already been uploaded to the server. + pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$ + billing: type: string - x-spec-enum-id: d21d329ca6d31930 readOnly: true + description: Detailed billing information including formatted amounts for display and raw values for processing. Contains both the total transaction amount and any applicable fees with their respective currency codes and labels. + card_acceptance_criteria: + allOf: + - $ref: "#/components/schemas/CardAcceptanceCriteria" description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + 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. - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: + **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. + checkout_page_url: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - status: + format: uri + readOnly: true + description: Frontend Checkout Url. + maxLength: 2000 + checkout_short_url: type: string + format: uri readOnly: true - default: canceled - description: The payment is canceled either by customer or failed due to - various reasons. `cancelCallback` must be triggered. - order_no: + description: A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True. + checkout_url: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: + format: uri + readOnly: true + description: URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use `checkout_short_url` instead. + customer_birthdate: type: string - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. - payment_gateway_info: - $ref: '#/components/schemas/PaymentGatewayInfo' - required: - - form_of_payment - - message - - order_no - - payment_gateway_info - - reference_number - - session_id - - status - SDKCancelOperation: - type: object - description: |- - Fetch the payment txn based on the order no or session id - also, if the payment txn is not in the accepted state for the - input operation, raise an error - properties: - order_no: + format: date + title: Customer Date of Birth + description: Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing. + customer_email: type: string - description: This is an optional identifier used to specify the payment - transaction upon which the operation should be performed. You can use - either the `order_no` or `session_id` field; at least one of these two - identifiers must be provided to select the payment transaction that should - be actioned. + format: email + description: 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. maxLength: 128 - session_id: + customer_first_name: type: string - description: Similar to `order_no`, `session_id` is an optional identifier - used to specify the payment transaction for the operation. You must provide - either `order_no` or `session_id` in order to select the appropriate payment - transaction. - maxLength: 128 - operation: - enum: - - cancel + description: 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. + maxLength: 64 + customer_id: type: string - description: '* `cancel` - cancel' - x-spec-enum-id: ae16339fd22f62b8 - required: - - operation - SDKCancelOperationResponse: - oneOf: - - $ref: '#/components/schemas/SDKCancelCallback' - SDKClientConfig: - type: object - description: Configuration for loading the Cybersource JavaScript SDK. - properties: - src: + description: 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. + maxLength: 64 + customer_last_name: type: string - format: uri - description: 'URL of the Cybersource JavaScript SDK library. This script - must be loaded before initializing the checkout widget. Example: https://testup.cybersource.com/uc/v1/assets/0.23.3/SecureAcceptance.js' - integrity: + description: 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. + maxLength: 64 + customer_phone: type: string - description: 'Subresource Integrity (SRI) hash for security verification. - Ensures the loaded script hasn''t been tampered with. Example: sha256-SV9gVCITF96ii3pttFE3JZs96WQdfJA5dwoGRQIzTmc=' - crossorigin: + description: 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. + maxLength: 16 + customer_phone_2: type: string - description: CORS setting for the script tag. Always set to 'anonymous' - to enable cross-origin resource sharing without credentials. - required: - - crossorigin - - integrity - - src - SDKErrorCallback: - type: object - properties: - message: + title: Customer additional phone + description: The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK. + maxLength: 16 + due_datetime: type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: - enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + format: date-time + title: Due date and time + description: The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date. + email_recipients: + type: array + items: + type: string + format: email + description: A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment. + expiration_time: type: string - x-spec-enum-id: d21d329ca6d31930 - readOnly: true - description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. - - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: + description: If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly. + generate_qr_code: type: boolean + writeOnly: true default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: - type: string - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: + description: If set to true, the `qr_code_url` field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page. + include_sdk_setup_preload: + type: boolean + writeOnly: true + default: false + description: Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included. + initiator_id: + type: integer + title: initiator + description: 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 + language: + enum: + - en + - ar type: string - description: The reference number. - status: + x-spec-enum-id: ac1757d67890d125 + default: en + description: |- + This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction. + + * `en` - English + * `ar` - Arabic + notifications: + allOf: + - $ref: "#/components/schemas/Notifications" + title: Notification settings + description: A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process. + operation: type: string readOnly: true - default: error - description: The payment is errored. `errorCallback` must be triggered. - required: - - form_of_payment - - message - - status - SDKSubmitRedirectResponse: - oneOf: - - $ref: '#/components/schemas/CheckoutSubmitSuccessResponse' - - $ref: '#/components/schemas/SDKErrorCallback' - SDKSubmitTokenResponse: - oneOf: - - $ref: '#/components/schemas/SDKSuccessCallback' - - $ref: '#/components/schemas/SDKCancelCallback' - - $ref: '#/components/schemas/SDKErrorCallback' - - $ref: '#/components/schemas/IFrame3DSResponse' - - $ref: '#/components/schemas/Redirect3DSResponse' - SDKSuccessCallback: - type: object - description: Callback payload to be forwarder directly to `successCallback` - SDK method. - properties: - message: + description: Specifies the type of operation to be performed by the payment gateway. If set to `purchase`, the payment source will be directly charged. If set to `authorize`, the payment source will only be authorized and the actual charge will be made at a later time. + order_no: type: string + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + maxLength: 128 + payment_instrument: + $ref: "#/components/schemas/PaymentInstrument" + payment_methods: + allOf: + - $ref: "#/components/schemas/PaymentMethodsForRedirect" readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: + description: An array containing all the payment methods derived from the `pg_codes` input. Each object in the array contains information about a single payment gateway, including its icon and the `redirect_url` that will redirect the customer to the payment gateway's payment page. + payment_type: enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + - one_off + - auto_debit + - save_card type: string - x-spec-enum-id: d21d329ca6d31930 - readOnly: true + x-spec-enum-id: b2ae60f7918918e7 + default: one_off description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + 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. - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: + Choose `save_card` if you want to perform a card tokenization operation. + + NOTE: If `auto_debit` is selected: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 + preload_checkout_page: type: boolean + writeOnly: true default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: + description: Pre-populate checkout page cache on transaction creation (POST only). Improves performance when clients immediately poll for the checkout page after creation. Ignored on updates (PATCH/PUT) - cache is automatically invalidated on any update. The cache expires based on the transaction's expiration time (max 1 hour). + product_type: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - status: + description: The type of product or service being purchased. This field may be used for tracking and reporting purposes. + maxLength: 128 + qr_code_url: type: string + format: uri readOnly: true - default: success - description: The payment is successful. `successCallback` must be triggered. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: - type: string - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. + description: A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when `generate_qr_code` is set to true. redirect_url: type: string format: uri + description: The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters. + maxLength: 2000 + sdk_setup_preload_payload: + allOf: + - $ref: "#/components/schemas/CheckoutSDK" readOnly: true - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - payment_gateway_info: - $ref: '#/components/schemas/PaymentGatewayInfo' - required: - - form_of_payment - - message - - order_no - - payment_gateway_info - - redirect_url - - reference_number - - session_id - - status - SMSPaymentAuthorizePayment: - type: object - description: |- - Serializer for handling SMS Payment authorize request - - Attributes: - pg_code (str): The gateway code associated with the payment. - session_id (str): The session ID associated with the payment. - customer_phone (str): The Customer Phone related to payment transaction - which will receive the transaction authorization OTP - save_card (boolean): Boolean decides if card will be created for next - payment, if created then user will be able to pay with token instead of otp API - properties: - pg_code: - type: string - description: The payment gateway code, selected for payment by customer - (for pay via PG). - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - customer_phone: - type: string - description: 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. - save_card: - type: boolean - description: |- - Boolean decides if card will be created for next - payment, if created then user will be able to pay with token instead of otp API - SMSPaymentSDKCancelCallback: - type: object - properties: - message: - type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: - enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway - type: string - x-spec-enum-id: d21d329ca6d31930 - readOnly: true - default: urpay - description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. - - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. + description: A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency. session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - status: type: string readOnly: true - default: canceled - description: The payment is canceled either by customer or failed due to - various reasons. `cancelCallback` must be triggered. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: - type: string - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. - payment_gateway_info: - $ref: '#/components/schemas/PaymentGatewayInfo' - required: - - form_of_payment - - message - - order_no - - payment_gateway_info - - reference_number - - session_id - - status - SMSPaymentSDKErrorCallback: - type: object - properties: - message: + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. + settled_pg_code: type: string readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: + title: Final Payment Gateway + description: The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction. + shortify_attachment_url: + type: boolean + writeOnly: true + default: false + description: If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp. + shortify_checkout_url: + type: boolean + writeOnly: true + default: false + description: If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp. + state: enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + - created + - pending + - attempted + - authorized + - paid + - failed + - canceled + - expired + - invalided + - refunded + - cod type: string - x-spec-enum-id: d21d329ca6d31930 + x-spec-enum-id: caee163196dbc11f readOnly: true - default: urpay description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + The current state of the payment transaction, it helps to understand the progress of the payment. - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: - type: string - order_no: + * `created` - Created + * `pending` - Pending + * `attempted` - Attempted + * `authorized` - Authorized + * `paid` - Paid + * `failed` - Failed + * `canceled` - Canceled + * `expired` - Expired + * `invalided` - Invalided + * `refunded` - Refunded + * `cod` - Cash on Delivery + unit_code: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: + writeOnly: true + title: Unit + description: The slug of the unit to be used for the transaction. + vendor_name: type: string - description: The reference number. - status: + description: The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes. + maxLength: 64 + webhook_url: type: string - readOnly: true - default: error - description: The payment is errored. `errorCallback` must be triggered. - required: - - form_of_payment - - message - - session_id - - status - SMSPaymentSDKSuccessCallback: + format: uri + description: "URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body. " + maxLength: 2000 + PaymentInstrument: + oneOf: + - $ref: "#/components/schemas/ApplePayInstrument" + - $ref: "#/components/schemas/GooglePayInstrument" + - $ref: "#/components/schemas/TokenPayInstrument" + - $ref: "#/components/schemas/SamsungPayInstrument" + - $ref: "#/components/schemas/WalletInstrument" + PaymentLabel: type: object - description: Callback payload to be forwarder directly to `successCallback` - SDK method. properties: - message: + payment_type: type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: - enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + instalment: + type: integer + description_en: type: string - x-spec-enum-id: d21d329ca6d31930 - readOnly: true - default: urpay - description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. - - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: + description_ar: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - status: + required: + - description_ar + - description_en + - instalment + - payment_type + PaymentMethod: + type: object + properties: + displayName: type: string - readOnly: true - default: success - description: The payment is successful. `successCallback` must be triggered. - order_no: + network: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: + type: type: string - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. - redirect_url: + required: + - displayName + - network + - type + PaymentMethodData: + type: object + description: https://developers.google.com/pay/api/web/reference/response-objects#PaymentMethodData + properties: + type: type: string - format: uri - readOnly: true - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - payment_gateway_info: - $ref: '#/components/schemas/PaymentGatewayInfo' + description: The type of payment method data. + description: + type: string + description: The description of the payment method. + info: + type: object + additionalProperties: {} + description: The payment method info. + tokenizationData: + type: object + additionalProperties: {} + description: The tokenization data. required: - - form_of_payment - - message - - order_no - - payment_gateway_info - - redirect_url - - reference_number - - session_id - - status - STCPay: + - description + - info + - tokenizationData + - type + PaymentMethodsForRedirect: type: object properties: code: @@ -17652,8 +8053,8 @@ components: description: The name of the payment method. type: enum: - - e_commerce - - payment_request + - e_commerce + - payment_request type: string x-spec-enum-id: ad398830c7970f0a description: |- @@ -17666,291 +8067,256 @@ components: description: The total amount to be charged, including fees. currency_code: type: string - description: The currency code for the payment method represented as an - ISO 4217 code. + description: The currency code for the payment method represented as an ISO 4217 code. maxLength: 3 fee: type: string description: The fee charged by the payment gateway. fee_description: type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. + description: This field provides the label for any additional transaction fee. In the SDK, this label will be displayed prominently during the checkout process to inform the payer about the nature of the fee. Ensure to incorporate this field in a clear and visible manner within the checkout UI to maintain transparency with the end-users. icon: type: string format: uri description: The svg URL of the icon for the payment method. icons: allOf: - - $ref: '#/components/schemas/Icons' + - $ref: "#/components/schemas/Icons" description: The URLs of the icon for the payment method. pg_icons: allOf: - - $ref: '#/components/schemas/MIDIcon' + - $ref: "#/components/schemas/MIDIcon" description: Represents list of mid icons configured for `pgmid` settings flow: - enum: - - stc_pay type: string - x-spec-enum-id: c6a31913ffbece38 - description: |- - Use the `submit_url` to retrieve the OTP needed to complete the payment.Then for the OTP submission process you can use the `payment_url` - - * `stc_pay` - STC Bank + default: redirect + description: The flow type of the payment method. redirect_url: - type: string + type: + - string + - "null" format: uri - description: 'This field is used for the `ottu_pg` payment flow. When `flow` - is `ottu_pg`, the payer will be directly redirected to this URL. This - field is only present when `flow` is `ottu_pg`. For web integrations: - Use `window.location.href = redirect_url` to redirect the payer to the - specified URL. For mobile SDK integrations: Open the `redirect_url` in - the webview. Upon redirecting to the provided URL, the webview should - be closed and the transaction refreshed using the `Checkout SDK / Retrieve - init data API`. Detect the URL redirection by listening to redirects in - the webview. When a redirect occurs to a URL containing the `merchant_id` - domain, close the webview and reload the SDK after calling the `Retrieve - init data API`.' + description: The URL where the customer should be redirected to perform the payment. branding_options: allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - can_save_card: - type: boolean - description: When true, display a checkbox in the SDK for card saving with - this payment method. When false, do not display the checkbox. - submit_url: - type: string - format: uri - description: The URL used in the SMS payment flow, such as for STC Bank. - It is utilized for submitting request for an OTP and authorizing the transaction, - This URL facilitates the first steps in the transaction verification and - payment process. - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - payment_url: - type: string - format: uri - description: The URL used in the SMS payment flow, such as for STC Bank. - It is utilized for submitting an OTP and capturing the transaction following - the authorization process and the OTP request. This URL facilitates the - final steps in the transaction verification and payment process. - required: - - amount - - billing - - can_save_card - - code - - currency_code - - fee - - fee_description - - flow - - icon - - icons - - name - - payment_url - - type - STCPayGenericError: + - $ref: "#/components/schemas/BrandingItem" + description: Merchant-supplied display customization for this payment method. Present only when the merchant provided branding data for this pg_code via the branding_options.payment_methods input field. + required: + - amount + - code + - currency_code + - fee + - fee_description + - icon + - icons + - name + - type + PaymentMethodsRequest: type: object properties: - message: + plugin: type: string - default: generic error. - STCPayPaymentRejectedResponse: - oneOf: - - $ref: '#/components/schemas/STCPayGenericError' - STCPayRejectedResponse: - oneOf: - - $ref: '#/components/schemas/STCPaySMSPaymentSDKCancelCallback' - - $ref: '#/components/schemas/STCPaySMSPaymentSDKErrorCallback' - - $ref: '#/components/schemas/STCPaySMSPaymentSDKSuccessCallback' - STCPaySMSPaymentSDKCancelCallback: - type: object - properties: - message: + description: Payment methods will be curated based on their compatibility with the specified plugin. + maxLength: 50 + currencies: + type: array + items: {} + description: "Specify the three-letter ISO 4217 codes representing the desired currencies. Examples include USD for United States Dollar, EUR for Euro, and GBP for British Pound Sterling. Example: ['KWD','USD']" + customer_id: type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: + description: If provided, `customer_payment_methods` will be filtered to show only those payment methods that have been successfully used with a paid payment attempts by this customer in the past. + maxLength: 64 + operation: enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + - purchase + - authorize type: string - x-spec-enum-id: d21d329ca6d31930 - readOnly: true - default: stc_pay + x-spec-enum-id: 4e59e52f76e448b3 description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + When specified, the available payment methods will be refined based on their compatibility with the indicated operation. - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: + * `purchase` - purchase + * `authorize` - authorize + tokenizable: type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - status: - type: string - readOnly: true - default: canceled - description: The payment is canceled either by customer or failed due to - various reasons. `cancelCallback` must be triggered. - order_no: - type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: - type: string - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. - payment_gateway_info: - $ref: '#/components/schemas/PaymentGatewayInfo' - required: - - form_of_payment - - message - - order_no - - payment_gateway_info - - reference_number - - session_id - - status - STCPaySMSPaymentSDKErrorCallback: - type: object - properties: - message: - type: string - readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. - form_of_payment: + description: If defined, payment methods will be filtered based on supporting tokenization and auto-debit action. + auto_debit: + type: boolean + description: If defined, payment methods will be filtered based on supporting tokenization and auto-debit action. + pg_names: + type: array + items: {} + description: |- + When provided, the payment methods will be narrowed down to those that support the specified payment gateway name. Example: ['kpay','mpgs'] + + Available Values:
  • `abapayway` - ABA PayWay

  • `rajhi` - Alrajhi Bank

  • `amazon_pay` - Amazon Pay

  • `bambora` - Bambora

  • `benefit` - Benefit

  • `benefit_pay` - BenefitPay

  • `beyon_money` - BeyonMoney

  • `bookeey` - Bookeey

  • `burgan` - Burgan

  • `cod` - Cash

  • `cbk` - CBK

  • `ccavenues` - Ccavenues

  • `checkoutcom` - checkout.com

  • `cybersource` - CyberSource

  • `csuc` - Cybersource Unified Checkout

  • `dapi` - Dapi

  • `deema` - Deema

  • `doku` - Doku

  • `enet` - Enet

  • `fawry` - Fawry

  • `fiserv` - Fiserv

  • `fss` - FSS

  • `geidea` - Geidea

  • `hesabe` - Hesabe

  • `hyperpay` - HyperPay

  • `kpay` - KNET

  • `moyasar` - Moyasar

  • `mpgs` - MPGS

  • `myfatoorah` - MyFatoorah

  • `ngenius` - N-Genius

  • `nbo` - NBO

  • `omannet` - OmanNet

  • `ottu_pg` - Ottu PG

  • `ottu_sandbox` - Ottu Sandbox

  • `paymob` - PayMob

  • `payon` - PayOn

  • `paypal` - PayPal

  • `payu_india` - PayU India

  • `qpay` - Qpay

  • `skipcash` - Skip Cash

  • `smart_pay` - SmartPay

  • `sohar` - SoharInternational

  • `stcbahrain` - STC Bahrain

  • `stc_pay` - STC Pay

  • `tabby` - Tabby

  • `taly` - Taly

  • `tamara` - Tamara

  • `tap` - Tap Payments

  • `tess` - Tess Payments

  • `upayments` - UPayments

  • `upg` - UPG

  • `urpay` - URPay
    • + type: enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + - sandbox + - production type: string - x-spec-enum-id: d21d329ca6d31930 - readOnly: true - default: stc_pay + x-spec-enum-id: 1e8a9859ef5c2b8e description: |- - Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. + When specified, the available payment methods will be refined based on their type determining if type is sandbox or production. - * `apple_pay` - Apple Pay - * `google_pay` - Google Pay - * `token_pay` - Token Pay - * `stc_pay` - STC Bank - * `urpay` - URPay - * `redirect` - Redirect - * `samsung_pay` - Samsung Pay - * `doku` - Doku - * `aba_payway` - ABA PayWay - challenge_occurred: - type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: - type: string - order_no: + * `sandbox` - sandbox + * `production` - production + tags: + type: array + items: + enum: + - e_commerce + - crm + - pos + - invoicing + - subscriptions + - marketplace + - mobile_app + - ticket_booking + - donations + - government + - education + - healthcare + - insurance + - logistics + - hospitality + - real_estate + - retail + - telecom + - utilities + - demo + - test + type: string + description: |- + * `e_commerce` - e_commerce + * `crm` - crm + * `pos` - pos + * `invoicing` - invoicing + * `subscriptions` - subscriptions + * `marketplace` - marketplace + * `mobile_app` - mobile_app + * `ticket_booking` - ticket_booking + * `donations` - donations + * `government` - government + * `education` - education + * `healthcare` - healthcare + * `insurance` - insurance + * `logistics` - logistics + * `hospitality` - hospitality + * `real_estate` - real_estate + * `retail` - retail + * `telecom` - telecom + * `utilities` - utilities + * `demo` - demo + * `test` - test + x-spec-enum-id: 397e40e715a6be71 + description: "When provided, the payment methods will be filtered to those matching any of the specified business vertical tags (OR logic). Example: ['e_commerce', 'pos']" + payment_services: + type: array + items: + enum: + - apple_pay + - google_pay + - samsung_pay + - wallet + type: string + description: |- + * `apple_pay` - Apple Pay + * `google_pay` - Google Pay + * `samsung_pay` - Samsung Pay + * `wallet` - Wallet + x-spec-enum-id: a4096334d394fe33 + description: |- + When provided, only payment methods that have at least one of the listed payment services attached are returned (OR logic). Each value maps to a configured `PaymentService` linked to the PGMID — for example a MID with an active Apple Pay configuration is returned for `payment_services=['apple_pay']`, and a MID linked to an active Ottu / Qitaf wallet is returned for `payment_services=['wallet']`. Example: ['wallet', 'apple_pay'] + + Available Values:
  • `apple_pay` - Apple Pay

  • `google_pay` - Google Pay

  • `samsung_pay` - Samsung Pay

  • `wallet` - Wallet
    • + required: + - plugin + PaymentMethodsResponse: + type: object + properties: + customer_payment_methods: + type: array + items: {} + description: Denotes a collection of payment gateways which used by user in successful payment attempts. + payment_methods: + type: array + items: + $ref: "#/components/schemas/PGPaymentMethods" + description: Provides a comprehensive overview of the available payment gateways, delineated as distinct payment methods. + PaymentNotificationErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/MessageNotificationFailure" + PaymentNotificationResponses: + oneOf: + - $ref: "#/components/schemas/MessageNotificationSuccess" + PaymentOperationErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/OperationFailure" + PaymentOperationResponses: + oneOf: + - $ref: "#/components/schemas/InternalOperation" + - $ref: "#/components/schemas/ExternalOperation" + PaymentServiceListing: + type: object + properties: + code: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: + description: Code to identify the service in the API/URLs/etc + maxLength: 16 + pattern: ^[-a-zA-Z0-9_]+$ + name: type: string - description: The reference number. - status: + description: "Name to be displayed in dropdown or anywhere else the settings are being displayed. IE: Apple Pay, Google Pay, etc" + maxLength: 16 + name_ar: type: string - readOnly: true - default: error - description: The payment is errored. `errorCallback` must be triggered. + title: Arabic Name + description: "Arabic Name to be displayed in dropdown or anywhere else the settings are being displayed. IE: Apple Pay, Google Pay, etc" + maxLength: 16 required: - - form_of_payment - - message - - session_id - - status - STCPaySMSPaymentSDKSuccessCallback: + - code + - name + PrePaymentCheckResponses: + oneOf: + - $ref: "#/components/schemas/TabbyPrePaymentCheck" + - $ref: "#/components/schemas/TamaraPrePaymentCheck" + - $ref: "#/components/schemas/TalyPrePaymentCheck" + Redirect3DSResponse: type: object - description: Callback payload to be forwarder directly to `successCallback` - SDK method. properties: - message: + status: + type: string + readOnly: true + default: 3DS + description: The payment is in 3DSecure process. Indicates a 3D Secure verification is required. html must be displayed to the customer in the iframe. + reference_number: type: string readOnly: true - description: A concise description detailing the outcome of the operation. - Suitable for presenting to the end-user if needed. + description: This is a unique value associated with each payment transaction made by a customer. It serves as the unique identifier for the payment when sent to the Payment Gateway (PG). allowing for multiple reference numbers per session_id. form_of_payment: enum: - - apple_pay - - google_pay - - token_pay - - stc_pay - - urpay - - redirect - - samsung_pay - - doku - - aba_payway + - apple_pay + - google_pay + - token_pay + - stc_pay + - urpay + - redirect + - samsung_pay + - doku + - aba_payway type: string x-spec-enum-id: d21d329ca6d31930 readOnly: true - default: stc_pay description: |- Indicates the form of payment used to process the transaction. This can be one of several options, including `apple_pay`, `google_pay`, `samsung_pay`, `token_pay`, `stc_pay`, `urpay`, or `redirect`.It's important to note that the `redirect` option is only present in the `errorCallback`. In other scenarios, especially with `cancelCallback` and `successCallback`, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed. * `apple_pay` - Apple Pay * `google_pay` - Google Pay * `token_pay` - Token Pay - * `stc_pay` - STC Bank + * `stc_pay` - STC Pay * `urpay` - URPay * `redirect` - Redirect * `samsung_pay` - Samsung Pay @@ -17958,176 +8324,116 @@ components: * `aba_payway` - ABA PayWay challenge_occurred: type: boolean - default: false - description: This flag indicates if an additional verification, such as - 3DS, OTP, PIN, etc., was initiated during the payment process. Use this - flag in cancelCallback and errorCallback to control the presentation of - error messages, especially for on-site payments undergoing a challenge - flow. For example, after a failed 3DS verification, it's useful to show - a custom popup informing the user of the payment failure. However, it's - crucial to note that not all on-site failed payments need custom error - messaging. In cases like GooglePay or ApplePay, error messages are inherently - handled by the Payment Sheet, which remains open for the user to retry, - making this distinction vital. - session_id: + default: true + description: This flag indicates if an additional verification, such as 3DS, OTP, PIN, etc., was initiated during the payment process. Use this flag in cancelCallback and errorCallback to control the presentation of error messages, especially for on-site payments undergoing a challenge flow. For example, after a failed 3DS verification, it's useful to show a custom popup informing the user of the payment failure. However, it's crucial to note that not all on-site failed payments need custom error messaging. In cases like GooglePay or ApplePay, error messages are inherently handled by the Payment Sheet, which remains open for the user to retry, making this distinction vital. + method: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - status: + readOnly: true + default: redirect + description: The method of 3D Secure verification. + redirect_url: type: string + format: uri readOnly: true - default: success - description: The payment is successful. `successCallback` must be triggered. + description: |- + The URL where the payer shall be redirected for 3D Secure verification. + + **Platform-specific behavior based on the `channel` HTTP header:** + + ### For Web (`web_sdk`): + The payer will be redirected to the payment details page where they can complete the payment process. + + Use the following JavaScript code: + ```javascript + window.location.href = redirect_url; + ``` + The browser will handle all subsequent redirects automatically. + + ### For Mobile SDK (`mobile_sdk`): + The `redirect_url` should be opened in a WebView. This is the page where the payer will enter their card details. + + - After card details are entered, the payer is redirected to the final payment details page within the WebView. + - You must detect URL changes within the WebView. When a redirect occurs to the URL pattern: + `{merchant_id}/b/gw/mobile-sdk-redirect`, close the WebView. + - This URL indicates the end of the payment process. It will appear as a blank page and should not be shown to the user. + - After closing the WebView, reload the SDK and call the Retrieve Init Data API to present the payment result to the payer. + + **Important:** + Ensure the `channel` HTTP header is set correctly (`web_sdk` or `mobile_sdk`) to enable the appropriate behavior. Incorrect or missing `channel` headers may result in improper handling of the redirection flow. order_no: type: string - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. - reference_number: - type: string - description: This is a unique value associated with each payment attempt - made by a customer. It serves as the unique identifier for the payment - when sent to the Payment Gateway (PG). It can be used to identify a specific - payment attempt within one session, allowing for multiple reference numbers - per session_id. - redirect_url: + readOnly: true + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. + session_id: type: string - format: uri readOnly: true - description: The URL where the customer will be redirected after the payment - stage only if the webhook URL returns a success status. `order_no`, `reference_number` - and `session_id` will be appended to the redirect URL as query parameters. - payment_gateway_info: - $ref: '#/components/schemas/PaymentGatewayInfo' + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. required: - - form_of_payment - - message - - order_no - - payment_gateway_info - - redirect_url - - reference_number - - session_id - - status - STCPaymentAuthorize: + - form_of_payment + - method + - order_no + - redirect_url + - reference_number + - session_id + - status + ReportAPIList: type: object properties: - message: + encrypted_id: type: string - default: The transaction's One-Time Password (OTP) has been successfully - sent. - SamsungPay: - type: object - description: Base serializer for payment configuration, to be used in SDK clients - like web and mobile. - properties: - code: + readOnly: true + report_name: type: string - description: The payment service code. - pattern: ^[-a-zA-Z0-9_]+$ - environment: - enum: - - TEST - - PRODUCTION - - STAGE + readOnly: true + interval: type: string - x-spec-enum-id: 3b7f3ed28de540a3 - description: |- - This field specifies the environment to use for the payment, either `TEST`, `STAGE`or `PRODUCTION`. In the TEST environment, transactions are not processed and can be used to test the integration. In the PRODUCTION environment, transactions are processed and real money is involved - - * `TEST` - TEST - * `PRODUCTION` - PRODUCTION - * `STAGE` - STAGE - product_id: - type: string - description: The Service ID obtained from the Samsung Pay partner portal - (required for partner verification).This field specifies the ID of the - merchant accepting the payment, This ID is used by Samsung Pay to identify - the merchant and associate the payment transaction with the correct merchant - account. - maxLength: 100 - merchant_name: - type: string - description: This field specifies the name of the merchant accepting the - payment. This name will be displayed to the user during the payment process - and on their payment confirmation - maxLength: 25 - total_price: - type: string - description: This field specifies the total price for the payment, including - any fees. The price should be formatted as a string with the decimal point - as a period, e.g. '10.99'. - maxLength: 20 - session_id: + readOnly: true + source: type: string - description: The unique session ID for the payment operation. - maxLength: 50 - currency_code: + readOnly: true + file_format: type: string - description: This field specifies the ISO 4217 currency code for the payment. - This code is used to specify the currency of the payment transaction. - If you are unsure what value to use for this field, please consult the - documentation provided by your payment gateway provider. maxLength: 10 - country_code: - type: string - description: This field specifies the ISO 3166-1 alpha-2 country code for - the payment currency. This code is used to specify the country of the - payment transaction. If you are unsure what value to use for this field, - please consult the documentation provided by your payment gateway provider. - maxLength: 2 - fee: + records_amount: + type: integer + maximum: 2147483647 + minimum: 0 + status: + enum: + - in_progress + - finished + - expired type: string - description: The fee for the payment. - maxLength: 20 - fee_description: + description: |- + * `in_progress` - In Progress + * `finished` - Finished + * `expired` - Expired + x-spec-enum-id: 915999f8860a5adb + generated_at: type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - maxLength: 128 - payment_url: + format: date-time + created_at: type: string - format: uri - description: The URL to use for submitting the payment. - maxLength: 2000 - flow: - enum: - - samsung_pay + format: date-time + readOnly: true + download_action: type: string - x-spec-enum-id: 6d871e435f026f68 - description: |- - The flow type of the payment method. - - * `samsung_pay` - SamsungPay - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. + readOnly: true required: - - billing - - code - - country_code - - currency_code - - environment - - fee - - fee_description - - flow - - merchant_name - - payment_url - - product_id - - session_id - - total_price + - created_at + - download_action + - encrypted_id + - generated_at + - interval + - report_name + - source SamsungPayInstrument: type: object description: Samsung Pay payment instrument properties: instrument_type: enum: - - samsung_pay + - samsung_pay type: string x-spec-enum-id: 33e26b87ac3fa6c2 default: samsung_pay @@ -18137,11 +8443,10 @@ components: * `samsung_pay` - samsung_pay payload: allOf: - - $ref: '#/components/schemas/SamsungPayPayload' - description: Samsung Pay payment token received from Samsung Pay SDK. Pass - the token exactly as received without modification. + - $ref: "#/components/schemas/SamsungPayPayload" + description: Samsung Pay payment token received from Samsung Pay SDK. Pass the token exactly as received without modification. required: - - payload + - payload SamsungPayPayload: type: object description: Payload for Samsung Pay @@ -18150,56 +8455,48 @@ components: type: string description: Encrypted Samsung Pay payment token. required: - - token + - token SchemaWebhook: type: object properties: pg_params: allOf: - - $ref: '#/components/schemas/PGParams' + - $ref: "#/components/schemas/PGParams" readOnly: true - description: "The `pg_params` field contains the details received \nfrom - the payment gateway callback these details are \nprovided to us by the - gateway after a user has completed \na payment transaction additionally, - `pg_params` \ncan include information obtained from an inquiry \nrequest - made to the payment gateway status check API. \n" + description: | + The `pg_params` field contains the details received + from the payment gateway callback these details are + provided to us by the gateway after a user has completed + a payment transaction additionally, `pg_params` + can include information obtained from an inquiry + request made to the payment gateway status check API. agreement: allOf: - - $ref: '#/components/schemas/Agreement' + - $ref: "#/components/schemas/Agreement" readOnly: true - description: "An established contractual arrangement with the payer, which - authorizes you to securely store and subsequently utilize their payment - information for specific purposes. This could encompass arrangements like - recurring payments for services such as mobile subscriptions, installment-based - payments for purchases, arrangements for ad-hoc charges like account top-ups, - or for standard industry practices like penalty charges for missed appointments. - \n\nNote: If your intention is solely to store payment details for transactions - initiated by the payer in the future, then this parameter group should - not be used." + description: |- + An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. + + Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used. amount: type: string readOnly: true - description: Denotes the total sum of the payment transaction, which encompasses - the cost of the procured items or services, excluding any supplementary - fees or charges. + description: 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: allOf: - - $ref: '#/components/schemas/AmountDetails' + - $ref: "#/components/schemas/AmountDetails" readOnly: true - description: 'A comprehensive set of amount details includes: Currency Code, - Amount, Total, Fee.' + description: "A comprehensive set of amount details includes: Currency Code, Amount, Total, Fee." capture_delivery_address: type: boolean - description: By enabling this, you will ask for user's address. If enabled, - capture delivery coordinates should also be active. + description: By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active. capture_delivery_location: type: boolean title: Capture delivery coordinates - description: 'By enabling this, you will ask for user''s delivery location - on a map. ' + description: "By enabling this, you will ask for user's delivery location on a map. " card_acceptance_criteria: allOf: - - $ref: '#/components/schemas/CardAcceptanceCriteria' + - $ref: "#/components/schemas/CardAcceptanceCriteria" readOnly: true description: |- 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. @@ -18209,104 +8506,76 @@ components: **Note**: The `card_acceptance_criteria` field is applicable only for direct payments and not for hosted session payments. currency_code: type: string - description: 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. + description: 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. maxLength: 3 minLength: 3 customer_address_city: type: string - description: The city of the customer's billing address. This field may - be used to send the billing address to the payment gateway. + description: The city of the customer's billing address. This field may be used to send the billing address to the payment gateway. maxLength: 40 customer_address_country: type: string - description: 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. + description: 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. maxLength: 2 minLength: 2 customer_address_line1: type: string title: Customer address line 1 - description: The first line of the customer's billing street address. This - field may be used to send the billing address to the payment gateway. + description: 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_line2: type: string title: Customer address line 2 - description: 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. + description: 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_birthdate: type: - - string - - 'null' + - string + - "null" format: date description: The customer's date of birth in ISO format (YYYY-MM-DD). customer_address_postal_code: type: string - description: The postal code of the customer's billing address. This field - may be used to send the billing address to the payment gateway. + description: The postal code of the customer's billing address. This field may be used to send the billing address to the payment gateway. maxLength: 12 customer_address_state: type: string - description: The state or region of the customer's billing address. This - field may be used to send the billing address to the payment gateway. + description: The state or region of the customer's billing address. This field may be used to send the billing address to the payment gateway. maxLength: 40 customer_email: type: string - description: 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. + description: 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. maxLength: 128 customer_first_name: type: string - description: 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. + description: 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. maxLength: 64 customer_id: type: string - description: 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. + description: 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. maxLength: 64 customer_last_name: type: string - description: 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. + description: 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. maxLength: 64 customer_phone: type: string - description: 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. + description: 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. maxLength: 32 + customer_wallet_transactions: + type: array + items: + $ref: "#/components/schemas/CustomerWalletTransaction" + readOnly: true + description: List of wallet legs that contributed to this payment — one entry per wallet provider (Ottu, Qitaf, …). Multi-wallet stacking emits multiple entries; full or single-wallet payments emit a one-element list. Omitted entirely (key absent) when no wallet was involved. extra: - description: The extra information for the payment details, which the merchant - has sent it in key value form. + description: The extra information for the payment details, which the merchant has sent it in key value form. fee: type: string - description: 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. + description: 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. readOnly: true gateway_account: type: string readOnly: true - description: This code corresponds to the payment gateway and plays an essential - role in facilitating payment transactions. + description: This code corresponds to the payment gateway and plays an essential role in facilitating payment transactions. gateway_name: type: string readOnly: true @@ -18314,72 +8583,60 @@ components: gateway_response: type: object additionalProperties: {} - description: This field stores the processed response received from the - payment gateway and forwarded to Ottu. + description: This field stores the processed response received from the payment gateway and forwarded to Ottu. readOnly: true initiator: allOf: - - $ref: '#/components/schemas/InitiatorUser' - description: 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 + - $ref: "#/components/schemas/InitiatorUser" + description: 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 is_sandbox: type: boolean title: Is Sandbox? - description: Indicates whether the operation was performed in a test environment - or not. + description: Indicates whether the operation was performed in a test environment or not. message: type: string readOnly: true - description: 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. + description: 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_no: type: - - string - - 'null' - description: The unique identifier assigned to this payment transaction. - It is used for tracking purposes and is set by the merchant or the system. + - string + - "null" + description: The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system. maxLength: 128 paid_amount: oneOf: - - type: number - format: double - - type: string - description: 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. + - type: number + format: double + - type: string + description: 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. readOnly: true payment_type: enum: - - one_off - - auto_debit - - save_card + - one_off + - auto_debit + - save_card type: string x-spec-enum-id: b2ae60f7918918e7 - description: "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. \n\nChoose `save_card` if you want to perform - a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. - `agreement` and `customer_id` parameters will also be mandatory. \n2. - Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: - If `save_card` is selected: \n1. The amount must be zero for the save - card operation. \n2. The selected MID(pg_code) must support tokenization - to enable the save card operation. \n3. Please note that the save card - operation is considered successful without any funds being charged.\n4. - Once a card is created, Ottu will send a webhook containing the card details - to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* - `save_card` - Save Card" + description: |- + 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: + 1. `agreement` and `customer_id` parameters will also be mandatory. + 2. 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: + 1. The amount must be zero for the save card operation. + 2. The selected MID(pg_code) must support tokenization to enable the save card operation. + 3. Please note that the save card operation is considered successful without any funds being charged. + 4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL. + 5. 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 reference_number: type: string readOnly: true @@ -18390,46 +8647,39 @@ components: remaining_amount: type: number format: double - description: The residual amount due. Together with the editable amount, - it indicates the outstanding balance of a transaction awaiting settlement. + description: The residual amount due. Together with the editable amount, it indicates the outstanding balance of a transaction awaiting settlement. readOnly: true result: enum: - - pending - - success - - failed - - canceled - - error - - cod - type: string - description: Indicates the outcome of the operation. `success` denotes a - successful operation. + - pending + - success + - failed + - canceled + - error + - cod + type: string + description: Indicates the outcome of the operation. `success` denotes a successful operation. x-spec-enum-id: 03c10fdf706d3f9a readOnly: true session_id: type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. + description: A unique identifier for each payment transaction, used to maintain the session state during the payment process. maxLength: 128 settled_amount: type: number format: double - description: The amount that has been paid or authorized in its original - currency, excluding any fees. + description: The amount that has been paid or authorized in its original currency, excluding any fees. readOnly: true signature: type: string readOnly: true - description: '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.' + description: "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." state: type: string readOnly: true token: allOf: - - $ref: '#/components/schemas/Card' + - $ref: "#/components/schemas/Card" description: |- Please note that if card is created via checkout save_card payment type @@ -18438,53 +8688,46 @@ components: For more details check Checkout API `payment_type` field documentation details transaction_log_id: type: - - integer - - 'null' + - integer + - "null" maximum: 2147483647 minimum: 0 - description: 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. + description: 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. timestamp_utc: type: string format: date-time readOnly: true - description: 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. + description: 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. transactions: type: array items: - $ref: '#/components/schemas/ChildPayment' - description: A list of dictionaries is generated, each containing a concise - summary of each child payment transaction that has been created. + $ref: "#/components/schemas/ChildPayment" + description: A list of dictionaries is generated, each containing a concise summary of each child payment transaction that has been created. voided_amount: type: number format: double description: The total voided amount for the payment transaction. required: - - agreement - - amount - - amount_details - - card_acceptance_criteria - - currency_code - - customer_address_country - - fee - - gateway_account - - gateway_name - - gateway_response - - message - - paid_amount - - pg_params - - reference_number - - remaining_amount - - result - - settled_amount - - signature - - state - - timestamp_utc + - agreement + - amount + - amount_details + - card_acceptance_criteria + - currency_code + - customer_address_country + - fee + - gateway_account + - gateway_name + - gateway_response + - message + - paid_amount + - pg_params + - reference_number + - remaining_amount + - result + - settled_amount + - signature + - state + - timestamp_utc ShippingAddress: type: object description: Nested serializer to save Address data into PaymentTransaction @@ -18503,255 +8746,255 @@ components: maxLength: 40 country: enum: - - AF - - AL - - DZ - - AS - - AD - - AO - - AI - - AQ - - AG - - AR - - AM - - AW - - AU - - AT - - AZ - - BS - - BH - - BD - - BB - - BY - - BE - - BZ - - BJ - - BM - - BT - - BO - - BQ - - BA - - BW - - BV - - BR - - IO - - BN - - BG - - BF - - BI - - CV - - KH - - CM - - CA - - KY - - CF - - TD - - CL - - CN - - CX - - CC - - CO - - KM - - CG - - CD - - CK - - CR - - HR - - CU - - CW - - CY - - CZ - - CI - - DK - - DJ - - DM - - DO - - EC - - EG - - SV - - GQ - - ER - - EE - - SZ - - ET - - FK - - FO - - FJ - - FI - - FR - - GF - - PF - - TF - - GA - - GM - - GE - - DE - - GH - - GI - - GR - - GL - - GD - - GP - - GU - - GT - - GG - - GN - - GW - - GY - - HT - - HM - - VA - - HN - - HK - - HU - - IS - - IN - - ID - - IR - - IQ - - IE - - IM - - IL - - IT - - JM - - JP - - JE - - JO - - KZ - - KE - - KI - - KP - - KR - - KW - - KG - - LA - - LV - - LB - - LS - - LR - - LY - - LI - - LT - - LU - - MO - - MG - - MW - - MY - - MV - - ML - - MT - - MH - - MQ - - MR - - MU - - YT - - MX - - FM - - MD - - MC - - MN - - ME - - MS - - MA - - MZ - - MM - - NA - - NR - - NP - - NL - - NC - - NZ - - NI - - NE - - NG - - NU - - NF - - MK - - MP - - 'NO' - - OM - - PK - - PW - - PS - - PA - - PG - - PY - - PE - - PH - - PN - - PL - - PT - - PR - - QA - - RO - - RU - - RW - - RE - - BL - - SH - - KN - - LC - - MF - - PM - - VC - - WS - - SM - - ST - - SA - - SN - - RS - - SC - - SL - - SG - - SX - - SK - - SI - - SB - - SO - - ZA - - GS - - SS - - ES - - LK - - SD - - SR - - SJ - - SE - - CH - - SY - - TW - - TJ - - TZ - - TH - - TL - - TG - - TK - - TO - - TT - - TN - - TM - - TC - - TV - - TR - - UG - - UA - - AE - - GB - - US - - UM - - UY - - UZ - - VU - - VE - - VN - - VG - - VI - - WF - - EH - - YE - - ZM - - ZW - - AX + - AF + - AL + - DZ + - AS + - AD + - AO + - AI + - AQ + - AG + - AR + - AM + - AW + - AU + - AT + - AZ + - BS + - BH + - BD + - BB + - BY + - BE + - BZ + - BJ + - BM + - BT + - BO + - BQ + - BA + - BW + - BV + - BR + - IO + - BN + - BG + - BF + - BI + - CV + - KH + - CM + - CA + - KY + - CF + - TD + - CL + - CN + - CX + - CC + - CO + - KM + - CG + - CD + - CK + - CR + - HR + - CU + - CW + - CY + - CZ + - CI + - DK + - DJ + - DM + - DO + - EC + - EG + - SV + - GQ + - ER + - EE + - SZ + - ET + - FK + - FO + - FJ + - FI + - FR + - GF + - PF + - TF + - GA + - GM + - GE + - DE + - GH + - GI + - GR + - GL + - GD + - GP + - GU + - GT + - GG + - GN + - GW + - GY + - HT + - HM + - VA + - HN + - HK + - HU + - IS + - IN + - ID + - IR + - IQ + - IE + - IM + - IL + - IT + - JM + - JP + - JE + - JO + - KZ + - KE + - KI + - KP + - KR + - KW + - KG + - LA + - LV + - LB + - LS + - LR + - LY + - LI + - LT + - LU + - MO + - MG + - MW + - MY + - MV + - ML + - MT + - MH + - MQ + - MR + - MU + - YT + - MX + - FM + - MD + - MC + - MN + - ME + - MS + - MA + - MZ + - MM + - NA + - NR + - NP + - NL + - NC + - NZ + - NI + - NE + - NG + - NU + - NF + - MK + - MP + - "NO" + - OM + - PK + - PW + - PS + - PA + - PG + - PY + - PE + - PH + - PN + - PL + - PT + - PR + - QA + - RO + - RU + - RW + - RE + - BL + - SH + - KN + - LC + - MF + - PM + - VC + - WS + - SM + - ST + - SA + - SN + - RS + - SC + - SL + - SG + - SX + - SK + - SI + - SB + - SO + - ZA + - GS + - SS + - ES + - LK + - SD + - SR + - SJ + - SE + - CH + - SY + - TW + - TJ + - TZ + - TH + - TL + - TG + - TK + - TO + - TT + - TN + - TM + - TC + - TV + - TR + - UG + - UA + - AE + - GB + - US + - UM + - UY + - UZ + - VU + - VE + - VN + - VG + - VI + - WF + - EH + - YE + - ZM + - ZW + - AX type: string description: |- * `AF` - Afghanistan @@ -19021,85 +9264,17 @@ components: type: string maxLength: 16 required: - - city - - country - - email - - first_name - - last_name - - line1 - - phone - ShortenedURL: - type: object - properties: - short_url: - type: string - description: The shortened version of the original URL. When accessed, it - redirects to the full long URL. - long_url: - type: string - description: The URL provided to endpoint to shorten it. - required: - - long_url - - short_url - SubmitClickToPay: - type: object - description: |- - Serializer for provisioning Click to Pay configuration. - - This is used before actual payment to provide configuration to the frontend. - properties: - pg_code: - type: string - description: Payment Gateway code selected for Click to Pay. - session_id: - type: string - description: Session ID used to identify the transaction. - required: - - pg_code - - session_id - SubmitSMSPaymentPaymentRequest: - type: object - properties: - session_id: - type: string - description: A unique identifier for each payment transaction, used to maintain - the session state during the payment process. - maxLength: 128 - otp: - type: string - description: The OTP (One-Time Password) is a mandatory field used to authorize - SMS Payment payment transactions. - maxLength: 12 - required: - - otp - - session_id - SubmitToken: - type: object - description: |- - This serializer is responsible for validating the data sent by the SDK - when the user submits the token. - properties: - session_id: - type: string - description: The unique identifier of the payment session. Provided in CheckoutSDK - init `session_id`. - token: - type: string - description: Use this field to provide the unique identifier of a saved - customer card for processing a payment in the API request. - cvv: - type: string - description: Input the 3 or 4-digit Card Verification Value (CVV) found - on the back of the credit/debit card. This may be required for new card - transactions or certain token transactions to verify the card's authenticity. - pattern: ^\d{3,4}$ - required: - - session_id - - token + - city + - country + - email + - first_name + - last_name + - line1 + - phone Success: oneOf: - - $ref: '#/components/schemas/CheckoutPOSTResponse' - - $ref: '#/components/schemas/DirectPaymentResponse' + - $ref: "#/components/schemas/CheckoutPOSTResponse" + - $ref: "#/components/schemas/DirectPaymentResponse" TabbyPrePaymentCheck: type: object properties: @@ -19122,25 +9297,18 @@ components: payment_labels: type: array items: - $ref: '#/components/schemas/PaymentLabel' + $ref: "#/components/schemas/PaymentLabel" required: - - is_available - - payment_labels - - single_checkout_enabled - TokenExpiredMessage: - type: object - properties: - error: - type: string - default: Download link has expired or is invalid - description: Error message explaining the token is no longer valid + - is_available + - payment_labels + - single_checkout_enabled TokenPayInstrument: type: object description: Token-based payment instrument for auto-debit properties: instrument_type: enum: - - token + - token type: string x-spec-enum-id: 961e6cfa88079418 default: token @@ -19150,11 +9318,10 @@ components: * `token` - token payload: allOf: - - $ref: '#/components/schemas/TokenPayPayload' - description: Token for auto-debit payment. Provide the payment token or - CVV code as received from your tokenization service. + - $ref: "#/components/schemas/TokenPayPayload" + description: Token for auto-debit payment. Provide the payment token or CVV code as received from your tokenization service. required: - - payload + - payload TokenPayPayload: type: object description: Payload for token-based payment (auto-debit) @@ -19163,496 +9330,544 @@ components: type: string description: Payment token or CVV code for auto-debit tokenization. required: - - token - TransactionMetadataResponse: - type: object - description: |- - Schema for the GET metadata in transaction OPTIONS response. - - The OPTIONS response wraps this in `{"GET": {...}}`. - properties: - GET: - allOf: - - $ref: '#/components/schemas/TransactionOptionsResponse' - description: Metadata for GET requests on the transaction list endpoint - required: - - GET - TransactionOptionsResponse: - type: object - description: |- - Schema for the OPTIONS response on transaction list endpoints. - - This response provides metadata about available filters, actions, - and search fields for the transaction list view. - properties: - filters_data: - type: array - items: - $ref: '#/components/schemas/FilterField' - description: |- - Array of configured filter fields for the transaction list. Each filter field describes how to filter transactions by a specific attribute. Filters are ordered by their configured display order. - - **Filter Types:** - - `dropdown`: Select from predefined options (state, currency, gateway, etc.) - - `datetime`: Date/time range filter (created, modified, state_changed_at) - - `date`: Date-only range filter - - `amount_range`: Numeric range filter with min/max bounds - export: - type: array - items: - type: string - description: |- - Available export options. - - - `default`: Standard export format - - `selected`: Custom field selection (requires `user.view_export_settings` permission) - actions: - type: array - items: - $ref: '#/components/schemas/Action' - description: |- - Available bulk actions that can be performed on transactions. - - Common actions include: - - `disclose`: Mark transactions as disclosed to merchant - - `inquiry`: Check payment status with gateway - - `acknowledge`: Acknowledge payment receipt - search_fields: - type: object - additionalProperties: - type: string - description: |- - Available search fields with their encrypted keys and labels. - - Keys are base64-encoded field identifiers. Values are human-readable field labels. - - Example: `{"AQAAAA==": "Internal ID", "Y3VzdG9tZXJfZW1haWw=": "Customer Email"}` - required: - - actions - - export - - filters_data - - search_fields - URLShortener: - type: object - properties: - url: - type: string - format: uri - description: 'The URL that needs to be shortened, Must be a valid HTTP or - HTTPS URL, For example: ''https://www.example.com'', The URL should not - exceed the maximum length of 2048 characters.' - code: - type: string - description: 'Represents the chosen URL shorter service provide ie:(djshorter, - yourls),if chosen backend will use it to shorten the URL, else backend - will use the default global configured instance,Note: the provider value - will be decided via offline communication ie(ottu core pm contacting real-estate - service pm).' - required: - - url - URPay: + - token + UserCards: type: object properties: - code: - type: string - description: The slug code of the payment method. - pattern: ^[-a-zA-Z0-9_]+$ - name: - type: string - description: The name of the payment method. type: enum: - - e_commerce - - payment_request + - sandbox + - production type: string - x-spec-enum-id: ad398830c7970f0a + x-spec-enum-id: df081db980375d31 description: |- - The type of the payment transaction. + Choose between `sandbox`, `production`. To retrieve the cards associated to specified environment type.Payment Gateway MIDs, or production to fetch real cards used in live transactions. - * `e_commerce` - Ecommerce - * `payment_request` - Payment Request - amount: - type: string - description: The total amount to be charged, including fees. - currency_code: + * `sandbox` - Sandbox + * `production` - Production + customer_id: type: string - description: The currency code for the payment method represented as an - ISO 4217 code. - maxLength: 3 - fee: + description: Retrieve cards associated with a specific customer using their unique customer_id. + pg_codes: + type: array + items: {} + description: Specify the `pg_code` if you want to retrieve cards for a particular payment gateway, such as `credit-card`. The pg_code is initialized in the `Checkout API` when the `session_id` is created, with each card being associated with a single payment gateway/pg_code. + agreement_id: type: string - description: The fee charged by the payment gateway. - fee_description: + description: Retrieve the card associated with a specific agreement ID. When this parameter is provided, the resulting array will contain a maximum of one entry, representing the latest card the customer has used for the auto-debit payment associated with the given agreement ID. + required: + - customer_id + - type + WalletAccountItem: + type: object + properties: + id: type: string - description: This field provides the label for any additional transaction - fee. In the SDK, this label will be displayed prominently during the checkout - process to inform the payer about the nature of the fee. Ensure to incorporate - this field in a clear and visible manner within the checkout UI to maintain - transparency with the end-users. - icon: + description: Wallet account ID (UUID). + customer_id: type: string - format: uri - description: The svg URL of the icon for the payment method. - icons: - allOf: - - $ref: '#/components/schemas/Icons' - description: The URLs of the icon for the payment method. - pg_icons: - allOf: - - $ref: '#/components/schemas/MIDIcon' - description: Represents list of mid icons configured for `pgmid` settings - flow: + description: Customer identifier. + currency: + type: string + description: ISO 4217 currency code (e.g. KWD, USD). + status: enum: - - urpay + - active + - suspended + - closed type: string - x-spec-enum-id: 1b60a00558bbffc5 + x-spec-enum-id: f781fab3fd9e8ab1 description: |- - Use the `submit_url` to retrieve the OTP needed to complete the payment.Then for the OTP submission process you can use the `payment_url` + Current account status. - * `urpay` - URPay - redirect_url: + * `active` - active + * `suspended` - suspended + * `closed` - closed + balance: type: string - format: uri - description: 'This field is used for the `ottu_pg` payment flow. When `flow` - is `ottu_pg`, the payer will be directly redirected to this URL. This - field is only present when `flow` is `ottu_pg`. For web integrations: - Use `window.location.href = redirect_url` to redirect the payer to the - specified URL. For mobile SDK integrations: Open the `redirect_url` in - the webview. Upon redirecting to the provided URL, the webview should - be closed and the transaction refreshed using the `Checkout SDK / Retrieve - init data API`. Detect the URL redirection by listening to redirects in - the webview. When a redirect occurs to a URL containing the `merchant_id` - domain, close the webview and reload the SDK after calling the `Retrieve - init data API`.' - branding_options: - allOf: - - $ref: '#/components/schemas/BrandingItem' - description: Merchant-supplied display customization for this payment method. - Present only when the merchant provided branding data for this pg_code - via the branding_options.payment_methods input field. - can_save_card: - type: boolean - description: When true, display a checkbox in the SDK for card saving with - this payment method. When false, do not display the checkbox. - submit_url: + description: Total account balance. + available_balance: type: string - format: uri - description: The URL used in the SMS payment flow, such as for STC Bank. - It is utilized for submitting request for an OTP and authorizing the transaction, - This URL facilitates the first steps in the transaction verification and - payment process. - billing: - allOf: - - $ref: '#/components/schemas/Billing' - description: Detailed billing information for the payment method, including - formatted amounts for display and raw values for processing. Contains - both the total transaction amount and any applicable fees with their respective - currency codes and labels. - payment_url: + description: Balance available for new transactions (excludes reserved funds). + created_at: type: string - format: uri - description: The URL used in the SMS payment flow, such as for STC Bank. - It is utilized for submitting an OTP and capturing the transaction following - the authorization process and the OTP request. This URL facilitates the - final steps in the transaction verification and payment process. - required: - - amount - - billing - - can_save_card - - code - - currency_code - - fee - - fee_description - - flow - - icon - - icons - - name - - payment_url - - type - URPayGenericError: - type: object - properties: - message: + format: date-time + description: Account creation timestamp. + updated_at: type: string - default: generic error. - URPayPayPaymentRejectedResponse: - oneOf: - - $ref: '#/components/schemas/URPayGenericError' - URPayPayRejectedResponse: + format: date-time + description: Last update timestamp. + required: + - available_balance + - balance + - created_at + - currency + - customer_id + - id + - status + - updated_at + WalletAccountsErrors: oneOf: - - $ref: '#/components/schemas/SMSPaymentSDKSuccessCallback' - - $ref: '#/components/schemas/SMSPaymentSDKCancelCallback' - - $ref: '#/components/schemas/SMSPaymentSDKErrorCallback' - URPayPaymentAuthorize: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/GenericErrorMessage" + WalletAccountsRequest: type: object properties: - message: + customer_id: type: string - default: The transaction's One-Time Password (OTP) has been successfully - sent. - UnauthorizedMessage: - type: object - properties: - error: + description: Customer identifier. + currency: + type: string + maxLength: 3 + status: + enum: + - active + - suspended + - closed type: string - default: You are not authorized to download this file - description: Error message for unauthorized access attempts - UnifiedUIInvoice: + description: |- + * `active` - active + * `suspended` - suspended + * `closed` - closed + x-spec-enum-id: f781fab3fd9e8ab1 + pagination: + $ref: "#/components/schemas/WalletPaginationCursor" + required: + - customer_id + WalletAccountsResponse: type: object properties: - id: + results: + type: array + items: + $ref: "#/components/schemas/WalletAccountItem" + description: List of wallet accounts. + count: type: integer - readOnly: true - status: + description: Total number of accounts returned. + next: + oneOf: + - $ref: "#/components/schemas/WalletPaginationCursor" + - type: "null" + description: Cursor for the next page, or null if no more pages. + previous: + oneOf: + - $ref: "#/components/schemas/WalletPaginationCursor" + - type: "null" + description: Cursor for the previous page, or null if on the first page. + required: + - count + - next + - previous + - results + WalletEntriesErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/GenericErrorMessage" + WalletEntriesRequest: + type: object + properties: + customer_id: + type: string + description: Customer identifier. + currency: + type: string + maxLength: 3 + entry_type: + enum: + - credit_refund + - debit_payment + - reserve + - release + - expire + - reversal + - credit_adjustment + - debit_adjustment + type: string + description: |- + * `credit_refund` - credit_refund + * `debit_payment` - debit_payment + * `reserve` - reserve + * `release` - release + * `expire` - expire + * `reversal` - reversal + * `credit_adjustment` - credit_adjustment + * `debit_adjustment` - debit_adjustment + x-spec-enum-id: 65a180006453c78d + direction: enum: - - sent - - paid - - overdue - - canceled + - credit + - debit type: string - x-spec-enum-id: c131c51a82b6f22a description: |- - Current status of the invoice. Can be one of the following: `sent`, `paid`, `overdue`, `canceled`. - - * `sent` - Sent - * `paid` - Paid - * `overdue` - Overdue - * `canceled` - Canceled - is_deleted: - type: boolean - title: Is Deleted? - description: Mark true to transfer this invoice to archived list. - txn: + * `credit` - credit + * `debit` - debit + x-spec-enum-id: 61c3cf55f7e48eaa + status: + enum: + - pending + - completed + - failed type: string - txn_type: + description: |- + * `pending` - pending + * `completed` - completed + * `failed` - failed + x-spec-enum-id: 6d6191fe2b5c6a10 + session_id: type: string - txn_session_id: + provider: type: string - invoice_number: + pg_code: type: string - description: A unique identifier for the invoice, typically used for tracking - and referencing purposes. - maxLength: 255 - invoice_date: + date_from: type: string format: date - readOnly: true - description: The date when the invoice was issued to the customer. - due_date: - type: - - string - - 'null' + date_to: + type: string format: date - description: The date by which the customer is expected to make payment - for the invoice. - tax_rate: + pagination: + $ref: "#/components/schemas/WalletPaginationCursor" + required: + - currency + - customer_id + WalletEntriesResponse: + type: object + properties: + results: + type: array + items: + $ref: "#/components/schemas/WalletEntryItem" + description: List of wallet ledger entries. + count: + type: integer + description: Total number of entries returned. + next: + oneOf: + - $ref: "#/components/schemas/WalletPaginationCursor" + - type: "null" + description: Cursor for the next page, or null if no more pages. + previous: + oneOf: + - $ref: "#/components/schemas/WalletPaginationCursor" + - type: "null" + description: Cursor for the previous page, or null if on the first page. + required: + - count + - next + - previous + - results + WalletEntryItem: + type: object + properties: + entry_type: + enum: + - credit_refund + - debit_payment + - reserve + - release + - expire + - reversal + - credit_adjustment + - debit_adjustment type: string - title: Tax - description: The tax rate applied to the invoice, expressed as a percentage. - maxLength: 8 - tax_amount: + x-spec-enum-id: 65a180006453c78d + description: |- + Type of ledger entry. + + * `credit_refund` - credit_refund + * `debit_payment` - debit_payment + * `reserve` - reserve + * `release` - release + * `expire` - expire + * `reversal` - reversal + * `credit_adjustment` - credit_adjustment + * `debit_adjustment` - debit_adjustment + direction: + enum: + - credit + - debit type: string - description: The total amount of tax applied to the invoice. - maxLength: 20 - discount_percentage: - type: - - string - - 'null' - description: The percentage-based discount applied to the full invoice amount, - including taxes. If set, the discount_amount field will be automatically - calculated. Both discount_amount and discount_percentage cannot be set - simultaneously. The discount cannot be higher than the `total_excl_tax` - field. - maxLength: 8 - discount_amount: - type: - - string - - 'null' - description: The fixed amount discount applied to the full invoice amount, - including taxes. If set, the discount_percentage field will be set to - null. Both discount_amount and discount_percentage cannot be set simultaneously. - The discount cannot be higher than the `total_excl_tax` field. - maxLength: 20 - shipping_tax_rate: + x-spec-enum-id: 61c3cf55f7e48eaa + description: |- + Whether the entry increases (credit) or decreases (debit) the balance. + + * `credit` - credit + * `debit` - debit + amount: type: string - description: 'The tax rate applied to the shipping cost, expressed as a - percentage. ' - maxLength: 20 - shipping_incl_tax: + description: Entry amount. + currency: type: string - title: Shipping Incl. Tax - description: The cost of shipping for the invoice, including all applicable - taxes. - maxLength: 20 - shipping_excl_tax: + description: ISO 4217 currency code. + status: + enum: + - pending + - completed + - failed type: string - title: Shipping Excl. Tax - description: The cost of shipping for the invoice, excluding taxes. - maxLength: 20 - shipping_method: + x-spec-enum-id: 6d6191fe2b5c6a10 + description: |- + Current status of the entry. + + * `pending` - pending + * `completed` - completed + * `failed` - failed + session_id: type: string - description: The method or service used for shipping the items associated - with the invoice. - maxLength: 255 - subtotal: + description: Payment session ID associated with this entry. + pg_code: type: string - description: Sum of total_incl_tax's of all invoice items. - maxLength: 20 - total_excl_tax: + description: Payment gateway code associated with this entry. + created_at: type: string - title: Total Excl. Tax - description: The total amount of the invoice, excluding taxes. - maxLength: 20 - total_incl_tax: + format: date-time + description: Entry creation timestamp. + required: + - amount + - currency + - direction + - entry_type + WalletFinalizationStatus: + type: object + properties: + status: + enum: + - SUCCEEDED + - FAILED + - CANCELLED + - PENDING type: string - title: Total Incl. Tax - description: The total amount of the invoice, including all applicable taxes. - maxLength: 20 - invoice_items: - type: array - items: - $ref: '#/components/schemas/UnifiedUIInvoiceItem' - currency_code: + description: "The finalization status of the payment transaction. `SUCCEEDED` — payment completed (paid, authorized, refunded, etc.). `FAILED` — payment did not complete (failed, expired, or invalidated). `CANCELLED` — payment was explicitly cancelled or voided. `PENDING` — payment is still in progress (created, pending, or attempted). " + x-spec-enum-id: b231c8b33220f4ec + readOnly: true + payment_transaction_id: type: string - customer_full_name: + description: The unique session identifier of the payment transaction. Corresponds to the `session_id` used when initiating the payment. + last_updated_at: type: string - company_name: + format: date-time + description: ISO 8601 timestamp of when the payment transaction last changed state. Use this to detect stale or recently updated records. + source: + enum: + - inquiry type: string - invoice_pdf_url: + description: The mechanism that last determined the current payment status. + x-spec-enum-id: d980b07fd79c8683 + readOnly: true + required: + - last_updated_at + - payment_transaction_id + - source + - status + WalletInstrument: + type: object + properties: + instrument_type: + enum: + - wallet type: string - format: uri - title: Invoice short url - description: A short URL that links to the invoice pdf file. This URL may - be included in email/sms notifications sent to the customer regarding - their payment or displayed on the checkout page to allow the customer - to easily access their invoice. - maxLength: 5000 + x-spec-enum-id: ba4affc717e2ff3d + default: wallet + description: |- + Payment type: Wallet. + + * `wallet` - wallet + payload: + allOf: + - $ref: "#/components/schemas/WalletPayload" + description: Wallet instrument payload. Must specify `wallet_code` so the native strategy knows which configured wallet to debit. + required: + - payload + WalletNativePayment: + type: object + properties: + payload: + type: object + additionalProperties: {} + pg_code: + type: + - string + - "null" + description: The unique pg_code used for this payment instrument. + session_id: + type: string + description: A unique identifier for the payment transaction (session). required: - - company_name - - currency_code - - customer_full_name - - id - - invoice_date - - invoice_items - - invoice_number - - shipping_excl_tax - - shipping_incl_tax - - shipping_tax_rate - - subtotal - - total_excl_tax - - total_incl_tax - - txn - - txn_session_id - - txn_type - UnifiedUIInvoiceItem: + - session_id + WalletOperationEntry: type: object properties: id: type: integer - readOnly: true - sku: - type: string - description: Unique identifier for the invoice item. - maxLength: 255 - description: + description: Entry ID. + entry_type: type: string - description: Product name or a brief description of the item. - maxLength: 255 - quantity: + description: Type of ledger entry. + direction: + enum: + - credit + - debit type: string - description: Number of units of the product. - maxLength: 20 - unit_price: + x-spec-enum-id: 61c3cf55f7e48eaa + description: |- + Whether the entry increases (credit) or decreases (debit) the balance. + + * `credit` - credit + * `debit` - debit + amount: type: string - description: Price per unit of the product, excluding tax. - maxLength: 20 - tax_rate: + description: Entry amount. + currency: type: string - title: Tax - description: Tax rate applied to the invoice item. - maxLength: 8 - tax_amount: + description: ISO 4217 currency code. + status: type: string - description: Total tax amount for the invoice item. - maxLength: 20 - discount_percentage: + description: Entry status. + created_at: type: string - description: Percentage-based discount applied to the invoice item. The - calculated discount cannot exceed theitem's total value, including tax. - maxLength: 8 - discount_amount: + format: date-time + description: Entry creation timestamp. + required: + - amount + - currency + - direction + - entry_type + - id + WalletOperationResponse: + type: object + properties: + operation_type: + enum: + - refund + - reservation + - deduction + - adjustment + - reversal type: string - description: Fixed amount discount applied to the invoice item. The discount - cannot exceed the item's total value, including tax. - maxLength: 20 - total_excl_tax: + x-spec-enum-id: 77531463918851c8 + description: |- + The type of wallet operation. + + * `refund` - refund + * `reservation` - reservation + * `deduction` - deduction + * `adjustment` - adjustment + * `reversal` - reversal + status: + enum: + - pending + - completed + - expired + - canceled + - failed + - reversed + - requires_review type: string - title: Total Excl. Tax - description: Total value of the invoice item, excluding tax. This is calculated - as (unit_price * quantity) - discount. - maxLength: 20 - total_incl_tax: + x-spec-enum-id: 36788b40a91bc793 + description: |- + Current status of the operation. + + * `pending` - pending + * `completed` - completed + * `expired` - expired + * `canceled` - canceled + * `failed` - failed + * `reversed` - reversed + * `requires_review` - requires_review + session_id: type: string - title: Total Incl. Tax - description: Total value of the invoice item, including tax. This is calculated - as (unit_price * quantity) - discount + applicable tax. - maxLength: 20 - required: - - description - - id - - quantity - - sku - - total_excl_tax - - total_incl_tax - - unit_price - Unit: + description: Payment session ID associated with this operation. + entries: + type: array + items: + $ref: "#/components/schemas/WalletOperationEntry" + description: Ledger entries created by this operation. + required: + - entries + - operation_type + - session_id + - status + WalletOperationsErrors: + oneOf: + - $ref: "#/components/schemas/FieldErrors" + - $ref: "#/components/schemas/GenericErrorMessage" + WalletOperationsRequest: type: object properties: - id: + operation_id: type: integer - readOnly: true - title: - type: string - slug: - type: string + description: Wallet operation ID. required: - - id - - slug - - title - UserCards: + - operation_id + WalletPaginationCursor: type: object properties: - type: + cursor: + type: + - integer + - "null" + description: Record ID cursor; null for the first page. + direction: enum: - - sandbox - - production + - forward + - backward type: string - x-spec-enum-id: df081db980375d31 + x-spec-enum-id: 437dcb7b7508c518 + default: forward description: |- - Choose between `sandbox`, `production`. To retrieve the cards associated to specified environment type.Payment Gateway MIDs, or production to fetch real cards used in live transactions. + Direction to paginate from the cursor. - * `sandbox` - Sandbox - * `production` - Production + * `forward` - forward + * `backward` - backward + per_page: + type: integer + maximum: 50 + minimum: 1 + default: 20 + description: Page size (1-50). + WalletPayload: + type: object + description: |- + Payload shape for `instrument_type=wallet`. + + Used as the runtime validator in `PaymentInstrumentWalletValidator` and + as the documented schema for the `payload` field of the wallet variant + of `payment_instrument`. + properties: + wallet_code: + type: string + description: The `code` of the active `WalletPaymentService` to debit. Required when `instrument_type=wallet` and the PGMID has more than one wallet configured (e.g. Ottu + Qitaf). The native strategy resolves the row by this code, then calls `provider.debit(...)` against it. + required: + - wallet_code + WalletServiceResponse: + type: object + properties: + amount: + type: string + description: Amount of the wallet operation. + status: + type: string + description: Operation status (e.g. 'completed', 'pending'). + currency: + type: string + description: ISO 4217 currency code. + created_at: + type: string + format: date-time + description: Operation creation timestamp. customer_id: type: string - description: Retrieve cards associated with a specific customer using their - unique customer_id. - pg_codes: - type: array - items: {} - description: Specify the `pg_code` if you want to retrieve cards for a particular - payment gateway, such as `credit-card`. The pg_code is initialized in - the `Checkout API` when the `session_id` is created, with each card being - associated with a single payment gateway/pg_code. - agreement_id: + description: Customer identifier in the wallet service. + operation_id: type: string - description: Retrieve the card associated with a specific agreement ID. - When this parameter is provided, the resulting array will contain a maximum - of one entry, representing the latest card the customer has used for the - auto-debit payment associated with the given agreement ID. - required: - - customer_id - - type + description: Wallet operation ID (opaque per provider). + payment_entry_id: + type: integer + description: Ledger entry ID for the payment debit. + reserve_entry_id: + type: integer + description: Ledger entry ID for the reservation hold. securitySchemes: SSO_BasicAuth: type: http @@ -19670,4 +9885,4 @@ components: name: Authorization description: Token-based authentication with required prefix "Token" servers: -- url: https://sandbox.ottu.net + - url: https://ksa.ottu.dev diff --git a/static/api-enrichments/_shared/permissions.yaml b/static/api-enrichments/_shared/permissions.yaml index 10f9e44f..2d801029 100644 --- a/static/api-enrichments/_shared/permissions.yaml +++ b/static/api-enrichments/_shared/permissions.yaml @@ -20,7 +20,7 @@ api_key_only: basic_auth_create_checkout: auth_method: "[Basic Auth]({{apiBaseUrl}}/getting-started/authentication/#basic-auth)" - permissions: "`Can add payment requests` ([Payment Request]({{apiBaseUrl}}/payments/payment-methods/#enabling-the-plugin)) or `Can add e-commerce payments` ([E-Commerce]({{apiBaseUrl}}/payments/payment-methods/#enabling-the-plugin))" + permissions: "`Can add payment requests` ([Payment Request](/business/plugins/payment-request)) or `Can add e-commerce payments` ([E-Commerce](/business/plugins/e-commerce))" extra: "`Can use pg_code` for the target [payment gateway]({{apiBaseUrl}}/payments/payment-methods/)" basic_auth_update_checkout: @@ -71,3 +71,10 @@ basic_auth_create_invoice: basic_auth_view_reports: auth_method: "[Basic Auth]({{apiBaseUrl}}/getting-started/authentication/#basic-auth)" permissions: "`report.can_view_report`" + +# ── Wallet API ──────────────────────────────────────────────── + +basic_auth_wallet_read: + auth_method: "[Basic Auth]({{apiBaseUrl}}/getting-started/authentication/#basic-auth)" + permissions: "`wallet.view`" + extra: "Read-only access to wallet accounts, ledger entries, and operations. Refund-to-wallet (which credits a wallet) uses `payment.refund` — see `basic_auth_operations`." diff --git a/static/api-enrichments/_variables.yaml b/static/api-enrichments/_variables.yaml index 16441e4f..f8e22756 100644 --- a/static/api-enrichments/_variables.yaml +++ b/static/api-enrichments/_variables.yaml @@ -6,4 +6,4 @@ apiBaseUrl: "/developers" glossaryUrl: "/glossary" -sandboxUrl: "https://sandbox.ottu.dev" +sandboxUrl: "https://ksa.ottu.dev" diff --git a/static/api-enrichments/operations/payment-operations.yaml b/static/api-enrichments/operations/payment-operations.yaml index 5534e420..2cb43802 100644 --- a/static/api-enrichments/operations/payment-operations.yaml +++ b/static/api-enrichments/operations/payment-operations.yaml @@ -12,6 +12,8 @@ operations: Use `session_id` or `order_no` to identify the target transaction. For `refund` and `capture`, specify `amount` (defaults to full/remaining amount). For `void`, always applies to the full amount. + Refunds can target the **original payment gateway** (default) or the **customer's wallet** by setting `destination: "wallet"`. See [Refund to Wallet]({{apiBaseUrl}}/operations#refund-to-wallet) and the [Wallet integration page]({{apiBaseUrl}}/payments/wallet/) for full behavior. + Include `Tracking-Key` header on external operations to prevent duplicates and retrieve status. inquiry: @@ -33,12 +35,12 @@ operations: - $perm:api_key_admin - $perm:basic_auth_auto_debit - apple_direct_payment: + apple_native_payment: permissions: - $perm:api_key_admin - $perm:basic_auth_native_payment - google_direct_payment: + google_native_payment: permissions: - $perm:api_key_admin - $perm:basic_auth_native_payment diff --git a/static/api-enrichments/operations/wallet.yaml b/static/api-enrichments/operations/wallet.yaml new file mode 100644 index 00000000..01fb345a --- /dev/null +++ b/static/api-enrichments/operations/wallet.yaml @@ -0,0 +1,36 @@ +# Enrichments for tag: "Wallet" +# +# Operation keys must match the operationId values in static/Ottu_API.yaml. + +operations: + + wallet_accounts: + permissions: + - $perm:api_key_admin + - $perm:basic_auth_wallet_read + description_replace: | + Returns the customer's wallet accounts — one per currency — with confirmed and available balances. + + Accounts are created lazily: one exists only after the first credit lands in that currency (a [refund to wallet]({{apiBaseUrl}}/operations/#refund-to-wallet), a manual adjustment, a promo, or a goodwill credit). A customer who has never received a wallet credit in a given currency has no account in that currency, and none is returned — `count: 0` with an empty `results` array is a valid response. + + `balance` reflects confirmed funds only; `available_balance` is `balance` minus the amounts held by in-flight checkout reservations, and is what the customer can actually spend right now. Results are cursor-paginated — pass the `pagination.cursor` value from the `next` object to fetch the following page. + + wallet_entries: + permissions: + - $perm:api_key_admin + - $perm:basic_auth_wallet_read + description_replace: | + Returns the immutable ledger of a customer's wallet account — credits, debits, reservations, releases, expiries, and adjustments — filtered by the parameters you supply. Use it to build a wallet transaction history in your own customer-facing UI. + + `customer_id` and `currency` are both required: Ottu resolves the matching wallet account internally and queries its ledger. If the customer has no account in that currency the call returns `400` with `{"detail": "No wallet account found for customer."}`. + + Each entry references the originating payment session via `session_id` when applicable. Entries are append-only — corrections are made by posting an opposing entry, never by editing or deleting an existing one. Results are cursor-paginated — pass the `pagination.cursor` value from the `next` object to fetch the following page. + + wallet_operation_details: + permissions: + - $perm:api_key_admin + - $perm:basic_auth_wallet_read + description_replace: | + Returns a single wallet operation by its `operation_id`, together with every ledger entry it produced. An operation is the atomic unit of work the wallet performs — a reservation, a refund, a deduction, an adjustment, or a reversal — and rolls up one or more ledger entries under one identifier. + + Use this when you have an operation ID from an earlier response — for example the operation returned by a [refund to wallet]({{apiBaseUrl}}/operations/#refund-to-wallet) — and you want the canonical record for audit or reconciliation. A reservation operation, for instance, produces a `reserve` entry that is later closed by a `debit_payment` entry from the deduction operation; both are returned here. diff --git a/static/api-enrichments/schemas/Inquiry.yaml b/static/api-enrichments/schemas/Inquiry.yaml new file mode 100644 index 00000000..6a7a30f4 --- /dev/null +++ b/static/api-enrichments/schemas/Inquiry.yaml @@ -0,0 +1,6 @@ +# Overrides for: components/schemas/Inquiry +# Request body for POST /b/pbl/v2/inquiry/ + +_example: + order_no: "string" + session_id: "string" diff --git a/static/api-enrichments/schemas/MessageNotification.yaml b/static/api-enrichments/schemas/MessageNotification.yaml index 0fcc9d88..815104b2 100644 --- a/static/api-enrichments/schemas/MessageNotification.yaml +++ b/static/api-enrichments/schemas/MessageNotification.yaml @@ -2,6 +2,8 @@ # Request body for POST /b/pbl/v2/notification/message/ _example: + session_id: "string" + order_no: "string" channels: - sms - email diff --git a/static/api-enrichments/schemas/Operation.yaml b/static/api-enrichments/schemas/Operation.yaml new file mode 100644 index 00000000..d018d754 --- /dev/null +++ b/static/api-enrichments/schemas/Operation.yaml @@ -0,0 +1,11 @@ +# Overrides for: components/schemas/Operation — the request body of POST /b/pbl/v2/operation/ + +properties: + destination: + description: | + Where refund proceeds are credited. Applies only when `operation` is `refund`; ignored for every other operation type. Defaults to `pg`. + + - `pg` (default) — funds are returned through the original payment gateway, exactly as a refund behaves without this field. + - `wallet` — funds are credited to the customer's [wallet]({{apiBaseUrl}}/payments/wallet/) balance for use at future Ottu checkouts. Requires that the settling payment method has an active wallet service and that the transaction has a `customer_id`. A wallet account is created automatically if one doesn't already exist for the `(merchant, customer_id, currency)` combination, and the credit is recorded as an immutable ledger entry linked to the original payment session. + + Cross-currency credits are not supported — the wallet credit currency always matches the original payment currency. diff --git a/static/api-enrichments/schemas/WalletAccountsRequest.yaml b/static/api-enrichments/schemas/WalletAccountsRequest.yaml new file mode 100644 index 00000000..f5369b16 --- /dev/null +++ b/static/api-enrichments/schemas/WalletAccountsRequest.yaml @@ -0,0 +1,9 @@ +# Overrides for: components/schemas/WalletAccountsRequest +# Request body for the wallet accounts endpoint (List Wallet Accounts). +# +# Keeps the API explorer "Try it" example minimal, scoped to the +# sandbox-usd demo customer in USD. + +_example: + customer_id: sandbox-usd + currency: USD diff --git a/static/api-enrichments/schemas/WalletEntriesRequest.yaml b/static/api-enrichments/schemas/WalletEntriesRequest.yaml new file mode 100644 index 00000000..3a56fe85 --- /dev/null +++ b/static/api-enrichments/schemas/WalletEntriesRequest.yaml @@ -0,0 +1,9 @@ +# Overrides for: components/schemas/WalletEntriesRequest +# Request body for the wallet ledger entries endpoint (List Ledger Entries). +# +# Keeps the API explorer "Try it" example minimal — only the two required +# fields, scoped to the sandbox-usd demo customer in USD. + +_example: + customer_id: sandbox-usd + currency: USD diff --git a/static/img/architecture-dark.svg b/static/img/architecture-dark.svg deleted file mode 100644 index 404695db..00000000 --- a/static/img/architecture-dark.svg +++ /dev/null @@ -1,105 +0,0 @@ - - Ottu Platform Architecture - The merchant backend calls Ottu's REST API. The customer enters card details in the Checkout SDK embedded in the merchant frontend. Ottu's orchestration engine routes to 45+ payment gateways. Webhooks deliver HMAC-signed outcome events back to the merchant backend. - - - - - - - - - - - OTTU PLATFORM - - - - Customer - - - - Merchant Frontend - Website or mobile app - - - - Merchant Backend - Your server - - - - Checkout SDK - Web · iOS · Android · Flutter - - - - REST API - Api-Key · Basic auth - - - - Orchestration Engine - Smart routing · Failover - - - - Webhooks - HMAC-SHA256 signed events - - - - Payment Gateway - - KNET - MPGS - Cybersource - Tabby · Tamara - STC Bank · Benefit - + 40 more gateways - - - - - - enters card - - - - - embeds - - - - - REST calls - - - - - - - - - - - routes - - - - - HMAC events - diff --git a/static/img/architecture-light.svg b/static/img/architecture-light.svg deleted file mode 100644 index bbaf5120..00000000 --- a/static/img/architecture-light.svg +++ /dev/null @@ -1,105 +0,0 @@ - - Ottu Platform Architecture - The merchant backend calls Ottu's REST API. The customer enters card details in the Checkout SDK embedded in the merchant frontend. Ottu's orchestration engine routes to 45+ payment gateways. Webhooks deliver HMAC-signed outcome events back to the merchant backend. - - - - - - - - - - - OTTU PLATFORM - - - - Customer - - - - Merchant Frontend - Website or mobile app - - - - Merchant Backend - Your server - - - - Checkout SDK - Web · iOS · Android · Flutter - - - - REST API - Api-Key · Basic auth - - - - Orchestration Engine - Smart routing · Failover - - - - Webhooks - HMAC-SHA256 signed events - - - - Payment Gateway - - KNET - MPGS - Cybersource - Tabby · Tamara - STC Bank · Benefit - + 40 more gateways - - - - - - enters card - - - - - embeds - - - - - REST calls - - - - - - - - - - - routes - - - - - HMAC events - diff --git a/static/img/business/wallet/.gitkeep b/static/img/business/wallet/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/static/img/business/wallet/payment-request-transactions.png b/static/img/business/wallet/payment-request-transactions.png new file mode 100644 index 00000000..537e8924 Binary files /dev/null and b/static/img/business/wallet/payment-request-transactions.png differ diff --git a/static/img/business/wallet/recon-procedure-01-transactions-list.png b/static/img/business/wallet/recon-procedure-01-transactions-list.png new file mode 100644 index 00000000..19bbf3db Binary files /dev/null and b/static/img/business/wallet/recon-procedure-01-transactions-list.png differ diff --git a/static/img/business/wallet/recon-procedure-02-classify.png b/static/img/business/wallet/recon-procedure-02-classify.png new file mode 100644 index 00000000..524c44fb Binary files /dev/null and b/static/img/business/wallet/recon-procedure-02-classify.png differ diff --git a/static/img/business/wallet/recon-procedure-03-amount-split.png b/static/img/business/wallet/recon-procedure-03-amount-split.png new file mode 100644 index 00000000..630f4ee7 Binary files /dev/null and b/static/img/business/wallet/recon-procedure-03-amount-split.png differ diff --git a/static/img/business/wallet/recon-procedure-04-refund-credit.png b/static/img/business/wallet/recon-procedure-04-refund-credit.png new file mode 100644 index 00000000..2ce5122c Binary files /dev/null and b/static/img/business/wallet/recon-procedure-04-refund-credit.png differ diff --git a/static/img/business/wallet/reconciliation-01-parent-amounts.png b/static/img/business/wallet/reconciliation-01-parent-amounts.png new file mode 100644 index 00000000..c390b54a Binary files /dev/null and b/static/img/business/wallet/reconciliation-01-parent-amounts.png differ diff --git a/static/img/business/wallet/reconciliation-02-child-transaction.png b/static/img/business/wallet/reconciliation-02-child-transaction.png new file mode 100644 index 00000000..b50c6890 Binary files /dev/null and b/static/img/business/wallet/reconciliation-02-child-transaction.png differ diff --git a/static/img/business/wallet/refund-01-transaction.png b/static/img/business/wallet/refund-01-transaction.png new file mode 100644 index 00000000..ebebda39 Binary files /dev/null and b/static/img/business/wallet/refund-01-transaction.png differ diff --git a/static/img/business/wallet/refund-02-refund-button.png b/static/img/business/wallet/refund-02-refund-button.png new file mode 100644 index 00000000..c4e63716 Binary files /dev/null and b/static/img/business/wallet/refund-02-refund-button.png differ diff --git a/static/img/business/wallet/refund-04-confirm.png b/static/img/business/wallet/refund-04-confirm.png new file mode 100644 index 00000000..ffde7f5c Binary files /dev/null and b/static/img/business/wallet/refund-04-confirm.png differ diff --git a/static/img/business/wallet/refund-05-success.png b/static/img/business/wallet/refund-05-success.png new file mode 100644 index 00000000..36997c14 Binary files /dev/null and b/static/img/business/wallet/refund-05-success.png differ diff --git a/static/img/business/wallet/reporting-01-accounts-listing.png b/static/img/business/wallet/reporting-01-accounts-listing.png new file mode 100644 index 00000000..6aa92625 Binary files /dev/null and b/static/img/business/wallet/reporting-01-accounts-listing.png differ diff --git a/static/img/business/wallet/reporting-01-accounts.png b/static/img/business/wallet/reporting-01-accounts.png new file mode 100644 index 00000000..593ca032 Binary files /dev/null and b/static/img/business/wallet/reporting-01-accounts.png differ diff --git a/static/img/business/wallet/reporting-02-filter.png b/static/img/business/wallet/reporting-02-filter.png new file mode 100644 index 00000000..dfaa1a5a Binary files /dev/null and b/static/img/business/wallet/reporting-02-filter.png differ diff --git a/static/img/business/wallet/reporting-03-detail.png b/static/img/business/wallet/reporting-03-detail.png new file mode 100644 index 00000000..f97c6df7 Binary files /dev/null and b/static/img/business/wallet/reporting-03-detail.png differ diff --git a/static/img/business/wallet/reporting-04-ledger.png b/static/img/business/wallet/reporting-04-ledger.png new file mode 100644 index 00000000..2ce5122c Binary files /dev/null and b/static/img/business/wallet/reporting-04-ledger.png differ diff --git a/static/img/business/wallet/reporting-05-operations.png b/static/img/business/wallet/reporting-05-operations.png new file mode 100644 index 00000000..7ed4a99c Binary files /dev/null and b/static/img/business/wallet/reporting-05-operations.png differ diff --git a/static/img/business/wallet/reporting-05-operations1.png b/static/img/business/wallet/reporting-05-operations1.png new file mode 100644 index 00000000..4ca09362 Binary files /dev/null and b/static/img/business/wallet/reporting-05-operations1.png differ diff --git a/static/img/business/wallet/reporting-06-export.png b/static/img/business/wallet/reporting-06-export.png new file mode 100644 index 00000000..d1f72c4c Binary files /dev/null and b/static/img/business/wallet/reporting-06-export.png differ diff --git a/static/img/business/wallet/reporting-06-ledger-exporting.png b/static/img/business/wallet/reporting-06-ledger-exporting.png new file mode 100644 index 00000000..7e116eb2 Binary files /dev/null and b/static/img/business/wallet/reporting-06-ledger-exporting.png differ diff --git a/static/img/business/wallet/reporting-07-export-cursor-step.png b/static/img/business/wallet/reporting-07-export-cursor-step.png new file mode 100644 index 00000000..c2e15db7 Binary files /dev/null and b/static/img/business/wallet/reporting-07-export-cursor-step.png differ diff --git a/static/img/business/wallet/reporting-ledger-filters.png b/static/img/business/wallet/reporting-ledger-filters.png new file mode 100644 index 00000000..a03aaf79 Binary files /dev/null and b/static/img/business/wallet/reporting-ledger-filters.png differ diff --git a/static/img/developers/wallet/.gitkeep b/static/img/developers/wallet/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/static/img/developers/wallet/full_coverage.png b/static/img/developers/wallet/full_coverage.png new file mode 100644 index 00000000..d7ae60d4 Binary files /dev/null and b/static/img/developers/wallet/full_coverage.png differ diff --git a/static/img/developers/wallet/no_wallet_01.png b/static/img/developers/wallet/no_wallet_01.png new file mode 100644 index 00000000..d838e387 Binary files /dev/null and b/static/img/developers/wallet/no_wallet_01.png differ diff --git a/static/img/developers/wallet/partial_coverage_03.png b/static/img/developers/wallet/partial_coverage_03.png new file mode 100644 index 00000000..dd80542a Binary files /dev/null and b/static/img/developers/wallet/partial_coverage_03.png differ diff --git a/static/img/developers/wallet/refund_operation.png b/static/img/developers/wallet/refund_operation.png new file mode 100644 index 00000000..40f10624 Binary files /dev/null and b/static/img/developers/wallet/refund_operation.png differ diff --git a/static/img/developers/wallet/sdk-01-wallet-method-android.png b/static/img/developers/wallet/sdk-01-wallet-method-android.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-01-wallet-method-android.png differ diff --git a/static/img/developers/wallet/sdk-01-wallet-method-flutter.png b/static/img/developers/wallet/sdk-01-wallet-method-flutter.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-01-wallet-method-flutter.png differ diff --git a/static/img/developers/wallet/sdk-01-wallet-method-ios.png b/static/img/developers/wallet/sdk-01-wallet-method-ios.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-01-wallet-method-ios.png differ diff --git a/static/img/developers/wallet/sdk-01-wallet-method.png b/static/img/developers/wallet/sdk-01-wallet-method.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-01-wallet-method.png differ diff --git a/static/img/developers/wallet/sdk-02-full-coverage-android.png b/static/img/developers/wallet/sdk-02-full-coverage-android.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-02-full-coverage-android.png differ diff --git a/static/img/developers/wallet/sdk-02-full-coverage-flutter.png b/static/img/developers/wallet/sdk-02-full-coverage-flutter.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-02-full-coverage-flutter.png differ diff --git a/static/img/developers/wallet/sdk-02-full-coverage-ios.png b/static/img/developers/wallet/sdk-02-full-coverage-ios.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-02-full-coverage-ios.png differ diff --git a/static/img/developers/wallet/sdk-02-full-coverage.png b/static/img/developers/wallet/sdk-02-full-coverage.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-02-full-coverage.png differ diff --git a/static/img/developers/wallet/sdk-03-partial-coverage-android.png b/static/img/developers/wallet/sdk-03-partial-coverage-android.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-03-partial-coverage-android.png differ diff --git a/static/img/developers/wallet/sdk-03-partial-coverage-flutter.png b/static/img/developers/wallet/sdk-03-partial-coverage-flutter.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-03-partial-coverage-flutter.png differ diff --git a/static/img/developers/wallet/sdk-03-partial-coverage-ios.png b/static/img/developers/wallet/sdk-03-partial-coverage-ios.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-03-partial-coverage-ios.png differ diff --git a/static/img/developers/wallet/sdk-03-partial-coverage.png b/static/img/developers/wallet/sdk-03-partial-coverage.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-03-partial-coverage.png differ diff --git a/static/img/developers/wallet/sdk-04-authorize-hidden-android.png b/static/img/developers/wallet/sdk-04-authorize-hidden-android.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-04-authorize-hidden-android.png differ diff --git a/static/img/developers/wallet/sdk-04-authorize-hidden-flutter.png b/static/img/developers/wallet/sdk-04-authorize-hidden-flutter.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-04-authorize-hidden-flutter.png differ diff --git a/static/img/developers/wallet/sdk-04-authorize-hidden-ios.png b/static/img/developers/wallet/sdk-04-authorize-hidden-ios.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-04-authorize-hidden-ios.png differ diff --git a/static/img/developers/wallet/sdk-04-authorize-hidden.png b/static/img/developers/wallet/sdk-04-authorize-hidden.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-04-authorize-hidden.png differ diff --git a/static/img/developers/wallet/sdk-05-live-demo-android.png b/static/img/developers/wallet/sdk-05-live-demo-android.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-05-live-demo-android.png differ diff --git a/static/img/developers/wallet/sdk-05-live-demo-flutter.png b/static/img/developers/wallet/sdk-05-live-demo-flutter.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-05-live-demo-flutter.png differ diff --git a/static/img/developers/wallet/sdk-05-live-demo-ios.png b/static/img/developers/wallet/sdk-05-live-demo-ios.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-05-live-demo-ios.png differ diff --git a/static/img/developers/wallet/sdk-05-live-demo.png b/static/img/developers/wallet/sdk-05-live-demo.png new file mode 100644 index 00000000..909c66db Binary files /dev/null and b/static/img/developers/wallet/sdk-05-live-demo.png differ diff --git a/static/img/developers/wallet/wallet_available.png b/static/img/developers/wallet/wallet_available.png new file mode 100644 index 00000000..c659c0d0 Binary files /dev/null and b/static/img/developers/wallet/wallet_available.png differ diff --git a/static/img/developers/wallet/wallet_reservation_03.gif b/static/img/developers/wallet/wallet_reservation_03.gif new file mode 100644 index 00000000..a259c213 Binary files /dev/null and b/static/img/developers/wallet/wallet_reservation_03.gif differ diff --git a/static/img/docusaurus-social-card.jpg b/static/img/docusaurus-social-card.jpg deleted file mode 100644 index ffcb4482..00000000 Binary files a/static/img/docusaurus-social-card.jpg and /dev/null differ diff --git a/static/schemas/SchemaWebhook.json b/static/schemas/SchemaWebhook.json index b6236a09..ee47e655 100644 --- a/static/schemas/SchemaWebhook.json +++ b/static/schemas/SchemaWebhook.json @@ -231,6 +231,82 @@ "description": "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.", "maxLength": 32 }, + "customer_wallet_transactions": { + "type": "array", + "items": { + "type": "object", + "description": "One wallet leg in `customer_wallet_transactions`.\n\nA txn that uses multiple wallets (Ottu + Qitaf stacked, etc.) emits one\nrecord per provider. Single-wallet txns emit a one-element list.", + "properties": { + "amount": { + "type": "string", + "description": "Amount charged from this wallet." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Wallet transaction creation timestamp." + }, + "currency": { + "type": "string", + "description": "ISO 4217 currency code." + }, + "modified_at": { + "type": "string", + "format": "date-time", + "description": "Wallet transaction last modification timestamp." + }, + "operation_id": { + "type": "string", + "description": "Wallet service operation ID (opaque per provider)." + }, + "provider_code": { + "type": "string", + "description": "Stable identifier of the wallet provider that handled this leg (e.g. `wallet_ottu`, `wallet_qitaf`). Empty for legacy native payments where the provider wasn't recorded on the attempt." + }, + "wallet_response": { + "properties": { + "amount": { + "type": "string", + "description": "Amount of the wallet operation." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Operation creation timestamp." + }, + "currency": { + "type": "string", + "description": "ISO 4217 currency code." + }, + "customer_id": { + "type": "string", + "description": "Customer identifier in the wallet service." + }, + "operation_id": { + "type": "string", + "description": "Wallet operation ID (opaque per provider)." + }, + "payment_entry_id": { + "type": "integer", + "description": "Ledger entry ID for the payment debit." + }, + "reserve_entry_id": { + "type": "integer", + "description": "Ledger entry ID for the reservation hold." + }, + "status": { + "type": "string", + "description": "Operation status (e.g. 'completed', 'pending')." + } + }, + "type": "object", + "description": "Full response returned by the wallet service for this leg." + } + } + }, + "readOnly": true, + "description": "List of wallet legs that contributed to this payment — one entry per wallet provider (Ottu, Qitaf, …). Multi-wallet stacking emits multiple entries; full or single-wallet payments emit a one-element list. Omitted entirely (key absent) when no wallet was involved." + }, "extra": { "description": "The extra information for the payment details, which the merchant has sent it in key value form." }, @@ -489,7 +565,7 @@ "customer_id": { "type": "string", "description": "The unique identifier for the customer who owns the card", - "maxLength": 36 + "maxLength": 64 }, "cvv_required": { "type": "boolean",