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

# Transactions

> Record and manage financial transactions

Transactions represent financial operations that need to be tracked for compliance purposes.

## Creating Transactions

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    import { Currency } from "@artu-ai/compliance-sdk";

    const transaction = await sdk.transactions.create({
      amount: 50000,
      currency: Currency.MXN,
      timestamp: new Date(),
      relatedClientIds: ["client_abc123"],
    });
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    import { Currency } from "@artu-ai/compliance-sdk";

    const transaction = await sdk.transactions.create({
      amount: 50000,
      currency: Currency.MXN,
      timestamp: new Date(),
      relatedClientIds: ["client_abc123"],
    });
    ```
  </Tab>

  <Tab title="Mexico AVI">
    With an AVI-scoped SDK, virtual asset fields are flattened to root level:

    ```typescript theme={null}
    import { Currency } from "@artu-ai/compliance-sdk";
    import { Enums } from "@artu-ai/compliance-sdk/mx/av/avi";

    const { TipoOperacion } = Enums;

    const transaction = await sdk.transactions.create({
      amount: 50000,
      currency: Currency.MXN,
      timestamp: new Date(),
      relatedClientIds: ["client_abc123"],
      operationType: TipoOperacion.Buy,
      crypto: "BTC",
      cryptoAmount: 0.5,
      cryptoExchangeRate: "100000",
      hash: "abc123def456...",
    });
    ```
  </Tab>

  <Tab title="Mexico JYS">
    With a JYS-scoped SDK, gaming/lottery fields are flattened to root level:

    ```typescript theme={null}
    import { Currency } from "@artu-ai/compliance-sdk";
    import { Enums } from "@artu-ai/compliance-sdk/mx/av/jys";

    const {
      TipoOperacion,
      LineaNegocio,
      MedioOperacion,
      TipoLiquidacion,
      TipoSucursal,
    } = Enums;

    const transaction = await sdk.transactions.create({
      amount: 100000,
      currency: Currency.MXN,
      timestamp: new Date(),
      relatedClientIds: ["client_abc123"],
      operationType: TipoOperacion.TicketSale,
      businessLine: LineaNegocio.Lotteries,
      operationMethod: MedioOperacion.InPerson,
      settlementType: TipoLiquidacion.Cash,
      branchInformation: {
        type: TipoSucursal.Own,
        postalCode: "06600",
      },
    });
    ```
  </Tab>

  <Tab title="Mexico TSC">
    With a TSC-scoped SDK, card transaction fields are flattened to root level:

    ```typescript theme={null}
    import { Currency } from "@artu-ai/compliance-sdk";
    import { Enums } from "@artu-ai/compliance-sdk/mx/av/tsc";

    const { TipoTarjeta, TipoOperacion } = Enums;

    const transaction = await sdk.transactions.create({
      amount: 10000,
      currency: Currency.MXN,
      timestamp: new Date(),
      relatedClientIds: ["client_abc123"],
      cardType: TipoTarjeta.CreditCard,
      idNumber: "4111111111111111",
      operationType: TipoOperacion.CardConsumption,
    });
    ```
  </Tab>
</Tabs>

## Accessing Transaction Properties

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    const txn = await sdk.transactions.retrieve("txn_xyz789");

    console.log(txn.id);              // "txn_xyz789"
    console.log(txn.amount);          // 50000
    console.log(txn.currency);        // "MXN"
    console.log(txn.formattedAmount); // "$50,000.00 MXN"
    console.log(txn.status);          // "completed"
    console.log(txn.isCompleted);     // true
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    const txn = await sdk.transactions.retrieve("txn_xyz789");

    console.log(txn.isActividadVulnerable); // true
    console.log(txn.activityCodes);         // ["AVI"]
    console.log(txn.hasActivity("AVI"));    // true
    ```
  </Tab>

  <Tab title="Mexico AVI">
    ```typescript theme={null}
    const txn = await sdk.transactions.retrieve("txn_xyz789");

    console.log(txn.operationType);      // "buy"
    console.log(txn.crypto);             // "BTC"
    console.log(txn.cryptoAmount);       // 0.5
    console.log(txn.cryptoExchangeRate); // "100000"
    console.log(txn.hash);               // "abc123..."
    ```
  </Tab>

  <Tab title="Mexico JYS">
    ```typescript theme={null}
    const txn = await sdk.transactions.retrieve("txn_xyz789");

    console.log(txn.operationType);     // "101"
    console.log(txn.businessLine);      // "9"
    console.log(txn.settlementType);    // "cash"
    console.log(txn.isCashSettlement);  // true
    console.log(txn.branchPostalCode);  // "06600"
    ```
  </Tab>

  <Tab title="Mexico TSC">
    ```typescript theme={null}
    const txn = await sdk.transactions.retrieve("txn_xyz789");

    console.log(txn.cardType);      // "2"
    console.log(txn.idNumber);      // "4111111111111111"
    console.log(txn.operationType); // "211"
    console.log(txn.isCreditCard);  // true
    ```
  </Tab>
