# Workflow: seller-managed buyer subscriptions

> Use the existing Remote Invoice API and signed Webhooks while the seller keeps subscription records and billing periods in their own application.

## Ownership and tools

The seller application owns its buyer records, access state, next billing date and grace policy. Do not add buyer subscriptions to Bankemes. Existing MCP tools are sufficient for Bankemes-side setup: `bankemes_get_next_setup_action`, `bankemes_list_cashiers`, `bankemes_start_cashier_connection`, `bankemes_create_resource`, `bankemes_provision_integration`, `bankemes_configure_webhook`, `bankemes_get_integration_guide`, and `bankemes_get_integration_status`. `bankemes_manage_recurring_invoice` configures a Bankemes-managed schedule, which is a different operating model.

## Alternative: schedules managed in Bankemes

When Bankemes should manage the invoice schedule, use `bankemes_create_customer` (or select an existing customer with `bankemes_list_customers`), then `bankemes_manage_recurring_invoice` with `action: "create"`. The owner sees the exact amount, dates, frequency, local hour, missed-period policy, reminders and payment deadline in the approval page. After approval repeat the unchanged call. Schedules support daily, weekly, monthly or custom dates, intervals, an Asia/Almaty local hour, reminders and a payment deadline. The missed-period policy invoices only the latest missed period by default, or up to 12 latest missed periods with `missed_policy: "all"`; older missed periods are skipped. Inspect schedules with `bankemes_list_recurring_invoices` and `bankemes_get_recurring_invoice`; pause, resume or cancel using `bankemes_manage_recurring_invoice`. This issues invoices the buyer pays manually; it never authorizes automatic debits. Do not run both scheduling models for the same billing period.

## Connect and implement

1. Connect the existing MCP endpoint using OAuth 2.1 PKCE in a compatible client; the seller approves on the Bankemes consent page. Or use a one-time setup key from the cabinet. Never ask for passwords or Kaspi SMS codes.
2. Ask which connected cashier receives subscription invoices; call `bankemes_create_resource` for the seller application origin.
3. Provision a test credential for ordinary sandbox payments. Provision a live Merchant API token only through the owner approval in the cabinet (`approval_required` → approve → repeat the call); required scopes are `remote-invoices:create` and `remote-invoices:read`.
4. Implement the seller backend from the project subscription guide: Node.js and Laravel examples are available in the repository. Configure an HTTPS webhook on the resource domain with `remote_invoice.paid`, `payment.expired`, and `remote_invoice.cancelled`.
5. A remote invoice has no sandbox token mode. Run its acceptance flow only against an isolated Kaspi simulator and isolated webhook receiver. Do not call the live API for a test.

## Remote Invoice API contract

Seller backend request:

```
POST /api/v1/invoices/remote
Authorization: Bearer $BANKEMES_API_TOKEN
Idempotency-Key: sub-<seller-subscription-id>-<period>
Content-Type: application/json

{
  "order_id": "sub-<seller-subscription-id>-<period>",
  "phone": "+77001234567",
  "amount": 2500,
  "currency": "KZT",
  "description": "Subscription 2026-11",
  "metadata": { "subscription_id": "<seller-id>", "period_start": "2026-11-01" }
}
```

## Apply Webhooks safely

- Verify `Bankemes-Signature` against the raw request body and a five-minute timestamp tolerance. Compare signatures in constant time; accept either `v1` during secret rotation.
- Atomically insert the unique `event.id` into the seller event ledger and apply the subscription state change. A duplicate event must return 2xx without extending twice.
- Extend access only for `remote_invoice.paid` with `data.status = "paid"` and `data.bank_verified = true`.
- `payment.expired` with `data.object = "remote_invoice"` and `bank_verified = true` is confirmed non-payment. If `bank_verified = false`, the result is unresolved: do not disable or extend yet.
- `remote_invoice.cancelled` means Kaspi confirmed cancellation. A later bank-verified `*.paid` can follow an expiry event; the seller must handle it idempotently and follow its late-payment policy.

## Repeat each billing period

When the seller’s next period is due, create a fresh `order_id` and `Idempotency-Key` from the seller subscription ID plus that period. On timeout or `creation_unknown`, retry/read the same invoice with the same key; do not invent a new period key to bypass an uncertain Kaspi result.

## Actions requiring seller approval

- Writing to or deploying changes in the seller production project.
- Provisioning a live token or putting live credentials in the seller server environment.
- Creating a real remote invoice to a buyer. Never issue one as an acceptance test.

Source: https://bankemes.kz/for-agents/workflows/merchant-subscriptions
