Throttling – Rate Limiting

All Stax API routes are throttled to 200 requests per minute per IP address. You are only allowed 10 failed API requests per minute per IP address. If you hit either of these limits, you will be blocked for one hour.

Stax.js routes are different. When you call the .pay() or the .tokenize() method, Stax.js hits the Stax API with the defined Web Payments token. This resource is throttled to 10 requests per minute per IP address.

Some of the other APIs that Stax offers may be throttled at a lower rate, dependent on the security risk of those APIs.

Note: If you need to process a higher number of requests, or have a use case where you think you may need to bypass these limits, please reach out to the Stax support or partner support team to have your IP address(es) whitelisted, or for more information about throttling.

ACH Transactions

Using Stax, you can accept ACH payments similarly to how you accept credit card payments using Stax.js and the Stax API. However, it is important to understand that ACH may follow a different payment flow once the transaction is made in Stax. ACH transactions may take up to 5 business days to receive the ultimate status of success or failure of payment.

An ACH transaction will always show as successful ("success": true) as long as the transaction passes the initial validations in Stax. Successful ACH transactions will then batch each day at 8 pm EST, at which point they go into a settling state ("is_settling": true). ACH transactions that fail the initial validation will show as a failed payment in Stax immediately at the time of payment. During the next 5 business days, the payment will take one of the two possible paths:

The payment will succeed and make it into a settlement. When the payment succeeds, the settled_at date will populate with the DATETIME of settlement. When this happens, you can expect the funds to be deposited in the merchant bank account within roughly 1-2 business days. (Although rare, if the funding instructions fail, it is possible that the funds will not be paid out on this timeline.)
The ACH rejects, and the payment will fail, resulting in an associated void transaction. When an ACH rejects, the Transaction.child_transactions array will be populated with a void transaction(Transaction.child_transactions[0].type will be "void"). The Transaction.is_voided boolean will also be true and there will be no value in the Transaction.settled_at field.

ACH Rejections

ACH rejections can happen for many reasons, such as a frozen account or insufficient funds. When these rejections occur, you may want to display the rejection information to the customer so they know if they need to contact their bank to resolve an issue or if they made a user error when entering their account information. Remember, this Rejection may happen between 1-5 business days after the transaction occurred. Stax provides ACH rejection information in a transaction voided due to Rejection. When the Transaction.method is "bank" and the Transaction.child_transactions[0].type is "void", the Transaction.child_transactions[0].meta object will contain an achDescription and an achStatus field which you can use to display to your customer if you wish directly.

achStatus will indicate the status of the ACH transaction. (ex. “FAILED”)
achDescription will include both the NACHA reason code as well as the reason’s description as a single string. (ex. “ReasonCode: R03.ReasonDescription: No Account/Unable to Locate Account”)

Testing ACH

You can mimic a successful ACH transaction with the following routing and account number. Any other combination will trigger a fail.

Routing Number: 021000021 Account Number: 9876543210

To simulate a rejection or a clawback at settlement, make a transaction for $730.14, and then utilize the “Simulate Settlements” capability within Stax Pay-> Reports->Deposit Report.

Testing Deposit Reporting

If you plan to implement deposit reporting in your software to understand when deposits are made and to connect them back to the initial transaction, you will use our Deposit Reporting API resource to pull this information from Stax. When you are in a sandbox account and testing this functionality, you must mock the settlement process for a payment to have data to work with. To generate mock data, you can utilize our Simulate Settlements feature in the API Keys App from within Stax. Clicking on Simulate Settlements here will look for any transactions made in the sandbox account and simulate a settlement on those transactions creating the deposit reporting data.

NOTE: Using the Simulate Settlements feature will fire the update_transaction_settled webhook event when transactions have been made before simulation.

Risks of double-crediting when performing ACH refunds

If you initiate a refund to your customer for an ACH payment when the transaction has not yet settled, you run the risk that the initial transaction may not ever settle, in which case, you would have credited the customer for an amount they never paid to you, resulting in a situation of double-crediting. To eliminate this risk, it is recommended to disable refunds until the transaction has officially settled. Once settled, you may refund an ACH transaction using the Refund Transaction API resource without issue.

ACH Specific Webhooks

create_transaction – This webhook event fires for ACH and CC transactions when created. In the case where the transaction’s method is "bank", even if the transaction’s success flag is true, you may want to display these transactions differently since they cannot be refunded or voided for risks of double-crediting and because they still run the risk of failing at some point before funds are disbursed (See section on ACH Transactions above for more information).

update_transaction_settled – This webhook event fires at the point when an ACH transaction either settles or fails. The response will include information on the entire transaction object as well as a boolean (is_transaction_settled) which you can use to easily determine whether the transaction succeeded or failed.

Go to the Webhooks API documentation to set up these webhooks.

Sample POST body response to your target URL for update_transaction_settled event

{
"id": "6f49149d-69a1-48e6-bec5-d63eb5816118", "child_transactions": [], "is_voided": false ... }

Stored Credentials / Recurring Payments

When you first store a customer’s card details after approval and a successful transaction, Stax records the transaction’s details.

On future transactions, the stored card details and previous transaction details are referenced to decrease the chance of a decline. In addition, the reason for the card being stored is also provided (for regular payments, installment plans, recurring, or other reasons).

You must specify who initiated storing card details (merchant or customer). Stax, by default, sends this data based on where the transaction occurred. For example, if the transaction occurred on the customer portal, then the type would be set to CIT or customer-initiated transaction.

Note: If you have your own scheduler or wish to override these settings, See our API for the correct metadata to send.

Credential on File Types

Scheduled: This is for regular payments, like subscriptions or payments split into several parts over time.
Unscheduled: For payments that don’t have a fixed schedule. Types of Future Transactions (MIT or CIT):

MIT (Merchant Initiated Transaction): This is when the merchant starts a transaction without the customer directly involved, like a subscription renewal or recurring transaction.
CIT (Customer Initiated Transaction): This is when the customer is actively involved in the transaction, like buying something from your merchant website.