Expi API Documentation

Welcome to the Expi API documentation. All endpoints are accessed via the central query handler.

The API is built for quick integration: send JSON requests, receive JSON responses, and keep all payment workflows in one place. Use it to build custom checkout experiences, manage customers, issue invoices, and automate recurring billing with minimal overhead.

If you are new to the platform, start with Authentication, then explore the endpoint sections for the resources you need. Each section highlights core fields and common workflows.

Base URL: https://your-domain.com/query

Authentication

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. These are required for all endpoints that hit the query handler.

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/login — Exchanges an application username/password for a Bearer token.
  • GET /query/me — Returns the current authenticated user and merchant context (requires authentication).
Example: Login (POST /query/login)
{
  "username": "user@example.com",
  "password": "your_password"
}
Example: Me (GET /query/me)
Authorization: Bearer <access_token>
Option 1: Basic Auth (Header)
Authorization: Basic <base64(username:secret_key)>

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

Option 2: Body Parameters
{
  "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.
Security Tips
  • Store secrets in server-side environment variables.
  • Rotate keys regularly and after staff changes.
  • Never log raw credentials in application logs.
Updated 8 days ago

REST API

Streamline Transactions with Expitrans API

Our REST API allows developers to integrate online payment functionalities into their applications. By making API requests, you can process transactions, manage customers, handle subscriptions, and generate invoices programmatically.

How It Works

The API uses JSON format for requests and responses, ensuring seamless communication between your application and our payment gateway. Authentication is required for secure access, and each request must include the necessary credentials.

Our REST API provides several key functionalities:

  • Customers – Create profiles, store billing details, and manage customer data.
  • Invoices – Generate invoices, track status, and collect payments.
  • Products – Define items and pricing used across invoices and recurring.
  • Card Issuing – Issue cards, fund balances, and fetch card activity.
  • Recurring – Automate scheduled billing with flexible intervals.

These endpoints allow businesses to automate payment workflows and enhance their integration capabilities. In the next sections, we’ll provide detailed instructions on how to use each API.

Tokens

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

POST /tokens Create Card Token
Body Parameters
Field Type Required Description
numberstringYes16-digit card number.
monthstringYes2-digit month 01–12.
yearstringYes2-digit year YY.
x_loginstringNoMerchant login (only if not using Authorization header).
x_tran_keystringNoMerchant tran key/secret (only if not using Authorization header).
Create Token Body
{
  "number": "4242424242424242",
  "month": "12",
    "year": "30"
}
Sample Response
{
  "result": "success",
  "token": "tok_..."
}
Updated 8 days ago

Charges

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

GET /charges List Charges
POST /charges Create a Charge
Create Charge Body Parameters
Field Type Required Description
tokenstringConditionalToken from /tokens. Required unless charging with payment_method_id.
payment_method_idnumberConditionalExisting saved payment method id (CustomerDetails). Required unless charging with token. Aliases: x_payment_id, paymentmethodid.
cvcstringConditionalRequired for token-based charges. Provide at charge time (do not store). You can also pass billing.cvc.
amountnumberYesCharge amount.
transtypestringNoDefaults to AUTH_CAPTURE. Use AUTH_ONLY for auth-then-capture flows.
billingobjectNoBilling/contact fields (first_name, last_name, address, city, state, zip, country, phone, email, description).
customer_idnumberNoOptional customer id. When charging with payment_method_id, if provided it must match the payment method’s customer.
save_payment_methodbooleanNoIf true, creates a customer/payment method (if needed) and charges it. Requires token-based charge (raw card data is needed).
use_customer_profilebooleanNoIf true and customer_id is set, instructs the gateway to use the stored customer profile where supported. Auto-enabled for payment_method_id charges.
x_loginstringNoMerchant login (only if not using Authorization header).
x_tran_keystringNoMerchant tran key/secret (only if not using Authorization header).
GET /charges/{id} Retrieve a Charge
PUT /charges/{id} Update a Charge
POST /charges/{id}/capture Capture a Charge
GET /charges/search?q={query} Search Charges
Create Charge (Token) Body
{
    "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"
    }
}
Create Charge (Payment Method) Body
{
  "payment_method_id": 12345,
  "customer_id": 67890,
  "amount": 12.34,
  "transtype": "AUTH_CAPTURE"
}
Create Charge + Save Payment Method
{
  "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"
  }
}
Create Charge (Sample Response)
{
  "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
Field Type Required Description
amountnumberNoOptional capture amount (omit for full capture where supported).
x_loginstringNoMerchant login (only if not using Authorization header).
x_tran_keystringNoMerchant tran key/secret (only if not using Authorization header).
Capture Charge Body
{
  "amount": 12.34
}
Updated 8 days ago

Transactions

Transaction records are backed by the transactions table. A transaction uniqueID 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

GET /query/transaction List Transactions
GET /query/transaction/{id} Retrieve a Transaction
POST /query/transaction Create a Transaction Record
Create Transaction Body Parameters
Field Type Required Description
amountnumberYesTransaction amount.
descriptionstringNoOptional description.
notesstringNoOptional notes.
transtypestring|numberNoDefaults to AuthCapture. Accepts string or numeric code.
statusstring|numberNoNot accepted on create. Always stored as Unprocessed.
statestring|numberNoDefaults to Unknown. Accepts string or numeric code.
sourcestring|numberNoDefaults to Endpoint. Accepts string or numeric code.
transdatestringNoOptional transaction timestamp (if omitted, DB/defaults apply).
invoice_idnumberNoOptional link to an invoice (maps to invoicing_id).
invoiceobjectNoIf provided and invoice_id is omitted, an invoice is created and linked.
items / line_itemsarrayNoOptional line items. Stored on the linked invoice as invoice details. If no invoice context is supplied, an invoice will be created (requires customer_id or enough customer/billing data to create one).
customer_idnumberNoCustomer association. If omitted, a customer record is created from customer or billing/shipping.
customerobjectNoOptional customer payload used to create a customer when customer_id is omitted.
payment_information.methodnumber|stringNoNon-sensitive payment method indicator (ex: CC, echeck, or numeric code).
payment_information.last4stringNoNon-sensitive last 4 digits (stored as provided digits only).
billingobjectNoOptional billing/contact fields (first_name, last_name, address, city, state, zip, country, phone, email).
shippingobjectNoOptional shipping/contact fields (first_name, last_name, address, city, state, zip, country, phone, email).
PUT /query/transaction/{id} Update a Transaction
DELETE /query/transaction/{id} Delete a Transaction
Create Transaction Body
{
    "amount": 12.34,
    "description": "Order #1001",
    "notes": "Recorded from mobile tap-to-pay",
    "transtype": "AuthCapture",
    "state": "Settled",
    "transdate": "2026-01-29 12:34:56",
    "payment_information": {
        "method": "CC",
        "last4": "4242"
    },
    "billing": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "phone": "555-555-5555"
    },
    "items": [
        {"title": "T-Shirt", "quantity": 1, "unit_price": 12.34}
    ]
}
Transaction (Sample Response)
{
  "result": "success",
  "transaction": {
    "uniqueID": 123456,
    "transaction_id": 98765,
        "customer_id": 555,
    "amount": 12.34,
    "currency": "USD",
    "created": "...",
    "description": "Order #1001",
    "notes": "Created by integration",
        "billing": {
            "first_name": "Jane",
            "last_name": "Smith",
            "email": "jane@example.com",
            "phone": "555-555-5555",
            "address": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null
        },
        "shipping": {
            "first_name": null,
            "last_name": null,
            "email": null,
            "phone": null,
            "address": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null
        },
    "payment_information": {
      "method": 16,
      "last4": "4242"
    },
        "invoice": {},
    "invoicing_id": null,
    "reference_id": null,
    "status": "Unprocessed",
    "state": "Unknown",
    "transtype": "AuthCapture",
    "source": "Endpoint"
  }
}
Updated 8 days ago

