Transactions

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

Creating Transactions

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

import { Currency } from "@artu-ai/compliance-sdk";

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

import { Currency } from "@artu-ai/compliance-sdk";

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

With an AVI-scoped SDK, virtual asset fields are flattened to root level:

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...",
});

With a JYS-scoped SDK, gaming/lottery fields are flattened to root level:

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",
  },
});

With a TSC-scoped SDK, card transaction fields are flattened to root level:

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,
});

Accessing Transaction Properties

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

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

const txn = await sdk.transactions.retrieve("txn_xyz789");

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

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..."

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"

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

Need to search by your own IDs or metadata? Use retrieveByExternalId or retrieveByMetadata (see SDK reference).

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

// Link originator
await sdk.transactions.linkClient(txnId, originatorId, "originator");

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

Updating Transactions

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

Listing Transactions

Basic List

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

With Filtering

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

const { data } = await sdk.transactions.listByClient("client_abc123");

Async Iterator

Base
Mexico AVI
Mexico JYS
Mexico TSC

for await (const txn of sdk.transactions.iterate()) {
  console.log(txn.id, txn.amount);
}

// Iterates MexAVITransaction instances
for await (const txn of sdk.transactions.iterate()) {
  console.log(txn.operationType, txn.crypto);
}

// Iterates MexJYSTransaction instances
for await (const txn of sdk.transactions.iterate()) {
  console.log(txn.businessLine, txn.settlementType);
}

// Iterates MexTSCTransaction instances
for await (const txn of sdk.transactions.iterate()) {
  console.log(txn.cardType, txn.idNumber);
}

Deleting Transactions

await sdk.transactions.delete("txn_xyz789");

Transaction Model Properties

Base
Mexico
Mexico AVI
Mexico JYS
Mexico TSC

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

Includes all base properties plus:

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

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

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

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

Link a Client

await sdk.transactions.linkClient(txnId, clientId, "originator");

Unlink a Client

await sdk.transactions.unlinkClient(txnId, clientId);

Replace All Clients

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

Batch Operations

Create multiple transactions in one request:

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);
}

See Batch Operations for more details.

Getting Started

Core Resources

Patterns

Concepts

Creating Transactions

Accessing Transaction Properties

Client Roles

Updating Transactions

Listing Transactions

Basic List

With Filtering

By Client

Async Iterator

Deleting Transactions

Transaction Model Properties

Link a Client

Unlink a Client

Replace All Clients

Batch Operations

​Creating Transactions

​Accessing Transaction Properties

​Client Roles

​Updating Transactions

​Listing Transactions

​Basic List

​With Filtering

​By Client

​Async Iterator

​Deleting Transactions

​Transaction Model Properties

​Managing Related Clients

​Link a Client

​Unlink a Client

​Replace All Clients

​Batch Operations

Creating Transactions

Accessing Transaction Properties

Client Roles

Updating Transactions

Listing Transactions

Basic List

With Filtering

By Client

Async Iterator

Deleting Transactions

Transaction Model Properties

Managing Related Clients

Link a Client

Unlink a Client

Replace All Clients

Batch Operations