Refund Tracker

Use the refund_tracker object in the order.updated webhook event to detect whether a refund or partial refund is pending, refunded, cancelled, or failed.

Refund tracker example

The refund_tracker field is returned as an array of refund status records.

"refund_tracker": [
  {
    "id": "9876",
    "rrn": "xxxx RRN Number xxxxx",
    "amount": "202.95",
    "status": "R",
    "gateway_key_type": "RefundReference",
    "gateway_transaction_id": "trx id"
  }
]

💡
Each refund tracker has status identified by P for pending,R for refunded, C for cancelled, and F for failed

Handle refund tracker updates

Use the refund_tracker array in your order.updated handler to process each refund decision and update your internal refund state.

async function handleOrderUpdated(webhook) {
  try {
    const refundTracker = webhook?.data?.refund_tracker;

    if (!Array.isArray(refundTracker)) {
      console.log('No refund tracker records found for this event.');
      return { status: 'ignored' };
    }

    if (refundTracker.length === 0) {
      console.log('Refund tracker is present but empty.');
      return { status: 'empty' };
    }

    for (const record of refundTracker) {
      switch (record.status) {
        case 'R':
          console.log(`Refund completed for tracker ${record.id}: ${record.amount}`);
          break;

        case 'C':
          console.log(`Refund cancelled for tracker ${record.id}`);
          break;

        case 'P':
          console.log(`Refund pending for tracker ${record.id}`);
          break;

        case 'F':
          console.error(`Refund failed for tracker ${record.id}`);
          break;

        default:
          console.warn(`Unknown refund status for tracker ${record.id}: ${record.status}`);
      }
    }

    return { status: 'processed', records: refundTracker.length };
  } catch (error) {
    console.error('Failed to process refund tracker:', error.message);
    return { status: 'error', message: error.message };
  }
}

const webhookPayload = {
  event_type: 'order.updated',
  data: {
    refund_tracker: [
      {
        id: '9876',
        rrn: 'xxxx RRN Number xxxxx',
        amount: '202.95',
        status: 'R',
        gateway_key_type: 'RefundReference',
        gateway_transaction_id: 'trx id'
      },
      {
        id: '9877',
        rrn: 'xxxx RRN Number yyyyy',
        amount: '50.00',
        status: 'P',
        gateway_key_type: 'RefundReference',
        gateway_transaction_id: 'trx id 2'
      }
    ]
  }
};

handleOrderUpdated(webhookPayload).then(result => {
  console.log('Processing result:', result);
});

Expected output:

Refund completed for tracker 9876: 202.95
Refund pending for tracker 9877
Processing result: { status: 'processed', records: 2 }

Field Reference

Field	Type	Description
id	string	Unique identifier for the Amwal refund tracker.
rrn	string	Bank Refund Reference Number returned within the refund tracker record.
amount	string	Refund amount for this tracker record.
status	string	`P` = pending, `R` = Refunded, `C` = Cancelled, and `F` for failed
gateway_key_type	string	Gateway key type returned for the refund tracker record.
gateway_transaction_id	string	Gateway transaction identifier returned for the refund record.