API Endpoints Reference#

Complete reference for all AuxCORE API endpoints.

Required Headers#

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

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

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

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

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#

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

See Environments for PCI, docs, and dashboard URLs.

API Surfaces#

AuxCORE exposes three API surfaces depending on your use case:

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#

Authentication (Public API)#

Transactions (Public API)#

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)#

Customers (Public API)#

Recurring (Public API)#

Merchants (Public API)#

OTP (Public API)#

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

Invoicing & Payment Links (Public API)#

Creating a link: Payment Links. The /payment-links/:linkId/* routes are called by the hosted pay page.

Checkout Sessions (Public API)#

Flow, request fields and confirmation: Hosted Checkout.

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

Payment Plans (Public API)#

Gateway Operations (Public API)#

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)#

Webhooks & Integrations (Public API)#

Dashboard Totals (Public API)#

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.

See SDK setup and Transactions 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.

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#

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#

Multi-merchant sessions#

For users who belong to more than one merchant. Full reference: Authentication Guide →

API Keys#

Transactions (Admin)#

Recurring (Admin)#

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 →

Customers (Admin)#

Merchants (Admin)#

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 →

Devices (Mobile / POS app)#

Called by the app on the terminal. Full reference: Mobile Device Integration →

Invoicing (Admin)#

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

Webhooks#

Notifications / Receipts#

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).

Batches#

Disputes & Refund Queue#

Reporting#

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

Audit & Compliance#

Roles & Permissions#

Standard Response Format#

All endpoints return a consistent JSON envelope:

Success#

{
  "success": true,
  "data": { ... }
}

Error#

{
  "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.

{
  "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#

Pagination#

List endpoints support pagination via query parameters:

Common Filters#

Most list endpoints accept date and status filters:

Next Steps#

• Authentication Guide →
• Quick Start →
• Transactions API →
• Error Codes →
• Webhook Events →

Need help? Contact support@auxcore.net