Payment Instruments API

The Payment Instruments API allows you to manage customer payment methods including credit cards and bank accounts in your React Native application.

Methods

getCustomerPaymentInstruments

Retrieve all payment instruments for a customer.

const { getCustomerPaymentInstruments } = useEasy();

const result = await getCustomerPaymentInstruments("cust_123");
const instruments = result.data;

Parameters

• customerId (string, required): The ID of the customer

Returns

ApiResponse<PaymentInstrumentData[]>;

Example

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

function PaymentMethodList({ customerId }) {
  const { getCustomerPaymentInstruments } = useEasy();
  const [instruments, setInstruments] = useState([]);

  useEffect(() => {
    const fetchInstruments = async () => {
      try {
        const result = await getCustomerPaymentInstruments(customerId);
        setInstruments(result.data);
      } catch (error) {
        console.error("Failed to fetch payment methods:", error);
      }
    };

    fetchInstruments();
  }, [customerId]);

  return (
    <FlatList
      data={instruments}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View style={styles.item}>
          <Text style={styles.name}>{item.name}</Text>
          {item.type === "PAYMENT_CARD" ? (
            <Text>
              {item.details?.card?.brand} ending in {item.details?.card?.last4}
            </Text>
          ) : (
            <Text>
              {item.details?.bank?.account_type} ending in{" "}
              {item.details?.bank?.last4}
            </Text>
          )}
        </View>
      )}
    />
  );
}

const styles = StyleSheet.create({
  item: {
    padding: 16,
    borderBottomWidth: 1,
    borderBottomColor: "#eee",
  },
  name: {
    fontSize: 16,
    fontWeight: "600",
    marginBottom: 4,
  },
});

---

createPaymentInstrument

Create a new payment instrument for a customer.

Payment Card

const { createPaymentInstrument } = useEasy();
const cardNumberRef = useRef(null);
const expiryRef = useRef(null);
const cvcRef = useRef(null);

const result = await createPaymentInstrument({
  type: "PAYMENT_CARD",
  customerId: "cust_123",
  cardNumberElement: cardNumberRef,
  cardExpirationDateElement: expiryRef,
  cardVerificationCodeElement: cvcRef,
  address: {
    line1: "123 Main St",
    city: "Anytown",
    state: "CA",
    postal_code: "12345",
    country: "US",
  },
  name: "My Primary Card",
});

Bank Account

const { createPaymentInstrument } = useEasy();
const routingRef = useRef(null);
const accountRef = useRef(null);

const result = await createPaymentInstrument({
  type: "BANK_ACCOUNT",
  customerId: "cust_123",
  accountType: "CHECKING",
  routingElement: routingRef,
  accountElement: accountRef,
  name: "My Checking Account",
});

Parameters

• params (required): Payment instrument details
  • type ('PAYMENT_CARD' | 'BANK_ACCOUNT'): Type of payment instrument
  • customerId (string, required): The ID of the customer
  • name (string, required): Display name for the payment method
  • For cards: cardNumberElement, cardExpirationDateElement, cardVerificationCodeElement, optional address
  • For bank accounts: accountType, routingElement, accountElement

Returns

ApiResponse<PaymentInstrumentData>;

Example

import {
  useEasy,
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
} from "@easylabs/react-native";
import { useRef, useState } from "react";
import { View, Text, Button, StyleSheet, Alert } from "react-native";

