# API Endpoints Reference

Complete reference for all AuxCORE API endpoints.

---

## Required Headers

### Public API (`/api/v1/public/*`)

```http
x-api-key: YOUR_API_KEY
Content-Type: application/json
```

| Key scope | Additional headers |
|-----------|-------------------|
| Merchant-scoped (`api-…`) | None — tenant and merchant resolve from the key (`X-Tenant-ID` is ignored on `/public/*`) |
| ERP / tenant-scoped (`lv_erp_…`) | `X-Merchant-ID` (or `merchantId` in body/query) — tenant resolves from the key |

The key is read from `x-api-key` (preferred), `api-key`, or `Authorization: <key>`.

### Admin API (`/api/v1/*` — dashboard)

```http
Authorization: Bearer YOUR_JWT_TOKEN
X-Tenant-ID: YOUR_TENANT_ID
Content-Type: application/json
```

Obtain a JWT via `POST /api/v1/public/accesstoken` (requires `x-api-key` + credentials in body). Most admin routes also accept an API key in `x-api-key` instead of a JWT, but routes guarded by a role permission (for example invoice external payments) return `403` for API keys. An expired JWT returns `401 TOKEN_EXPIRED`.

---

## Base URLs

| Environment | Host | Public API prefix |
|-------------|------|-------------------|
| **Sandbox** | `https://uat.auxcore.net` | `/api/v1/public` |
| **Production** | `https://app.auxcore.net` | `/api/v1/public` |

Example: `POST /api/v1/public/transaction` on Sandbox →  
`POST https://uat.auxcore.net/api/v1/public/transaction`

See [Environments](../getting-started/environments.md) for PCI, docs, and dashboard URLs.

---

## API Surfaces

AuxCORE exposes three API surfaces depending on your use case:

| Surface | Prefix | Auth | Use Case |
|---------|--------|------|----------|
| **Public API** | `/api/v1/public/` | `x-api-key` (ERP keys also need `X-Merchant-ID`) | Current `auxVault.js`, ERP, plugins, server integration |
| **Admin API** | `/api/v1/` | `Authorization: Bearer JWT` + `X-Tenant-ID` | Dashboard, admin operations |
| **AuxCORE SDK API (v2.0)** | `/api/v1/auxvault/` | Server-side `x-api-key` (ERP keys also need `X-Merchant-ID`) | Official AuxCORE SDK namespace |

> **Note:** `/api/v1/auxvault/*` is the official API v2.0 SDK namespace; the root has no handler.

---

## Public API Endpoints (`/api/v1/public/*`)

These are the primary endpoints for ERP and server-to-server integrations.

**Server integration** routes require `x-api-key` unless noted below. `X-Tenant-ID` is ignored on `/public/*`; the tenant always comes from the key. An unknown or disabled key returns `401` with message `API key validation failed`.

**Customer-facing** payment link, invoice, checkout pay, and payment plan routes are called from hosted pages in the browser — **no API key**.

