Skip to main content
GET
/
api
/
cards
/
:id
Get Cards by User
curl --request GET \
  --url https://api.example.com/api/cards/:id
{
  "status": true,
  "message": "<string>",
  "data": [
    {
      "id": "<string>",
      "object": "<string>",
      "brand": "<string>",
      "last4": "<string>",
      "exp_month": 123,
      "exp_year": 123,
      "country": "<string>",
      "fingerprint": "<string>",
      "funding": "<string>",
      "customer": "<string>"
    }
  ]
}
Retrieves a list of all cards (payment sources) associated with a specific customer. This is useful for displaying saved payment methods to users.

Path Parameters

id
string
required
The Stripe customer ID. Must start with cus_.Example: "cus_QRs9eKZ4xUzN2TP9"

Response

status
boolean
Indicates if the request was successful (true) or failed (false).
message
string
Human-readable message describing the result.Example: "Tarjetas listadas correctamente"
data
array
Array of card objects associated with the customer. Limited to 10 cards.

Example Request

curl -X GET https://your-api.com/api/cards/cus_QRs9eKZ4xUzN2TP9 \
  -H "Content-Type: application/json"

Example Response

{
  "status": true,
  "message": "Tarjetas listadas correctamente",
  "data": [
    {
      "id": "card_1QRs9eKZ4xUzN2TPabcdefgh",
      "object": "card",
      "brand": "Visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2026,
      "country": "US",
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "funding": "credit",
      "customer": "cus_QRs9eKZ4xUzN2TP9",
      "cvc_check": "pass",
      "address_zip_check": null
    },
    {
      "id": "card_2ABc9eKZ4xUzN2TPxyzdefgh",
      "object": "card",
      "brand": "MasterCard",
      "last4": "5555",
      "exp_month": 6,
      "exp_year": 2027,
      "country": "US",
      "fingerprint": "Yt6FXMMDS8GKkS2d",
      "funding": "debit",
      "customer": "cus_QRs9eKZ4xUzN2TP9",
      "cvc_check": "pass",
      "address_zip_check": "pass"
    }
  ]
}

Display Cards to Users

Example of displaying saved cards in a user interface:
React
import { useState, useEffect } from 'react';

function PaymentMethods({ customerId }) {
  const [cards, setCards] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchCards() {
      try {
        const response = await fetch(`https://your-api.com/api/cards/${customerId}`);
        const data = await response.json();
        
        if (data.status) {
          setCards(data.data);
        }
      } catch (error) {
        console.error('Error fetching cards:', error);
      } finally {
        setLoading(false);
      }
    }

    fetchCards();
  }, [customerId]);

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

  return (
    <div>
      <h2>Saved Payment Methods</h2>
      {cards.length === 0 ? (
        <p>No cards on file</p>
      ) : (
        <ul>
          {cards.map(card => (
            <li key={card.id}>
              {card.brand} ending in {card.last4}
              <br />
              Expires {card.exp_month}/{card.exp_year}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Pagination

The API limits results to 10 cards by default. If a customer has more than 10 cards, you may need to implement pagination (though this is rare in practice).
Security Best Practice: Only show the last 4 digits and brand to users. Never expose full card numbers, even if you have access to them.

Card Verification Status

Cards in the response include verification fields:
  • cvc_check: Result of CVC verification (pass, fail, unavailable, or unchecked)
  • address_zip_check: Result of ZIP code verification (pass, fail, unavailable, or unchecked)
  • address_line1_check: Result of address verification
These fields help identify the reliability of the payment method.

Build docs developers (and LLMs) love