Refunds

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

POST /refunds Create a Refund
Create Refund Body Parameters
Field Type Required Description
charge_idnumberYesOriginal charge Transaction presentation_id. Alias: transaction_id.
amountnumberYesRefund amount. Must be greater than 0 and not exceed the original charge amount.
notesstringNoOptional notes sent to the gateway.
x_loginstringNoMerchant login (only if not using Authorization header).
x_tran_keystringNoMerchant tran key/secret (only if not using Authorization header).
Create Refund (Body)
{
  "charge_id": 123456,
  "amount": 12.34,
  "notes": "Customer requested refund"
}
Create Refund (Sample Response)
{
  "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"
  }
}
Updated 8 days ago

Customer

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

GET /query/customer Get All Customers
GET /query/customer/{id} Get Single Customer
Sample Response
{
  "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"
      }
    ]
  }
}
POST /query/customer Create Customer
Body Parameters
{
  "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"
    }
  }
}
PUT /query/customer/{id} Update Customer
Update Customer Body
{
  "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
      }
    ]
  }
}
DELETE /query/customer/{id} Delete Customer
Test Customer API Updated 8 days ago

Recurring

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

Required: customer_id, payment_id, and product_id are required to create a recurring schedule.

GET /query/recurring Get All Recurring
GET /query/recurring/{id} Get Single Recurring
POST /query/recurring Create Recurring
Parameters
Field Required Notes
customer_idYesCustomer for the schedule.
payment_idNoStored payment method for the customer. If omitted, uses the customer's default payment method when available; otherwise returns a failed response.
product_idYesCreates the recurring item; amount is product price + surcharge.
intervalNoOverrides product rule: 1=Day, 2=Week, 3=Month, 4=Year.
interval_numberNoOverrides product rule: interval multiplier.
run_untilNo0=Until terminated, 1=Specific date, 2=Fixed count.
run_limitNoRequired when run_until is 2.
end_dateNoRequired when run_until is 1 (YYYY-MM-DD).
run_nextNoNext run date (YYYY-MM-DD); ignored if run_transaction is true.
surchargeNoAdded to product price for total amount.
statusNo1=Active, 2=Completed, 4=Paused, 5=Terminated.
run_transactionNoWhen true, runs immediately and recalculates next run.
Sample Body (Full)
{
  "x_login": "...",
  "x_tran_key": "...",
  "recurring": {
    "customer_id": 123,
    "payment_id": 456,
    "product_id": 111,
    "run_transaction": true,
    "status": 1,
    "interval": 2,
    "interval_number": 1,
    "run_until": 2,
    "run_limit": 12,
    "end_date": null,
    "run_next": "2024-12-01",
    "surcharge": 0.00
  }
}
Sample Body (Override Schedule)
{
  "x_login": "...",
  "x_tran_key": "...",
  "recurring": {
    "customer_id": 123,
    "payment_id": 456,
    "product_id": 111,
    "interval": 2,
    "interval_number": 1,
    "run_until": 2,
    "run_limit": 12,
    "run_next": "2024-12-01",
    "surcharge": 3.50,
    "status": 1
  }
}
PUT /query/recurring/{id} Update Recurring
Parameters
Field Required Description
uniqueIDNoOptional when calling /query/recurring/{id}; otherwise required.
statusNo1=Active, 2=Completed, 4=Paused, 5=Terminated.
intervalNo1=Day, 2=Week, 3=Month, 4=Year.
interval_numberNoNumber of intervals between runs.
run_untilNo0=Until terminated, 1=Specific date, 2=Fixed count.
run_limitNoRequired when run_until is 2 (count).
end_dateNoRequired when run_until is 1 (YYYY-MM-DD).
run_nextNoNext run date (YYYY-MM-DD).
surchargeNoSurcharge amount added to product price.
payment_idNoStored payment method ID.

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

