Skip to main content

Transfers API

Process payments, refunds, and manage fund transfers.

Methods​

createTransfer​

Create a transfer (charge a payment instrument).

const transfer = await easy.createTransfer({
  amount: 2500, // $25.00 in cents
  currency: "USD",
  source: "pi_123", // Payment instrument ID
  statement_descriptor: "Purchase from Store",
  tags: {
    order_id: "ord_456",
    product: "widget",
  },
});

Parameters​

  • data (object, required)
    • amount (number, required): Amount in cents (positive for charges, negative for refunds)
    • currency (string, required): Three-letter currency code (e.g., 'USD')
    • source (string, required): Payment instrument ID
    • statement_descriptor (string, optional): Description shown on customer's statement
    • tags (object, optional): Custom metadata

Returns​

Promise<ApiResponse<TransferData>>;

getTransfer​

Get a transfer by ID.

const transfer = await easy.getTransfer("trn_123");

Parameters​

  • transferId (string, required): The ID of the transfer

Returns​

Promise<ApiResponse<TransferData>>;

getTransfers​

List all transfers with optional filtering.

// Get all transfers with pagination
const transfers = await easy.getTransfers({
  limit: 50,
  offset: 0,
});

// Get specific transfers by ID
const specificTransfers = await easy.getTransfers({
  ids: ["trn_123", "trn_456"],
});

Parameters​

  • params (object, optional)
    • ids (string[], optional): Filter by specific transfer IDs
    • limit (number, optional): Maximum number of transfers to return
    • offset (number, optional): Number of transfers to skip

Returns​

Promise<ApiResponse<TransferData[]>>;

updateTransfer​

Update transfer metadata/tags.

const updated = await easy.updateTransfer("trn_123", {
  status: "completed",
  processed_at: new Date().toISOString(),
});

Parameters​

  • transferId (string, required): The ID of the transfer
  • tags (object, required): Metadata to update

Returns​

Promise<ApiResponse<TransferData>>;

Refunds​

To process a refund, create a transfer with a negative amount:

// Get the original transfer
const transfer = await easy.getTransfer("trn_123");

// Create a refund (negative amount)
const refund = await easy.createTransfer({
  amount: -transfer.data.amount,
  currency: transfer.data.currency,
  source: transfer.data.source,
  statement_descriptor: "Refund",
  tags: {
    type: "refund",
    original_transfer_id: "trn_123",
    reason: "customer_request",
  },
});

Type Definitions​

TransferData​

interface TransferData {
  id: string;
  amount: number;
  currency: string;
  source: string;
  statement_descriptor?: string;
  state: "PENDING" | "SUCCEEDED" | "FAILED" | "CANCELED";
  created_at: string;
  updated_at: string;
  tags?: Record<string, unknown>;
}