> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.paylias.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> A transaction in Paylias represents a finalized commitment to move money

A **Transaction** in the Paylias network is a fundamental ledger record that reflects the complete movement of funds between two partners. It adheres to double-entry accounting principles, meaning every transaction consists of both a **debit** and a **credit** line, ensuring the financial state of all parties remains consistent and auditable.

Transactions are system generated and represent the successful culmination of a payment flow whether initiated via a **push** or **pull** payment.

## Key Characteristics

Every transaction:

* Is linked to a specific payment via its `payment_id`
* Contains one debit and one credit entry in `transaction_lines`
* Records lifecycle timestamps for initiation, processing, and settlement
* Includes optional approval or response codes
* Reflects real-time status updates and error handling through defined enums

## Transaction Fields

| Field               | Type      | Description                                   |
| ------------------- | --------- | --------------------------------------------- |
| `token`             | `string`  | Unique identifier for the transaction         |
| `transaction_id`    | `string`  | External-facing reference for the transaction |
| `payment_id`        | `string`  | ID of the related payment                     |
| `status`            | `enum`    | Lifecycle status of the transaction           |
| `transaction_lines` | `array`   | List of credit/debit entries (see below)      |
| `response_code`     | `string`  | Optional processor response code              |
| `approval_code`     | `string`  | Optional authorization code                   |
| `initiated_on`      | `integer` | Timestamp when the transaction began          |
| `processed_on`      | `integer` | Timestamp when the transaction was processed  |
| `settled_on`        | `integer` | Timestamp when the transaction was settled    |
| `expires_on`        | `integer` | Timestamp when the transaction expires        |
| `created_on`        | `integer` | Timestamp when the transaction was created    |
| `updated_on`        | `integer` | Timestamp of last update                      |

### Transaction Lines

Each transaction line captures a single leg of the ledger entry—either a **debit** or a **credit**. Lines include:

| Field              | Type     | Description                                                |
| ------------------ | -------- | ---------------------------------------------------------- |
| `token`            | `string` | Unique identifier for this transaction line                |
| `transaction_id`   | `string` | Parent transaction                                         |
| `partner_id`       | `string` | ID of the partner associated with this line                |
| `direction`        | `enum`   | Direction of funds (see below)                             |
| `transaction_type` | `enum`   | Type of transaction (e.g., payment, refund)                |
| `amount`           | `object` | Object with `currency` and `total` (amount in minor units) |

### Status Types

| Enum            | Value | Description                           |
| --------------- | ----- | ------------------------------------- |
| `TS_INITIATED`  | 1     | Transaction started                   |
| `TS_PROCESSING` | 2     | Transaction is being processed        |
| `TS_COMPLETED`  | 3     | Successfully completed                |
| `TS_FAILED`     | 4     | Failed to complete                    |
| `TS_REVERSED`   | 5     | Manually or programmatically reversed |
| `TS_EXPIRED`    | 6     | Timed out                             |
| `TS_RECOVERED`  | 7     | Recovered from a failure              |

### Direction Types

| Enum        | Value | Description    |
| ----------- | ----- | -------------- |
| `TD_Credit` | 1     | Funds received |
| `TD_Debit`  | 2     | Funds sent     |

### Transaction Types

| Enum          | Value | Description                |
| ------------- | ----- | -------------------------- |
| `TT_PAYMENT`  | 1     | Normal payment transaction |
| `TT_REFUND`   | 2     | Refund transaction         |
| `TT_REVERSAL` | 3     | Payment reversal           |
| `TT_FEE`      | 4     | Service or platform fee    |

### Retrieve a Transaction

Fetch details of a specific transaction associated with a payment using the [Fetch Transaction](/api-reference/transactions/fetch-tranasction) endpoint.

```bash theme={null}
curl --request GET \
     --url https://sandbox.paylias.xyz/gateway/api/v1/csp/payments/{payment_id}/transactions/{transaction_id} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-paylias-api-key: <API-KEY>' \
     --header 'x-org-id: <Org-ID>' \
     --header 'x-partner-id: <Partner-ID>'
```

#### Response

```json expandable theme={null}
{
  "ok": true,
  "data": {
    "approval_code": "123456",
    "created_on": "2023-08-12T08:55:04Z",
    "initiated_on": "2023-08-12T08:55:04Z",
    "payment_id": "pay_123456789",
    "status": 1,
    "token": "trans_123456789",
    "transaction_id": "transaction_123456789",
    "updated_on": "2023-08-12T08:55:04Z",
    "transaction_lines": [
      {
        "amount": {
          "currency": "USD",
          "total": "10000"
        },
        "direction": "TD_Credit",
        "partner_id": "part_abc123",
        "token": "tline_1",
        "transaction_id": "transaction_123456789",
        "transaction_type": "TT_PAYMENT"
      },
      {
        "amount": {
          "currency": "USD",
          "total": "10000"
        },
        "direction": "TD_Debit",
        "partner_id": "part_xyz456",
        "token": "tline_2",
        "transaction_id": "transaction_123456789",
        "transaction_type": "TT_PAYMENT"
      }
    ]
  }
}
```