Transactions API

Process credit card, ACH, and tokenized payments with the AuxVault Transactions API.

Overview

The Transactions API allows you to:

Process sales — One-step payment authorization and capture
Authorize payments — Reserve funds for later capture
Capture authorized payments — Complete a previously authorized transaction
Void transactions — Cancel a transaction before settlement
Refund payments — Return funds to customers (full or partial)
Issue credits — Provide unlinked credits
Rerun transactions — Retry a declined transaction

API Surfaces

AuxVault has two paths for processing transactions. Choose based on your integration type:

Surface	Base Path	Auth	Use Case
Public API	`/api/v1/public/`	`x-api-key` + `X-Tenant-ID`	ERP, server-to-server, plugins
Admin API	`/api/v1/transactions/`	`Authorization: Bearer JWT` + `X-Tenant-ID`	Dashboard integrations
AuxVault SDK	`/api/v1/auxvault/`	`x-api-key` (Bearer format)	auxVault.js SDK

For ERP and server integrations, use the Public API.

Transaction Types

Type	Description	Use Case
`sale`	Auth + Capture in one step	Immediate payment
`auth`	Reserve funds only	Hotels, rentals, pre-orders
`capture`	Capture a previously authorized transaction	After service delivered
`void`	Cancel before settlement	Order cancelled
`refund`	Return funds (full or partial)	Returns, disputes
`credit`	Unlinked credit	Store credit, compensation

Process a Sale — Public API

Endpoint

POST /api/v1/public/transaction

Required Headers

x-api-key: YOUR_API_KEY
X-Tenant-ID: YOUR_TENANT_ID
Content-Type: application/json

Card Payment

curl -X POST https://dev.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 150.75,
    "SuggestedMode": "Card",
    "CardNumber": "4111111111111111",
    "ExpiryMonth": "12",
    "ExpiryYear": "2027",
    "CVV": "123",
    "BillingCustomerName": "John Doe",
    "BillingEmail": "john.doe@example.com",
    "BillingAddress": "123 Main Street",
    "BillingCity": "New York",
    "BillingState": "NY",
    "BillingPostalCode": "10001",
    "OrderId": "ORDER-2026-001",
    "Description": "Widget purchase"
  }'

ACH Payment

curl -X POST https://dev.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 500.00,
    "SuggestedMode": "ACH",
    "account_number": "1234567890",
    "routing_number": "021000021",
    "account_type": "checking",
    "BillingCustomerName": "John Doe",
    "BillingEmail": "john.doe@example.com"
  }'

Token Payment (Stored Card)

curl -X POST https://dev.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 75.00,
    "token": "tok_abc123xyz",
    "BillingEmail": "john.doe@example.com"
  }'

Request Fields

Core Fields

Field	Type	Required	Description
`Amount`	number	Yes	Transaction amount in USD (e.g., `125.00`)
`SuggestedMode`	string	No	`"Card"` (default) or `"ACH"`
`OrderId`	string	No	Your order reference number
`Description`	string	No	Transaction description

Card Fields (when `SuggestedMode = "Card"`)

Field	Type	Required	Description
`CardNumber`	string	Yes*	13-19 digit card number
`ExpiryMonth`	string	Yes*	2-digit month (`"01"`–`"12"`)
`ExpiryYear`	string	Yes*	4-digit year (e.g., `"2027"`)
`CVV`	string	Conditional	3-4 digit security code
`token`	string	Alt*	Use a stored token instead of raw card data

*Required unless using token

ACH Fields (when `SuggestedMode = "ACH"`)

Field	Type	Required	Description
`account_number`	string	Yes	Bank account number
`routing_number`	string	Yes	Bank routing number
`account_type`	string	No	`"checking"` (default) or `"savings"`

Billing Fields

Field	Type	Required	Description
`BillingCustomerName`	string	Recommended	Cardholder name
`BillingEmail`	string	Recommended	Customer email (for receipts)
`BillingAddress`	string	Conditional*	Street address
`BillingCity`	string	Conditional*	City
`BillingState`	string	Conditional*	2-letter state code
`BillingPostalCode`	string	Conditional*	ZIP/postal code

*Required if AVS filtering is enabled for this merchant

Response

{
  "status": "success",
  "status_code": 200,
  "message": "Transaction processed successfully",
  "data": {
    "TransactionId": "txn_1234567890abcdef",
    "Status": "1",
    "Amount": 150.75,
    "BaseAmount": 150.75,
    "CardNumber": "****1111",
    "BillingEmail": "john.doe@example.com",
    "BillingCustomerName": "John Doe",
    "ResponseCode": "100",
    "ResponseMessage": "Approved",
    "AuthCode": "123456",
    "AvsResult": "Y",
    "CvvResult": "M",
    "GatewayTransactionId": "3456789012",
    "ProcessedAt": "2026-02-23T14:00:00.000Z"
  }
}

Status Codes

Status	Meaning
`"1"`	Approved
`"2"`	Pending
`"3"`	Processing
`"4"`	Authorized (auth-only)
`"9"`	Declined

Void a Transaction — Public API

Cancel an approved transaction before it settles (typically within 24 hours).

Endpoint

POST /api/v1/public/void

