> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> A payment is the merchant intent, a transaction is a single provider attempt. One payment can produce multiple transactions when Yuno retries or cascades.

## Payments vs transactions

A **payment** represents the merchant's intent to collect funds. A **transaction** represents a single processing attempt against a provider. One payment can have multiple transactions when Yuno retries or cascades across providers.

```mermaid theme={"theme":{"light":"github-dark","dark":"github-dark"}}
graph LR
    P([Payment]):::payment
    T1[Transaction 1<br/>Provider A<br/>DECLINED]:::declined
    T2[Transaction 2<br/>Provider B<br/>SUCCEEDED]:::succeeded
    P --> T1
    P --> T2

    classDef payment fill:#f4f4f5,stroke:#71717a,color:#09090b
    classDef declined fill:#fff,stroke:#e4e4e7,color:#52525b
    classDef succeeded fill:#eef0fe,stroke:#3e4fe0,color:#09090b
```

## Why multiple transactions

Yuno creates additional transactions in these scenarios:

| Scenario             | Description                                                          |
| -------------------- | -------------------------------------------------------------------- |
| **Provider decline** | Primary provider declines, Yuno retries with a fallback provider     |
| **Provider timeout** | Primary provider does not respond within the configured window       |
| **Cascading rules**  | Your routing configuration specifies retry behavior across providers |
| **Capture**          | A separate transaction records the capture of an authorized payment  |
| **Refund**           | Each refund (full or partial) creates its own transaction            |

## Transaction types

| Type            | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| `AUTHORIZATION` | Reserves funds on the customer's payment instrument           |
| `CAPTURE`       | Transfers previously authorized funds to the merchant         |
| `SALE`          | Combined authorization and capture in one step (auto capture) |
| `REFUND`        | Returns captured funds to the customer                        |
| `VOID`          | Releases an authorization without capturing                   |
| `CANCELLATION`  | Cancels a pending or authorized payment                       |
| `VERIFY`        | Zero amount card verification without charging                |
| `3DS`           | 3D Secure authentication challenge transaction                |

## Transaction statuses