Sample Update Body
{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "recurring": {
    "status": 1,
    "interval": 2,
    "interval_number": 1,
    "run_until": 2,
    "run_limit": 12,
    "run_next": "2024-12-08"
  }
}
DELETE /query/recurring/{id} Delete Recurring
Test Recurring API Updated 8 days ago

Invoice

Create and manage invoices.

GET /query/invoice Get All Invoices

Returns a paginated list of invoices. Supports optional filters:

Filter Description
customer_idLimit to a specific customer
statusInvoice status (e.g., Pending, Sent, Paid)
due_beforeInvoices due before date (YYYY-MM-DD)
due_afterInvoices due after date (YYYY-MM-DD)
GET /query/invoice/{id} Get Single Invoice

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

POST /query/invoice Create Invoice

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

Create Invoice Body
{
  "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
      }
    ]
  }
}
PUT /query/invoice/{id} Update Invoice
Update Invoice Body
{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "invoice": {
    "uniqueID": 456,
    "notes": "Updated notes",
    "status": "Sent"
  }
}
DELETE /query/invoice/{id} Delete Invoice
Delete Example
DELETE /query/invoice/456
Test Invoice API Updated 8 days ago

Products

Manage products and services.

GET /query/product Get All Products

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

GET /query/product/{id} Get Single Product
POST /query/product Create Product
Body Parameters
Field Type Required Description
namestringYesProduct name.
descriptionstringNoProduct description.
pricenumberNoProduct price.
isBookablebooleanNoMarks product as bookable.
durationintegerNoDuration in minutes (for bookable products).
is_recurringbooleanNoEnable recurring schedule; provide recurring_rule when true.
recurring_rule object Conditional Recurring schedule config; required when is_recurring is true.

