The Transaction API property status allows you to determine the status of a transaction. The status can be:

• SUCCESS
• FAILED
• PENDING

The PENDING state applies to all transaction types: charge, pre-auth, capture, refund, void, or credit. Developers can retrieve a transaction to view the status using the Transaction APIs. Using the webhook update_transaction you can be notified of updates on a transaction’s status.

The SUCCESS and FAILED statuses indicate whether the transaction was a success or a failure. The PENDING status is used when Stax cannot receive a response from the gateway. This typically occurs in the rare scenario of a gateway or other third-party system outage.

Transactions with this status always have a Gateway Unreachable error message (API property named message).

To prevent these transactions from having a PENDING status indefinitely, Stax has an automated process that will attempt to fetch the final status from the gateway and update the transactions. This process will run continuously until a final status is found or three hours have elapsed since the transaction was created.

Note: If the transaction never made it to the gateway, it is possible that a final status will not be found.

Testing

Pending to Successful

Any transaction made on a test gateway for $763.64 will result in a transaction with a PENDING status and a message Gateway Unreachable error.

Transactions for $763.64 will successfully reach the gateway and consequently be automatically updated with a final status by the automated update process.

Pending indefinitely

Transactions made on a test gateway for a total of $763.63 will result in a transaction with a PENDING status and a Gateway Unreachable error. These transactions will not be sent to the gateway and, consequently, will not be successfully updated with a final status by the automated update process.

The transaction will remain in the PENDING state indefinitely.

Error Handling

With transactions with a PENDING status, your application and error handling for the customer or payer should account for this use case. Since the transaction status is unknown at the time of payment, it is not suggested for the payer to attempt a new payment for the risk of a duplicate transaction.

See idempotency for more details on how to mitigate duplicate charges.

If your software detects a PENDING status, the software should poll those transactions for a final state until a final state is determined.

Below is an image demonstrating how developers, product teams, and partners can handle these Gateway Error/PENDING cases at the time of payment in their payment forms: