# Payment cycle gaps — status & how to finish charges

**Site:** https://ngenius.milestoneksa.com  
**Desk:** NGenius Settings → **Payment Not Done** / **Channel Status** / **Gaps Doc URL**  
**Last diagnostics:** `15 passed, 0 failed · channel=OK` · **Payment Not Done = 0**

---

## Full cycle (what “done” means)

```
create_order → STARTED (+ pay_page_url)
    → presentment (Hosted Page | Hosted Session | submit_test_card)
    → AWAIT_3DS (complete 3DS in browser / complete-3ds API)
    → AUTHORISED or PURCHASED
    → (if AUTH) capture → CAPTURED
    → optional refund / reverse / void
```

---

## Active outlet (use this)

| Item | Value |
|------|--------|
| Outlet name | `instant_signup_outlet` |
| Outlet UUID | `c34ac178-f74e-490a-8375-b3aa3a8cf665` |
| Type | Outlet (trading unit) |
| TIDs / POS MID | 1 / 0 |
| Token group | `V6jgOB65UR3LTdth7vtdG3q4cdPsoHJ5meQj` |
| Portal status | **Active** |
| Org (Myth Fit) | `d021d110-c565-4c6a-81bf-94ed4bc37984` |
| Lab currency | `AED` |

**Do not use** legacy **MainOutlet** `ac576f4a-3fb2-436e-985a-7a3a49041250` — it returns `CHANNEL_OFF` / `noPaymentMethodsAvailableForCurrency` until card eCom MIDs are enabled there.

### How this was fixed

1. Portal → Myth Fit → switch lab Settings **Outlet Reference** to `instant_signup_outlet` (`c34ac178-…`).
2. Confirm outlet **Active** with card eCom for **AED**.
3. Desk → **Run Full API Test** → channel becomes `OK`.

If create-order fails again with `CHANNEL_OFF`:

