> ## 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"
      }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.