# Transaction Lifecycle & Status Codes

<figure><img src="https://1759075701-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIS9AkCawNWrhCXwEyUbh%2Fuploads%2FOgmHAPtT5nzsLmavRnqf%2Fmedium.png?alt=media&#x26;token=0f8a4ca4-c1dc-4c0b-a09b-0b71576f08e4" alt=""><figcaption></figcaption></figure>

***

#### Supported Transaction Types

The API supports the following transaction types:

| Transaction Type        | Description                                                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Sale**                | A combined authorization and capture of funds in a single step.                                                              |
| **Pre-Authorization**   | Authorization only, holds funds without capture.                                                                             |
| **Force Authorization** | Capture with an authorization code. Used in exceptional cases.                                                               |
| **Return**              | Refund or credit applied to a settled transaction.                                                                           |
| **Repeat Sale**         | A repeat sale transaction that uses a previously stored token to charge the customer again without re-entering payment data. |

*Note:* Recurring payment processing is handled via a separate recurring payments API and is not part of these transaction types.

***

#### Transaction Status Values

The **transactionStatus** field in API responses can hold the following documented values:

| Status       | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| **Approved** | Transaction successfully authorized or captured.              |
| **Declined** | Transaction declined by card issuer or processor.             |
| **Error**    | Processing error due to invalid data or system failure.       |
| **Void**     | Authorization canceled before capture/settlement.             |
| **Refunded** | Amount refunded to the cardholder from a settled transaction. |
| **Pending**  | Transaction awaiting further processing or settlement.        |

***

#### HTTP Response Status Codes

The API uses standard HTTP status codes. The documented ones include:

| Code | Meaning                                                   |
| ---- | --------------------------------------------------------- |
| 200  | Request processed successfully.                           |
| 201  | Resource created successfully (e.g., transaction logged). |
| 400  | Bad request due to invalid or missing parameters.         |
| 401  | Unauthorized: invalid or missing API credentials.         |
| 403  | Forbidden: insufficient permissions.                      |
| 404  | Resource not found.                                       |
| 409  | Conflict, such as duplicate transactions.                 |
| 500  | Internal server error.                                    |

***

#### Key Response Fields

The following fields are included in the API transaction responses relevant to lifecycle and status:

* **transactionId:** Unique identifier for the transaction.
* **transactionType:** One of the documented transaction types above (Sale, Pre-Authorization, etc.).
* **transactionStatus:** Status value from the documented set (Approved, Declined, etc.).
* **responseCode:** Numeric processor or gateway result code.
* **responseText:** Human-readable description of the transaction outcome.
* **authCode:** Issuer authorization code, when applicable.
* **timestamp:** Date and time of the transaction or last status update.

***

#### Best Practices

* Rely primarily on **transactionStatus** and **responseCode** to drive your business logic.
* Log declined and error transactions for troubleshooting and customer support.
* Implement retries only for transient server or network failures, not for declined or error responses caused by invalid payment data or issuer decisions.
* Use **responseText** for user-facing messaging or logging.