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/mfaresend — Starts a replacement challenge for the method in mfa_token and returns a replacement token.
• POST /query/auth/mfarecovery — Requires an SMS mfa_token plus password re-entry and starts controlled email recovery.
• 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_method": "sms"
}

{
  "mfa_token": "sms_mfa_token",
  "password": "your_password"
}

{
  "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,
  "cvc": "123",
  "transtype": "AUTH_CAPTURE"
}

{
  "wallet": {
    "type": "apple_pay",
    "payment_data": {
      "version": "EC_v1",
      "data": "...",
      "signature": "...",
      "header": {
        "ephemeralPublicKey": "...",
        "publicKeyHash": "...",
        "transactionId": "..."
      }
    }
  },
  "amount": 12.34,
  "billing": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com"
  }
}

{
  "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,
    "payment_method": "card",
    "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_subtotal": 10.09,
    "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}
    ]
}

{
    "amount_total": 12.34,
    "amount_subtotal": 12.34,
    "description": "Guest checkout record",
    "customer_id": null
}

PUT /query/transaction/{id}

{
    "customer_id": null
}

{
  "result": "success",
  "transaction": {
    "uniqueID": 123456,
    "customer_id": 555,
    "coupon_id": 0,
    "recurring_id": 0,
    "amount_total": 12.34,
    "amount_subtotal": 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"
  }
}

Apple Pay lets customers authorize a card payment from a supported Apple device. You can offer it through a hosted checkout page or submit an Apple Pay payment token through POST /charges from your own checkout.

Choose an integration

Custom website setup

1. Send support your merchant account ID, checkout display name, and the fully qualified production and test domains that will show Apple Pay.
2. Support will provide the domain-association file for your integration. Host that exact file at https://<your-domain>/.well-known/apple-developer-merchantid-domain-association. It must be publicly available over HTTPS without authentication or a redirect.
3. Wait for support to confirm that the domain is verified and Apple Pay is enabled before testing a payment.

Merchant validation on the web

Hosted checkout pages handle merchant validation automatically. When Apple Pay JS fires onvalidatemerchant, the page sends the event's validationURL with a short-lived validation token issued by the gateway. The merchant account ID is derived from that signed token and must not be supplied by browser code.

session.onvalidatemerchant = async (event) => {
  const response = await fetch('/applepay/validate-merchant', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      validationURL: event.validationURL,
      validationToken: checkout.applePayValidationToken
    })
  });

  if (!response.ok) {
    session.abort();
    return;
  }

  const merchantSession = await response.json();
  session.completeMerchantValidation(merchantSession);
};

Always use the validationURL supplied by the Apple Pay event. Never expose gateway credentials or construct a validation token in browser code. A merchant session is short-lived and single-use; do not cache or reuse it.

Create a charge

After the customer authorizes the payment, send event.payment.token.paymentData unchanged as wallet.payment_data. The charge amount must match the amount shown in the Apple Pay payment sheet.

{
  "wallet": {
    "type": "apple_pay",
    "payment_data": {
      "version": "EC_v1",
      "data": "...",
      "signature": "...",
      "header": {
        "ephemeralPublicKey": "...",
        "publicKeyHash": "...",
        "transactionId": "..."
      }
    }
  },
  "amount": 12.34,
  "billing": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com"
  }
}

See the Charges documentation for authentication, idempotency, the complete request schema, and response fields.

Requirements and limitations

• Show the Apple Pay button only when the Apple Pay APIs are available and ApplePaySession.canMakePayments() returns true.
• Serve custom checkout pages over HTTPS and follow Apple's current Apple Pay on the Web requirements and button guidelines.
• Treat paymentData as sensitive, single-use payment data. Send it only to the gateway over HTTPS; do not log, alter, decrypt, cache, or reuse it.
• Apple Pay cannot be used with save_payment_method and cannot be initiated from a virtual terminal.
• Refunds, voids, and captures use the standard endpoints and the resulting transaction ID. No Apple Pay token is needed for these follow-up operations.

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"
  }
}

Process Apple Tap to Pay on iPhone transactions through Query. The mobile client sends encrypted ttp_… envelopes; Expitrans decrypts them only to forward the required provider fields. Never decrypt, alter, or log those envelopes in your application.

Authentication: Authorization: Bearer <access_token>, Basic merchant credentials, or x_login and x_tran_key in the request body.

magensaResponse is Magensa's response object and only contains fields supplied by the processor. The client model exposes transactionOutput.authorizedAmount as a string; Magensa can serialize it as either a JSON string or number.