### Connection

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/public/testConnection` | Verify API key and connection |
| GET | `/api/v1/public/key-info` | Resolve API key metadata (tenant, merchant scope) |
| GET | `/api/v1/public/sdk-info` | Get SDK version and hosted fields URL |

### Authentication (Public API)

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| POST | `/api/v1/public/accesstoken` | Login — get JWT token | `x-api-key` + credentials in body |
| POST | `/api/v1/public/refreshToken` | Refresh an expired JWT | `x-api-key` + refresh token in body |
| POST | `/api/v1/public/client-token` | Generate SDK client token | `x-api-key` |
| POST | `/api/v1/public/validate-client-token` | Validate a client token | None (rate-limited, 30 per 15 min per IP) |

### Transactions (Public API)

| Method | Endpoint | Description | Body Key Fields |
|--------|----------|-------------|-----------------|
| POST | `/api/v1/public/transaction` | Process sale, auth, or ACH payment | `Amount`, `SuggestedMode`, `pciToken` or card fields; `transactionType: "auth"` for auth-only |
| POST | `/api/v1/public/void` | Void a transaction | `transactionId` |
| POST | `/api/v1/public/refund` | Full or partial refund (only lowercase `amount` makes it partial; `Amount` is ignored and a full refund runs) | `transactionId`, `amount?` |
| POST | `/api/v1/public/token-transaction` | Charge a stored card token | `pciToken`, `amount` |
| POST | `/api/v1/public/token-transaction-ach` | Charge a stored ACH token | See [Transactions](../core/transactions.md) |
| GET | `/api/v1/public/transaction/:id` | Get transaction by ID | — |
| GET | `/api/v1/public/transaction-list` | List transactions (paginated) | — |
| GET | `/api/v1/public/merchant-transactions` | List merchant transactions (alias) | — |
| GET | `/api/v1/public/fee-preview` | Convenience-fee preview before charging | `amount`, `paymentMethod?` (query) |

> **Note:** `POST /api/v1/public/rerun` is registered at the gateway but the transaction service has no matching route, so it returns `404`. Submit a new `POST /api/v1/public/transaction` instead.

### Tokenization (Public API)

| Method | Endpoint | Description | Body Key Fields |
|--------|----------|-------------|-----------------|
| POST | `/api/v1/public/tokenize-card` | Tokenize a card | `cardNumber`, `expiryMonth`, `expiryYear` |
| POST | `/api/v1/public/tokenize-ach` | Tokenize a bank account | `routingNumber`, `accountNumber` |
| POST | `/api/v1/public/save-card` | Save vaulted card from PCI token | `pciToken`, `customerId?` |
| POST | `/api/v1/public/decrypt-token` | Get masked card details from token | `token` *(Sandbox only — 404 in production)* |

### Customers (Public API)

| Method | Endpoint | Description | Body Key Fields |
|--------|----------|-------------|-----------------|
| GET | `/api/v1/public/customers` | List customers | — |
| POST | `/api/v1/public/customer` | Create a customer | `firstName`, `lastName`, `email` |
| GET | `/api/v1/public/customer/:id` | Get customer by ID | — |
| PUT | `/api/v1/public/customer/:id` | Update customer | Any customer fields |
| DELETE | `/api/v1/public/customer/:id` | Delete customer | — |
| POST | `/api/v1/public/customer/:id/payment-method` | Add payment method to customer | `merchantId`, `pciToken` (or `pciAchToken` for ACH) |
| GET | `/api/v1/public/customer/:id/payment-methods` | List customer payment methods | — |
| DELETE | `/api/v1/public/customer/:id/payment-method/:pmId` | Remove a stored payment method | — |
| POST | `/api/v1/public/customer/:id/payment-method/:pmId/charge-ach` | Charge a stored ACH payment method | `amount` |

### Recurring (Public API)

| Method | Endpoint | Description | Body Key Fields |
|--------|----------|-------------|-----------------|
| POST | `/api/v1/public/recurring` | Create a recurring subscription | `customerId`, `recurringAmount`, `period`, `recurringDate1` |

### Merchants (Public API)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/public/merchants/provision` | Provision a new merchant (tenant-level key required) |
| GET | `/api/v1/public/merchants` | Get merchant details for current API key |
| GET | `/api/v1/public/merchants/:merchantId` | Get merchant by ID |
| GET | `/api/v1/public/merchant` | Get merchant by ID (pass `?id=merchantId`) |
| GET | `/api/v1/public/getConfig` | Get merchant runtime configuration |
| GET | `/api/v1/public/getFee` | Get merchant fee schedule |
| GET | `/api/v1/public/field-config` | Which checkout fields to show, and which to require (`?channel=sdk`, `?paymentMethod=card`) |
| GET | `/api/v1/public/payment-purposes` | Payment purposes configured for the merchant's gateways |
| POST | `/api/v1/public/kyc/verify` | Run a KYC verification (60 per hour per IP) |

### OTP (Public API)

| Method | Endpoint | Description | Body Key Fields |
|--------|----------|-------------|-----------------|
| POST | `/api/v1/public/otp/generate` | Generate and send OTP via SMS or email | `type`, `destination` |
| POST | `/api/v1/public/otp/verify` | Verify a customer-entered OTP | `otpId`, `code` |
| POST | `/api/v1/public/otp/resend` | Resend an OTP | `otpId` |

OTP generate and resend are limited to 10 per hour per IP.

### Invoicing & Payment Links (Public API)

Creating a link: [Payment Links](../invoicing/payment-links.md). The `/payment-links/:linkId/*` routes are called by the hosted pay page.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/public/generate-url` | Create a payment link (legacy invoice URL) |
| POST | `/api/v1/public/payment-links` | Create payment link (REST alias of generate-url) |
| POST | `/api/v1/public/shorten-url` | Shorten a payment URL |
| POST | `/api/v1/public/shorten-url-sms` | Create short URL and send SMS |
| POST | `/api/v1/public/shorten-url-payment-sms` | Create payment link and text customer |
| GET | `/api/v1/public/invoices/link/:linkId` | Fetch public invoice by link ID |
| GET | `/api/v1/public/invoices/link/:linkId/fee-preview` | Fee preview for invoice link |
| GET | `/api/v1/public/invoices/:id` | Fetch invoice by internal ID |
| POST | `/api/v1/public/invoices/:linkId/pay` | Pay an invoice link |
| POST | `/api/v1/public/invoices/:linkId/pay-ach` | Pay an invoice link by ACH |
| POST | `/api/v1/public/invoices/:linkId/send-receipt` | Email or text a receipt for an invoice payment |
| PATCH | `/api/v1/public/invoices/:linkId/next-payment` | Set the date of the next installment |
| POST | `/api/v1/public/invoices/:linkId/saved-card/request-otp` | OTP for saved-card pay (also `verify-otp`, `resend-otp`) |
| POST | `/api/v1/public/invoices/:linkId/pay-with-saved-card` | Charge a saved card on an invoice |
| PUT | `/api/v1/public/invoices/:linkId/saved-card/:paymentMethodId/set-default` | Set default saved card |
| DELETE | `/api/v1/public/invoices/:linkId/saved-card/:paymentMethodId` | Remove saved card |
| GET | `/api/v1/public/payment-links/:linkId` | Fetch hosted payment link |
| POST | `/api/v1/public/payment-links/:linkId/pay` | Pay via card on payment link |
| POST | `/api/v1/public/payment-links/:linkId/pay-ach` | Pay via ACH on payment link |
| POST | `/api/v1/public/payment-links/:linkId/pay-crypto` | Pay via crypto (CoinVoyage) on payment link |
| POST | `/api/v1/public/payment-links/:linkId/apple-pay-session` | Apple Pay merchant session |
| GET | `/api/v1/public/payment-links/:linkId/fee-preview` | Convenience fee preview |
| GET | `/api/v1/public/payment-links/:linkId/setup-info` | Saved-card setup metadata |
| POST | `/api/v1/public/payment-links/:linkId/setup` | Save card on payment link |
| POST | `/api/v1/public/payment-links/:linkId/saved-card/request-otp` | OTP for saved-card pay |
| POST | `/api/v1/public/payment-links/:linkId/saved-card/verify-otp` | Verify saved-card OTP |
| POST | `/api/v1/public/payment-links/:linkId/saved-card/resend-otp` | Resend saved-card OTP |
| POST | `/api/v1/public/payment-links/:linkId/pay-with-saved-card` | Charge saved card |
| PUT | `/api/v1/public/payment-links/:linkId/saved-card/:paymentMethodId/set-default` | Set default saved card |
| DELETE | `/api/v1/public/payment-links/:linkId/saved-card/:paymentMethodId` | Remove saved card |
| POST | `/api/v1/public/payment-links/:linkId/send-receipt` | Email payment link receipt |
| POST | `/api/v1/public/receipt-pdf` | Generate receipt PDF |

### Checkout Sessions (Public API)

Flow, request fields and confirmation: [Hosted Checkout](../core/hosted-checkout.md).

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/public/checkout-session` | Create a hosted checkout session |
| POST | `/api/v1/public/checkout-sessions/:sessionId/pay` | Complete payment for a session |
| GET | `/api/v1/public/checkout-sessions/:sessionId` | Fetch session details for the hosted page |
| GET | `/api/v1/public/checkout-sessions/:sessionId/fee` | Convenience fee for the session |
| GET | `/api/v1/public/checkout-sessions/:sessionId/status` | Poll session status |
| GET | `/api/v1/public/checkout-sessions/:sessionId/return` | Return URL handler after a redirect |
| POST | `/api/v1/public/checkout-sessions/:sessionId/event` | Report `payment_cancelled` / `payment_expired` from the hosted page (`event`); fires `session.cancelled` / `session.expired` |