</Tabs>

Need to search by your own IDs or metadata? Use `retrieveByExternalId` or `retrieveByMetadata` (see [SDK reference](/sdk/resources)).

## Client Roles

When linking clients, you can specify their role:

| Role           | Description                  |
| -------------- | ---------------------------- |
| `originator`   | Transaction initiator        |
| `beneficiary`  | Transaction recipient        |
| `intermediary` | Intermediary party           |
| `guarantor`    | Guarantor of the transaction |

```typescript theme={null}
// Link originator
await sdk.transactions.linkClient(txnId, originatorId, "originator");

// Link beneficiary
await sdk.transactions.linkClient(txnId, beneficiaryId, "beneficiary");
```

## Updating Transactions

```typescript theme={null}
const updated = await sdk.transactions.update("txn_xyz789", {
  metadata: {
    reference: "INV-2024-001",
    category: "payment",
  },
});
```

## Listing Transactions

### Basic List

```typescript theme={null}
const { data, pagination } = await sdk.transactions.list({
  limit: 50,
});
```

### With Filtering

```typescript theme={null}
import { dateRange, atLeast } from "@artu-ai/compliance-sdk";

const { data } = await sdk.transactions.list({
  filter: {
    amount: atLeast(10000),
    createdAt: dateRange(new Date("2024-01-01"), new Date("2024-12-31")),
  },
});
```

### By Client

```typescript theme={null}
const { data } = await sdk.transactions.listByClient("client_abc123");
```

