Transaction Management

After a payment is captured, you can query its status, issue refunds, or reverse it before settlement — all from your server.

Query Transaction Status

const result = await client.getTransactionStatus({
  orderId: 'order-20240601-001',
})

if (result.success) {
  const { status, amount, currency, transactionRef } = result.data
  console.log(`Order status: ${status} — ${amount} ${currency} (ref: ${transactionRef})`)
} else {
  console.error('Status query failed:', result.error)
}

const result = await client.getTransactionStatus({
  orderId: 'order-20240601-001',
})

if (result.success) {
  const { status, amount, currency, transactionRef } = result.data
  console.log(`Order status: ${status} — ${amount} ${currency} (ref: ${transactionRef})`)
} else {
  console.error('Status query failed:', result.error)
}

Full Refund

const refundResult = await client.refund({
  transactionRef: 'TXN_REF_HERE',
  amount: 19.99,
  currency: 'EUR',
  urlNotify: 'https://mystore.example/api/payment/notify',
})

if (refundResult.success) {
  console.log('Full refund issued')
} else {
  console.error('Refund failed:', refundResult.error)
}

const refundResult = await client.refund({
  transactionRef: 'TXN_REF_HERE',
  amount: 19.99,
  currency: 'EUR',
  urlNotify: 'https://mystore.example/api/payment/notify',
})

if (refundResult.success) {
  console.log('Full refund issued')
} else {
  console.error('Refund failed:', refundResult.error)
}

Partial Refund

Pass a amount less than the original charged amount to issue a partial refund:

const partialRefund = await client.refund({
  transactionRef: 'TXN_REF_HERE',
  amount: 5.00,
  currency: 'EUR',
  urlNotify: 'https://mystore.example/api/payment/notify',
})

if (partialRefund.success) {
  console.log('Partial refund of €5.00 issued')
}

const partialRefund = await client.refund({
  transactionRef: 'TXN_REF_HERE',
  amount: 5.00,
  currency: 'EUR',
  urlNotify: 'https://mystore.example/api/payment/notify',
})

if (partialRefund.success) {
  console.log('Partial refund of €5.00 issued')
}

Reversal (Void Before Settlement)

Reverse a transaction before it settles. This cancels the charge entirely and does not produce a separate refund transaction.

const reversal = await client.reversal({
  transactionRef: 'TXN_REF_HERE',
  urlNotify: 'https://mystore.example/api/payment/notify',
})

if (reversal.success) {
  console.log('Transaction reversed successfully')
} else {
  console.error('Reversal failed:', reversal.error)
}

const reversal = await client.reversal({
  transactionRef: 'TXN_REF_HERE',
  urlNotify: 'https://mystore.example/api/payment/notify',
})

if (reversal.success) {
  console.log('Transaction reversed successfully')
} else {
  console.error('Reversal failed:', reversal.error)
}

Error Handling

Cart and transaction errors are represented by MyPOSCartError:

Error type	When thrown
`MyPOSCartError`	Cart construction or transaction operation failed (e.g., invalid amount, unknown order ID)

import { MyPOSCartError } from 'mypos-online-checkout'

try {
  const result = await client.refund({ /* ... */ })
} catch (err) {
  if (err instanceof MyPOSCartError) {
    console.error('Cart/transaction error:', err.message)
  } else {
    throw err
  }
}

const { MyPOSCartError } = require('mypos-online-checkout')

try {
  const result = await client.refund({ /* ... */ })
} catch (err) {
  if (err instanceof MyPOSCartError) {
    console.error('Cart/transaction error:', err.message)
  } else {
    throw err
  }
}