Pay an invoice with a saved card
POST /api/v2/billing/invoices/{id}/actions/pay
Charge a saved card for an unpaid invoice. Send {} to charge the account’s saved card for the whole balance. An account has one saved card, so savedCardId is optional. Set amount to pay part of the balance. Check actions.canPay and paymentMethods.card on GET /api/v2/billing/invoices/{id} first. When isBulkPaymentChild is true, pay the invoice in bulkPaymentParentId instead. actions.canPay does not block such an invoice today. The amount must be above the card minimum in paymentMethods.card.requirements.minimumAmount and no more than totals.outstanding. Check both before you call. A wrong amount also comes back as payment_failed. The card is charged at once. The response is the updated invoice. A refused charge returns 400 payment_failed with paymentFailure.kind: card_declined, insufficient_funds, card_expired, authentication_required, card_missing or unknown.
Authentication: An API key with the scope write:billing. About keys and scopes
Request
Path parameters
idstringrequiredGET /api/v2/billing/invoices (inv_…).Body (optional)
paymentMethodstringcard. Optional. One of card.savedCardIdstringprimary or a card ID (card_…) from GET /api/v2/billing/payment-methods. Default primary.amountnumberExample
curl -X POST "https://cloud.hostup.se/api/v2/billing/invoices/inv_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/pay" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json"curl -X POST "https://cloud.hostup.se/api/v2/billing/invoices/inv_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/pay" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "paymentMethod": "card", "savedCardId": "card_01hxa3b4c5d6e7f8g9h0j1k2m3", "amount": 159 }'Responses
200 The updated invoice.
{ "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3", "orderId": "ord_01hxa3b4c5d6e7f8g9h0j1k2m3", "number": "202600001", "status": "paid", "dates": { "issuedAt": "2026-04-27T12:00:00.000Z", "dueAt": "2026-05-11T23:59:59.000Z", "paidAt": "2026-04-27T12:10:00.000Z" }, "totals": { "currencyCode": "SEK", "subtotal": 127.2, "taxAmount": 31.8, "taxRateDecimal": 0.25, "creditApplied": 0, "total": 159, "amountPaid": 159, "amountRefunded": 0, "outstanding": 0 }, "lineItemCount": 1, "lineItems": [ { "description": "Cloud VPS monthly service", "displayDescription": "Cloud VPS monthly service", "kind": "vps", "productName": "Cloud VPS", "quantity": 1, "unitAmount": 127.2, "totalAmount": 127.2, "currencyCode": "SEK", "period": { "startAt": "2026-04-27T12:00:00.000Z", "endAt": "2026-05-27T12:00:00.000Z" }, "resource": { "type": "vps", "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3", "displayName": "example.com" }, "configurableOptions": [ { "key": "os", "label": "OS", "value": "Debian 13" }, { "key": "block_storage", "label": "Block Storage (NVMe)", "value": "50 GB" }, { "key": "bandwidth_limit", "label": "Bandwidth limit", "value": "2 TB" }, { "key": "backups", "label": "Backups", "value": "7" } ] } ], "payments": [ { "method": "card", "methodLabel": "Card", "amount": 159, "currencyCode": "SEK" } ], "actions": { "canPay": { "allowed": false, "reason": "Invoice is already paid." }, "canGeneratePaymentLink": { "allowed": false, "reason": "Invoice is already paid." }, "canBulkPay": { "allowed": false, "reason": "Invoice is already paid." }, "canCancel": { "allowed": false, "reason": "Only unpaid invoices can be cancelled.", "code": "invoice_not_unpaid" }, "canEmail": { "allowed": true, "reason": null }, "canDownload": { "allowed": true, "reason": null }, "canReissueInCurrency": { "allowed": false, "reason": "Swedish billing accounts pay SEK invoices by bankgiro, Swish or card.", "code": "account_country_not_eligible" } }, "paymentMethods": { "card": { "method": "card", "label": "Card", "available": false, "reason": "Invoice is already paid.", "checkoutMode": "payment", "requirements": { "minimumAmount": { "amount": 3, "currencyCode": "SEK", "comparison": "greater_than" } } }, "accountCredit": { "method": "accountCredit", "label": "Account credit", "available": false, "reason": "Invoice is already paid.", "checkoutMode": null, "requirements": { "invoiceCurrencyCode": "SEK", "accountCurrencyCode": "SEK", "availableBalance": { "amount": 0, "currencyCode": "SEK" }, "maximumAmount": { "amount": 0, "currencyCode": "SEK", "comparison": "less_than_or_equal" } } }, "swish": { "method": "swish", "label": "Swish", "available": false, "reason": "Invoice is already paid.", "checkoutMode": null, "requirements": { "invoiceCurrencyCode": "SEK", "accountCountryCode": "SE" } }, "bankgiro": { "method": "bankgiro", "label": "Bankgiro", "available": false, "reason": "Invoice is already paid.", "checkoutMode": null, "requirements": { "invoiceCurrencyCode": "SEK", "accountCountryCode": "SE" } }, "sepa": { "method": "sepa", "label": "SEPA bank transfer", "available": false, "reason": "Invoice is already paid.", "checkoutMode": "sepa_bank_transfer_payment", "requirements": { "invoiceCurrencyCode": "EUR" } }, "alipay": { "method": "alipay", "label": "Alipay", "available": false, "reason": "Invoice is already paid.", "checkoutMode": "alipay_payment", "requirements": { "invoiceCurrencyCodes": [ "EUR", "USD" ] } }, "crypto": { "method": "crypto", "label": "Cryptocurrency", "available": false, "reason": "Cryptocurrency payments are not available for Swedish billing accounts.", "checkoutMode": null, "requirements": { "invoiceCurrencyCodes": [ "SEK", "EUR", "USD" ], "accountCountryExcludedCode": "SE", "accountType": "private", "requiresCardVerification": true }, "visible": false } }, "paymentLinkGeneratorUrl": null, "isBulkPaymentChild": false, "bulkPaymentParentId": null}Response fields
idstringorderIdstringord_…) when the invoice belongs to an order. A domain renewal invoice whose order is still open is cancelled by cancelling that order first.numberstringstatusstringdraft, unpaid, partially_paid, paid, cancelled, refunded.datesobjectissuedAtstringdueAtstringpaidAtstringtotalsobjectcurrencyCodestringsubtotalnumbertaxAmountnumbertaxRateDecimalnumbercreditAppliednumbertotalnumberamountPaidnumberamountRefundednumberoutstandingnumberlineItemCountintegerlineItemsarray of objectkindstringvps, shared_hosting, domain, addon, credit, setup, other.purposestringrenewal, registration, transfer, account_credit_top_up, credit, setup.resourceobjecttypestringvps, shared_hosting, domain.idstring or nulldisplayNamestring or nullproductNamestringconfigurableOptionsarray of objectkey is the label in lower case with the bracket part dropped and other characters turned into _.keystringlabelstringvaluestringdescriptionstringdisplayDescriptionstringdisplaySecondaryLinesarray of stringdisplayDescription, such as the period.monthlyHintstringdetailsHintstringquantitynumberunitAmountnumbertotalAmountnumbercurrencyCodestringperiodobjectstartAtstringendAtstringoverpaymentCreditobjectdecisionstringcard_bankgiro_overpayment_already_credited.currencyCodestringSEK.invoiceAmountnumberexcessAmountnumbercreditedAtstringcurrentCreditBalancenumberpaymentsarray of objectkindstring or nullpayment: a payment of the invoice. account_credit_added: an overpayment added to account credit, not counted as a payment. refund: money returned (see refundedTo). rounding: a remainder under 1 SEK that Hostup wrote off so the invoice counts as paid. It is not money the customer paid. It is never a refund or a credit movement. One of payment, account_credit_added, refund, rounding.methodstring or nullmethodLabel for the text to show. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto, paypal, invoice, rounding, other.methodLabelstring or nullamountnumbercurrencyCodestringamount.refundedbooleanrefund row says where the money went.refundedTostringaccountCredit: the money is on the account balance and pays the next invoice automatically. paymentMethod: returned to the payment method. unknown: not recorded. One of accountCredit, paymentMethod, unknown.atstringnotestringactionsobjectcanPayobjectallowedbooleanreasonstring or nullcodestring or nullcanGeneratePaymentLinkobjectallowedbooleanreasonstring or nullcodestring or nullcanBulkPayobjectallowedbooleanreasonstring or nullcodestring or nullcanCancelobjectallowedbooleanreasonstring or nullcodestring or nullcanEmailobjectallowedbooleanreasonstring or nullcodestring or nullcanDownloadobjectallowedbooleanreasonstring or nullcodestring or nullcanReissueInCurrencyobjectPOST /api/v2/billing/invoices/{id}/actions/reissue-in-currency. When it is blocked, branch on code: invoice_order_backed (a pending order or plan change backs the invoice: cancel that order, change currency, then order again), invoice_domain_renewal (cancel the renewal order, then renew again), invoice_partially_settled, invoice_multiple_services, invoice_usage_not_reissuable and renewal_period_ended (contact support), account_country_not_eligible (Swedish accounts pay by bankgiro, Swish or card).allowedbooleanreasonstring or nullcodestring or nullpaymentMethodsobjectcard, accountCredit, swish, bankgiro, sepa, alipay and crypto. Check them before you start a payment.cardobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.accountCreditobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.swishobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.bankgiroobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.sepaobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.alipayobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.cryptoobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.paymentLinkGeneratorUrlstring or nullPOST /api/v2/billing/invoices/{id}/actions/generate-payment-link). Null when actions.canGeneratePaymentLink.allowed is false.isBulkPaymentChildbooleanbulkPaymentParentId instead. actions.canPay can still be allowed on such an invoice.bulkPaymentParentIdstring or nullisBulkPaymentChild is false.coversInvoiceIdsarray of stringrenewalInvoicingobjectpreferencestringconsolidated, separate.generatedByAutomationbooleanisConsolidatedbooleanlabelstringsettingsUrlstringdeliveryobjectchannelstringpeppol.statusstringqueued: accepted for sending and waiting, for example for the send window. An unpaid invoice from today for an organisation registered in Peppol is also queued until it is sent. sent: sent into the Peppol network. delivered: the recipient’s access point confirmed receipt. A failed or ineligible delivery never shows here. Such an invoice has no delivery field. One of queued, sent, delivered.sentAtstring or nulldeliveredAtstring or nullcancellationobjectcodestringdomain_registered_elsewhere: an unpaid order for a new domain registration was cancelled automatically. Someone else registered the name before the invoice was paid. A new domain is registered only once its invoice is paid. The name was never on this account and nothing was charged. One of domain_registered_elsewhere.reasonstringcode to branch or to pick a translated text.domainNamestringregistrarNamestring or nullnull when unknown.registeredAtstring or nullnull when unknown.cancelledAtstring or nullregisteredAt, since the cancellation follows that registration.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_request: the body is wrong. Causes: an unknown field; a paymentMethod other than card; a savedCardId that is neither primary nor one of the account’s card IDs; an amount that is not a positive number up to 1000000. The error points at /paymentMethod whichever field is wrong. detail lists the rules for all three fields. payment_failed: nothing was charged. The card was refused (paymentFailure.kind says why). It also comes back, with paymentFailure.kind unknown, in these cases: amount is more than the balance; the amount (or the whole balance) is at or below paymentMethods.card.requirements.minimumAmount; the invoice is in debt collection. Show detail to the payer. Do not retry in a loop. |
| 401 | Unauthorized. Authentication is required. |
| 403 | forbidden: the API key lacks write:billing. requiredScopes names it. The same code comes back when the account is not active. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is invoice_not_found. |
| 409 | The invoice cannot be charged now. invoice_already_paid: it is already paid. invoice_not_payable: it is not unpaid or has nothing left to pay. payment_method_invalid: no saved card was found. paymentLinkGeneratorUrl then points to a payment link instead. invoice_payment_in_progress: another payment for the invoice is running. payment_failed: the invoice changed while the payment was being prepared. Nothing was charged. Read the invoice again, then retry. |
| 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 | upstream_invoice_shape_invalid: the card was charged, but the updated invoice could not be loaded. Do not pay again. Read the invoice with GET /api/v2/billing/invoices/{id}?skipCache=1. |
| 503 | payment_failed: the payment could not be started. Nothing was charged. Retry later. |