Skip to main content

Transactions Service

The Transactions service provides methods for managing payment transactions and sessions.

Methods​

getMany()​

List transactions with pagination.

const transactions = await sdk.transactions.getMany({
  take: 10,
  skip: 0,
  currency: CURRENCY.USD,
});

console.log('Transactions:', transactions.items);
console.log('Total:', transactions.totalCount);

getOne()​

Get a single transaction by ID.

const transaction = await sdk.transactions.getOne({
  id: 'transaction-id',
});

voidOne()​

Void a transaction.

const voided = await sdk.transactions.voidOne({
  id: 'transaction-id',
});

refundOne()​

Refund a transaction (full or partial).

// Full refund
const refunded = await sdk.transactions.refundOne({
  id: 'transaction-id',
});

// Partial refund
const partialRefund = await sdk.transactions.refundOne({
  id: 'transaction-id',
  amount: 1000n, // Refund $10.00
});

syncOne()​

Sync transaction with the payment provider.

const synced = await sdk.transactions.syncOne({
  id: 'transaction-id',
});

Client Sessions​

clientSessions.getBaseConfig()​

Get base configuration for payment sessions.

const config = await sdk.transactions.clientSessions.getBaseConfig({
  transactionProvider: TRANSACTION_PROVIDER.NUVEI,
  merchantTransactionProviderId: 'provider-id', // optional
});

Client Session Payments​

clientSessions.payments.start()​

Start a new payment session.

const session = await sdk.transactions.clientSessions.payments.start({
  transactionProvider: TRANSACTION_PROVIDER.NUVEI,
  merchantTransactionProviderId: 'provider-id', // optional
  data: {
    amount: 10000n,
    currency: CURRENCY.USD,
    merchantInternalCustomerCode: 'customer-123',
    merchantInternalTransactionCode: 'txn-456',
    billing: {
      billingFirstName: 'John',
      billingLastName: 'Doe',
      billingEmail: 'john@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
    storePaymentMethod: false,
  },
});

clientSessions.payments.verify()​

Verify payment completion after frontend processing.

const transaction = await sdk.transactions.clientSessions.payments.verify({
  id: session.id,
  // OR
  token: session.token,
  // OR
  providerCode: session.providerCode,
  // OR
  merchantInternalTransactionCode: 'txn-456',
});

Client Session Payment Method (Add)​

clientSessions.paymentMethod.add.start()​

Start a session to add a payment method without making a payment (for $0 authorization).

const addPmSession = await sdk.transactions.clientSessions.paymentMethod.add.start({
  transactionProvider: TRANSACTION_PROVIDER.NUVEI,
  merchantTransactionProviderId: 'provider-id', // optional
  data: {
    currency: CURRENCY.USD,
    merchantInternalCustomerCode: 'customer-123',
    merchantInternalTransactionCode: `add-pm-${Date.now()}`,
    billing: {
      billingFirstName: 'John',
      billingLastName: 'Doe',
      billingEmail: 'john@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
  },
});

clientSessions.paymentMethod.add.verify()​

Verify the add payment method session completion.

const transaction = await sdk.transactions.clientSessions.paymentMethod.add.verify({
  id: addPmSession.id,
  // OR use token, providerCode, or merchantInternalTransactionCode
});

// Access the stored payment method
console.log('Payment method stored:', transaction.paymentMethod);

clientSessions.getOne()​

Get session details.

const sessionDetails = await sdk.transactions.clientSessions.getOne({
  id: 'session-id',
});

clientSessions.getMany()​

List payment sessions.

const sessions = await sdk.transactions.clientSessions.getMany({
  take: 10,
  skip: 0,
  status: CLIENT_TRANSACTION_SESSION_STATUS.PENDING,
});

Server-Initiated Payments​

payments.ach.initiate()​

Initiate an ACH (bank transfer) transaction on the server.

const achTx = await sdk.transactions.payments.ach.initiate({
  transactionProvider: TRANSACTION_PROVIDER.NUVEI, // or omit and use merchantTransactionProviderId
  merchantTransactionProviderId: 'provider-id', // optional
  data: {
    amount: 5000n,
    currency: CURRENCY.USD,
    merchantInternalCustomerCode: 'cust-1',
    merchantInternalTransactionCode: 'txn-ach-1',
    billing: {
      billingEmail: 'john@example.com',
      billingFirstName: 'John',
      billingLastName: 'Doe',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
    ach: {
      accountNumber: '000123456789',
      routingNumber: '011000015',
    },
    storePaymentMethod: false,
  },
});

payments.paymentMethod.charge()​

Charge using a stored customer payment method.

const pmTx = await sdk.transactions.payments.paymentMethod.charge({
  transactionProvider: TRANSACTION_PROVIDER.NUVEI,
  merchantTransactionProviderId: 'provider-id', // optional
  data: {
    amount: 2500n,
    currency: CURRENCY.USD,
    merchantCustomerPaymentMethodId: 'pm_123',
    merchantInternalCustomerCode: 'cust-1',
    merchantInternalTransactionCode: 'txn-pm-1',
    billing: {
      billingEmail: 'john@example.com',
      billingFirstName: 'John',
      billingLastName: 'Doe',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
  },
});

Examples​

Complete Payment Flow (Client Session)​

// 1. Start session
const session = await sdk.transactions.clientSessions.payments.start({/* ... */});

// 2. Process payment on frontend using session.token

// 3. Verify payment
const transaction = await sdk.transactions.clientSessions.payments.verify({
  id: session.id,
});

if (transaction.status === TRANSACTION_STATUS.SUCCESS) {
  console.log('Payment successful!');
} else {
  console.log('Payment failed');
}

Add Payment Method Flow​

// 1. Start add payment method session
const addPmSession = await sdk.transactions.clientSessions.paymentMethod.add.start({
  transactionProvider: TRANSACTION_PROVIDER.NUVEI,
  data: {
    currency: CURRENCY.USD,
    merchantInternalCustomerCode: 'customer-123',
    merchantInternalTransactionCode: `add-pm-${Date.now()}`,
    billing: {
      billingEmail: 'john@example.com',
      billingFirstName: 'John',
      billingLastName: 'Doe',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
  },
});

// 2. Process on frontend using session.token

// 3. Verify to get stored payment method
const transaction = await sdk.transactions.clientSessions.paymentMethod.add.verify({
  id: addPmSession.id,
});

console.log('Payment method ID:', transaction.paymentMethod?.id);

List Recent Transactions​

const recent = await sdk.transactions.getMany({
  take: 10,
  skip: 0,
  sorting: [{ field: 'createdAt', order: SORT_ORDER.DESC }],
});

Refund Pattern​

// Check transaction status
const transaction = await sdk.transactions.getOne({ id: 'txn-123' });

if (transaction.status === TRANSACTION_STATUS.SUCCESS) {
  // Process refund
  const refund = await sdk.transactions.refundOne({
    id: transaction.id,
    amount: transaction.amount, // Full refund
  });
}

Next Steps​