Transfers

A transfer is the money-movement record produced by a charge. Most transfers are created indirectly (by checkout, payInvoice, subscription billing, or captureAuthorization); this resource lets you create raw transfers, list and read them, update tags, and reverse them via refunds.

Methods

`createTransfer(data)`

POST /transfer.

const { data: transfer } = await easy.createTransfer({
  amount: 4999,           // smallest currency unit (cents for USD)
  currency: "USD",
  source: instrumentId,   // payment-instrument ID to debit
  tags: { internal_order_id: "ord_42" },
});

`updateTransfer(transferId, data)`

PATCH /transfer/:id. The body is a free-form Record<string, unknown> — currently used to attach or replace tags.

await easy.updateTransfer(transfer.id, { tags: { fulfilment: "shipped" } });

`getTransfer(transferId)`

GET /transfer/:id.

`getTransfers(params?)`

GET /transfer. Standard pagination.

`createRefund(transferId, body)`

See refunds — under the hood this issues a POST /transfer/:id/reversals and the response is itself a TransferData with type: "REVERSAL".

Object shape

TransferData is the underlying processor record. The fields you'll touch most:

Field	Type	Notes
`id`	`string`	Transfer ID.
`amount` / `amount_requested`	`number`	In smallest currency units.
`currency`	`string`	ISO 4217.
`source` / `destination`	`string` \| `null`	Payment-instrument IDs.
`state`	`TransferState`	`PENDING`, `SUCCEEDED`, `FAILED`, `CANCELED`, `DISPUTED`, etc.
`type`	`TransferType`	`DEBIT`, `CREDIT`, `REVERSAL`, `FEE`, `DISPUTE`.
`subtype`	`TransferSubtype`	E.g. `API`, `PUSH`, `PLATFORM`.
`failure_code` / `failure_message`	`string` \| `null`	Populated on `FAILED`.
`fee` / `supplemental_fee`	`number`	Processor + platform fees.
`parent_transfer`	`string` \| `null`	Set on reversals to point at the original.
`tags`	`Record<string, string>`	Application metadata.
`_links`	object	HATEOAS links — `reversals`, `disputes`, `fees`, etc.

Examples

Find every refund issued against a transfer

const refunds = (await easy.getTransfers({ limit: 100 })).data.filter(
  (t) => t.type === "REVERSAL" && t.parent_transfer === originalId,
);

Tag a charge with your internal order number

await easy.updateTransfer(transferId, {
  tags: { internal_order_id: "ord_42", channel: "web" },
});

Read failure details

const { data: t } = await easy.getTransfer(transferId);
if (t.state === "FAILED") {
  console.error(t.failure_code, t.failure_message);
}

Transfers

On this page