Skip to main content

Transfers API

The Transfers API allows you to move funds between accounts, process refunds, and manage payouts.

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>
      {transfer.description && <p>Description: {transfer.description}</p>}
    </div>
  );
}

createTransfer​

Create a new transfer.

const { createTransfer } = useEasy();

const transfer = await createTransfer({
  amount: 5000, // $50.00 in cents
  currency: "usd",
  source_account: "acct_123",
  destination_account: "acct_456",
  description: "Payment for services",
  metadata: {
    order_id: "ord_789",
  },
});

Parameters​

  • params (required)
    • amount (number, required): Amount in cents
    • currency (string, required): Three-letter ISO currency code
    • source_account (string, required): Source account ID
    • destination_account (string, required): Destination account ID
    • description (string, optional): Transfer description
    • metadata (object, optional): Additional custom data

Returns​

ApiResponse<TransferData>;

Example​

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

function CreateTransferForm() {
  const { createTransfer } = useEasy();
  const [amount, setAmount] = useState("");
  const [description, setDescription] = useState("");
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);

    try {
      const transfer = await createTransfer({
        amount: Math.round(parseFloat(amount) * 100), // Convert to cents
        currency: "usd",
        source_account: "acct_123",
        destination_account: "acct_456",
        description,
      });
      console.log("Transfer created:", transfer.data.id);
      // Reset form
      setAmount("");
      setDescription("");
    } catch (error) {
      console.error("Failed to create transfer:", error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="number"
        placeholder="Amount (USD)"
        value={amount}
        onChange={(e) => setAmount(e.target.value)}
        step="0.01"
        min="0"
        required
      />
      <input
        type="text"
        placeholder="Description"
        value={description}
        onChange={(e) => setDescription(e.target.value)}
      />
      <button type="submit" disabled={loading}>
        {loading ? "Processing..." : "Create Transfer"}
      </button>
    </form>
  );
}

Type Definitions​

TransferData​

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

CreateTransferParams​

interface CreateTransferParams {
  amount: number;
  currency: string;
  source_account: string;
  destination_account: string;
  description?: string;
  metadata?: Record<string, unknown>;
}

ListParams​

interface ListParams {
  limit?: number;
  offset?: number;
}

Transfer Statuses​

  • pending - Transfer is being processed
  • succeeded - Transfer completed successfully
  • failed - Transfer failed (insufficient funds, invalid accounts, etc.)
  • canceled - Transfer was canceled before completion

Error Handling​

try {
  const transfer = await createTransfer({ ... });
} catch (error) {
  if (error.message.includes('insufficient')) {
    console.error('Insufficient funds');
  } else if (error.message.includes('account')) {
    console.error('Invalid account');
  } else {
    console.error('Transfer failed:', error);
  }
}

Best Practices​

  1. Validate amounts before creating transfers
  2. Use metadata to track transfer purposes
  3. Handle failed transfers gracefully
  4. Monitor transfer status for async operations
  5. Keep descriptions clear for accounting purposes

Next Steps​