Exchange the identifier returned by Apple's reader APIs for the token used to configure the payment card reader.

Reader token request parameters

{ "paymentCardReaderIdentifier": "reader_01HZXT8C3MGK" }

{
  "result": "success",
  "paymentCardReader": {
    "traceID": "provider-trace-id",
    "customerTransactionID": "reader-token-request-id",
    "transactionUTCTimeStamp": "2026-07-28T16:30:00Z",
    "paymentCardReaderToken": "<reader-token>"
  }
}

customerTransactionID is the sale's stable idempotency key. Reusing it with the same amount after the first attempt returns 409; reusing it with different transaction data returns 422. Treat either result as a reconciliation signal, not a reason to issue a new sale.

EMV sale request parameters

{
  "customerTransactionID": "ttp-sale-01HZXT8C3MGK",
  "transactionInput": { "transactionType": "SALE", "amount": 12.34 },
  "transactionContext": { "customer_id": 12345, "description": "Coffee and pastry" },
  "dataInput": {
    "encryptedData": { "dataType": "AppleTapToPay", "data": "ttp_<encrypted-apple-payment-data>" },
    "tlvList": "ttp_<encrypted-emv-tlv-data>",
    "paymentMode": "EMV",
    "paymentType": "CREDIT"
  },
  "deviceInfo": { "serialNumber": "D123456", "make": "Apple", "model": "iPhone", "nickName": "Front counter" }
}

{
  "result": "success",
  "magensaResponse": {
    "traceID": "provider-trace-id",
    "magTranID": "mag-transaction-id",
    "customerTransactionID": "ttp-sale-01HZXT8C3MGK",
    "transactionUTCTimeStamp": "2026-07-28T16:30:00Z",
    "transactionOutput": { "isTransactionApproved": true, "authorizedAmount": "12.34", "authCode": "A1B2C3", "transactionID": "processor-transaction-id", "transactionStatus": "APPROVED", "transactionMessage": "Approved" },
    "dataOutput": { "panLast4": "4242" }
  },
  "transaction": { "uniqueID": 98765, "presentation_id": 98765 }
}

Keep magTranID for post-sale operations and traceID for provider support. A successful HTTP response is not itself an approval—always check transactionOutput.isTransactionApproved.

Other optional provider fields include additionalResponseData, dataOutput.additionalOutputData, dataOutput.cardID, and the converted or normalized processor responses. Treat card IDs, tokens, issuer data, scripts, and receipts as sensitive.

Use the original sale's magTranID. The reference must identify an approved Tap to Pay sale recorded for the authenticated merchant. transactionInputDetails must contain the Magensa fields required for the original payment; this API validates only that it is an object and forwards it unchanged.

Tip adjustment request parameters

{
  "referenceMagTranID": "mag-transaction-id",
  "tipAmount": 2.50,
  "transactionInputDetails": { "amount": 12.34 }
}

{
  "result": "success",
  "magensaResponse": { "traceID": "provider-trace-id", "magTranID": "mag-tip-adjustment-id", "transactionUTCTimeStamp": "2026-07-28T16:30:00Z", "transactionOutput": { "isTransactionApproved": true, "transactionStatus": "APPROVED", "transactionMessage": "Approved" } },
  "transaction": { "uniqueID": 98765, "tip": 2.50 }
}

Use the original sale's magTranID. This operation is idempotent by referenceMagTranID: retrying the same reference returns 409, and changing its amount returns 422. Include a positive amount only for a partial void; omit it to use the original amount.

Void request parameters

{
  "referenceMagTranID": "mag-transaction-id",
  "amount": 12.34
}

{
  "result": "success",
  "magensaResponse": { "traceID": "provider-trace-id", "magTranID": "mag-void-id", "transactionUTCTimeStamp": "2026-07-28T16:30:00Z", "transactionOutput": { "isTransactionApproved": true, "transactionStatus": "APPROVED", "transactionMessage": "Approved" } },
  "transaction": { "uniqueID": 98766, "reference_id": 98765 }
}

Use the original sale's magTranID. This operation is idempotent by referenceMagTranID: retrying the same reference returns 409, and changing its amount returns 422. Include a positive amount only for a partial refund; omit it to use the original amount.

Refund request parameters

{
  "referenceMagTranID": "mag-transaction-id",
  "amount": 12.34
}