Format: {"interval":"1","interval_number":"1","run_limit":"7"}.

interval: 1=Day, 2=Week, 3=Month, 4=Year.

interval_number: how many intervals between charges (e.g., 2 with interval=Week means every 2 weeks).

run_limit: number of times to run; omit or use 0 for unlimited.
Create Product Body
{
  "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"
    }
  }
}
PUT /query/product/{id} Update Product
Body Parameters
Field Type Required Description
uniqueIDintegerNoOptional when calling /query/product/{id}; otherwise required.
namestringNoProduct name.
descriptionstringNoProduct description.
pricenumberNoProduct price.
isBookablebooleanNoMarks product as bookable.
durationintegerNoDuration in minutes (for bookable products).
is_recurringbooleanNoEnable recurring schedule; provide recurring_rule when true.
recurring_rule object Conditional Recurring schedule config; required when is_recurring is true.

Format: {"interval":"1","interval_number":"1","run_limit":"7"}.

interval: 1=Day, 2=Week, 3=Month, 4=Year.

interval_number: how many intervals between charges (e.g., 2 with interval=Week means every 2 weeks).

run_limit: number of times to run; omit or use 0 for unlimited.

Notes:

- Omit fields you do not want to change.

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

Update Product Body
{
  "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"
    }
  }
}
Test Product API Updated 8 days ago

Coupons

Manage discount coupons.

GET /query/coupon Get All Coupons

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

GET /query/coupon/{id} Get Single Coupon
GET /query/coupon?code={code} Get Coupon By Code
POST /query/coupon Create Coupon
Body Parameters
Field Type Required Description
namestringYesCoupon name.
descriptionstringNoCoupon description.
codestringNoCoupon code customers enter.
percent_offnumberNoPercent discount (e.g., 10 for 10% off).
duration_typestringNoDiscount duration (e.g., once).
first_purchase_onlybooleanNoOnly apply to the first purchase.
max_redemptionsintegerNoMaximum number of redemptions allowed.
enabledbooleanNoEnable/disable coupon.
Create Coupon Body
{
  "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
  }
}
PUT /query/coupon/{id} Update Coupon
Body Parameters
Field Type Required Description
uniqueIDintegerNoOptional when calling /query/coupon/{id}; otherwise required.
namestringNoCoupon name.
descriptionstringNoCoupon description.
codestringNoCoupon code customers enter.
percent_offnumberNoPercent discount.
duration_typestringNoDiscount duration.
first_purchase_onlybooleanNoOnly apply to the first purchase.
max_redemptionsintegerNoMaximum number of redemptions allowed.
enabledbooleanNoEnable/disable coupon.
Update Coupon Body
{
  "x_login": "...",
  "x_tran_key": "...",
  "_method": "PUT",
  "coupon": {
    "name": "Updated Coupon Name",
    "percent_off": 15,
    "enabled": true
  }
}
DELETE /query/coupon/{id} Delete Coupon
Delete Coupon Example
DELETE /query/coupon/123
Updated 8 days ago

Card Issuing

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
GET /query/expicard List Cards (Primary account)

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

List Cards Example
GET /query/expicard
GET /query/expicard?uniqueID={CARD_ID} Get Card Details (Primary account)

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 Card Details Example
GET /query/expicard?uniqueID=CARD-12345
GET /query/expicard?subaction=summary&uniqueID={CARD_ID} Get Card Summary (Primary account)

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 Card Summary Example
GET /query/expicard?subaction=summary&uniqueID=CARD-12345
POST /query Issue Card (Primary account)

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.

Issue Card Body
{
  "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"
}
POST /query Fund Card (Primary account)
Fund Card Body
{
  "action": "expicard",
  "subaction": "fund",
  "uniqueID": "CARD-67890",
  "amount": 50.00
}
GET /query/expicard?subaction=transactions&uniqueID={CARD_ID} Get Transactions (Primary account)

Optional filters supported: from, to, status.

Transactions Example
GET /query/expicard?subaction=transactions&uniqueID=CARD-12345&from=2025-10-01&to=2025-10-31&status=approved
POST /query Create Funding Bank (Subaccount)

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.

Create Funding Bank Body
{
  "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.

GET /query/expicard?role=user&subaction=user_cards List Cards (User)

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.

User Auth Header
Authorization: Basic <base64(cardholder_username:cardholder_password)>
User Body
{
  "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.

Test Card Issuing API Updated 8 days ago