Checkout endpoints share a 30 requests per 15 minutes per IP limit.

### Payment Plans (Public API)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/public/payment-plans/:planId` | Fetch payment plan details |
| POST | `/api/v1/public/payment-plans/:planId/authorize` | Authorize first payment on plan |

### Gateway Operations (Public API)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/public/transaction-logs` | Append/query transaction logs |
| POST | `/api/v1/public/send-decline-notifications` | Trigger decline notifications |

> **Note:** `gateway-state`, `watchdog-transaction-count` and `gateway-selection` are registered at the gateway but forward to watchdog routes that do not exist (they return `404`), so they are not listed.

### Settlement, funding & disputes (Public API — CoinVoyage / ERP)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/public/batches` | List settlement batches |
| GET | `/api/v1/public/batches/schedule` | Auto-settle schedule |
| GET | `/api/v1/public/batches/:id` | Batch detail |
| GET | `/api/v1/public/deposits` | List deposits |
| GET | `/api/v1/public/deposits/:id` | Deposit detail |
| GET | `/api/v1/public/settlements/funding-report` | Funding report (`date` or `dateFrom` / `dateTo`) |
| GET | `/api/v1/public/settlements/schedule/:merchantId` | Per-merchant settlement schedule |
| GET | `/api/v1/public/fraud-reports` | Fraud/chargeback export (`since` required) |
| GET | `/api/v1/public/chargebacks` | List chargebacks |
| GET | `/api/v1/public/chargebacks/:id` | Chargeback detail |
| GET | `/api/v1/public/dispute-alerts` | Pre-dispute ICS alerts |
| GET | `/api/v1/public/dispute-alerts/:id` | Single dispute alert |
| POST | `/api/v1/public/capture` | Capture a prior auth (`transactionId`) |

### Webhooks & Integrations (Public API)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/public/register-webhook` | Register webhook endpoint |
| GET | `/api/v1/public/woocommerce-status` | WooCommerce plugin health |
| POST | `/api/v1/public/shopifyTransaction` | Process a Shopify transaction |

### Dashboard Totals (Public API)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/public/dashboard/summary/multi` | Multi-merchant dashboard summary (API key) |
| GET | `/api/v1/public/totalTransactions/multi/:ids` | Total transactions for several users (no key; `X-Tenant-ID`, 300 per 15 min per IP) |

---

## Current AuxCORE SDK (Hosted Fields)