{
  "result": "success",
  "magensaResponse": { "traceID": "provider-trace-id", "magTranID": "mag-refund-id", "transactionUTCTimeStamp": "2026-07-28T16:30:00Z", "transactionOutput": { "isTransactionApproved": true, "authorizedAmount": "12.34", "transactionStatus": "APPROVED", "transactionMessage": "Approved" } },
  "transaction": { "uniqueID": 98767, "reference_id": 98765 }
}

Errors and response handling

Invalid envelopes, missing fields, and unsupported values return the standard failed response. Provider failures include a structured providerError when Magensa returns one.

{
  "result": "failed",
  "message": "Provider declined the transaction",
  "providerError": { "code": "DECLINED", "message": "Provider declined the transaction", "traceID": "provider-trace-id" }
}

Process encrypted MagTek physical-card-reader transactions through Query. These routes use the merchant's server-side Magensa credentials; send the encrypted reader output only. They do not accept Apple Tap to Pay ttp_… envelopes.

Authentication: Authorization: Bearer <access_token>, Basic merchant credentials, or x_login and x_tran_key in the request body.

magensaResponse is Magensa's response object and only contains fields supplied by the processor. The client model exposes transactionOutput.authorizedAmount as a string; Magensa can serialize it as either a JSON string or number.

Checks the configured Magensa physical-reader credentials. There are no operation-specific request fields; when using body credentials, include the authentication fields described above.

{}

{
  "result": "success",
  "magensaResponse": {
    "code": "404",
    "message": "Transaction not found"
  }
}

Magensa documents the provider's 404 for its credential-check transaction (custTranID=0) as a successful authorization check, so it is returned in the success envelope above.

customerTransactionID is the sale idempotency key. Do not reuse it for another sale. If the network result is unknown, call recall before attempting any recovery. The reader ARQC must be an even-length hexadecimal string; it is normalized to uppercase before forwarding.

EMV sale request parameters

{
  "customerTransactionID": "external-sale-01HZXT8C3MGK",
  "transactionInput": { "transactionType": "SALE", "amount": 12.34 },
  "transactionContext": { "description": "Coffee and pastry" },
  "dataInput": {
    "encryptedData": { "dataType": "ARQC", "data": "A1B2C3D4E5F6" },
    "paymentType": "Credit"
  }
}

{
  "result": "success",
  "magensaResponse": {
    "traceID": "provider-trace-id",
    "magTranID": "mag-transaction-id",
    "customerTransactionID": "external-sale-01HZXT8C3MGK",
    "transactionUTCTimeStamp": "2026-07-28T16:30:00Z",
    "transactionOutput": {
      "isTransactionApproved": true,
      "authorizedAmount": "12.34",
      "authCode": "A1B2C3",
      "transactionID": "processor-transaction-id",
      "transactionStatus": "APPROVED",
      "transactionMessage": "Approved",
      "issuerAuthenticationData": "<return-to-reader-when-present>"
    },
    "dataOutput": { "panLast4": "4242" }
  },
  "transaction": { "uniqueID": 98765, "presentation_id": 98765 }
}

For chip flows, return issuerAuthenticationData (and either issuer script template when supplied) to the reader according to the reader integration. Retain magTranID for all post-sale operations and traceID for provider support.

Other optional provider fields include additionalResponseData, dataOutput.additionalOutputData, dataOutput.cardID, and the converted or normalized processor responses. Treat card IDs, tokens, issuer data, scripts, and receipts as sensitive.

Use this after a timeout or disconnected client to retrieve the provider outcome for the original customerTransactionID. It does not submit another charge.

Recall request parameters

{ "customerTransactionID": "external-sale-01HZXT8C3MGK" }

{
  "result": "success",
  "magensaResponse": {
    "traceID": "provider-trace-id",
    "magTranID": "mag-transaction-id",
    "customerTransactionID": "external-sale-01HZXT8C3MGK",
    "transactionUTCTimeStamp": "2026-07-28T16:30:00Z",
    "transactionOutput": { "isTransactionApproved": true, "authorizedAmount": "12.34", "transactionStatus": "APPROVED", "transactionMessage": "Approved" }
  }
}

Use the sale response's magTranID as referenceMagTranID. transactionInputDetails must contain the Magensa fields required for the original payment; this API validates only that it is an object and forwards it unchanged.

Tip adjustment request parameters

{
  "referenceMagTranID": "mag-transaction-id",
  "tipAmount": 2.50,
  "transactionInputDetails": { "amount": 12.34 }
}

