Skip to content

Save a payment card

POST /api/v2/billing/cards

Saves a card on the account and makes it the default card. Send the card payment token from client-side card tokenization (pm_… or tok_…) in paymentMethodToken. Card numbers are never sent to this API. Other saved cards stay saved. Saving the same card again does not add a second copy. On an account that receives Peppol e-invoices and has not turned card auto-charge on, saving a card sets auto-charge off. This keeps e-invoices from being paid twice. The response is the default card after the save.

Authentication: An API key with the scope write:payment_methods. About keys and scopes

Request

Body

paymentMethodTokenstringrequired
Card payment token from client-side card tokenization, up to 500 characters.
last4string
Optional. Last four digits of the card, for display.
expMonthinteger
Optional. Expiry month, 1 to 12. 1 to 12.
expYearinteger
Optional. Four-digit expiry year. 2000 to 9999.
brandstring
Optional. Card brand, such as visa. Up to 64 characters.

Example

POST /api/v2/billing/cards
curl -X POST "https://cloud.hostup.se/api/v2/billing/cards" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"paymentMethodToken": "pm_01hxa3b4c5d6e7f8g9h0j1k2m3",
"last4": "4242",
"expMonth": 12,
"expYear": 2028,
"brand": "visa"
}'

Responses

201 The card is saved. The body is the account’s default card after the save, which is normally the new card. If the default could not be switched, the body is the previous default card and the new card is saved next to it.

Response 201
{
"id": "card_01hxa3b4c5d6e7f8g9h0j1k2m3",
"brand": "visa",
"last4": "4242",
"expMonth": 12,
"expYear": 2028,
"cardholderName": null,
"isPrimary": true,
"addedAt": "2026-11-02T10:15:00.000Z"
}
Response fields
idstring
Card ID (card_…).
brandstring
Card brand in lowercase, such as visa or mastercard. unknown when not known.
last4string or null
Last four digits of the card number.
expMonthnumber or null
Expiry month, 1 to 12.
expYearnumber or null
Expiry year, four digits.
cardholderNamestring or null
Name on the card.
isPrimaryboolean
true on the default card. Automatic charges use it.
addedAtstring or null
When the card was saved.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400The body is invalid or has an unsupported field such as makeDefault. Also returned when the card cannot be stored with these details.
401Unauthorized. Authentication is required.
403The API key lacks write:payment_methods. A session that is not the account owner gets it too.
404Not found. The resource does not exist or is not owned by the caller.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502The card could not be stored. Try again shortly.