# Postman Collection

One Postman collection, **AuxCORE API v2.0**, covers the whole API: the Public API and current SDK (`/api/v1/public/*`), AuxCORE SDK API (`/api/v1/auxvault/*`) and the Admin API (`/api/v1/*`). It has about 400 ready-made requests with example bodies.

---

## Download

Pick the host you are testing against. The file is the same on both:

| Environment | Download |
|-------------|----------|
| Sandbox | [https://uat.auxcore.net/postman-collection](https://uat.auxcore.net/postman-collection) |
| Production | [https://app.auxcore.net/postman-collection](https://app.auxcore.net/postman-collection) |

You can also download it from **Settings → Developer & Integrations → SDK & API Docs** (`/settings/developer/sdk` on your dashboard host), using the Postman button.

> The file is also served at `/AuxCORE.postman_collection.json`. The older `/AuxVault.postman_collection.json` and `/LuqraVault.postman_collection.json` links redirect to the current collection.

---

## Quick Start

1. In Postman, choose **Import** and select the downloaded file.
2. Open the collection's **Variables** tab and set `baseUrl` and `apiKey` (see the table below).
3. Run **Connection → Test Connection**. A `200` response means your key works.
4. To use the **Admin API** folder, run **Auth → Login (Get JWT)** first. Replace the example `email` and `password` in its body with your dashboard login. The request saves the returned token into `jwtToken`, and the Admin API folder uses it from then on.

---

## Collection Variables

**Set these yourself:**

| Variable | Example | Used for |
|----------|---------|----------|
| `baseUrl` | `https://uat.auxcore.net` | Every request. Use `https://app.auxcore.net` for production. No trailing slash. |
| `apiKey` | `api-…` | Public API and SDK requests (`x-api-key` header). Create it in the dashboard under `/settings/developer/api-keys`. |
| `tenantId` | `your-tenant-id` | Admin API requests (`X-Tenant-ID` header) and the login request. Not needed for Public API calls with a merchant key. |
| `merchantId` | *(blank)* | Requests that act on one merchant. For a tenant-wide ERP key (`lv_erp_…`), set it and enable the optional `X-Merchant-ID` header in the SDK requests. |
| `merchantOrigin` | `https://your-checkout.example` | For SDK embed keys with allowed origins, enable `X-Merchant-Origin` in **Hosted Fields (Public API)** and set an allowed website origin. |

**Set these only if you use that folder:**

| Variable | Folder |
|----------|--------|
| `processingBaseUrl`, `processingApiKey`, `serverEgressIp` | Transactions → Token Processing (partner PCI processing, uses its own `ltk_…` key) |
| `yeastarApiKey` | Checkout & Webhooks → Yeastar |

**Filled in automatically:** `jwtToken` (from login), plus ids such as `testToken`, `testTransactionId`, `testCustomerId`, `invoiceId`, `recurringId`, `planId`, `deviceToken` and `webhookEndpointId`. A request that creates something saves its id, and later requests in the same folder reuse it. `sdkCardToken` is populated by PascalCase tokenization and is separate from the PCI `testToken`. Run a folder's "create" request before its "get", "update" or "delete" requests.

---

## Authentication

You don't add auth headers by hand. The collection sets them:

| Folder | Sent automatically |
|--------|--------------------|
| All folders except Admin API | `x-api-key: {{apiKey}}` |
| Admin API (and its sub-folders) | `Authorization: Bearer {{jwtToken}}` and `X-Tenant-ID: {{tenantId}}` |
| Payment Links (Public), Invoice Payments (Public) | No auth: these are the customer-facing pay pages |

---

## Folders

| Folder | What it covers |
|--------|----------------|
| **Connection** | Test your key; SDK and key info |
| **Auth** | Login to get a JWT, refresh, client token |
| **Transactions** | Sale, void, refund, token sale, list, get; sub-folders for the public dashboard summary and partner Token Processing |
| **Tokenization** | Tokenize a card or bank account, save a card |
| **Customer Vault** | Customers and their saved payment methods |
| **Recurring Billing** | Create a subscription; sub-folder for the public payment-plan pages |
| **Merchants** | Merchant details, config and fees, checkout field config, payment purposes, KYC check, provisioning |
| **OTP** | Generate, verify, resend |
| **Invoicing** | Payment links and text-to-pay; sub-folders for the public invoice and payment-link pay pages |
| **AuxCORE SDK** | **Hosted Fields (Public API)**: current `auxVault.js` sale/auth, key info, config and fees. **API (v2.0)**: the eight `/api/v1/auxvault/*` routes, with full/partial refund examples |
| **Checkout & Webhooks** | Hosted checkout sessions, webhook registration, integrations, Yeastar lookup |
| **Admin API** | Dashboard operations, grouped into sub-folders: transactions, invoices, products, recurring, payment plans, customers, settlement, batches, refund queue, disputes, reports, webhooks, API keys, users and permissions, devices, mobile, virtual terminal, audit |

---

## Before you run the requests

- **Current SDK payments use a PCI token.** Obtain a fresh `pci_tok_…` token from PCI hosted fields and set `testToken` before running **AuxCORE SDK → Hosted Fields (Public API)**. On Sandbox, the Public API **Tokenize Card** request (secret key) can also produce one. Raw card payments are rejected on Sandbox and Production.
- **SDK auth-only uses `TransactionType: "auth"`** (or `"2"`) on `POST /api/v1/public/transaction`. The `/auxvault/transaction` adapter always calls sale, even with `"0"`, and does not forward `pciToken`; its raw-card sale sample is for development.
- **PascalCase tokenization returns a card-security token.** `/api/v1/auxvault/tokenize` accepts raw card data and returns `tok_…`, saved as `sdkCardToken`, separate from the PCI `testToken`. Its handler has no development-only PCI guard; gateway auth requires a server-side key and rejects SDK public keys.
- **A prefix is not an endpoint.** `/api/v1/auxvault` has no root handler. To test connectivity use **Connection → Test Connection**; call SDK child paths with the documented method. Use a server-side key in `x-api-key` on `/auxvault` and omit `Authorization`.
- **Two requests are marked as not working:** Rerun Transaction (returns `404`) and Decrypt Token (development environments only). Their descriptions in Postman say so.
- If a request in the collection disagrees with these docs, follow the docs.

---

## Related

- [Authentication](../getting-started/authentication.md): API key types and how to get a JWT
- [Testing](../getting-started/testing.md): test cards and the sandbox
- [All Endpoints](../reference/endpoints.md): every endpoint in one list
- Swagger UI: `/api-docs` on your host, only on non-production builds