1. [Sandbox portal](https://portal.sandbox.ngenius-payments.com/#/login) → **instant_signup_outlet**
2. Re-check Active + MID/currency
3. Settings outlet UUID = `c34ac178-f74e-490a-8375-b3aa3a8cf665` → **Run Full API Test**

---

## API status matrix (current)

### Working (cycle can start)

| Lab REST | Frappe method | Status | Notes |
|----------|---------------|--------|--------|
| `POST /ngenius/v1/orders` | `checkout.create_order` | **OK** | Returns `STARTED` + `pay_page_url` |
| Hosted Page (UI) | same + redirect | **OK** | Use `/pay/purchase` → Pay via Hosted Page |
| Hosted Session bootstrap | `checkout.get_hosted_session_bootstrap` | **OK** | Prepare → mount card → Pay |
| `POST …/hosted-session` | `checkout.complete_hosted_session` | **OK** | After browser session id |
| `POST /ngenius/v1/pay-by-link` | `checkout.create_pay_by_link` | **OK** | Shareable link |
| `GET /ngenius/v1/orders/{name}` | `checkout.get_order_status` | **OK** | Refresh state |
| `GET /ngenius/v1/transactions` | `checkout.list_test_transactions` | **OK** | Lab list |
| Access token / Test Connection | `checkout.test_connection` | **OK** | Merchant Service key valid |
| OpenAPI / Swagger | `/ngenius/v1/openapi.yaml`, `/api-docs` | **OK** | |

### Presentment — works but needs 3DS to finish

| Lab REST | Frappe method | Status | How to finish |
|----------|---------------|--------|----------------|
| `POST …/test-card` | `checkout.submit_test_card` | **OK → `AWAIT_3DS`** | Sandbox cards on this outlet go to 3DS. Prefer **Hosted Page / Hosted Session in the browser** to complete challenge UI. Expiry: lab accepts `12/30` and sends `YYYY-MM`. PAN e.g. `4111111111111111`. |
| `POST …/complete-3ds` | `checkout.complete_3ds` | Ready when 3DS links exist | Use after challenge; or finish via HPP/HS UI |

**Recommended happy path (browser):**

1. https://ngenius.milestoneksa.com/pay/purchase  
2. Amount `10.00` → **Pay via Hosted Page** (or Prepare Hosted Session → Pay)  
3. Card `4111111111111111` / expiry `12/30` / CVV `123`  
4. Complete 3DS if shown → land on `/pay/complete`  
5. Desk → NGenius Transaction → confirm `AUTHORISED` or `PURCHASED`

### Follow-ups (after AUTHORISED / PURCHASED)

| Lab REST | Frappe method | Status | Needs / how to fix |
|----------|---------------|--------|---------------------|
| `POST …/capture` | `checkout.capture_payment` | Ready | State must be `AUTHORISED` (not `STARTED` / `AWAIT_3DS`) |
| `POST …/refund` | `checkout.refund_payment` | Ready | `PURCHASED` or `CAPTURED` |
| `POST …/reverse` | `checkout.reverse_auth` | Ready | `AUTHORISED` hold |
| `POST …/void` | `checkout.void_payment` | Ready | If gateway void link exists |
| `POST …/cancel` | `checkout.cancel_order` | Ready | Abandon `STARTED` before pay |
| cancel-capture / cancel-refund | matching methods | Ready | Only if cancel links exist on payment |

Capture on `STARTED` or `AWAIT_3DS` returns `LINK_MISSING` / `NOT_AUTHORISED` **by design** — finish presentment (+ 3DS) first.

### Still incomplete / optional (not blocking card HPP)

| Feature | Lab surface | Gap | How to fix |
|---------|-------------|-----|------------|
| **AANI** | `POST /ngenius/v1/aani`, `/pay/aani` | `CHANNEL_OFF` — AANI not on outlet `paymentMethods` | Portal → **instant_signup_outlet** → enable AANI; sandbox mobiles `971500000001` / `971500000002` |
| **Wallets** | `/pay/wallets` | Wallet methods must be on outlet | Portal → enable Apple / Google / Samsung Pay on this outlet |
| **Token pay** | `POST /ngenius/v1/token-pay` | Needs saved token from a prior tokenising charge | Complete one successful card payment that returns a token, then call token-pay (token group already set) |
| **Click to Pay (VCTP)** | `GET …/click-to-pay/config`, `/pay/click-to-pay` | Config often `406 Not Acceptable`; UI is stub | Enable VCTP on Myth Fit → Settings **Sync Click to Pay Config**; ask N-Genius if 406 persists |
| **Webhook** | `POST /ngenius/v1/webhooks/ngenius` | `webhook_secret` empty until configured | Portal → Webhooks → URL = Settings **Lab Webhook URL** → paste secret into **Webhook Secret** |
| **Pay-by-link resend** | `POST …/pay-by-link/{name}/resend` | Needs an existing PBL order | Create PBL first, then resend |

---

## Error cheat sheet

| Code | Meaning | Fix |
|------|---------|-----|
| `CHANNEL_OFF` | No payment method for currency on outlet | Use `instant_signup_outlet` or enable MID+currency in portal |
| `AWAIT_3DS` | Card accepted; challenge pending | Complete 3DS in HPP/HS UI (or `complete-3ds`) |
| `NOT_AUTHORISED` / `LINK_MISSING` on capture | Order not yet authorised | Finish presentment first |
| `TOKEN_MISSING` | No saved card token | Run a tokenising payment first |
| `TOKEN_EXPIRED` / `Unauthorized, access token expired` | Cached N-Genius bearer expired | Lab **auto-refreshes and retries once** — click Prepare again if needed; or Desk → Test Connection |

---

## Re-verify anytime

```bash
bench --site ngenius.milestoneksa.com execute ngenius_payments.api.diagnostics.run_full_api_test
```

Or Desk → NGenius Settings → **Diagnostics → Run Full API Test**.  
Report is stored on the form; this file is also at `/assets/ngenius_payments/payment-cycle-gaps.md`.

---

## Related

- Integration API: [api.md](./api.md)  
- OpenAPI: `/ngenius/v1/openapi.yaml` · Swagger: `/api-docs`  
- Hub + test data: `/pay`  
- Sandbox cards: https://docs.ngenius-payments.com/reference/sandbox-test-environment  
- Portal: https://portal.sandbox.ngenius-payments.com/#/login  
