---
name: natural-get-transaction
description: Get the status and details of a transaction on the Natural platform. Use when you need to verify a payment was processed, check its current status, or retrieve transaction details.
metadata:
  author: Natural
  version: "1.0"
---

# Get Transaction

Retrieve the status and details of a transaction on the Natural platform.

## Prerequisites

- A valid API key (`sk_*`) is configured
- You have a `transactionId` (`txn_xxx`)
- You have the `customerPartyId` (`pty_xxx`) that the transaction belongs to

## Workflow

### 1. Retrieve transaction

Fetch the transaction using the `transactionId` and `customerPartyId`.

**Important:** Always pass the `customerPartyId` that was used when the transaction was created — the transaction is scoped to the customer's party. Omitting it will result in a 404.

### 2. Interpret status

| Status          | Meaning                                   |
| --------------- | ----------------------------------------- |
| `PROCESSING`    | Payment is being processed                |
| `COMPLETED`     | Payment delivered                         |
| `PENDING_CLAIM` | Recipient has not yet claimed the payment |
| `IN_REVIEW`     | Payment held for review (escalation)      |
| `FAILED`        | Payment failed                            |

### 3. Handle special statuses

- **`IN_REVIEW`:** The payment requires manual approval in the dashboard. Do not retry — inform the user and provide the `transactionId`.
- **`PENDING_CLAIM`:** The recipient needs to claim the payment before Natural can bind their wallet. The `claimLink` is available via MCP but not currently exposed in CLI JSON output.
- **`FAILED`:** Check the error details and determine if the payment should be retried (with the same `idempotencyKey`).

## Error handling

- **404 Not Found:** Either the `transactionId` is wrong or the `customerPartyId` doesn't match — verify both values
- **Auth error:** API key is missing, invalid, or lacks permission — check credentials
- **Network/server error:** Retry the request

---

## CLI Adapter

Execute the get-transaction workflow using the `natural` CLI. All commands should use `--format json` for structured output that agents can parse.

### Command

```bash
natural transactions get --transaction-id txn_xxx --party-id pty_xxx --format json
```

For delegated transactions, pass the customer's `pty_*` as `--party-id`. The flag is named after the API's `partyId` query parameter; it is the same customer party ID used when the transaction was created.

Response shape:

```json
{
  "transactionId": "txn_xxx",
  "status": "COMPLETED",
  "amount": 5000,
  "currency": "USD",
  "memo": "Invoice #789",
  "transactionType": "PAYMENT",
  "category": "payment",
  "direction": "OUTBOUND",
  "isDelegated": true,
  "customerName": "John Doe",
  "senderName": "John Doe",
  "recipientName": "bob@example.com",
  "sourcePartyId": "pty_xxx",
  "destinationPartyId": "pty_yyy",
  "createdAt": "2026-04-03T12:00:00Z",
  "updatedAt": "2026-04-03T12:01:00Z"
}
```

Note: `claimLink` is not included in CLI JSON output. Use the MCP adapter if claim-link handling is required.

### Exit codes

| Code | Meaning                                    | Action                           |
| ---- | ------------------------------------------ | -------------------------------- |
| 0    | Success                                    | Parse JSON response              |
| 1    | Business error (not found, wrong customer) | Read error message, do not retry |
| 3    | Auth error (missing or invalid API key)    | Check credentials                |
| 4    | Network/server error (timeout, rate limit) | Retry                            |

### Notes

- Always pass `--format json` — human-formatted output is not designed for agent parsing
- Amounts are always minor units (cents) in output
- Pass the format flag explicitly for clarity, even when stdout is piped

---

## MCP Adapter

Execute the get-transaction workflow using Natural MCP server tools. The MCP server authenticates via Bearer token in the session.

### Tool

Tool: `get_payment_status`

```json
{
  "transactionId": "txn_xxx",
  "customerPartyId": "pty_xxx"
}
```

Always pass the same `customerPartyId` used when the payment was created — the transaction is scoped to the customer's party.

Full transaction object is returned, including `claimLink` if present for `PENDING_CLAIM` status.

### Error handling

MCP tool errors are returned as tool call failures with an error message. Categorize by the message content:

- Authentication errors: API key issues
- Not found: wrong `transactionId` or `customerPartyId` mismatch
- Server errors: retry the request