Refunds

A refund is a reversal of an existing transfer. The Easy API models it as a child transfer (type: "REVERSAL", parent_transfer pointing at the original) created against the original transfer's /reversals collection.

Methods

`createRefund(transferId, body)`

POST /transfer/:id/reversals. Returns ApiResponse<TransferData> — the reversal transfer itself.

// Full refund
await easy.createRefund(transferId, { refund_amount: originalAmount });

// Partial refund
await easy.createRefund(transferId, { refund_amount: 500 });

// With tags for reconciliation
await easy.createRefund(transferId, {
  refund_amount: 500,
  tags: { reason: "shipping_delay", approved_by: "agent_42" },
});

refund_amount is in the smallest currency unit (cents for USD). The API enforces the partial-refund accumulation limit — issuing more than the original captured amount returns 422.

There is no dedicated "list refunds" method. List transfers and filter by type === "REVERSAL" and parent_transfer === originalTransferId, or follow the _links.reversals.href on the parent transfer.

Object shape

The returned TransferData carries:

type: "REVERSAL" — distinguishes it from forward charges.
parent_transfer: string — the ID of the transfer being reversed.
parent_transfer_trace_id: string | null — convenience trace.
amount — the refunded amount in smallest currency units.
state — PENDING initially, transitioning to SUCCEEDED when the funds clear back.
tags — anything you passed in body.tags.

Refer to Transfers for the rest of the field list.

Examples

Refund-on-cancel

async function cancelAndRefund(orderId: string, reason: string) {
  const { data: order } = await easy.getOrder(orderId);
  if (!order.transfer) throw new Error("Order has no captured transfer.");
  return easy.createRefund(order.transfer.id, {
    refund_amount: order.transfer.amount,
    tags: { reason, source: "support_console" },
  });
}

Partial refund driven by a webhook

When you receive a dispute.created event you may want to refund preemptively rather than fight:

async function refundDisputedTransfer(transferId: string) {
  const { data: t } = await easy.getTransfer(transferId);
  return easy.createRefund(transferId, {
    refund_amount: t.amount,
    tags: { reason: "dispute_received" },
  });
}

Reconcile the reversal back to your ledger

const reversal = await easy.createRefund(transferId, { refund_amount: 250 });
console.log({
  original: reversal.data.parent_transfer,
  reversal: reversal.data.id,
  state: reversal.data.state,
});