### Async Iterator

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    for await (const txn of sdk.transactions.iterate()) {
      console.log(txn.id, txn.amount);
    }
    ```
  </Tab>

  <Tab title="Mexico AVI">
    ```typescript theme={null}
    // Iterates MexAVITransaction instances
    for await (const txn of sdk.transactions.iterate()) {
      console.log(txn.operationType, txn.crypto);
    }
    ```
  </Tab>

  <Tab title="Mexico JYS">
    ```typescript theme={null}
    // Iterates MexJYSTransaction instances
    for await (const txn of sdk.transactions.iterate()) {
      console.log(txn.businessLine, txn.settlementType);
    }
    ```
  </Tab>

  <Tab title="Mexico TSC">
    ```typescript theme={null}
    // Iterates MexTSCTransaction instances
    for await (const txn of sdk.transactions.iterate()) {
      console.log(txn.cardType, txn.idNumber);
    }
    ```
  </Tab>
</Tabs>

## Deleting Transactions

```typescript theme={null}
await sdk.transactions.delete("txn_xyz789");
```

## Transaction Model Properties

<Tabs>
  <Tab title="Base">
    | Property           | Type                  | Description           |
    | ------------------ | --------------------- | --------------------- |
    | `id`               | `string`              | Unique identifier     |
    | `amount`           | `number`              | Transaction amount    |
    | `currency`         | `Currency`            | Currency code         |
    | `formattedAmount`  | `string`              | Formatted amount      |
    | `timestamp`        | `Date`                | Transaction timestamp |
    | `status`           | `TransactionStatus`   | Transaction status    |
    | `isCompleted`      | `boolean`             | Is completed          |
    | `isPending`        | `boolean`             | Is pending            |
    | `relatedClientIds` | `string[]`            | Linked client IDs     |
    | `description`      | `string \| undefined` | Description           |
    | `externalId`       | `string \| undefined` | Your system's ID      |
    | `metadata`         | `object \| undefined` | Custom metadata       |
    | `createdAt`        | `Date`                | Creation timestamp    |
    | `updatedAt`        | `Date`                | Last update timestamp |
  </Tab>

  <Tab title="Mexico">
    Includes all base properties plus:

    | Property                | Type       | Description                  |
    | ----------------------- | ---------- | ---------------------------- |
    | `isActividadVulnerable` | `boolean`  | Has vulnerable activity data |
    | `activityCodes`         | `string[]` | Activity codes (AVI/JYS/TSC) |
  </Tab>

  <Tab title="Mexico AVI">
    Includes all Mexico properties plus:

    | Property             | Type                  | Description            |
    | -------------------- | --------------------- | ---------------------- |
    | `operationType`      | `string`              | Operation type         |
    | `crypto`             | `string \| undefined` | Cryptocurrency code    |
    | `cryptoAmount`       | `number \| undefined` | Crypto amount          |
    | `cryptoExchangeRate` | `string \| undefined` | Exchange rate to MXN   |
    | `cryptoDescription`  | `string \| undefined` | Asset description      |
    | `hash`               | `string \| undefined` | Blockchain tx hash     |
    | `monetaryInstrument` | `string \| undefined` | For deposit/withdrawal |
  </Tab>

  <Tab title="Mexico JYS">
    Includes all Mexico properties plus:

    | Property             | Type                  | Description           |
    | -------------------- | --------------------- | --------------------- |
    | `operationType`      | `string \| undefined` | Operation type        |
    | `businessLine`       | `string \| undefined` | Business line         |
    | `operationMethod`    | `string \| undefined` | Operation method      |
    | `settlementType`     | `string \| undefined` | Settlement type       |
    | `isCashSettlement`   | `boolean`             | Is cash settlement    |
    | `isInKindSettlement` | `boolean`             | Is in-kind settlement |
    | `monetaryInstrument` | `string \| undefined` | Monetary instrument   |
    | `branchInfo`         | `object \| undefined` | Branch information    |
    | `branchPostalCode`   | `string \| undefined` | Branch postal code    |
    | `isOperatorBranch`   | `boolean`             | Is operator branch    |
  </Tab>

  <Tab title="Mexico TSC">
    Includes all Mexico properties plus:

    | Property        | Type                  | Description     |
    | --------------- | --------------------- | --------------- |
    | `cardType`      | `string \| undefined` | Card type       |
    | `idNumber`      | `string \| undefined` | Card/account ID |
    | `operationType` | `string \| undefined` | Operation type  |
    | `isServiceCard` | `boolean`             | Is service card |
    | `isCreditCard`  | `boolean`             | Is credit card  |
  </Tab>
</Tabs>

## Managing Related Clients

### Link a Client

```typescript theme={null}
await sdk.transactions.linkClient(txnId, clientId, "originator");
```

### Unlink a Client

```typescript theme={null}
await sdk.transactions.unlinkClient(txnId, clientId);
```

### Replace All Clients

```typescript theme={null}
await sdk.transactions.setClients(txnId, [
  { clientId: "client_a", role: "originator" },
  { clientId: "client_b", role: "beneficiary" },
]);
```

## Batch Operations

Create multiple transactions in one request:

```typescript theme={null}
const result = await sdk.transactions.createMany([
  { amount: 10000, currency: Currency.MXN, ... },
  { amount: 25000, currency: Currency.MXN, ... },
]);

if (result.atomic) {
  console.log("All transactions created:", result.data.length);
}
```

<Info>See [Batch Operations](/guides/batch-operations) for more details.</Info>