Top Up Account Credit
top_up_account_creditCharges your saved payment card to add funds to your Porkbun account credit, so you can complete a purchase that failed for insufficient funds right away.
Instructions
Charges the user's saved payment method (amount_cents is integer cents: 803 charges $8.03; tell the user the dollar figure first) and adds the money to their Porkbun account credit immediately. Use it when a purchase failed with INSUFFICIENT_FUNDS and the user wants to continue now — enabling auto top-up does not help in that moment, because it only fires on the next order.
It charges the primary card and falls back to the backups if it is declined, charging at most one: the response's card is the one that paid; usedBackup: true means the primary was declined (listed in declinedFirst), so tell the user their primary card needs attention. CARD_DECLINED means every saved card refused (declined lists each with its decline code).
Ask the user before calling, with the figure. This spends real money off a card, not credit they already bought. Omit amount_cents and it charges what the account has configured (or $50 if it never has) — that is the right default, and amountSource in the response says which was used. Pass amount_cents only when the user wants a specific one-off figure, e.g. enough to cover a particular purchase; it does NOT change their saved setting, so prefer it over calling configure_auto_topup for a single charge.
Fails with NO_PAYMENT_METHOD when nothing is saved to charge (the user has to save a card or buy credit on porkbun.com; the API cannot add one), CARD_DECLINED when the card refuses, and TOPUP_LIMIT_EXCEEDED when the month's dollars or the frequency run out — the account's monthly spend limit caps top-up dollars as well as domain spend, an account with no limit set gets $100/month, card, auto, MPP and USDC top-ups all count toward it, and there are 5/day and 20/month count caps. get_auto_topup reports monthlyCeiling, ceilingSource and toppedUpThisMonth, so check there before promising a user a top-up will go through. Every successful charge emails the account holder. A sandbox key grants simulated credit and charges nothing. Supports dry_run, which previews and charges nothing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Deprecated alias of `amount_cents`, same unit (integer US cents). Send `amount_cents` instead. | |
| dry_run | No | If true, report what would be charged without charging it. | |
| amount_cents | No | One-off amount to charge, 500-50000. Omit to charge the account's configured top-up amount. Does not change any saved setting. Integer US cents: 803 means $8.03, not $803. |