{
  "result": "success",
  "magensaResponse": { "traceID": "provider-trace-id", "magTranID": "mag-tip-adjustment-id", "transactionUTCTimeStamp": "2026-07-28T16:30:00Z", "transactionOutput": { "isTransactionApproved": true, "transactionStatus": "APPROVED", "transactionMessage": "Approved" } },
  "transaction": { "uniqueID": 98765, "tip": 2.50 }
}

Use the original sale's magTranID. Only an approved, not-yet-voided External Reader sale can be voided. A declined, unapproved, or already-voided sale returns 422 without sending a request to Magensa. If the gateway cannot verify the sale's local void history, it returns 503 and does not submit the void. Include a positive amount for a partial void; omit it when Magensa should use the original transaction amount. A concurrent repeat may return 409; a repeat after a successful void returns 422.

Void request parameters

{
  "referenceMagTranID": "mag-transaction-id",
  "amount": 12.34
}

{
  "result": "success",
  "magensaResponse": { "traceID": "provider-trace-id", "magTranID": "mag-void-id", "transactionUTCTimeStamp": "2026-07-28T16:30:00Z", "transactionOutput": { "isTransactionApproved": true, "transactionStatus": "APPROVED", "transactionMessage": "Approved" } },
  "transaction": { "uniqueID": 98766, "reference_id": 98765 }
}

Use the original sale's magTranID and a new customerTransactionID for this refund. The refund ID is its idempotency key; reuse it only to retry this exact refund. Include a positive amount for a partial refund, or omit it to use the original transaction amount.

Refund request parameters

{
  "referenceMagTranID": "mag-transaction-id",
  "customerTransactionID": "external-refund-01HZXT8C3MGK",
  "amount": 12.34
}

{
  "result": "success",
  "magensaResponse": { "traceID": "provider-trace-id", "magTranID": "mag-refund-id", "transactionUTCTimeStamp": "2026-07-28T16:30:00Z", "transactionOutput": { "isTransactionApproved": true, "authorizedAmount": "12.34", "transactionStatus": "APPROVED", "transactionMessage": "Approved" } },
  "transaction": { "uniqueID": 98767, "reference_id": 98765 }
}

Errors and response handling

A provider rejection or transport error uses the standard failure envelope. The provider's HTTP status is preserved where possible.

{
  "result": "failed",
  "message": "Provider declined the transaction",
  "providerError": { "code": "DECLINED", "message": "Provider declined the transaction", "traceID": "provider-trace-id" }
}

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"
    }
  }
}

Deposits (payouts) made to your account. Payouts are pulled from the same backend as the Payouts page of the dashboard, so only merchants with a MID configured on their account can use this endpoint. List-only: there is no single-payout lookup by id, and payouts have no accept/challenge-style response workflow.

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 Payouts Query Parameters

{
  "result": "success",
  "payouts": [
    {
      "uniqueID": 91234,
      "deposit_date": "2026-08-01",
      "amount": 1542.30,
      "routing_number": "****6789"
    }
  ],
  "pageCount": 3,
  "totalCount": 58
}

Payout Object Fields

Fields are included only when the upstream system provides them.

HTTP Status Codes

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-11-19 00:00:00",
    "run_last": "2026-10-19 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-20260919215931",
    "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-20260919215931",
    "run_next": "2026-10-19",
    "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-20260919215931",
    "interval": 2,
    "interval_number": 1,
    "run_until": 1,
    "end_date": "2027-03-19"
  }
}

{
  "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-10-26"
  }
}

Failed Payment Behavior

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

• 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, once per day, until the payment succeeds or the retry limit below is reached.
• Retry limit: after 3 consecutive failed attempts for the same billing date, the schedule is automatically set to 4 (Paused) and stops retrying. A manual run via the recurring detail page also counts toward this limit.
• A successful payment resets the consecutive-failure count back to 0.
• To resume a schedule that was auto-paused, update its status back to 1 (Active) via the update endpoint (after fixing the underlying issue, for example updating payment_id to a valid stored payment method). Reactivating resets the failure count, so the schedule gets a fresh 3 attempts.
• 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. When the retry limit is reached, a recurring.paused event is emitted in addition to that attempt's recurring.payment_failed event. 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.

Item Fields

{
  "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
      },
      {
        "title": "Haircut Appointment",
        "quantity": 1,
        "unit_price": 30.00,
        "booking_id": "uuid"
      }
    ]
  }
}

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