Transactions - Artu Compliance SDK

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.

​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