function AddPaymentMethod({ customerId }) {
  const { createPaymentInstrument } = useEasy();
  const cardNumberRef = useRef(null);
  const expiryRef = useRef(null);
  const cvcRef = useRef(null);
  const [loading, setLoading] = useState(false);

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

    try {
      const result = await createPaymentInstrument({
        type: "PAYMENT_CARD",
        customerId: customerId,
        cardNumberElement: cardNumberRef,
        cardExpirationDateElement: expiryRef,
        cardVerificationCodeElement: cvcRef,
        name: "My Card",
      });

      Alert.alert("Success", "Payment method added!");
    } catch (error) {
      Alert.alert("Error", error.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.label}>Card Number</Text>
      <CardNumberElement btRef={cardNumberRef} style={styles.input} />

      <Text style={styles.label}>Expiration Date</Text>
      <CardExpirationDateElement btRef={expiryRef} style={styles.input} />

      <Text style={styles.label}>CVC</Text>
      <CardVerificationCodeElement btRef={cvcRef} style={styles.input} />

      <Button
        title={loading ? "Adding..." : "Add Payment Method"}
        onPress={handleAdd}
        disabled={loading}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
  },
  label: {
    fontSize: 16,
    fontWeight: "600",
    marginBottom: 8,
    marginTop: 16,
  },
  input: {
    borderWidth: 1,
    borderColor: "#ccc",
    borderRadius: 8,
    padding: 12,
  },
});

---

updatePaymentInstrument

Update an existing payment instrument's details.

const { updatePaymentInstrument } = useEasy();

const result = await updatePaymentInstrument("pi_123", {
  name: "Updated Card Name",
});

Parameters

• instrumentId (string, required): The ID of the payment instrument
• updates (object, required): Fields to update
  • name (string, optional): Display name for the payment method

Returns

ApiResponse<PaymentInstrumentData>;

Example

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

function RenamePaymentMethod({ instrumentId, currentName }) {
  const { updatePaymentInstrument } = useEasy();
  const [name, setName] = useState(currentName);
  const [loading, setLoading] = useState(false);

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

    try {
      await updatePaymentInstrument(instrumentId, { name });
      Alert.alert("Success", "Payment method updated!");
    } catch (error) {
      Alert.alert("Error", error.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={styles.container}>
      <TextInput
        style={styles.input}
        value={name}
        onChangeText={setName}
        placeholder="Payment method name"
      />
      <Button
        title={loading ? "Updating..." : "Update Name"}
        onPress={handleUpdate}
        disabled={loading}
      />
    </View>
  );
}

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

---

tokenizePaymentInstrument

Tokenize payment instrument data securely (advanced use).

const { tokenizePaymentInstrument } = useEasy();

const token = await tokenizePaymentInstrument({
  type: "PAYMENT_CARD",
  cardNumberElement: cardNumberRef,
  cardExpirationDateElement: expiryRef,
  cardVerificationCodeElement: cvcRef,
});

Parameters

Same as createPaymentInstrument but without customerId and name.

Returns

Promise<string | undefined>;

Returns a tokenized string that can be used later to create a payment instrument.

Type Definitions

PaymentInstrumentData

interface PaymentInstrumentData {
  id: string;
  type: "PAYMENT_CARD" | "BANK_ACCOUNT";
  name: string;
  customer_id: string;
  details?: {
    card?: {
      brand: string;
      last4: string;
      exp_month: number;
      exp_year: number;
    };
    bank?: {
      account_type: string;
      last4: string;
      routing_number: string;
    };
  };
  created_at: string;
  updated_at: string;
}

Best Practices

1. Error Handling

Always handle errors when managing payment instruments:

try {
  const result = await createPaymentInstrument(data);
  Alert.alert("Success", "Payment method added");
} catch (error) {
  if (error.message.includes("invalid")) {
    Alert.alert("Invalid", "Please check your payment details");
  } else {
    Alert.alert("Error", "Failed to add payment method");
  }
}

2. Loading States

Show loading indicators during operations:

const [loading, setLoading] = useState(false);

const handleAdd = async () => {
  setLoading(true);
  try {
    await createPaymentInstrument(data);
  } finally {
    setLoading(false);
  }
};

3. Display Payment Methods

Show payment methods in a user-friendly format:

const formatPaymentMethod = (instrument) => {
  if (instrument.type === "PAYMENT_CARD") {
    return `${instrument.details?.card?.brand} •••• ${instrument.details?.card?.last4}`;
  }
  return `${instrument.details?.bank?.account_type} •••• ${instrument.details?.bank?.last4}`;
};

Next Steps

• Process Payments with Checkout
• Manage Customers
• View Payment Form Example