Skip to main content

Transfers API

The Transfers API allows you to view and manage payment transfers, process refunds, and track transaction history in your React Native 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
    • ids (string[], optional): Filter by specific transfer IDs

Returns​

ApiResponse<TransferData[]>;

Example​

import { useEasy } from "@easylabs/react-native";
import { useState, useEffect } from "react";
import { FlatList, View, Text, StyleSheet } from "react-native";

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();
  }, []);

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

  return (
    <FlatList
      data={transfers}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View style={styles.item}>
          <Text style={styles.amount}>${(item.amount / 100).toFixed(2)}</Text>
          <Text style={styles.date}>
            {new Date(item.created_at).toLocaleDateString()}
          </Text>
          <Text style={styles.status}>{item.status}</Text>
        </View>
      )}
    />
  );
}

const styles = StyleSheet.create({
  item: {
    padding: 16,
    borderBottomWidth: 1,
    borderBottomColor: "#eee",
  },
  amount: {
    fontSize: 18,
    fontWeight: "600",
  },
  date: {
    fontSize: 14,
    color: "#666",
    marginTop: 4,
  },
  status: {
    fontSize: 14,
    marginTop: 4,
  },
});

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

Returns​

ApiResponse<TransferData>;

Example​

import { useEasy } from "@easylabs/react-native";
import { useState, useEffect } from "react";
import { View, Text, ActivityIndicator, StyleSheet } from "react-native";

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

  useEffect(() => {
    const fetchTransfer = async () => {
      try {
        const result = await getTransfer(transferId);
        setTransfer(result.data);
      } catch (error) {
        console.error("Failed to fetch transfer:", error);
      } finally {
        setLoading(false);
      }
    };

    fetchTransfer();
  }, [transferId]);

  if (loading) return <ActivityIndicator />;
  if (!transfer) return <Text>Transfer not found</Text>;

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Transfer Details</Text>
      <Text style={styles.label}>Amount</Text>
      <Text style={styles.value}>${(transfer.amount / 100).toFixed(2)}</Text>
      <Text style={styles.label}>Status</Text>
      <Text style={styles.value}>{transfer.status}</Text>
      <Text style={styles.label}>Date</Text>
      <Text style={styles.value}>
        {new Date(transfer.created_at).toLocaleString()}
      </Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
  },
  title: {
    fontSize: 24,
    fontWeight: "bold",
    marginBottom: 20,
  },
  label: {
    fontSize: 14,
    color: "#666",
    marginTop: 16,
  },
  value: {
    fontSize: 16,
    marginTop: 4,
  },
});

createTransfer​

Create a new transfer (advanced use - typically handled by checkout).

const { createTransfer } = useEasy();

const result = await createTransfer({
  amount: 2500, // $25.00 in cents
  currency: "USD",
  source: "pi_123",
  destination: "merchant_account",
  description: "Payment for order #1234",
});

Parameters​

  • data (object, required):
    • amount (number, required): Amount in cents
    • currency (string, required): Currency code (e.g., "USD")
    • source (string, required): Payment instrument ID
    • destination (string, optional): Destination account
    • description (string, optional): Transfer description
    • metadata (object, optional): Additional metadata

Returns​

ApiResponse<TransferData>;
tip

Most applications should use the checkout method instead of creating transfers directly.

updateTransferTags​

Update metadata tags on an existing transfer.

const { updateTransferTags } = useEasy();

const result = await updateTransferTags("tr_123", {
  order_id: "order_456",
  customer_note: "Rush delivery",
  updated_at: new Date().toISOString(),
});

Parameters​

  • transferId (string, required): The ID of the transfer
  • tags (object, required): Key-value pairs to update

Returns​

ApiResponse<TransferData>;

Example​

import { useEasy } from "@easylabs/react-native";
import { useState } from "react";
import { View, TextInput, Button, Alert, StyleSheet } from "react-native";

function AddTransferNote({ transferId }) {
  const { updateTransferTags } = useEasy();
  const [note, setNote] = useState("");
  const [loading, setLoading] = useState(false);

  const handleUpdate = async () => {
    setLoading(true);

    try {
      await updateTransferTags(transferId, {
        customer_note: note,
      });
      Alert.alert("Success", "Note added to transfer");
      setNote("");
    } catch (error) {
      Alert.alert("Error", error.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={styles.container}>
      <TextInput
        style={styles.input}
        value={note}
        onChangeText={setNote}
        placeholder="Add a note..."
        multiline
      />
      <Button
        title={loading ? "Saving..." : "Add Note"}
        onPress={handleUpdate}
        disabled={loading || !note.trim()}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
  },
  input: {
    borderWidth: 1,
    borderColor: "#ccc",
    borderRadius: 8,
    padding: 12,
    marginBottom: 16,
    minHeight: 100,
    textAlignVertical: "top",
  },
});

Type Definitions​

TransferData​

interface TransferData {
  id: string;
  amount: number; // Amount in cents
  currency: string;
  status: string;
  source: string;
  destination?: string;
  description?: string;
  metadata?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

Transfer Statuses​

  • pending - Transfer is being processed
  • succeeded - Transfer completed successfully
  • failed - Transfer failed
  • canceled - Transfer was canceled
  • requires_action - Additional action required

Best Practices​

1. Display Amounts Correctly​

Always divide by 100 to display dollar amounts:

<Text>${(transfer.amount / 100).toFixed(2)}</Text>

2. Handle Transfer States​

Show appropriate UI based on transfer status:

const getStatusColor = (status) => {
  switch (status) {
    case "succeeded":
      return "#4CAF50";
    case "pending":
      return "#FF9800";
    case "failed":
      return "#F44336";
    default:
      return "#999";
  }
};

3. Pagination​

Implement pagination for large lists:

const [page, setPage] = useState(0);
const limit = 20;

const loadMore = async () => {
  const result = await getTransfers({
    limit,
    offset: page * limit,
  });
  setTransfers([...transfers, ...result.data]);
  setPage(page + 1);
};

Next Steps​