Every request must be authenticated. You can do this via Basic Auth or by including credentials in the JSON body. Pick one method and keep it consistent across your integration.

Use your merchant username as x_login and your secret key as x_tran_key for protected merchant endpoints. The login token flow on /query/auth/* is public and uses user credentials instead.

Quick Checklist

• Credentials are present on every request.
• Only one auth method is used per request.
• Secrets never appear in client-side code.

Auth Endpoints

• POST /query/auth/mfatoken — Validates username/password and returns an mfa_token.
• POST /query/auth/token — If payload contains mfa_token and code, verifies MFA and issues an access token.
• POST /query/auth/token — If payload contains username (or email) and password, it also requires trusted-device credentials to issue an access token.
• GET /query/me — Returns the current authenticated user, merchant, and organization context (requires authentication).

{
  "username": "user@example.com",
  "password": "your_password"
}

{
  "result": "success",
  "mfa_token": "dummy_mfa_token",
  "expires_in": 300
}

{
  "mfa_token": "dummy_mfa_token",
  "code": "123456",
  "remember_device": 1
}

{
  "username": "user@example.com",
  "password": "your_password",
  "trusted_device_id": "32_hex_device_id",
  "trusted_device_token": "device_token"
}

{
  "result": "success",
  "user_id": 12,
  "merchant": "MERCHANTCODE",
  "access_token": "dummy_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "trusted_device_id": "32_hex_device_id",
  "trusted_device_token": "device_token",
  "trusted_device_expires_in": 2592000
}

Authorization: Bearer <access_token>

Authorization: Basic <base64(username:secret_key)>

Base64 must be generated from the exact string username:secret_key (one colon, no extra spaces).

{
  "x_login": "your_username",
  "x_tran_key": "your_secret_key"
}

Common Pitfalls

• Wrong key: Make sure you use the secret key, not a public identifier.
• Mixed methods: Do not send both Basic Auth and body credentials in the same request.
• Invalid JSON: Trailing commas or comments will cause auth to fail.
• MFA challenge shape: An MFA-required login returns result: "success" with mfa_token and expires_in.
• Remember device default: If remember_device is omitted during MFA verification, the device is remembered by default.
• Trusted login requirements: The username/password token flow requires both trusted_device_id and trusted_device_token; otherwise it fails with Unknown Device.

Security Tips

• Store secrets in server-side environment variables.
• Rotate keys regularly and after staff changes.
• Never log raw credentials in application logs.

Create short-lived card tokens for use with the Charges API.

Authentication:

- Authorization: Bearer <access_token> (recommended if you use the login/JWT flow)

- or Authorization: Basic (merchant x_login / x_tran_key)

- or include x_login and x_tran_key in the JSON body

Body Parameters

{
  "number": "4242424242424242",
  "month": "12",
    "year": "30"
}

{
  "result": "success",
  "token": "tok_..."
}

Charge operations backed by Transactions. A charge id corresponds to the Transaction presentation_id within the authenticated merchant scope.

Authentication:

- Authorization: Bearer <access_token> (recommended if you use the login/JWT flow)

- or Authorization: Basic (merchant x_login / x_tran_key)

- or include x_login and x_tran_key in the JSON body

Idempotency (optional):

Send an Idempotency-Key header (or idempotency_key body field, max 128 characters) on POST /charges and POST /charges/{id}/capture to safely retry requests without charging the card twice. If a request with the same key already completed, the original response is replayed with an Idempotency-Replayed: true header. Reusing a key with a different payload returns 422; a duplicate sent while the original is still processing returns 409 with Retry-After. Keys are kept for 7 days and are scoped to your merchant account and endpoint. Requests without a key behave exactly as before.

Create Charge Body Parameters

{
    "token": "tok_...",
    "cvc": "123",
    "amount": 12.34,
    "transtype": "AUTH_CAPTURE",
    "billing": {
        "first_name": "Jane",
        "last_name": "Smith",
        "address": "123 Main St",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "USA",
        "email": "jane@example.com",
        "phone": "5550123",
        "description": "Online Purchase"
    }
}

{
  "payment_method_id": 12345,
  "customer_id": 67890,
  "amount": 12.34,
  "transtype": "AUTH_CAPTURE"
}

{
  "token": "tok_...",
    "cvc": "123",
  "amount": 12.34,
  "save_payment_method": true,
  "billing": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "company": "Acme Inc",
    "address": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "USA",
    "phone": "5550123"
  }
}

{
  "result": "success",
  "charge": {
    "id": 123456,
    "transaction_id": 98765,
    "amount": 12.34,
    "currency": "USD",
    "status": 1,
    "status_text": "succeeded",
    "type": 1,
    "created": "...",
    "description": "Online Purchase",
    "notes": null,
    "reference_id": 0,
    "last4": "4242"
  },
    "customer_id": 67890,
    "payment_method_id": 12345,
  "transaction": {
    "status": 1,
    "status_text": "Success",
    "reason_text": "...",
    "transaction_id": "123456"
    }
}

Capture Charge Body Parameters

{
  "amount": 12.34
}

HTTP Status Codes

Transaction records are backed by the transactions table.

ID behavior: for GET /query/transaction/{id}, the endpoint first resolves {id} against merchant-scoped presentation_id, then falls back to internal transaction_id. In responses, uniqueID reflects merchant-facing presentation_id.

Authentication:

- Authorization: Bearer <access_token> (recommended if you use the login/JWT flow)

- or Authorization: Basic (merchant x_login / x_tran_key)

- or include x_login and x_tran_key in the JSON body

Optional query parameters for GET /query/transaction:

• page: page number (1-based). When provided, results are paginated.
• pageSize: records per page. Optional; defaults to 50.

List Query Parameters

GET /query/transaction?page=1&pageSize=25&sort=-uniqueID

Create Transaction Body Parameters

{
    "amount_total": 12.34,
    "amount_tax": 0.50,
    "amount_discount": 1.00,
    "amount_shipping": 2.50,
    "amount_surcharge": 0.25,
    "amount_tip": 1.50,
    "currency": "USD",
    "description": "Order #1001",
    "notes": "Recorded from mobile tap-to-pay",
    "transtype": "AuthCapture",
    "state": "Settled",
    "created": "2026-01-29 12:34:56",
    "payment_information": {
        "method": "CC",
        "last4": "4242"
    },
    "billing": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "phone1": "555-555-5555"
    },
    "items": [
        {"title": "T-Shirt", "quantity": 1, "unit_price": 12.34}
    ]
}

{
  "result": "success",
  "transaction": {
    "uniqueID": 123456,
    "customer_id": 555,
    "coupon_id": 0,
    "recurring_id": 0,
    "amount_total": 12.34,
    "amount_tax": 0,
    "amount_discount": 12.34,
    "amount_shipping": 0,
    "amount_surcharge": 0,
    "amount_tip": 0,
    "currency": "USD",
    "created": "2026-01-29 12:34:56",
    "description": "Order #1001",
    "notes": "Created by integration",
    "billing": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone1": "555-555-5555",
      "phone2": "",
      "address": "",
      "address2": "",
      "city": "",
      "state": "",
      "zip": "",
      "country": ""
    },
    "shipping": {
      "first_name": "",
      "last_name": "",
      "email": "",
      "phone1": "",
      "phone2": "",
      "address": "",
      "address2": "",
      "city": "",
      "state": "",
      "zip": "",
      "country": ""
    },
    "payment_information": {
      "method": 16,
      "last4": "4242"
    },
    "invoicing_id": null,
    "reference_id": null,
    "status": "Unprocessed",
    "state": "Settled",
    "transtype": "AuthCapture",
    "source": "Endpoint"
  }
}

Refund operations backed by Transactions. Refunds are processed as gateway CREDIT transactions against an existing charge (Transaction presentation_id) within the authenticated merchant scope.

Authentication:

- Authorization: Bearer <access_token> (recommended if you use the login/JWT flow)

- or Authorization: Basic (merchant x_login / x_tran_key)

- or include x_login and x_tran_key in the JSON body

Idempotency (optional):

Send an Idempotency-Key header (or idempotency_key body field, max 128 characters) on POST /refunds to safely retry a refund without crediting the card twice. If a request with the same key already completed, the original response is replayed with an Idempotency-Replayed: true header. Reusing a key with a different payload returns 422; a duplicate sent while the original is still processing returns 409 with Retry-After. Keys are kept for 7 days and are scoped to your merchant account and endpoint. Requests without a key behave exactly as before.

Create Refund Body Parameters

{
  "charge_id": 123456,
  "amount": 12.34,
  "notes": "Customer requested refund"
}

{
  "result": "success",
  "refund": {
    "id": 222222,
    "transaction_id": 98765,
    "amount": 12.34,
    "currency": "USD",
    "status": 1,
    "status_text": "succeeded",
    "type": 4,
    "created": "...",
    "description": null,
    "notes": null,
    "reference_id": 0,
    "last4": "4242"
  },
  "original_charge": {
    "id": 123456,
    "transaction_id": 12345,
    "amount": 12.34,
    "currency": "USD",
    "status": 1,
    "status_text": "succeeded",
    "type": 1,
    "created": "...",
    "description": "Online Purchase",
    "notes": null,
    "reference_id": 0,
    "last4": "4242"
  },
  "transaction": {
    "status": 1,
    "status_text": "Success",
    "reason_text": "...",
    "transaction_id": "222222"
  }
}

HTTP Status Codes

Chargebacks and retrievals (disputes) filed against your account. You can list disputes, retrieve a single dispute, and respond to an open dispute by accepting it or challenging it with evidence. Disputes are pulled from the chargeback processing system, so only merchants with a MID configured on their account can use this endpoint. Data and behavior match the Disputes page of the dashboard.

Authentication:

- Authorization: Bearer <access_token> (recommended if you use the login/JWT flow)

- or Authorization: Basic (merchant x_login / x_tran_key)

- or include x_login and x_tran_key in the JSON body

List Disputes Query Parameters

{
  "result": "success",
  "disputes": [
    {
      "uniqueID": 448821,
      "case_number": "7211930051",
      "case_type": "Chargeback",
      "case_status": "Needs Response",
      "case_amount": 74.95,
      "currency": "USD",
      "reason_code": "10.4",
      "reason_description": "Other Fraud - Card Absent Environment",
      "cardholder_account_number": "************4242",
      "posted_date": "2026-07-02",
      "due_date": "2026-07-18",
      "item_type": "Open"
    }
  ],
  "pageCount": 4,
  "totalCount": 92
}

The list returns a summary of each dispute. Fields only available on the full record (e.g. card_brand, card_name, auth_code, arn, order_id, transaction_date, chargeback_date, notes) are omitted from list results — retrieve the dispute by id to get them.

Returns the full dispute record by its uniqueID. Disputes belonging to another merchant return 404.

{
  "result": "success",
  "dispute": {
    "uniqueID": 448821,
    "case_number": "7211930051",
    "case_type": "Chargeback",
    "case_status": "Needs Response",
    "case_amount": 74.95,
    "currency": "USD",
    "reason_code": "10.4",
    "reason_description": "Other Fraud - Card Absent Environment",
    "card_brand": "Visa",
    "card_name": "JOHN SMITH",
    "cardholder_account_number": "************4242",
    "auth_code": "081522",
    "arn": "74537506123456789012345",
    "order_id": "ORD-10592",
    "transaction_date": "2026-06-02",
    "chargeback_date": "2026-07-01",
    "posted_date": "2026-07-02",
    "due_date": "2026-07-18",
    "item_type": "Open",
    "notes": ""
  }
}

Accepts liability for an open dispute. Only disputes that are open for responses (e.g. status Needs Response) can be accepted; otherwise 409 is returned.

Accept Dispute Body Parameters

Challenges an open dispute with supporting evidence. Send the request as multipart/form-data with the evidence document in a file field. The file is required unless documents have already been uploaded to the dispute (e.g. through the dashboard). Allowed file types: JPG, PNG, GIF, PDF, TXT (max 32 MB).

Challenge Dispute Body Parameters (multipart/form-data)

curl -X POST https://api.example.com/query/disputes/448821/challenge \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@signed_receipt.pdf" \
  -F "comment=Customer signed for delivery on 2026-06-04"

{
  "result": "success",
  "message": "Challenge submitted",
  "dispute": {
    "uniqueID": 448821,
    "case_status": "Under Review",
    "item_type": "Resolved",
    "...": "..."
  }
}

Dispute Object Fields

Fields are included only when the upstream system provides them: list results contain the summary fields shown in the list sample above, while retrieving a dispute by id returns the full set below.

HTTP Status Codes

Void operations backed by Transactions. Voids are processed as gateway VOID transactions against an existing charge (Transaction presentation_id) within the authenticated merchant scope.

Authentication:

- Authorization: Bearer <access_token> (recommended if you use the login/JWT flow)

- or Authorization: Basic (merchant x_login / x_tran_key)

- or include x_login and x_tran_key in the JSON body

Create Void Body Parameters

{
  "charge_id": 123456,
  "notes": "Customer requested cancellation"
}

{
  "result": "success",
  "void": {
    "id": 333333,
    "transaction_id": 99999,
    "amount": 12.34,
    "currency": "USD",
    "status": 1,
    "status_text": "succeeded",
    "type": 8,
    "created": "...",
    "description": null,
    "notes": null,
    "reference_id": 0,
    "last4": "4242"
  },
  "original_charge": {
    "id": 123456,
    "transaction_id": 12345,
    "amount": 12.34,
    "currency": "USD",
    "status": 1,
    "status_text": "succeeded",
    "type": 1,
    "created": "...",
    "description": "Online Purchase",
    "notes": null,
    "reference_id": 0,
    "last4": "4242"
  },
  "transaction": {
    "status": 1,
    "status_text": "Success",
    "reason_text": "...",
    "transaction_id": "333333"
  }
}

Webhooks let a merchant register HTTPS endpoints that receive signed event payloads when payment activity happens. The API is available through /query/webhook, /query/webhooks, or /query/expiwebhook.

Authentication:

- Authorization: Bearer <access_token>

- or Authorization: Basic using merchant x_login / x_tran_key

- or include x_login and x_tran_key in the JSON body

Endpoint Body Parameters

{
  "url": "https://example.com/webhooks/expitrans",
  "description": "Production payment events",
  "events": [
    "charge.created",
    "charge.captured",
    "charge.failed",
    "recurring.payment_succeeded",
    "recurring.payment_failed",
    "refund.created"
  ],
  "enabled": true
}

{
  "result": "success",
  "webhook": {
    "id": 101,
    "object": "webhook_endpoint",
    "url": "https://example.com/webhooks/expitrans",
    "description": "Production payment events",
    "enabled": true,
    "events": ["charge.created", "charge.captured", "charge.failed", "recurring.payment_succeeded", "recurring.payment_failed", "refund.created"],
    "api_version": "2026-06-29",
    "created_at": "2026-06-29 12:00:00-06",
    "updated_at": "2026-06-29 12:00:00-06",
    "secret": "whsec_..."
  }
}

Supported Events

Delivery Format

Receivers get a JSON event object. Delivery includes Expi-Event-Id and Expi-Signature headers. The signature format is t={timestamp},v1={hmac}, where hmac is HMAC-SHA256(timestamp + "." + raw_body, endpoint_secret).

Failed deliveries are retried by the webhook delivery cron (lib/cron/webhooks.php) when their next_attempt_at time is due, up to the configured maximum attempt count. Manual resend marks a delivery due immediately so the same worker can process it.

{
  "id": "evt_...",
  "object": "event",
  "type": "charge.created",
  "created": 1782765600,
  "data": {
    "object": {
      "id": 123456,
      "transaction_id": 98765,
      "amount": 12.34,
      "currency": "USD",
      "status_text": "succeeded"
    }
  }
}

Manage customer profiles with a single endpoint. Create customers and store contact, billing, and custom fields for downstream billing workflows.

List Query Parameters

GET /query/customer?page=1&pageSize=25&sort=-uniqueID

{
  "result": "success",
  "customer": {
    "uniqueID": 1234,
    "customer_information": {
      "firstname": "Alex",
      "lastname": "Rivera",
      "address1": "123 Market Street",
      "address2": "",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "USA",
      "phone1": "4155550134",
      "phone2": "",
      "email": "alex.rivera@example.com"
    },
    "billing_information": {
      "firstname": "Alex",
      "lastname": "Rivera",
      "address1": "123 Market Street",
      "address2": "",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "USA",
      "phone": "4155550134",
      "email": "alex.rivera@example.com"
    },
    "custom": {
      "custom1": "A-1001",
      "custom2": "Gold",
      "custom3": "West",
      "custom4": "",
      "custom5": "",
      "custom6": "",
      "custom7": "",
      "custom8": "",
      "custom9": "",
      "custom10": ""
    },
    "defaultPaymentID": 2002,
    "customer_payments": [
      {
        "paymentID": 2001,
        "paymenttype": "Credit Card",
        "lastfour": "4242"
      },
      {
        "paymentID": 2002,
        "paymenttype": "Checking",
        "lastfour": "6789"
      }
    ]
  }
}

{
  "x_login": "...",
  "x_tran_key": "...",
  "customer": {
    "customer_information": {
      "firstname": "Jane",
      "lastname": "Smith",
      "email": "jane@example.com",
      "phone1": "555-0123",
      "address1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "billing_information": {
      "firstname": "Jane",
      "lastname": "Smith",
      "address1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "custom": {
      "custom1": "VIP Client"
    }
  }
}

{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "customer": {
    "customer_information": {
      "firstname": "Jane",
      "lastname": "Smith",
      "email": "jane@example.com",
      "phone1": "555-0123"
    },
    "billing_information": {
      "address1": "456 Elm St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "custom": {
      "custom1": "VIP Client"
    },
    "customer_payments": [
      {
        "paymentID": 2002
      }
    ]
  }
}

Create and manage recurring billing schedules through the central query handler.

Create Modes: recurring creation supports single-product mode (product_id) and multi-product mode (products).

Required (Create): customer_id, payment_id, status, surcharge, run_transaction, and exactly one mode input: product_id OR products.

List Query Parameters

GET /query/recurring?page=1&pageSize=25&sort=-uniqueID

{
  "result": "success",
  "data": {
    "uniqueID": 12345,
    "status": 1,
    "interval": 3,
    "interval_number": 1,
    "run_until": 2,
    "run_limit": 12,
    "end_date": null,
    "run_next": "2026-09-25 00:00:00",
    "run_last": "2026-08-25 00:00:00",
    "run_count": 2,
    "run_total": 400.00,
    "amount": 203.50,
    "surcharge": 3.50,
    "currency": "USD",
    "customer_id": 6531,
    "payment_id": 3370,
    "idempotency_key": "recurring-single-20260725223646",
    "items": [
      {
        "product_id": 823,
        "product_name": "Monthly Service",
        "description": "Monthly recurring service fee",
        "qty": 1,
        "price": 200
      },
      {
        "product_id": null,
        "product_name": "Custom Support Add-on",
        "description": "Optional support fee",
        "qty": 1,
        "price": 0
      }
    ]
  }
}

Parameters

Validation Notes (Create):

• Date/time values are passed through by the endpoint and handled by the existing recurring model/database conversion.
• run_next and date-based end_date must be future dates based on the merchant-local date; today's merchant-local date is not accepted.
• idempotency_key is created by the client and should be unique per create request for the merchant. Reuse it only when retrying the same request after an unclear response.
• All referenced products must belong to the same merchant as x_login.
• In multi-product mode, each item may use product_id (or alias productID). For custom items without a product ID, name and price are required; qty defaults to 1.
• Schedule resolution in multi-product mode:
  • If recurring_rule_product is provided, its recurring rule is used.
  • If omitted and exactly one recurring-enabled product exists in products, that product's recurring rule is used.
  • If omitted and multiple recurring-enabled products exist, provide recurring_rule_product or explicit schedule fields.
  • If omitted and no recurring-enabled products exist, explicit schedule fields are required.
• Amount calculation:
  • Single-product mode: amount = product price + surcharge
  • Multi-product mode: amount = sum(qty * unit_price) + surcharge

{
  "x_login": "...",
  "x_tran_key": "...",
  "recurring": {
    "customer_id": 123,
    "payment_id": 456,
    "product_id": 111,
    "status": 1,
    "surcharge": 3.50,
    "run_transaction": true,
    "idempotency_key": "recurring-single-20260725223646",
    "run_next": "2026-08-25",
    "interval": 2,
    "interval_number": 1,
    "run_until": 2,
    "run_limit": 12
  }
}

{
  "x_login": "...",
  "x_tran_key": "...",
  "recurring": {
    "customer_id": 123,
    "payment_id": 456,
    "recurring_rule_product": 111,
    "products": [
      {
        "product_id": 111
      },
      {
        "productID": 222,
        "qty": 2
      },
      {
        "name": "Custom Item",
        "description": "Manual line item",
        "qty": 1,
        "price": 12.50
      }
    ],
    "status": 1,
    "surcharge": 3.50,
    "run_transaction": false,
    "idempotency_key": "recurring-multi-20260725223646",
    "interval": 2,
    "interval_number": 1,
    "run_until": 1,
    "end_date": "2027-01-25"
  }
}

{
  "x_login": "...",
  "x_tran_key": "...",
  "recurring": {
    "customer_id": 123,
    "payment_id": 456,
    "products": [
      {
        "name": "Custom Item A",
        "qty": 1,
        "price": 15.00
      },
      {
        "name": "Custom Item B",
        "qty": 2,
        "price": 20.00
      }
    ],
    "status": 1,
    "surcharge": 3.50,
    "run_transaction": false,
    "interval": 3,
    "interval_number": 1,
    "run_until": 2,
    "run_limit": 6
  }
}

Parameters

Note: Recurring line items cannot be updated via the update endpoint.

{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "recurring": {
    "status": 1,
    "interval": 2,
    "interval_number": 1,
    "run_until": 2,
    "run_limit": 12,
    "run_next": "2026-09-01"
  }
}

Failed Payment Behavior

When a scheduled recurring payment run fails (card declined or gateway transport error), the schedule itself is not changed:

• The recurring status remains 1 (Active); the schedule is not paused or terminated automatically.
• run_next, run_count, and run_total are not advanced. The schedule only advances after a successful payment.
• The failed run is retried automatically on the next daily billing cycle, and continues to retry once per day until the payment succeeds or the schedule's status is changed (for example to 4=Paused or 5=Terminated via the update endpoint).
• There is no retry limit. To stop retries, update the schedule's status, or update payment_id to a valid stored payment method so the next retry can succeed.
• A recurring.payment_failed webhook event is emitted for each failed attempt. When a retry later succeeds, recurring.payment_succeeded is emitted and the schedule advances normally. See the Webhooks documentation for event details.

Create and manage invoices.

List Query Parameters

GET /query/invoice?page=1&pageSize=25&sort=-uniqueID

Supports optional invoice filters:

Returns a single invoice by unique ID. If not found, returns 404.

Note: Provide customer_id to associate with an existing customer. If customer_id is omitted, include a customer object to create a new customer.

{
  "x_login": "...",
  "x_tran_key": "...",
  "invoice": {
    "invoice_number": "INV-2024-001",
    "due_date": "2024-12-31",
    "notes": "Thank you for your business",
    "discount": 0,
    "tax": 10.50,
    "shipping": 5.00,
    "amount": 635.50,
    "customer_id": 123,
    "items": [
      {
        "title": "Web Design",
        "description": "Homepage design",
        "quantity": 1,
        "unit_price": 500.00
      },
      {
        "title": "Hosting",
        "quantity": 12,
        "unit_price": 10.00
      }
    ]
  }
}

{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "invoice": {
    "uniqueID": 456,
    "notes": "Updated notes",
    "status": "Sent"
  }
}

DELETE /query/invoice/456

Manage products and services.

Returns a list of products. If none exist, returns an empty list: { "products": [] } with status 200.

Optional query parameters for GET /query/product:

• page: page number (1-based). When provided, results are paginated.
• pageSize: records per page. Optional; defaults to 50.

List Query Parameters

GET /query/product?page=1&pageSize=25&sort=-uniqueID

Body Parameters

{
  "x_login": "...",
  "x_tran_key": "...",
  "product": {
    "name": "Premium Service",
    "description": "One hour consultation",
    "price": 99.99,
    "isBookable": true,
    "duration": 60,
    "is_recurring": true,
    "recurring_rule": {
      "interval": "1",
      "interval_number": "1",
      "run_limit": "7"
    }
  }
}

Body Parameters

Notes:

- Omit fields you do not want to change.

- When setting is_recurring to false, the recurring schedule is cleared.

{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "product": {
    "name": "Updated Service Name",
    "price": 149.99,
    "isBookable": true,
    "duration": 60,
    "is_recurring": false,
    "recurring_rule": {
      "interval": "1",
      "interval_number": "1",
      "run_limit": "7"
    }
  }
}

Manage discount coupons.

Returns a list of coupons. If none exist, returns an empty list: { "coupons": [] } with status 200.

Optional query parameters for GET /query/coupon:

• page: page number (1-based). When provided, results are paginated.
• pageSize: records per page. Optional; defaults to 50.

List Query Parameters

GET /query/coupon?page=1&pageSize=25&sort=-uniqueID

Create accepts either a nested coupon object or a flat top-level payload. name is required and cannot be blank.

Body Parameters

{
  "x_login": "...",
  "x_tran_key": "...",
  "coupon": {
    "name": "New Customer Discount",
    "description": "10% off first purchase",
    "code": "WELCOME10",
    "percent_off": 10,
    "duration_type": "once",
    "first_purchase_only": true,
    "max_redemptions": 100,
    "enabled": true
  }
}

{
  "x_login": "...",
  "x_tran_key": "...",
  "name": "New Customer Discount",
  "code": "WELCOME10",
  "percent_off": 10,
  "duration_type": "once",
  "first_purchase_only": true,
  "max_redemptions": 100,
  "enabled": true
}

Update accepts either a nested coupon object or a flat top-level payload. uniqueID is optional when calling /query/coupon/{id}, and required for non-path updates.

Body Parameters

{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "coupon": {
    "name": "Updated Coupon Name",
    "percent_off": 15,
    "enabled": true
  }
}

DELETE /query/coupon/123

Manage organizations and look up the merchants that belong to one.

Authentication is different from other endpoints: organizations are scoped by user (the owner and any linked team members), not by merchant. Every call below still authenticates the same way as any other endpoint — either a Bearer token or x_login/x_tran_key — but the gateway resolves it to a user:

• Bearer token — Authorization: Bearer <token> (or token field). The user is read directly from the token's sub claim.
• x_login / x_tran_key — validated as merchant credentials exactly like every other endpoint, then resolved to that merchant's attached user account. That resolved user is who the organization actions run as.

A user can only read or manage organizations they own or belong to. There is no unauthenticated/public route on this endpoint.

{
  "uniqueID": 4,
  "name": "Acme Salons",
  "orgKey": "acme-salons",
  "ownerUserId": 12,
  "notes": "Rolled up under the Acme parent account",
  "enabled": true
}

This shape is returned under organization for create/read/update, and under organizations (as a list) for GET /query/organization.

Returns the organizations the authenticated user owns or belongs to. If none exist, returns an empty list: { "organizations": [] } with status 200.

Optional query parameters for GET /query/organization:

• page: page number (1-based). When provided, results are paginated.
• pageSize: records per page. Optional; defaults to 50.

Returns 404 if the organization doesn't exist, is disabled, or the authenticated user doesn't have access to it.

The authenticated user becomes the organization's owner. System administrator accounts cannot create organizations.

Body Parameters

{
  "x_login": "...",
  "x_tran_key": "...",
  "organization": {
    "name": "Acme Salons",
    "org_key": "acme-salons",
    "notes": "Rolled up under the Acme parent account"
  }
}

Only the organization's owner or an admin member may update it. Omit fields you don't want to change.

Body Parameters

{
  "x_login": "...",
  "x_tran_key": "...",
  "organization": {
    "name": "Acme Salons & Spa",
    "notes": "Updated after the spa line launch"
  }
}

Soft-disables the organization (enabled = false) rather than removing the row, and unlinks every merchant that belonged to it (so they're free to join another organization). Once disabled, it stops appearing in list/lookup results for every user, including the owner. Only the organization's owner or an admin member may delete it.

Looks up an organization by its public org_key and returns the merchant IDs linked to it. Requires the same authentication as every other action above — there is no public/unauthenticated version of this route.

Query Parameters

GET /query/organization/merchants?org_key=acme-salons

{
  "result": "success",
  "merchants": [
    { "merchant_id": 1024 },
    { "merchant_id": 1031 }
  ]
}

Issue and manage cards via the central query handler. Primary-account endpoints require merchant authentication; the cardholder list-cards endpoint uses cardholder credentials in the body.

Two request sections:

• Primary Account: Operates on subaccounts using Primary Account API credentials.
• User: Cardholder actions using Primary Account API credentials, plus cardholder username/password in body.

Primary Account Endpoints

Optional filters: search, type (virtual|physical), status.

GET /query/expicard

Returns full details (including PAN/CVC) for authorized merchant/enhanced users. The response includes card.id (the requested card ID) and card.token (partner token).

GET /query/expicard?uniqueID=CARD-12345

Lightweight, cached card summary without sensitive details; falls back to full read if unavailable. Includes card.id (requested card ID) and card.token (partner token).

GET /query/expicard?subaction=summary&uniqueID=CARD-12345

Body fields: first_name, last_name, email, amount, address_line1, city, state, zip, type (virtual|physical), cardholder_type (team_member|vendor|contractor), optional external_id.

{
  "action": "expicard",
  "subaction": "create",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "password": "TempPassword123",
  "amount": 200.00,
  "address_line1": "123 Main St",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "type": "virtual",
  "cardholder_type": "team_member",
  "external_id": "CARD-EXT-001"
}

{
  "action": "expicard",
  "subaction": "fund",
  "uniqueID": "CARD-67890",
  "amount": 50.00
}

Optional filters supported: from, to, status.

GET /query/expicard?subaction=transactions&uniqueID=CARD-12345&from=2025-10-01&to=2025-10-31&status=approved

Creates a funding bank (bank account) for a specific subaccount.

Body fields: subaccountId, bankAccountNumber, bankRoutingNumber. Additional fields may be included per partner requirements.

Note: The query handler lowercases top-level JSON keys. To avoid casing issues, you can send snake_case keys (bank_account_number, bank_routing_number) or nest fields under a bank object.

{
  "action": "expicard",
  "subaction": "subaccount_bank_create",
  "subaccountId": "SUB-123456",
  "bank_account_number": "1234567890",
  "bank_routing_number": "021000021"
}

Note: Sensitive card detail fields are only returned to authorized merchant/enhanced users; summaries are optimized for portal views.

User Endpoints

These endpoints do not require merchant authentication. They use merchant API credentials for partner access internally, but require cardholder username and password in the request body.

Response: Returns full card details for the authenticated cardholder, including sensitive fields such as full card number (PAN), CVC, and expiration. Handle this response securely.

Authentication: You can provide the cardholder username/password either in the body or via HTTP Basic Auth (recommended). When using Basic Auth, the body credentials are optional.

Authorization: Basic <base64(cardholder_username:cardholder_password)>

{
  "action": "expicard",
  "role": "user",
  "subaction": "user_cards",
  "username": "cardholder@example.com",
  "password": "cardholderPassword"
}

Note: User endpoints restrict access to cards linked to the authenticated cardholder; sensitive fields are not returned.