Transaction statuses describe a **single provider attempt**. For the overall payment outcome (which rolls up across every transaction in a payment) see [payment flow](/core-concepts/payment-flow#payment-statuses).

| Status      | Meaning                                           |
| ----------- | ------------------------------------------------- |
| `CREATED`   | Transaction initiated, not yet sent to provider   |
| `PENDING`   | Transaction submitted, awaiting provider response |
| `SUCCEEDED` | Provider confirmed successful processing          |
| `DECLINED`  | Provider or issuer declined the transaction       |
| `REJECTED`  | Transaction blocked by validation or fraud rules  |
| `FAILED`    | Processing error (network issue, provider error)  |
| `CANCELLED` | Transaction cancelled before completion           |
| `EXPIRED`   | Transaction timed out without resolution          |
| `ERROR`     | Unexpected system or provider error               |

## Transaction flows by type

Each transaction type can reach specific statuses. The table below shows every valid outcome per type.

| Transaction type    | Possible statuses                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| **PURCHASE**        | `CREATED` · `SUCCEEDED` · `PENDING` · `CANCELLED` · `EXPIRED` · `DECLINED` · `REJECTED` · `ERROR` |
| **AUTHORIZE**       | `CREATED` · `SUCCEEDED` · `DECLINED` · `ERROR`                                                    |
| **VERIFY**          | `CREATED` · `SUCCEEDED` · `DECLINED` · `ERROR`                                                    |
| **CAPTURE**         | `PENDING` · `DECLINED` · `ERROR`                                                                  |
| **CANCEL**          | `SUCCEEDED`                                                                                       |
| **REFUND**          | `CREATED` · `SUCCEEDED` · `PENDING` · `DECLINED` · `ERROR`                                        |
| **3DS**             | `DECLINED` · `ERROR`                                                                              |
| **CHARGEBACK**      | `CREATED` · `WON` · `PENDING` · `LOST` · `ERROR`                                                  |
| **FRAUD SCREENING** | `CREATED` · `SUCCEEDED` · `PENDING` · `CANCELLED` · `DECLINED` · `ERROR`                          |

### How a purchase flows

The most common type. This shows every path a purchase can take.

<a href="/diagrams/state-and-architecture/purchase-transaction-flow.html" target="_blank" style={{ display: 'block', cursor: 'zoom-in', textDecoration: 'none' }}>
  <iframe src="/diagrams/state-and-architecture/purchase-transaction-flow.html" width="100%" height="450" style={{ border: 'none', borderRadius: '12px', boxShadow: '0 4px 24px rgba(0,0,0,0.08)', pointerEvents: 'none' }} loading="lazy" />
</a>

### How authorize and capture flow

Two step payment: authorize reserves funds, capture transfers them.

<a href="/diagrams/state-and-architecture/authorize-capture-transaction.html" target="_blank" style={{ display: 'block', cursor: 'zoom-in', textDecoration: 'none' }}>
  <iframe src="/diagrams/state-and-architecture/authorize-capture-transaction.html" width="100%" height="450" style={{ border: 'none', borderRadius: '12px', boxShadow: '0 4px 24px rgba(0,0,0,0.08)', pointerEvents: 'none' }} loading="lazy" />
</a>

### How chargebacks flow

<a href="/diagrams/state-and-architecture/chargeback-flow.html" target="_blank" style={{ display: 'block', cursor: 'zoom-in', textDecoration: 'none' }}>
  <iframe src="/diagrams/state-and-architecture/chargeback-flow.html" width="100%" height="450" style={{ border: 'none', borderRadius: '12px', boxShadow: '0 4px 24px rgba(0,0,0,0.08)', pointerEvents: 'none' }} loading="lazy" />
</a>

## View transactions

Retrieve every transaction for a payment.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl --request GET \
  --url https://api-sandbox.y.uno/v1/payments/{payment_id}/transactions \
  --header 'public-api-key: your-public-api-key' \
  --header 'private-secret-key: your-private-secret-key' \
```

Each transaction includes the provider used, the provider's raw response code, and timing. The codes below are illustrative ISO 8583 values. Actual code sets vary by provider:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "transactions": [
    {
      "transaction_id": "txn_001",
      "type": "SALE",
      "status": "DECLINED",
      "provider": "provider_a",
      "provider_response_code": "51",
      "provider_response_message": "Insufficient funds",
      "created_at": "2026-02-28T10:00:00Z"
    },
    {
      "transaction_id": "txn_002",
      "type": "SALE",
      "status": "SUCCEEDED",
      "provider": "provider_b",
      "provider_response_code": "00",
      "provider_response_message": "Approved",
      "created_at": "2026-02-28T10:00:02Z"
    }
  ]
}
```

See the [Transaction object](/api-reference/payments/transaction-object) for the full schema.

<Note>
  `provider_response_code` and `provider_response_message` contain the raw acquirer or issuer response. Useful for debugging declines, but they vary across providers.
</Note>

## Transaction vs payment status

The payment status reflects the **final outcome** across all transactions. If the first transaction is declined but a cascade succeeds, the payment status is `SUCCEEDED` even though one transaction was `DECLINED`.

<Warning>
  Use **payment status** for business logic (order fulfillment, customer notifications). Use transaction level data only for debugging and analytics.
</Warning>

### When to look at transaction-level data

Transaction records answer questions that payment records cannot: *which* provider approved the charge, *which* one declined and with what code, and how long each attempt took. Typical uses:

* **Debugging a cascade.** A payment succeeds on the second try. The transactions list shows which provider failed, the decline reason (`provider_response_message`), and which provider recovered the sale.
* **Reconciling with a specific acquirer.** Finance teams matching settlement reports to one provider filter by the `provider` field on transactions.
* **Analyzing retry health.** Approval rate per provider and average cascade depth come from aggregating transactions, not payments.

## What next

<div className="mdx-card-tiles">
  <CardGroup cols={2}>
    <Card title="Payments" icon="credit-card" href="/core-concepts/payments">
      Create, capture, refund, and cancel with code.
    </Card>

    <Card title="Payment flow" icon="arrows-spin" href="/core-concepts/payment-flow">
      The conceptual lifecycle and status state machine.
    </Card>

    <Card title="Providers" icon="plug" href="/core-concepts/providers">
      How Yuno picks which provider to run each transaction against.
    </Card>

    <Card title="Transaction object" icon="book" href="/api-reference/payments/transaction-object">
      The full transaction schema in the API reference.
    </Card>
  </CardGroup>
</div>