Qontak | Chatbot & AI | Midtrans Native Integration — Phase 1: P0 Core Actions
Midtrans provider — Phase 1 (P0 Core Actions) PRD under the Native Integration ANCHOR. Midtrans is the inaugural payment provider of the Native Integration umbrella (folded in from the former standalone
midtrans-native-integration/initiative on 2026-06-17). Imported from Confluence.
HEADER BLOCK
| Field | Value |
|---|---|
| PM | Dimas Fauzi Hidayat |
| PRD Version | 1.2 |
| Status | DRAFT |
| PRD Type | NEW |
| Epic | BOT-4340 |
| Squad | BOT |
| RFC Link | Planned — RFC to be created and linked once aligned with engineering team |
| Figma Master | N/A — no UI changes in this phase (follows Google Calendar native integration pattern) |
| Anchor | Native Integration — ANCHOR — Midtrans provider (Confluence) |
| Labels | epic:chatbot-ai | module:ai-agent | feature:midtrans-native-integration |
| Last Updated | 2026-06-15 |
2. One-liner + Problem
One-liner: Enable the Qontak AI Agent to check, create, cancel, and refund Midtrans payments natively — without agents leaving the conversation.
Problem: Qontak admins and supervisors who want to automate payment-related customer interactions via the AI Agent are currently forced to use the generic API Integration action menu, which requires manual configuration of API endpoints, headers, request body, and authentication credentials — a process too technical for non-developer users. As a result, routine payment tasks (checking payment status, generating payment links, processing cancellations and refunds) remain dependent on human agents despite being fully automatable. This increases agent response time and resolution time, and prevents businesses from closing sales or resolving support tickets autonomously via the AI Agent in real time.
3. Target Users + Persona Context
| Persona | Role | Goal | Pain | Workaround |
|---|---|---|---|---|
| Primary — Admin/SPV | Qontak admin or supervisor responsible for configuring AI Agent flows on behalf of their company | Configure Midtrans payment actions in the AI Agent without developer involvement | Generic API Integration action menu requires manual URL, header, body, and auth configuration — too technical for non-developer admins | Use the API Integration action menu with developer assistance, or escalate payment queries entirely to human CS agents |
4. Non-Goals
- Midtrans dashboard UI embedded in Qontak — no in-app transaction management view in this phase.
- Support for multiple Midtrans accounts per workspace — single account connection only.
- Manual trigger by human agents — all P0 actions are AI Agent-initiated only in this phase.
- P1 billing & subscription actions (create_snap_token, create_invoice, get_invoice, void_invoice, create_subscription, get_subscription, cancel_subscription) — deferred to Phase 2.
- P2 advanced actions (get_transaction_history, capture_transaction, direct_refund, update_subscription) — deferred to Phase 3.
5. Constraints
- Platform: AI Agent configuration — Web only. Conversation output — Web + Mobile (read-only on mobile).
- Performance: AI Agent action must complete within 60 seconds. Requests exceeding 60s are timed out.
- Data limits: Aligned with Midtrans API limits per endpoint (to be confirmed during RFC).
- Plan scope: Sales Suite Plus, Ultimate, and Qontak 360 only. Not available on Starter or Free plans.
- Feature flag: TBD (to be aligned with engineering team) | default: OFF
- Read/write: Admin/SPV: Can configure, edit, and disconnect. AI Agent: Can execute. CS Agent/Human: Read-only.
- Auth: All actions use Bearer token via BOT-4243 midtrans_oauth auth_type. Redis cache ~15 min TTL. Credentials: server_key, client_key, environment (sandbox/production), partner_id (optional), merchant_id (optional).
6. New Features
This phase introduces 4 new Midtrans native action types in the AI Agent action builder (Bot & Automation → Actions). Each appears as an independent entry in the action type selector, following the Google Calendar native integration UX pattern.
Shared UX: URL: /bot-automation/actions. Access: Admin and SPV on eligible plans with flag ON.
Shared component tree (all 4 action config panels):
- MidtransActionConfigPanel
- ActionNameField (text, required)
- TriggerDescriptionField (textarea, required)
- MidtransAuthBlock
- ConnectionStatusIndicator
- ConnectButton (if not connected) — opens ServerKeyField, ClientKeyField, EnvironmentSelector, PartnerIdField (optional), MerchantIdField (optional)
- ReauthorizeButton (if connected)
- DisconnectButton (if connected)
- DynamicFieldsSection (action-specific; per Midtrans API docs; confirmed during RFC)
Shared UI States:
- Loading: Skeleton loader while auth status is fetched
- Empty: All fields blank; auth block shows "Not connected" with ConnectButton; Save disabled
- Error: "Failed to connect to Midtrans. Check your credentials and try again." Save disabled.
- Success: "Midtrans connected [environment]" shown; Save enabled on required fields filled
4 Action Types — provisional DynamicFieldsSection per action. Field lists below are a first pass drawn from the public Midtrans API docs to give Engineering a concrete starting contract. They are draft — confirm exact names, types, and required/optional status during RFC (tracked in Open Question #3).
Action 1 — Check Payment Status (GET /v2/{order_id}/status)
| Field | Type | Req? | Source | Notes |
|---|---|---|---|---|
| order_id | string | required | customer message / config | Path param; the Midtrans order_id (or transaction_id) to look up |
No request body — read-only status lookup.
Action 2 — Create Payment Link (POST /v1/payment-links)
| Field | Type | Req? | Source | Notes |
|---|---|---|---|---|
| transaction_details.order_id | string | required | config / conversation | Unique per link |
| transaction_details.gross_amount | integer (IDR) | required | conversation / config | Must equal sum of item_details prices if item_details sent |
| item_details[] | array (id, name, price, quantity) | recommended | config | Line items shown on the payment page |
| customer_details | object (first_name, last_name, email, phone) | optional | conversation | Pre-fills payer info |
| usage_limit | integer | optional | config | Max number of successful payments against the link |
| expiry | object (start_time, duration, unit) | optional | config | Link validity window; defaults to Midtrans account setting if omitted |
| enabled_payments[] | array | optional | config | Restrict to specific payment channels |
Action 3 — Cancel Transaction (POST /v2/{order_id}/cancel)
| Field | Type | Req? | Source | Notes |
|---|---|---|---|---|
| order_id | string | required | customer message / conversation | Path param; transaction to cancel |
No request body — cancel is keyed on the path order_id. Cancellable only from pending/authorize (enforced by the pre-check in §7 #3).
Action 4 — Request Refund (POST /v2/{order_id}/refund)
| Field | Type | Req? | Source | Notes |
|---|---|---|---|---|
| order_id | string | required | customer message / conversation | Path param; transaction to refund |
| refund_key | string | optional (recommended) | system-generated | Idempotency/reference key — see §7 idempotency note |
| amount | integer (IDR) | optional | conversation / config | Omit for full refund; provide for partial refund (if enabled on the merchant account) |
| reason | string | optional | conversation | Free-text refund reason, surfaced in Midtrans dashboard |
7. API & Webhook Behavior
All actions use Authorization: Bearer token via BOT-4243. Technical details (HTTP methods, JSON schemas, error codes) resolved during RFC.
| # | Behavior | Entity Affected | Triggered By | Expected Behavior | Failure Behavior |
|---|---|---|---|---|---|
| 1 | Check Payment Status | Payment record (read-only) | AI Agent identifies payment status intent | Calls GET /v2/{order_id}/status. Returns status (settlement/pending/deny/cancel/expire/failure) in conversation. Logs midtrans_action_success. | Timeout >60s: error message + log timeout. Invalid order_id (404): "Payment not found." Auth failure: refresh attempted; if fails, log auth_error. |
| 2 | Create Payment Link | Payment link (created in Midtrans) | AI Agent identifies payment/purchase intent | Calls POST /v1/payment-links. Returns URL as WhatsApp CTA-URL button (WhatsApp) or clickable link (other channels). Logs midtrans_payment_link_created. | Timeout: error message + log timeout. Invalid fields (400): "Unable to create payment link." Auth failure: same pattern. |
| 3 | Cancel Transaction | Transaction status (changed to cancelled) | AI Agent receives explicit customer confirmation | Checks status first (GET /v2/{order_id}/status). If cancellable (pending/authorize): shows confirmation prompt. On confirm: calls POST /v2/{order_id}/cancel. | Not cancellable: "Cannot cancel — current status: [status]." Cancel endpoint NOT called. Customer declines: "Not cancelled." Timeout: error + log. Auth failure: abort + log. |
| 4 | Request Refund | Transaction (refund initiated) | AI Agent receives explicit customer confirmation | Checks eligibility first. If settlement: shows confirmation prompt. On confirm: calls POST /v2/{order_id}/refund. | Not eligible: "Not eligible for refund — status: [status]." Refund NOT called. Customer declines: "No refund requested." Timeout: error + log. Auth failure: abort + log. |
Idempotency, rate limits & partial refunds (to resolve during RFC):
- Idempotency on mutating calls (cancel #3, refund #4). A flaky WhatsApp connection can produce a duplicated customer "yes", risking a double cancel/refund POST. Cancel is naturally idempotent on Midtrans (a second cancel on an already-cancelled order is rejected by the status pre-check). Refund is not — RFC must define a
refund_key(idempotency key) per refund attempt and a short in-conversation dedupe window so one confirmation maps to exactly one refund POST. - Rate limits. Midtrans enforces per-endpoint rate limits. RFC to define backoff/retry behavior and the user-facing message when a call is rate-limited (distinct from the generic timeout copy).
- Partial vs. full refund. Refund supports an optional
amount(full when omitted, partial when provided). RFC to confirm whether partial refunds are in scope for P0; if so, S05 needs an AC for the partial-amount path. Default assumption for P0: full refund only unless RFC decides otherwise.
8. System Flow + User Stories + ACs
8.1 System Flow
Setup Phase (Admin configures action):
- Admin navigates to Bot & Automation → Actions
- Admin creates new action, selects Midtrans action type
- Config panel opens with Action name, Trigger description, auth block (Not connected), disabled dynamic fields
- Admin enters credentials → clicks Connect
- System validates credentials. Valid → "Midtrans connected [env]." Invalid → error shown.
- Admin fills dynamic fields → clicks Save
- Action created and appears in Actions list
Execution Phase (AI Agent executes in conversation): 8. Customer sends message; AI Agent identifies payment intent 9. System calls BOT-4243 token manager → retrieves/refreshes Bearer token 10. For cancel/refund: system validates transaction state first; AI Agent asks for customer confirmation 11. System calls Midtrans API endpoint 12. On success: AI Agent delivers result (create_payment_link → CTA-URL button on WhatsApp; others → text) 13. On failure: AI Agent returns error message; midtrans_action_failed logged
8.2 User Stories
MIDTRANS-S01 — Admin configures a Midtrans native action | Must Have
Story: As an Admin/SPV, I want to configure a Midtrans native action in the AI Agent action builder, so that the AI Agent can execute Midtrans payment operations without requiring manual API configuration.
Before: Admin used the generic API Integration menu requiring manual endpoint/header/body/auth setup. After: Admin selects a Midtrans action type and connects credentials once via a native integration panel.
Data Fields: action_name (string, required), trigger_description (string, required), server_key (string, required), client_key (string, required), environment (sandbox/production, required), partner_id (string, optional), merchant_id (string, optional), [action_dynamic_fields] (per Midtrans API docs)
Happy Path:
- AC-1: Given I am an Admin/SPV on the Actions page (eligible plan, flag ON), when I select a Midtrans action type, then the config panel opens with Action name, Trigger description, auth block "Not connected", and disabled dynamic fields.
- AC-2: Given auth block shows "Not connected", when I click Connect and enter valid credentials, then auth block shows "Midtrans connected [environment]" and dynamic fields become enabled.
- AC-3: Given connection established and required fields filled, when I click Save, then action appears in Actions list with correct Midtrans action type label.
- AC-4: Given existing Midtrans action, when I click Re-authorize and enter updated credentials, then connection is refreshed and updated environment is shown.
Error Path:
- ERR-1: Given invalid credentials, when I click Connect, then "Connection failed. Check your credentials and try again." Save remains disabled. Event midtrans_action_failed logged reason: auth_error.
- ERR-2: Given connection not established, when I attempt to Save, then "Midtrans connection required before saving."
- ERR-3: Given panel open, when auth status fetch fails on load, then "Failed to load configuration. Try again." + Retry button. Event logged reason: panel_load_error.
Permission Model:
- CAN: Admin, SPV (eligible plan, flag ON)
- CANNOT: CS Agents, read-only users
- Unauthorized: Midtrans action types not rendered in selector for ineligible roles/plans
UI States: Loading (skeleton), Empty (all blank, Not connected), Error (load failed + Retry), Success (connected, fields filled, Save enabled)
MIDTRANS-S02 — AI Agent checks payment status | Must Have
Story: As a customer talking to the Qontak AI Agent, I want to ask about my payment status and receive an immediate answer, so that I don't need to wait for a human agent.
Before: AI Agent couldn't check payment status; CS agent manually navigated to Midtrans dashboard. After: AI Agent calls GET /v2/{order_id}/status and returns status in the conversation in real time.
Data Fields: order_id (string, required — from customer message), bearer_token (string, required — BOT-4243), action_type (check_payment_status, internal)
Happy Path:
- AC-1: Given Check Payment Status action configured (flag ON), when customer asks about status and AI Agent identifies order_id, then AI Agent calls GET /v2/{order_id}/status and returns status in conversation.
- AC-2: Given API call completes within 60s, when Midtrans returns valid status, then AI Agent delivers natural language message. Event midtrans_action_success logged with action_type, order_id, status.
- AC-3: Given customer has not provided order_id, when AI Agent identifies payment status intent, then AI Agent asks customer for order_id before calling API.
Error Path:
- ERR-1: Given check_payment_status called, when no response within 60s, then AI Agent: "I was unable to check your payment status. Please try again or contact support." Event logged reason: timeout.
- ERR-2: Given non-existent order_id, when Midtrans returns 404, then AI Agent: "I couldn't find a payment with that order ID. Please verify and try again."
- ERR-3: Given Bearer token expired and refresh fails, then error message in conversation + event logged reason: auth_error.
Permission Model: CAN: AI Agent (configured, flag ON, eligible plan). CANNOT: Human CS agents (no manual trigger). Unauthorized: Not executed if flag OFF or action not configured.
UI States: Loading (typing indicator ≤60s), Empty (N/A — AI Agent prompts for order_id), Error (error message in conversation), Success (status delivered in conversation)
MIDTRANS-S03 — AI Agent creates a payment link | Must Have
Story: As a customer talking to the Qontak AI Agent, I want to receive a payment link directly in our conversation, so that I can complete my purchase immediately without leaving the chat.
Before: CS agent manually created payment link in Midtrans, pasted as plain text. After: AI Agent calls POST /v1/payment-links and delivers URL as WhatsApp CTA-URL button (WhatsApp) or clickable link (other channels) — no human involvement.
Data Fields: [transaction_fields] (per Midtrans POST /v1/payment-links API docs, required), bearer_token (required — BOT-4243), channel_type (whatsapp/other — determines link delivery format)
Happy Path:
- AC-1: Given Create Payment Link action configured (flag ON), when AI Agent identifies payment intent and all required fields available, then AI Agent calls POST /v1/payment-links using Bearer token.
- AC-2: Given valid URL returned within 60s, when channel is WhatsApp, then AI Agent sends URL as WhatsApp CTA-URL button (not plain text). Event midtrans_payment_link_created logged channel_type: whatsapp.
- AC-3: Given valid URL returned, when channel is NOT WhatsApp, then AI Agent sends URL as clickable link. Event logged with appropriate channel_type.
Error Path:
- ERR-1: Given create_payment_link called, when no response within 60s, then "I was unable to generate a payment link. Please try again or contact support." Event logged reason: timeout.
- ERR-2: Given Midtrans returns 400 (invalid/missing fields), then "I was unable to create a payment link. Please contact support." Event logged reason: invalid_request.
- ERR-3: Given Bearer token refresh fails, then action aborted + event logged reason: auth_error.
Permission Model: CAN: AI Agent (configured, flag ON, eligible plan). CANNOT: Human CS agents (no manual trigger). CANNOT: Payment links cannot be revoked via this action once created. Link expiry governed by Midtrans account settings. Unauthorized: Not executed if flag OFF.
UI States: Loading (typing indicator ≤60s), Empty (N/A — fields must be present), Error (error message in conversation), Success (CTA-URL button on WhatsApp / clickable link on other channels)
MIDTRANS-S04 — AI Agent cancels a transaction (with confirmation) | Must Have
Story: As a customer talking to the Qontak AI Agent, I want to cancel my transaction through the chat, so that I can reverse my order without waiting for a human agent.
Before: CS agent manually processed cancellation in Midtrans dashboard. After: AI Agent validates cancellability, requests customer confirmation, then calls POST /v2/{order_id}/cancel — fully automated.
Data Fields: order_id (required — from customer), transaction_status (internal — retrieved via status check), customer_confirmation (boolean, required), bearer_token (required — BOT-4243)
Happy Path:
- AC-1: Given Cancel Transaction action configured (flag ON), when AI Agent identifies cancellation request with order_id, then AI Agent calls GET /v2/{order_id}/status first to check if transaction is cancellable (pending or authorize).
- AC-2: Given transaction is cancellable, when status returns pending/authorize, then AI Agent presents: "Are you sure you want to cancel order [order_id]? This action cannot be undone." before calling cancel endpoint.
- AC-3: Given customer confirms, when POST /v2/{order_id}/cancel returns success, then AI Agent responds: "Your order [order_id] has been successfully cancelled." Event midtrans_action_success logged.
Error Path:
- ERR-1: Given transaction NOT cancellable (settlement/expire/cancel/deny/failure), when AI Agent checks status, then "This transaction cannot be cancelled — current status: [status]." Cancel endpoint NOT called.
- ERR-2: Given customer declines confirmation, then "Understood. Your order has not been cancelled — no changes were made."
- ERR-3: Given customer confirms, when cancel API no response within 60s, then "Unable to cancel your transaction. Please try again or contact support." Event logged reason: timeout.
- ERR-4: Given Bearer token refresh fails, then action aborted + event logged reason: auth_error.
Permission Model: CAN: AI Agent (configured, flag ON). CANNOT: Human CS agents. Unauthorized: Not executed if flag OFF.
UI States: Loading (typing indicator during status check + cancel call ≤60s), Empty (AI Agent prompts for order_id), Error (error in conversation), Success (cancellation confirmed in conversation)
MIDTRANS-S05 — AI Agent requests a refund (with confirmation) | Must Have
Story: As a customer talking to the Qontak AI Agent, I want to request a refund for my order through the chat, so that I can get my money back without waiting for a human agent.
Before: CS agent manually processed refund in Midtrans dashboard. After: AI Agent validates refund eligibility, requests customer confirmation, then calls POST /v2/{order_id}/refund — fully automated.
Data Fields: order_id (required — from customer), transaction_status (internal — retrieved via status check), customer_confirmation (boolean, required), [refund_fields] (per Midtrans API docs), bearer_token (required — BOT-4243)
Happy Path:
- AC-1: Given Request Refund action configured (flag ON), when AI Agent identifies refund request with order_id, then AI Agent calls GET /v2/{order_id}/status first to check eligibility (settlement status required).
- AC-2: Given transaction eligible (settlement), when eligibility check passes, then AI Agent presents: "Are you sure you want to request a refund for order [order_id]? This action cannot be undone." before calling refund endpoint.
- AC-3: Given customer confirms, when POST /v2/{order_id}/refund returns success, then AI Agent: "Your refund request for order [order_id] has been submitted successfully." Event midtrans_action_success logged.
Error Path:
- ERR-1: Given transaction NOT eligible (pending/cancel/expire/deny/failure/already refunded), when AI Agent checks status, then "This transaction is not eligible for a refund — current status: [status]." Refund endpoint NOT called.
- ERR-2: Given customer declines, then "Understood. No refund has been requested — no changes were made."
- ERR-3: Given customer confirms, when refund API no response within 60s, then "Unable to process your refund request. Please try again or contact support." Event logged reason: timeout.
- ERR-4: Given Bearer token refresh fails, then action aborted + event logged reason: auth_error.
Permission Model: CAN: AI Agent (configured, flag ON). CANNOT: Human CS agents. Unauthorized: Not executed if flag OFF.
UI States: Loading (typing indicator during eligibility check + refund call ≤60s), Empty (AI Agent prompts for order_id), Error (error in conversation), Success (refund submission confirmed in conversation)
Negative Scenarios
- NEG-1: Given Admin/SPV tries to add second Midtrans account while one connected, when they view auth block, then no "add another account" option — only Re-authorize and Disconnect shown.
- NEG-2: Given human CS agent views conversation where AI Agent executed Midtrans action, when they look for manual re-trigger, then no trigger control rendered — action results are read-only in this phase.
- NEG-3: Given Admin/SPV in action type selector, when they search for P1/P2 Midtrans actions (e.g., Create Invoice, Create Subscription), then these types are not available in this phase.
- NEG-4: Given Admin/SPV using Qontak mobile app, when they navigate to Bot & Automation settings, then AI Agent Actions configuration menu is not rendered — Midtrans action setup requires web (AI Agent config: Web only).
9. Rollout
- Feature flag: TBD | default: OFF. Enabled per account after connecting Midtrans credentials.
- Stage 1: Internal QA (BOT squad sandbox accounts)
- GA: All Sales Suite Plus, Ultimate, Qontak 360 on request
- Backward compat: Yes — no existing behavior modified. Net-new feature.
- Migration: None required.
10. Observability
| Event Name | Trigger | Properties |
|---|---|---|
| midtrans_action_executed | AI Agent initiates any Midtrans action | action_type, order_id (if applicable), cid, conversation_id, timestamp |
| midtrans_action_success | Midtrans API returns successful response | action_type, order_id, response_status, duration_ms, cid, conversation_id |
| midtrans_action_failed | Midtrans API fails, times out, or auth error | action_type, order_id (if applicable), failure_reason (timeout/auth_error/invalid_request/api_error), cid, conversation_id |
| midtrans_payment_link_created | Successful create_payment_link; URL delivered | payment_link_url, channel_type, cid, conversation_id |
| midtrans_auth_token_refreshed | Bearer token refresh triggered by BOT-4243 | environment, duration_ms, cache_hit (true/false), cid |
Dashboard owner: BOT Squad
Alerts:
- midtrans_action_failed rate > 5% in any 15-min window → Slack: BOT squad alert channel
- midtrans_auth_token_refreshed failure (3 consecutive for same cid) → Slack + escalation to Eng Lead
Post-Launch Monitoring Cadence: TBD (target: monthly). Owner: Dimas Fauzi Hidayat (BOT Squad PM). Investigation triggered by alert firing, not scheduled threshold. Rollback: if midtrans_action_failed > 10% sustained for 1 hour and unresolvable within 2 hours, PM disables flag globally.
11. Success Metrics
⭐ Primary KPI: Number of CIDs actively using at least one Midtrans action in production
- Definition: Unique accounts on eligible plans that configured and triggered at least one P0 action via AI Agent in the past 30 days
- Baseline: N/A (new feature)
- Target: ≥5 CIDs within 90 days of GA
Quality: AI Agent Midtrans action success rate
- Definition: % of midtrans_action_executed resulting in midtrans_action_success (all 4 P0 actions combined)
- Baseline: N/A
- Target: ≥95% within 60 days of GA
12. Launch Plan & Stage Gates
| Stage | Audience | Duration | Success Gate | Owner |
|---|---|---|---|---|
| Internal QA | BOT squad internal test accounts (sandbox) | 2 weeks | QA AI Agent testing passed for all 4 P0 actions. Zero P0/P1 bugs. Confirmation flow (cancel/refund) verified. Auth token lifecycle verified. | PM + QA |
| Closed Beta | 3–5 Production accounts (Sales Suite Plus or Ultimate, manually enabled) | 3 weeks | Success rate ≥95% for 1 consecutive week in production. Zero P0 bugs. Auth token refresh verified under real credentials. No critical UX issues from beta accounts. | PM + CSM |
| GA | All Sales Suite Plus, Ultimate, Qontak 360 | Ongoing | Closed Beta gates sustained for 2 consecutive weeks. Success rate ≥95%. Zero P0 bugs. PMM launch comms sent. | PM + BOT Squad |
13. Dependencies
| Dependency | Owning Team | Deliverable Needed | Blocking? |
|---|---|---|---|
| BOT-4243 — Midtrans OAuth Authentication | BOT Squad | midtrans_oauth auth_type with Redis-cached token manager (~15 min TTL). Fields: server_key, client_key, environment, partner_id, merchant_id. Token endpoint: POST https://api.midtrans.com/v1/access-token | NO — Done |
| Midtrans sandbox environment access | Midtrans / PM | Sandbox API credentials for QA testing of all 4 P0 actions | NO — obtain in parallel with development |
14. Key Decisions + Alternatives Rejected
14a — Decisions Made
| Date | Decision | Rationale |
|---|---|---|
| 2026-06-12 | Build as native integration, not generic API connector | Generic API Integration menu requires manual endpoint/header/body/auth config — too technical for Admin/SPV. Native integration eliminates this friction entirely. |
| 2026-06-12 | All 4 P0 actions in one PRD | Actions share BOT-4243 auth architecture and 2 mandatory base fields. Separating them adds overhead without benefit. |
| 2026-06-12 | create_payment_link sends URL as WhatsApp CTA-URL button, not plain text | CTA-URL buttons are Qontak's primary WhatsApp USP — higher conversion. Non-WhatsApp channels receive a clickable link. |
| 2026-06-12 | ANCHOR + NEW PRD structure for Midtrans initiative | 15 total actions across 3 phases (P0/P1/P2) warrant ANCHOR to track initiative history and phase dependencies. |
| 2026-06-12 | cancel_transaction and request_refund require AI Agent to check transaction state before calling API | Prevents API calls on ineligible transactions, reducing unnecessary calls and improving error quality. |
| 2026-06-12 | cancel_transaction and request_refund require explicit customer confirmation before mutating API call | Cancellation and refund are irreversible. Confirmation prevents accidental execution — standard practice for destructive actions in conversational AI. |
| 2026-06-12 | UX pattern follows Google Calendar native integration | Consistent with existing pattern familiar to Admin/SPV users: connect once → actions appear in agent builder. |
14b — Alternatives Rejected
| Alternative | Why Rejected | Date |
|---|---|---|
| Generic API Integration menu for Midtrans actions | Requires manual endpoint/header/body/auth config per action — defeats native integration value prop and blocks non-developer admins | 2026-06-12 |
| Separate PRDs per P0 action | Over-engineered given shared auth architecture. Increases PM and eng overhead without improving spec quality. | 2026-06-12 |
| WhatsApp-only channel restriction for create_payment_link | Creates inconsistent AI Agent behavior across channels. All channels should return a usable link. | 2026-06-12 |
| Skip confirmation step for cancel/refund | Higher risk of accidental irreversible actions in conversational context. Low-friction confirmation is standard practice. | 2026-06-12 |
15. Open Questions
| # | Type | Question | Owner | Deadline |
|---|---|---|---|---|
| 1 | Open Question | Feature flag name — TBD, needs engineering alignment | BOT Squad Eng Lead | 2026-06-20 |
| 2 | Open Question | RFC link — planned, not yet created with engineering team | Dimas / BOT Squad | 2026-06-27 |
| 3 | Open Question | Confirm/finalize the provisional dynamic field lists in S6 (names, types, required vs optional) against Midtrans API docs during RFC | BOT Squad Eng Lead | 2026-06-27 |
| 6 | Open Question | Refund idempotency (refund_key + dedupe window), rate-limit/backoff behavior, and partial-vs-full refund scope for P0 — see S7 idempotency note | BOT Squad Eng Lead | 2026-06-27 |
| 4 | Open Question | Midtrans refund SLA — needed for S05 AC-3 message copy | Dimas / Midtrans docs | 2026-06-20 |
| 5 | Open Question | Post-launch monitoring cadence formal thresholds — TBD | Dimas / BOT Squad | 2026-07-30 |
PRD CHANGELOG
| Version | Date | By | Section | Type | Summary |
|---|---|---|---|---|---|
| 1.0 | 2026-06-12 | Claude | All | CREATED | Initial NEW PRD (Phase 1: P0 Core Actions) generated from grooming session. Covers 4 P0 actions: check_payment_status, create_payment_link, cancel_transaction, request_refund. ANCHOR PRD created alongside. |
| 1.1 | 2026-06-12 | Claude | S8, S12, S15 | MODIFIED | Applied AI-readiness scoring fixes: S03 payment link lifecycle CANNOT; NEG-4 web-only constraint; S05 Test Coverage Matrix; S12 Closed Beta stage + durations; S15 calendar dates. |
| 1.2 | 2026-06-15 | Claude | S6, S7, S15 | MODIFIED | Post-score-prd improvements: (1) S6 — added provisional DynamicFieldsSection field schemas for all 4 actions (draft, confirm in RFC). (2) S7 — added idempotency (refund_key + dedupe window), rate-limit, and partial-vs-full refund note. (3) S15 — reworded OQ#3, added OQ#6 (refund idempotency/rate-limit/partial scope). |