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
paymentMethodTokenstringrequiredCard payment token from client-side card tokenization, up to 500 characters.
last4stringOptional. Last four digits of the card, for display.
expMonthintegerOptional. Expiry month, 1 to 12. 1 to 12.
expYearintegerOptional. Four-digit expiry year. 2000 to 9999.
brandstringOptional. Card brand, such as
visa. Up to 64 characters.Example
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" }'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" }'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.
{ "id": "card_01hxa3b4c5d6e7f8g9h0j1k2m3", "brand": "visa", "last4": "4242", "expMonth": 12, "expYear": 2028, "cardholderName": null, "isPrimary": true, "addedAt": "2026-11-02T10:15:00.000Z"}Response fields
idstringCard ID (
card_…).brandstringCard brand in lowercase, such as
visa or mastercard. unknown when not known.last4string or nullLast four digits of the card number.
expMonthnumber or nullExpiry month, 1 to 12.
expYearnumber or nullExpiry year, four digits.
cardholderNamestring or nullName on the card.
isPrimarybooleantrue on the default card. Automatic charges use it.addedAtstring or nullWhen the card was saved.
Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The body is invalid or has an unsupported field such as makeDefault. Also returned when the card cannot be stored with these details. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The API key lacks write:payment_methods. A session that is not the account owner gets it too. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | The card could not be stored. Try again shortly. |