Transactions represent financial activities within the Stax API. A transaction signifies an exchange of money between a merchant and a customer and is associated with a payment_method and customer.
Transactions can be created using the POST /charge endpoint when processing payments.
Core Transaction Operations
List & Filter Transactions
Retrieve all transactions associated with a merchant account with query parameters to sort and filter transaction data.
Requirements: Authentication Token, Active Team, and Enabled Team
Get Transaction Details
Retrieve detailed information about a specific transaction using its unique ID, including payment method, customer details, and child transactions.
Requirements: Authentication Token, Active Team, and Enabled Team
Update Transaction
Update certain details of manually created transactions. Cannot be used for transactions created by Stax from invoices or POST /charge.
Requirements: Authentication Token, Active Team, and Enabled Team
Transaction Communication
Email Receipt
Send an email receipt for a transaction to the customer's email on file, with option to send copies to additional addresses.
Requirements: Authentication Token, Active Team, and Enabled Team
SMS Receipt
Send a transaction receipt via SMS to the customer. Feature must be enabled for your account.
Requirements: Authentication Token, Active Team, and Enabled Team
Transaction Management
Void or Refund a Transaction
Handle transaction reversals based on current status:
- Void: Cancels a transaction before it is batched, preventing fees. Only possible before settlement.
- Refund: Returns funds after a transaction has been batched (settled). Partial refunds supported.
Key Points:
- Transactions typically batch around 8 pm EST
- Use the
is_refundableflag to determine refund eligibility - Partial refunds require specifying amount in request body
- Partial voids are not supported
Requirements: Authentication Token, Active Team, and Enabled Team
Best Practices & Important Notes
Authentication Requirements
Ensure you have a valid Authentication Token, Active Team, and Enabled Team for all transaction-related operations.
Timing Considerations
Voids and Refunds Timing
- Be aware of batching times for transactions
- Voids must be performed before a transaction is batched
- Refunds can only be performed after batching
- In sandbox accounts, transactions may not be refundable until 12 am EST
Settlement Tokenization
- For card-present transactions, certain features may affect refund capabilities
- Contact support to enable these features if needed
Transaction Modifications
Updating Transactions
- Exercise caution when updating transaction data, especially within the
metaobject - Modifications may affect receipts, invoices, and integrations like QuickBooks Online
- Only manually created transactions can be updated
Partial Operations
- Partial refunds: Specify amount in request body
- Full refunds: Can be performed without specifying amount
- Partial voids: Not supported
Error Handling & Testing
Error Handling Implement robust error handling to capture:
- Invalid transaction IDs
- Authorization failures
- Validation errors
Testing Environment
- Sandbox behavior may differ from production
- Certain refund behaviors may be different in testing
- Contact support for feature enablement questions