curl -X POST https://dev.auxcore.net/api/v1/public/void \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_1234567890abcdef",
    "reason": "Customer request"
  }'

Field	Required	Description
`transactionId`	Yes	AuxVault transaction ID to void
`reason`	No	Reason for voiding

Note: After settlement (typically 24+ hours), use /refund instead.

Refund a Transaction — Public API

Issue a full or partial refund for a settled transaction.

Endpoint

POST /api/v1/public/refund

# Full refund
curl -X POST https://dev.auxcore.net/api/v1/public/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_1234567890abcdef",
    "reason": "Item returned"
  }'

# Partial refund
curl -X POST https://dev.auxcore.net/api/v1/public/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_1234567890abcdef",
    "amount": 50.00,
    "reason": "Partial return"
  }'

Field	Required	Description
`transactionId`	Yes	AuxVault transaction ID
`amount`	No	Partial refund amount. Omit for full refund.
`reason`	No	Reason for refund

Get Transaction — Public API

Retrieve the full details of a specific transaction.

Endpoint

GET /api/v1/public/transaction/:id

curl https://dev.auxcore.net/api/v1/public/transaction/txn_1234567890abcdef \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

List Transactions — Public API

Search and filter transactions.

Endpoint

GET /api/v1/public/transaction-list

# All recent transactions
curl "https://dev.auxcore.net/api/v1/public/transaction-list" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

# Filter by date range
curl "https://dev.auxcore.net/api/v1/public/transaction-list?startDate=2026-02-01&endDate=2026-02-28" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

# Filter by status
curl "https://dev.auxcore.net/api/v1/public/transaction-list?status=approved" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 50, max: 200)
`startDate`	date	Filter start date (ISO 8601)
`endDate`	date	Filter end date (ISO 8601)
`status`	string	`approved`, `declined`, `voided`, `refunded`, `settled`

Rerun a Declined Transaction — Public API

Retry a previously declined transaction.

Endpoint

POST /api/v1/public/rerun

curl -X POST https://dev.auxcore.net/api/v1/public/rerun \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_1234567890abcdef"
  }'

Token-Based Transaction — Public API

Charge a stored card token from the Card Vault.

Endpoint

POST /api/v1/public/token-transaction

curl -X POST https://dev.auxcore.net/api/v1/public/token-transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "tok_abc123xyz",
    "amount": 125.00,
    "description": "Monthly renewal"
  }'

Admin API Routes (Dashboard / JWT Auth)

These routes are used by the AuxVault dashboard and require a JWT Bearer token. They accept a different request body format.

Process a Sale

POST /api/v1/transactions

curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sale",
    "amount": 150.75,
    "currency": "USD",
    "paymentMethod": "card",
    "cardNumber": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "2027",
    "cvv": "123",
    "customerName": "John Doe",
    "email": "john@example.com"
  }'

Capture an Authorization

POST /api/v1/transactions/:transactionId/capture

curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_auth_abc123/capture \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 250.00 }'

Cancel Capture

POST /api/v1/transactions/:transactionId/cancel-capture

curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/cancel-capture \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Issue an Unlinked Credit

POST /api/v1/transactions/:transactionId/credit

curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/credit \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "reason": "Goodwill credit for service delay"
  }'

AVS Response Codes

Code	Meaning
`Y`	Address and 5-digit ZIP match
`A`	Address matches, ZIP does not
`Z`	ZIP matches, address does not
`N`	Neither address nor ZIP match
`U`	Address information unavailable
`R`	Retry — system unavailable
`S`	Service not supported

CVV Response Codes

Code	Meaning
`M`	CVV matches
`N`	CVV does not match
`P`	CVV not processed
`S`	CVV should be on card but not provided
`U`	Issuer unable to process CVV

Error Handling

Declined Transaction

{
  "status": "error",
  "status_code": 400,
  "message": "Transaction declined",
  "data": {
    "TransactionId": "txn_declined_123",
    "Status": "9",
    "ResponseCode": "200",
    "ResponseMessage": "Insufficient funds"
  }
}

Validation Error

{
  "success": false,
  "error": "Transaction ID required",
  "message": "Please provide a transactionId in the request body"
}

Next Steps

Questions? Contact support@auxvault.com

Transactions API

Overview

API Surfaces

Transaction Types

Process a Sale — Public API

Endpoint

Required Headers

Card Payment

ACH Payment

Token Payment (Stored Card)

Request Fields

Core Fields

Card Fields (when SuggestedMode = "Card")

ACH Fields (when SuggestedMode = "ACH")

Billing Fields

Response

Status Codes

Void a Transaction — Public API

Endpoint

Refund a Transaction — Public API

Endpoint

Get Transaction — Public API

Endpoint

List Transactions — Public API

Endpoint

Query Parameters

Rerun a Declined Transaction — Public API

Endpoint

Token-Based Transaction — Public API

Endpoint

Admin API Routes (Dashboard / JWT Auth)

Process a Sale

Capture an Authorization

Cancel Capture

Issue an Unlinked Credit

AVS Response Codes

CVV Response Codes

Error Handling

Declined Transaction

Validation Error

Next Steps

Card Fields (when `SuggestedMode = "Card"`)

ACH Fields (when `SuggestedMode = "ACH"`)