​
Payments — Node.js SDK

​
Create a transaction

const transaction = await simiz.transactions.create({
  amount: 5000,
  currency: 'XAF',
  payment_method: 'ORANGE_MONEY',
  payer: {
    phone: '237690000000',
    name: 'John Doe',
    email: 'john@example.com',        // optional
  },
  description: 'Order #12345',
  reference: 'ORDER-123',             // your internal reference
  metadata: {                          // custom key-value pairs
    order_id: '123',
    customer_id: 'cust_456',
  },
  callback_url: 'https://your-site.com/webhooks/simiz',
  return_url: 'https://your-site.com/payment/success',
});

console.log(transaction.id);          // tx_xxx
console.log(transaction.status);      // PENDING
console.log(transaction.payment_url); // Payment URL for customer

​
Retrieve a transaction

const transaction = await simiz.transactions.retrieve('tx_xxx');

if (transaction.status === 'COMPLETED') {
  console.log('Payment successful!');
}

​
List transactions

// With filters and pagination
const transactions = await simiz.transactions.list({
  limit: 20,
  status: 'COMPLETED',
  created_after: '2024-01-01',
});

for (const tx of transactions.data) {
  console.log(tx.id, tx.amount);
}

// Automatic pagination (iterates all pages)
for await (const tx of simiz.transactions.list({ limit: 100 })) {
  console.log(tx.id);
}

​
Filter options

ParameterTypeDescription
limitnumberMax items per page (1–100, default 20)
statusstringFilter by status
created_afterstringISO date — only transactions after this date
created_beforestringISO date — only transactions before this date
payment_methodstringFilter by payment method

​
Cancel a transaction

Cancel a pending transaction before the customer confirms: 
const cancelled = await simiz.transactions.cancel('tx_xxx');
console.log(cancelled.status); // CANCELLED
You can only cancel transactions with status PENDING. Once a transaction is PROCESSING or later, it cannot be cancelled.

​
Create a refund

const refund = await simiz.refunds.create({
  transaction_id: 'tx_xxx',
  amount: 2500,           // Partial refund (half of 5000)
  reason: 'Item returned',
});

console.log(refund.id);     // rf_xxx
console.log(refund.status); // PENDING

​
Error handling

import {
  Simiz,
  SimizError,
  APIError,
  AuthenticationError
} from '@simiz/node-sdk';

try {
  const tx = await simiz.transactions.create({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof APIError) {
    console.error(`${error.code}: ${error.message}`);
    console.error('Request ID:', error.requestId);
  } else if (error instanceof SimizError) {
    console.error('Network error:', error.message);
  }
}