Skip to main content
POST
/
api
/
cards
/
default
Set Default Card
curl --request POST \
  --url https://api.example.com/api/cards/default \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "default_source": "<string>"
}
'
{
  "status": true,
  "message": "<string>",
  "data": {
    "id": "<string>",
    "default_source": "<string>",
    "email": "<string>",
    "name": "<string>",
    "sources": {}
  }
}
Sets a specific card as the default payment source for a customer. This card will be used for automatic payments unless otherwise specified.

​
Request Body

​
userId
string
required
The Stripe customer ID. Must start with cus_.Example: "cus_QRs9eKZ4xUzN2TP9"
​
default_source
string
required
The card ID to set as default. Must start with card_ or src_.This must be a card that’s already attached to the customer. Use Assign Card first if needed.Example: "card_1QRs9eKZ4xUzN2TPabcdefgh"

​
Response

​
status
boolean
Indicates if the request was successful (true) or failed (false).
​
message
string
Human-readable message describing the result.Example: "Método de pago actualizado con éxito"
​
data
object
The updated Stripe customer object. This is the raw customer object from Stripe containing all customer information.

​
Example Request

curl -X POST https://your-api.com/api/cards/default \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "cus_QRs9eKZ4xUzN2TP9",
    "default_source": "card_1QRs9eKZ4xUzN2TPabcdefgh"
  }'

​
Example Response

{
  "status": true,
  "message": "Método de pago actualizado con éxito",
  "data": {
    "id": "cus_QRs9eKZ4xUzN2TP9",
    "object": "customer",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "+1234567890",
    "default_source": "card_1QRs9eKZ4xUzN2TPabcdefgh",
    "created": 1710259200,
    "sources": {
      "object": "list",
      "data": [
        {
          "id": "card_1QRs9eKZ4xUzN2TPabcdefgh",
          "object": "card",
          "brand": "Visa",
          "last4": "4242",
          "exp_month": 12,
          "exp_year": 2026
        }
      ]
    }
  }
}

​
Use Cases

​
Setting Default After Card Assignment

After assigning a new card to a customer, you may want to set it as the default:
Node.js
// First, assign the card
const assignResponse = await fetch('https://your-api.com/api/cards/assign', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userId: 'cus_QRs9eKZ4xUzN2TP9',
    source: 'tok_1QRs9eKZ4xUzN2TP9vQqWXYZ'
  })
});
const assignData = await assignResponse.json();

// Then set it as default
const defaultResponse = await fetch('https://your-api.com/api/cards/default', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userId: 'cus_QRs9eKZ4xUzN2TP9',
    default_source: assignData.data.cardId
  })
});
const defaultData = await defaultResponse.json();
console.log('Default card set:', defaultData);

​
Switching Default Cards

If a customer has multiple cards and wants to switch the default:
Node.js
// Get the customer's cards first
const cardsResponse = await fetch('https://your-api.com/api/cards/cus_QRs9eKZ4xUzN2TP9');
const cardsData = await cardsResponse.json();

// User selects a different card
const selectedCardId = cardsData.data[1].id; // Second card

// Update default
const response = await fetch('https://your-api.com/api/cards/default', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userId: 'cus_QRs9eKZ4xUzN2TP9',
    default_source: selectedCardId
  })
});
The default payment source will be automatically used for subscription charges and invoice payments when no specific payment method is provided.

Build docs developers (and LLMs) love

Get started for freeTalk to us