Skip to main content

Transfers API

Breaking Change — v1.0.0

Balance transfer operations have been removed from the SDK. createTransfer with source_account/destination_account parameters is no longer supported. Treasury operations are now managed internally by Easy Labs.

See the Migration Guide below.

The Transfers API allows you to view payment transfers and track transaction history in your React application.

Methods​

getTransfers​

Retrieve a list of all transfers with optional pagination.

const { getTransfers } = useEasy();

const result = await getTransfers({
  limit: 50,
  offset: 0,
});

Parameters​

  • params (optional)
    • limit (number): Maximum number of transfers to return (default: 10, max: 100)
    • offset (number): Number of transfers to skip for pagination

Returns​

ApiResponse<TransferData[]>;

Example​

import { useEasy } from "@easylabs/react";
import { useState, useEffect } from "react";

function TransferHistory() {
  const { getTransfers } = useEasy();
  const [transfers, setTransfers] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchTransfers = async () => {
      try {
        const result = await getTransfers({ limit: 50 });
        setTransfers(result.data);
      } catch (error) {
        console.error("Failed to fetch transfers:", error);
      } finally {
        setLoading(false);
      }
    };

    fetchTransfers();
  }, [getTransfers]);

  if (loading) return <div>Loading...</div>;

  return (
    <table>
      <thead>
        <tr>
          <th>Date</th>
          <th>Amount</th>
          <th>Status</th>
        </tr>
      </thead>
      <tbody>
        {transfers.map((transfer) => (
          <tr key={transfer.id}>
            <td>{new Date(transfer.created_at).toLocaleDateString()}</td>
            <td>${(transfer.amount / 100).toFixed(2)}</td>
            <td>{transfer.status}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

getTransfer​

Retrieve a specific transfer by ID.

const { getTransfer } = useEasy();

const result = await getTransfer("tr_123");
const transfer = result.data;

Parameters​

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

Returns​

ApiResponse<TransferData>;

Example​

import { useEasy } from "@easylabs/react";
import { useState, useEffect } from "react";

function TransferDetails({ transferId }) {
  const { getTransfer } = useEasy();
  const [transfer, setTransfer] = useState(null);

  useEffect(() => {
    const fetchTransfer = async () => {
      try {
        const result = await getTransfer(transferId);
        setTransfer(result.data);
      } catch (error) {
        console.error("Transfer not found:", error);
      }
    };

    fetchTransfer();
  }, [transferId, getTransfer]);

  if (!transfer) return <div>Loading...</div>;

  return (
    <div>
      <h2>Transfer {transfer.id}</h2>
      <p>Amount: ${(transfer.amount / 100).toFixed(2)}</p>
      <p>Status: {transfer.status}</p>
      <p>Date: {new Date(transfer.created_at).toLocaleString()}</p>
    </div>
  );
}

Type Definitions​

TransferData​

interface TransferData {
  id: string;
  amount: number;
  currency: string;
  source: string;
  status: "pending" | "succeeded" | "failed" | "canceled";
  created_at: string;
  updated_at: string;
  tags?: Record<string, unknown>;
}

Transfer Statuses​

  • pending — Transfer is being processed
  • succeeded — Transfer completed successfully
  • failed — Transfer failed
  • canceled — Transfer was canceled

Migration​

Removed: Balance Transfer Operations​

Balance transfers (moving funds between merchant accounts) have been removed from the SDK surface. This is a semver-major breaking change introduced in v1.0.0.

Removed APIs:

  • createTransfer({ source_account, destination_account, ... }) — balance transfer between accounts

What to do:

Treasury and account-to-account fund movements are now managed internally by Easy Labs. You do not need to initiate balance transfers from the SDK.

For customer payment processing, use the checkout method instead:

// ✅ Correct: use checkout for customer payments
const { checkout } = useEasy();

const result = await checkout({
  // customer and payment instrument details
});

If you were relying on balance transfers for payouts or settlements, contact support@itseasy.co — these operations are now handled automatically by the Easy platform.

Next Steps​