The current `auxVault.js` uses the Public API, with `x-api-key`. An SDK embed key with allowed origins also needs `Origin` or `X-Merchant-Origin`; tenant-scoped / ERP keys need `X-Merchant-ID`.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/public/transaction` | Token payment: `Amount`, `pciToken`, `SuggestedMode: "Card"`; `TransactionType: "sale"` / `"1"` for sale or `"auth"` / `"2"` for auth-only |
| GET | `/api/v1/public/key-info` | Key scope, merchant, tenant and PCI public key |
| GET | `/api/v1/public/getConfig` | Merchant checkout configuration |
| GET | `/api/v1/public/field-config?channel=sdk` | SDK field visibility and requirements |
| GET | `/api/v1/public/fee-preview?amount=100&paymentMethod=card` | Fee quote before payment |

See [SDK setup](../getting-started/sdks.md) and [Transactions](../core/transactions.md) for the full Public API contract. `TransactionType: "0"` is **sale** on this endpoint.

## AuxCORE SDK API

These AuxCORE SDK API requests use PascalCase field names such as `Amount` and `TransactionId`. PascalCase describes the payload format, not a separate SDK.

These eight child routes are registered in the gateway. **There is no handler for `/api/v1/auxvault` itself**, and the method must match the table. Use the Public API connection test for a health check.

Authenticate with a server-side secret or ERP key in `x-api-key`; SDK public keys get `403` at gateway authentication. Tenant resolves from the key; tenant-scoped / ERP keys also need `X-Merchant-ID` or lowercase `merchantId` in the body. Omit `Authorization` when using an API key: gateway JWT validation and the shared adapter's key validator can otherwise conflict.

| Method | Endpoint | Description | Body Fields |
|--------|----------|-------------|-------------|
| POST | `/api/v1/auxvault/transaction` | Raw-card sale; PCI token and auth-only unsupported | `Amount`, card/billing fields below |
| POST | `/api/v1/auxvault/void` | Void a transaction | `TransactionId` |
| POST | `/api/v1/auxvault/refund` | Full refund without `Amount`; positive `Amount` selects partial refund | `TransactionId`, optional `Amount` |
| POST | `/api/v1/auxvault/capture` | Capture full authorization; `Amount` is ignored | `TransactionId` |
| POST | `/api/v1/auxvault/cancel-capture` | Reverse a capture in the platform record, without a gateway call | `TransactionId` |
| POST | `/api/v1/auxvault/credit` | Record a credit against a transaction, without a gateway call | `TransactionId`, `Amount` |
| POST | `/api/v1/auxvault/tokenize` | Raw-card tokenization; returns card-security `tok_…` | `CardNumber`, expiry (see below) |
| GET | `/api/v1/auxvault/query/:transactionId` | Get transaction by ID | — |

The transaction adapter always forwards to `/transactions/sale`. Although it maps `TransactionType: "0"` to an internal field named `auth`, the sale controller explicitly executes a sale. It does not forward `pciToken`, `PciToken`, `cardToken` or `paymentToken`. Raw-card payments are blocked on Sandbox and Production. Use `/api/v1/public/transaction` for token payments and authorizations.

`/api/v1/auxvault/tokenize` normalizes expiry to `MM/YY` and returns `{ success, Status, token, data: { tokenId, ... } }` (normally HTTP `201`). Its `tok_…` value is separate from the PCI vault's `pci_tok_…` token; do not use it as `pciToken`. The tokenization handler has no development-only PCI guard. Gateway authentication on `/auxvault` requires a server-side key and rejects SDK public keys. Prefer PCI hosted fields for new card collection.

### PascalCase Field Reference

| Field | Type | Description |
|-------|------|-------------|
| `Amount` | string or number | Transaction amount, parsed as a number |
| `TransactionType` | string | Does not select auth-only on `/auxvault/transaction`; the adapter calls sale |
| `SuggestedMode` | string | Payment method, lowercased; defaults to `card` |
| `CardNumber` | string | Raw PAN; whitespace removed |
| `ExpiryDate` / `CardExpiry` | string | Sale forwards expiry as supplied; use `MM/YY`. Tokenize accepts `MMYY`, `MM/YY`, `MM/YYYY`, or separate `ExpiryMonth` / `ExpiryYear` |
| `Cvv` / `CardCvv` | string | Card security code |
| `BillingCustomerName` | string | Cardholder name; tokenize also accepts `CardHolderName` |
| `BillingEmail` | string | Customer email |
| `BillingAddress` | string | Street address |
| `BillingCity` | string | City |
| `BillingState` | string | State |
| `BillingPostalCode` | string | ZIP/postal code |
| `TransactionId` / `transactionId` | string | Required for void, refund, capture, cancel-capture and linked credit |

Tokenize also accepts camelCase card fields. Query returns `success: true` when lookup succeeds, with `Status: 1` for approved/completed/captured/settled, `2` for pending/processing and `9` otherwise; lookup success alone does not mean payment approval.

---

## Admin API Routes (`/api/v1/*`)

Dashboard and admin operations. Require `Authorization: Bearer JWT` + `X-Tenant-ID`.  
Obtain a JWT from `POST /api/v1/public/accesstoken`.

### Authentication

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/auth/login` | Login (returns JWT) |
| POST | `/api/v1/auth/token` | Login alias (what `/public/accesstoken` calls) |
| POST | `/api/v1/auth/logout` | Logout and invalidate token |
| POST | `/api/v1/auth/refresh` | Refresh JWT — keeps the merchant the session was scoped to |
| GET | `/api/v1/auth/me` | Get current user info (reports the session's merchant) |
| POST | `/api/v1/auth/verify-otp` | Verify 2FA OTP |
| POST | `/api/v1/auth/resend-otp` | Resend 2FA OTP |
| POST | `/api/v1/auth/forgot-password` | Send password reset email |
| POST | `/api/v1/auth/reset-password` | Reset password |

### Multi-merchant sessions

For users who belong to more than one merchant. Full reference: [Authentication Guide →](../getting-started/authentication.md#multi-merchant-sessions)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/auth/select-merchant` | Complete login after the merchant picker — requires the 10-minute `selectionToken` from `/auth/login` |
| GET | `/api/v1/auth/my-merchants` | Merchants the signed-in user can work in, each with `deviceRegistration.hasActiveDevice` |
| POST | `/api/v1/auth/switch-merchant` | Switch the active merchant without logging out; re-issues the JWT scoped to the new merchant |

### API Keys

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/api-keys` | Create API key |
| GET | `/api/v1/api-keys` | List API keys |
| GET | `/api/v1/api-keys/:id` | Get API key details |
| PATCH | `/api/v1/api-keys/:id` | Update API key |
| POST | `/api/v1/api-keys/:id/regenerate` | Regenerate the key (new `plainKey`) |
| POST | `/api/v1/api-keys/:id/disable` | Disable key |
| POST | `/api/v1/api-keys/:id/enable` | Re-enable key |
| DELETE | `/api/v1/api-keys/:id` | Revoke API key (soft delete) |

### Transactions (Admin)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/transactions/sale` | Process sale (card, cash, etc.); mobile card calls may include optional immutable `enhancedData` |
| POST | `/api/v1/transactions/auth` | Authorize only (capture later) |
| POST | `/api/v1/transactions/ach-sale` | ACH sale |
| POST | `/api/v1/transactions/token-sale` | Charge saved card / vault token |
| GET | `/api/v1/transactions/fee-preview` | Pre-sale cash / credit / ACH prices (POS dual pricing) |
| GET | `/api/v1/transactions` | List transactions |
| GET | `/api/v1/transactions/:id` | Get transaction details |
| POST | `/api/v1/transactions/:id/capture` | Capture authorization |
| POST | `/api/v1/transactions/:id/cancel-capture` | Cancel a capture |
| POST | `/api/v1/transactions/:id/void` | Void transaction |
| POST | `/api/v1/transactions/:id/refund` | Full refund |
| POST | `/api/v1/transactions/:id/refund/partial` | Partial refund |
| POST | `/api/v1/transactions/:id/credit` | Record a linked credit (no gateway call) |
| POST | `/api/v1/transactions/credit` | Issue an unlinked credit through the gateway |
| POST | `/api/v1/transactions/external-payment` | Record a device payment made outside the API; optional immutable `enhancedData` is stored locally only |

### Recurring (Admin)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/recurring` | Create subscription |
| GET | `/api/v1/recurring` | List subscriptions |
| GET | `/api/v1/recurring/overview` | Counts and totals |
| GET | `/api/v1/recurring/:id` | Get subscription details |
| PUT | `/api/v1/recurring/:id` | Update subscription |
| DELETE | `/api/v1/recurring/:id` | Delete subscription |
| POST | `/api/v1/recurring/:id/pause` | Pause |
| POST | `/api/v1/recurring/:id/resume` | Resume |
| POST | `/api/v1/recurring/:id/skip-next` | Skip next payment |
| POST | `/api/v1/recurring/:id/cancel` | Cancel |
| POST | `/api/v1/recurring/:id/charge-now` | Charge the next payment immediately |
| POST | `/api/v1/recurring/:id/retry-failed` | Reset failed counters so the next run retries (does not charge) |
| GET | `/api/v1/recurring/:id/payment-history` | Payment history |
| GET | `/api/v1/recurring/:id/history` | Change history |
| GET | `/api/v1/recurring/:id/schedule` | Payment schedule rows |
| POST | `/api/v1/recurring/:id/link-payment-method` | Attach a payment method |
| POST | `/api/v1/recurring/:id/send-method-update-link` | Email a payment-method update link |
| POST | `/api/v1/recurring/:id/resend-auth` | Resend the authorization request |

The cron endpoints `process-due`, `process-auto-retry` and `check-expired` are internal (`X-Internal-Service-Key`) and not part of the public API.

### Payment Plans (Admin)

Installment plans, served by the billing service (JWT only). The path is `/api/v1/billing/payment-plans`; `/api/v1/payment-plans` does not exist. Full reference: [Payment Plans →](../recurring/payment-plans.md)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/billing/payment-plans` | Create plan |
| GET | `/api/v1/billing/payment-plans` | List plans |
| GET | `/api/v1/billing/payment-plans/:id` | Get plan |
| POST | `/api/v1/billing/payment-plans/:id/activate` | Activate |
| POST | `/api/v1/billing/payment-plans/:id/pause` | Pause |
| POST | `/api/v1/billing/payment-plans/:id/resume` | Resume |
| POST | `/api/v1/billing/payment-plans/:id/cancel` | Cancel |
| POST | `/api/v1/billing/payment-plans/:id/charge-now` | Charge next installment now |

### Customers (Admin)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/customers` | Create customer |
| GET | `/api/v1/customers` | List customers |
| GET | `/api/v1/customers/:id` | Get customer |
| PUT | `/api/v1/customers/:id` | Update customer |
| DELETE | `/api/v1/customers/:id` | Delete customer |
| GET | `/api/v1/customers/:id/transactions` | Customer transaction history |
| GET | `/api/v1/customers/:id/payment-methods` | List payment methods |
| POST | `/api/v1/customers/:id/payment-methods` | Add payment method |
| PUT | `/api/v1/customers/:id/payment-methods/:pmId/set-default` | Set default payment method |
| DELETE | `/api/v1/customers/:id/payment-methods/:pmId` | Remove payment method |

### Merchants (Admin)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/merchants` | Create merchant |
| GET | `/api/v1/merchants` | List merchants |
| GET | `/api/v1/merchants/:id` | Get merchant details |
| PUT | `/api/v1/merchants/:id` | Update merchant |
| DELETE | `/api/v1/merchants/:id` | Delete merchant |
| GET | `/api/v1/merchants/:id/fraud-settings` | Get fraud settings |
| PUT | `/api/v1/merchants/:id/fraud-settings` | Update fraud settings |
| GET | `/api/v1/merchants/:id/vt-settings` | Get virtual terminal settings |
| PUT | `/api/v1/merchants/:id/vt-settings` | Update virtual terminal settings |
| GET | `/api/v1/merchants/:id/branding` | Get branding |
| PUT | `/api/v1/merchants/:id/branding` | Update branding |
| GET | `/api/v1/merchants/:id/field-config` | Checkout field configuration |
| GET | `/api/v1/merchants/:id/notification-preferences` | Get notification preferences |
| PUT | `/api/v1/merchants/:id/notification-preferences` | Update notification preferences |
| GET | `/api/v1/merchants/:id/messaging-defaults` | Get receipt / reminder / failed-payment email toggles |
| PUT | `/api/v1/merchants/:id/messaging-defaults` | Update them |
| GET | `/api/v1/merchants/:id/watchdog-rules` | Get WatchDog volume rules |
| POST | `/api/v1/merchants/:id/watchdog-rules` | Save WatchDog volume rules |
| GET | `/api/v1/merchants/:id/users` | List team members |
| GET | `/api/v1/merchants/:id/gateways` | List merchant gateways |
| POST | `/api/v1/merchants/:id/gateways` | Add gateway |
| PUT | `/api/v1/merchants/:id/gateways/:gwId` | Update gateway (including `routingRules`, AVS/CVV rules, limits) |
| PATCH | `/api/v1/merchants/:id/gateways/:gwId/status` | Set gateway status |
| PATCH | `/api/v1/merchants/:id/gateways/:gwId/priority` | Set gateway priority |
| DELETE | `/api/v1/merchants/:id/gateways/:gwId` | Remove gateway |

Merchant settings (name, contact, timezone, descriptor, notification emails) are fields on `GET` / `PUT /api/v1/merchants/:id`. There are no `/settings`, `/permissions`, `/dunning-settings` or `/gateway-routing` sub-resources. Branding also supports `POST /:id/branding/upload` and `/:id/logo` (POST / GET / DELETE). `POST /api/v1/merchants/provision` provisions a merchant from the API.

### Devices (Admin)

Portal-side device provisioning. Full reference: [Devices →](../merchants/devices.md)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/merchants/:id/devices` | List devices (`?status=&limit=&offset=`) |
| POST | `/api/v1/merchants/:id/devices` | Create device — server generates TPN + pairing code |
| GET | `/api/v1/merchants/:id/devices/:deviceId` | Get device |
| PATCH | `/api/v1/merchants/:id/devices/:deviceId` | Update device (TPN and pairing code are immutable) |
| PATCH | `/api/v1/merchants/:id/devices/:deviceId/status` | Change status — any move out of `ACTIVE` revokes the device's sessions |
| POST | `/api/v1/merchants/:id/devices/:deviceId/refresh-pairing-code` | Issue a new pairing code; resets device to `PENDING` |
| POST | `/api/v1/merchants/:id/devices/:deviceId/archive` | Archive (soft delete) |
| POST | `/api/v1/merchants/:id/devices/:deviceId/unarchive` | Restore to `INACTIVE` |
| DELETE | `/api/v1/merchants/:id/devices/:deviceId` | Deprecated alias for archive |
| GET | `/api/v1/merchants/:id/devices/:deviceId/parameters` | Get device parameters |
| PUT | `/api/v1/merchants/:id/devices/:deviceId/parameters` | Update device parameters |
| POST | `/api/v1/merchants/:id/devices/:deviceId/parameters/apply-template` | Apply a parameter template |
| POST | `/api/v1/merchants/:id/devices/:deviceId/parameters/reset` | Reset parameters to defaults |
| GET | `/api/v1/merchants/:id/device-templates` | List parameter templates |
| POST | `/api/v1/merchants/:id/device-templates` | Create parameter template |
| GET | `/api/v1/merchants/:id/device-templates/:templateId` | Get template |
| PATCH | `/api/v1/merchants/:id/device-templates/:templateId` | Update template |
| DELETE | `/api/v1/merchants/:id/device-templates/:templateId` | Delete template |
| POST | `/api/v1/merchants/:id/device-templates/:templateId/set-default` | Set as merchant default |

### Devices (Mobile / POS app)

Called by the app on the terminal. Full reference: [Mobile Device Integration →](../mobile/device-integration.md)

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/api/v1/device/register` | user JWT | Pair the app using TPN + pairing code; returns the device token |
| GET | `/api/v1/device/session` | user JWT + `X-Device-Token` | Is the stored device token still usable for this merchant? Answers `200` with `reusable` + `reason` |
| POST | `/api/v1/device/test-connection` | user JWT + `X-Device-Token` | Validate gateway config; `REGISTERED` → `ACTIVE` |
| GET | `/api/v1/device/me` | user JWT + `X-Device-Token` | Current device record (`ACTIVE` only) |
| GET | `/api/v1/device/parameters` | user JWT + `X-Device-Token` | Device configuration |
| GET | `/api/v1/device/heartbeat` | user JWT + `X-Device-Token` | Poll `paramVersion` for config changes |
| POST | `/api/v1/device/logout` | user JWT + `X-Device-Token` | **Unregister Device** — releases it and sets `INACTIVE`. Not user sign-out |

### Invoicing (Admin)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/invoices` | Create invoice |
| GET | `/api/v1/invoices` | List invoices |
| GET | `/api/v1/invoices/:id` | Get invoice |
| GET | `/api/v1/invoices/summary` | Status counts and totals |
| GET | `/api/v1/invoices/lookup` | Look up an invoice by number or link |
| PUT | `/api/v1/invoices/:id` | Update invoice |
| DELETE | `/api/v1/invoices/:id` | Delete invoice |
| POST | `/api/v1/invoices/:id/send` | Send invoice (`method`: `email` or `sms`) |
| POST | `/api/v1/invoices/:id/send-email` | Send by email |
| POST | `/api/v1/invoices/:id/send-sms` | Send by SMS |
| POST | `/api/v1/invoices/:id/send-reminder` | Email a payment reminder |
| POST | `/api/v1/invoices/:id/payment` | Record an already-collected payment (alias `/record-payment`) |
| POST | `/api/v1/invoices/:id/payment-preflight` | Validate a payment amount |
| POST | `/api/v1/invoices/:id/external-payment` | Record a cash / check / wire payment |
| POST | `/api/v1/invoices/:id/cancel` | Cancel invoice |
| GET | `/api/v1/invoices/:id/qr-code` | Get QR code |
| GET | `/api/v1/invoices/:id/pdf` | Download PDF |
| GET | `/api/v1/products` | Product catalog (also `POST`, `PUT /:id`, `DELETE /:id`, bulk, import, export) |
| GET | `/api/v1/product-categories` | Product categories |

Invoices do not expire (`expiresAt` is legacy). There are no invoice-template endpoints; the invoice look comes from merchant branding.

### Webhooks

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/webhooks/endpoints` | Create webhook endpoint |
| GET | `/api/v1/webhooks/endpoints` | List webhook endpoints |
| GET | `/api/v1/webhooks/endpoints/:id` | Get endpoint details |
| PATCH | `/api/v1/webhooks/endpoints/:id` | Update endpoint |
| DELETE | `/api/v1/webhooks/endpoints/:id` | Delete endpoint |
| POST | `/api/v1/webhooks/endpoints/:id/test` | Send a `webhook.test` event |
| POST | `/api/v1/webhooks/endpoints/:id/regenerate-secret` | Rotate the signing secret |
| GET | `/api/v1/webhooks/endpoints/:id/deliveries` | Delivery attempts (`limit`, `offset`) |
| POST | `/api/v1/webhooks/deliveries/:deliveryId/retry` | Retry a delivery |

### Notifications / Receipts

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/notifications/receipt/email` | Send email receipt |
| POST | `/api/v1/notifications/receipt/sms` | Send SMS receipt |
| GET | `/api/v1/notifications/receipts/:transactionId/pdf` | Download PDF receipt |
| POST | `/api/v1/notifications/receipt/print` | Get printable receipt |
| POST | `/api/v1/notifications/receipt/refund/email` | Send refund receipt by email |
| POST | `/api/v1/notifications/receipt/refund/sms` | Send refund receipt by SMS |

### Settlement & Funding

The settlement service mounts under the plural `/api/v1/settlements`; the singular `/api/v1/settlement/*` paths reach no handler (the gateway answers `403 SERVICE_UNAVAILABLE` or `404`, depending on the tenant's plan).

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/settlements` | List settlements (`merchantId`, `dateFrom`, `dateTo`, `status`) |
| GET | `/api/v1/settlements/:settlementId` | Settlement detail |
| POST | `/api/v1/settlements/:settlementId/approve` | Approve a settlement |
| POST | `/api/v1/settlements/:settlementId/reconcile` | Reconcile against the gateway (`gatewayType`) |
| GET | `/api/v1/settlements/schedule/:merchantId` | Get settlement schedule |
| POST | `/api/v1/settlements/schedule` | Create settlement schedule |
| PUT | `/api/v1/settlements/schedule/:merchantId` | Update settlement schedule |
| DELETE | `/api/v1/settlements/schedule/:merchantId` | Delete settlement schedule |
| GET | `/api/v1/settlements/history/:merchantId` | Schedule change history |
| GET | `/api/v1/settlements/funding-report` | Get funding report |
| GET | `/api/v1/settlements/funding-report/export/csv` | Export funding report as CSV |
| POST | `/api/v1/settlements/funding-report/email` | Email funding report |
| POST | `/api/v1/settlements/payout` | Initiate a payout (`merchantId`, `date`, `amount`) |
| POST | `/api/v1/settlements/batch-payouts/generate` | Generate a batch payout (`dateFrom`, `dateTo`) |
| GET | `/api/v1/settlements/batch-payouts` | List batch payouts |
| GET | `/api/v1/settlements/batch-payouts/:id` | Batch payout detail |
| PATCH | `/api/v1/settlements/batch-payouts/items/:itemId/inclusion` | Include / exclude an item |
| POST | `/api/v1/settlements/batch-payouts/:id/approve` | Approve |
| POST | `/api/v1/settlements/batch-payouts/:id/process` | Mark processed |
| POST | `/api/v1/settlements/batch-payouts/:id/cancel` | Cancel |
| GET | `/api/v1/settlements/batch-payouts/:id/export` | Export as `.xlsx` |
| GET | `/api/v1/deposits` | List deposits |

### Batches

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/batches` | List batches |
| GET | `/api/v1/batches/:id` | Batch detail |
| GET | `/api/v1/batches/:id/transactions` | Transactions in a batch |
| POST | `/api/v1/batches/:id/settle` | Settle a batch |
| POST | `/api/v1/batches/:id/resubmit` | Resubmit a batch |
| GET / POST | `/api/v1/batches/schedule` | Auto-settle schedule |

### Disputes & Refund Queue

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/chargebacks` | List disputes |
| GET | `/api/v1/chargebacks/:id` | Dispute detail |
| POST | `/api/v1/chargebacks/:id/respond` | Submit a response |
| POST | `/api/v1/chargebacks/:id/accept` | Accept the dispute |
| GET | `/api/v1/dispute-alerts` | Pre-dispute alerts |
| GET | `/api/v1/refund-decline-queue` | Declined refunds awaiting retry |
| POST | `/api/v1/refund-decline-queue/:id/retry` | Retry now |
| POST | `/api/v1/refund-decline-queue/process-retries` | Run all due retries (nothing schedules this; retries only happen when it or `/:id/retry` is called) |
| POST | `/api/v1/refund-decline-queue/:id/resolve` | Resolve (`notes`) |
| POST | `/api/v1/refund-decline-queue/:id/cancel` | Cancel (`reason`) |

### Reporting

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/reports/transactions` | Transaction report (`dateFrom`, `dateTo`) |
| GET | `/api/v1/reports/batches` | Batch report |
| GET | `/api/v1/reports/daily-summary` | Daily summary |
| GET | `/api/v1/reports/card-aggregate` | Totals by card brand |
| GET | `/api/v1/reports/export/csv` | Export transactions (CSV) |
| GET | `/api/v1/reports/export/excel` | Export transactions (Excel) |
| GET | `/api/v1/reports/export` | Generic export (`format`: `csv` or `json`) |
| GET | `/api/v1/dashboard/summary` | Dashboard totals, channel breakdown, period comparison |

There are no `/api/v1/analytics/*` or `/api/v1/reporting/*` routes.

### Audit & Compliance

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/audit-logs` | Get audit log entries |
| GET | `/api/v1/user-sessions` | Get active user sessions |

### Roles & Permissions

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/roles` | List roles |
| POST | `/api/v1/roles` | Create role |
| GET | `/api/v1/roles/:id` | Get role details |
| PUT | `/api/v1/roles/:id` | Update role |
| DELETE | `/api/v1/roles/:id` | Delete role |
| GET | `/api/v1/roles/permissions` | Permission catalog |
| GET | `/api/v1/roles/merchant` | Merchant role definitions (`PUT` / `DELETE /roles/merchant/:code` to customise) |
| POST | `/api/v1/users` | Create a team member (also `GET`, `GET` / `PUT` / `DELETE /:id`) |
| PATCH | `/api/v1/users/:id/status` | Activate / deactivate a user |
| POST | `/api/v1/users/:id/send-invite` | Send an invite email |

---

## Standard Response Format

All endpoints return a consistent JSON envelope:

### Success
```json
{
  "success": true,
  "data": { ... }
}
```

### Error
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount is required"
  }
}
```

### Paginated List

List responses are not fully uniform: most return `data` plus a `meta` object, and some (for example `GET /api/v1/recurring`) return `{ data, total, page, perPage, totalPages }`. Check the topic page for the exact shape.

```json
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1234
  }
}
```

Some services (merchant gateways, settlement, batch payouts) return errors as `{ "success": false, "message": "..." }` instead of the `error` object.

---

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 | Request succeeded |
| 201 | Resource created |
| 400 | Bad request / validation error |
| 401 | Authentication required or failed |
| 402 | Card declined (Public API `/transaction` only) |
| 403 | Permission denied, or the tenant's plan lacks the feature (`SERVICE_UNAVAILABLE`) |
| 404 | Resource not found |
| 409 | Conflict (for example duplicate email, request already in progress) |
| 422 | Unprocessable entity |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
| 502 | Upstream gateway error |
| 503 | Downstream service unavailable |
| 504 | Downstream service timed out (`GATEWAY_TIMEOUT`) |

---

## Pagination

List endpoints support pagination via query parameters:

```
GET /api/v1/public/transaction-list?page=2&limit=50
```

| Parameter | Type | Default | Maximum |
|-----------|------|---------|---------|
| `page` | integer | 1 | — |
| `limit` | integer | varies by endpoint (10–100) | varies (for example 200 for invoices, products and disputes); the transaction list has no fixed cap |

---

## Common Filters

Most list endpoints accept date and status filters:

```
GET /api/v1/public/transaction-list?dateFrom=2026-02-01&dateTo=2026-02-28&status=approved
```

| Parameter | Description |
|-----------|-------------|
| `dateFrom` | Start date (ISO 8601, e.g., `2026-02-01`) |
| `dateTo` | End date (ISO 8601, e.g., `2026-02-28`) |
| `status` | Filter by status |
| `page` | Page number |
| `limit` | Items per page |

---

## Next Steps

- [Authentication Guide →](../getting-started/authentication.md)
- [Quick Start →](../getting-started/quickstart.md)
- [Transactions API →](../core/transactions.md)
- [Error Codes →](./error-codes.md)
- [Webhook Events →](./webhook-events.md)

---

**Need help?** Contact support@auxcore.net