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 a customer. Transactions are central to recording payments, refunds, voids, and other financial operations.
Transactions can be created using the POST /charge endpoint when processing payments.
Key Concepts and Features
List and Filter All Transactions
You can retrieve all transactions associated with a merchant account. The API allows you to apply query parameters to sort and filter transaction data, enabling you to find specific transactions or analyze transaction history.
Note: An Authentication Token, Active Team, and Enabled Team are required.
Get a Transaction's Information
Retrieve detailed information about a specific transaction using its unique ID. This includes data such as the payment method used, customer details, and any child transactions (e.g., refunds or voids).
Note: An Authentication Token, Active Team, and Enabled Team are required.
Update a Transaction
Update certain details of a transaction that you have created manually. This can be useful for correcting metadata or other information associated with the transaction.
Important Notes:
- This endpoint cannot be used to update transactions created by Stax from paying an invoice or running
POST /charge. - Modifying certain fields, especially within the
metaobject, may affect integrations and displays in receipts, invoices, or third-party integrations like QuickBooks Online.
Note: An Authentication Token, Active Team, and Enabled Team are required.
Email Transaction Receipt
Send an email receipt for a transaction to the associated customer's email on file. You can also send copies to additional email addresses by specifying them in the request.
Note: An Authentication Token, Active Team, and Enabled Team are required.
Send Transaction Receipt by SMS
Send a transaction receipt via SMS (text message) to the customer. This feature must be enabled for your account, and you can specify additional phone numbers to receive copies.
Note: An Authentication Token, Active Team, and Enabled Team are required.
Void or Refund a Transaction
Void or refund a transaction based on its current status:
- Void: Cancels a transaction before it is batched, preventing fees from being assessed. Voids are only possible before the transaction is settled.
- Refund: Returns funds to the customer after a transaction has been batched (settled). Partial refunds are supported, but partial voids are not.
Important Notes:
- Transactions typically batch around 8 pm EST, but this can vary.
- Use the
is_refundableflag on a transaction to determine if it can be refunded. - Partial refunds require specifying the amount in the request body.
Note: An Authentication Token, Active Team, and Enabled Team are required.
Get a Related Transaction
Retrieve child transactions associated with a parent transaction. Child transactions include voids and refunds linked to the original transaction. This helps in tracking the history and changes to a transaction.
Note: An Authentication Token, Active Team, and Enabled Team are required.
Get a Transaction's Funding Instructions
For transactions involving Split Funding (advanced feature), you can fetch the funding instructions provided at the time of the transaction. This includes details on how funds are distributed to multiple accounts.
Requirements:
- Enrollment in the Split Funding feature.
- An Authentication Token, Active Team, and Enabled Team.
Best Practices and Important Notes
Authentication
Ensure you have a valid Authentication Token, Active Team, and Enabled Team for all transaction-related operations.
Voids and Refunds Timing
Be aware of batching times for transactions. Voids must be performed before a transaction is batched, while refunds can only be performed after batching.
Partial Refunds
Specify the amount to refund in the request body for partial refunds. Full refunds can be performed without specifying an amount.
Modifying Transactions
Exercise caution when updating transaction data, especially within the meta object, to avoid unintended consequences in receipts, invoices, and integrations.
Testing Environment
In sandbox accounts, certain behaviors (like refund availability) may differ from production. Transactions may not be refundable until 12 am EST in sandbox environments.
Settlement Tokenization
For card-present transactions, certain features like Settlement Tokenization may affect refund capabilities. Contact support to enable these features if needed.
Error Handling
Implement robust error handling to capture and address issues such as invalid transaction IDs, authorization failures, or validation errors.