Charge

Initiates a card-present sale (auth + capture) on a paired terminal. The initial synchronous response will often have success = false and a message like terminalservice.waiting while the customer is interacting with the device. Poll GET /terminal/{registerId}/status/{transactionId} (or listen for webhooks, if configured) until the transaction reaches an approved or declined state.

Workflow:

1. POST this endpoint with total, register, optional invoiceId, and meta fields.
2. Terminal wakes and prompts customer to insert, tap, or swipe.
3. (Optional) Signature / additional prompts may fire based on card brand, amount, or merchant configuration.
4. Status endpoint returns approved/declined details; final transaction object will have success = true when approved.

Key Fields:

• total: Decimal amount in dollars; must be >= 0.01; negative values are not allowed.
• meta.lineItems: Array of { price, quantity, item, details } used for receipts & reporting (schema not previously documented).
• printReceipt: One of Merchant|Customer|Both|No; defaults to Both. If the hardware cannot print, receipt is silently skipped.
• paymentType: Currently most terminals default to Credit; Debit, Gift, etc. depend on device/gateway support.
• tokenize: If card-present tokenization feature is enabled and true, Stax will attempt to create a reusable payment method after settlement (see Settlement Tokenization).
• invoiceId: Link the sale to an existing invoice for reporting and partial payments.

Business Rules:

• Pre-authorizations: For variable final amounts, pass pre_auth = true (if supported); capture later via standard transaction endpoints.
• Idempotency: Provide a unique idempotency_id in meta if you need safe retries; duplicate will return original transaction.
• Tips: If supported by device configuration, tip prompts may occur automatically (not defined in schema here).
• Custom Fees: Card-present sales cannot use meta.customFee.

Errors & States:

• 422 validation errors before reaching a gateway (e.g. missing register).
• 400 gateway errors after processing attempt (e.g. decline).
• Cancellation: Customer or merchant cancels; cancelled = true.
• Offline Approval: Terminals may approve offline; final capture occurs at batch close.

Security: Requires ApiKeyAuth or EphemeralAuth. PartnerApiKey may be required for advanced features (e.g. settlement tokenization enablement).

PCI: Raw PAN data never passes through your application; terminal handles encryption.

Polling Recommendation: 1–2s interval, max 30 attempts, then surface a timeout error and instruct merchant to check device.

Receipts: Email/SMS receipts can be triggered using transaction receipt endpoints after approval.