# Let an agent add credit with the user's card (MPP)

Everything you buy over the Porkbun API is paid from prepaid **account credit**.
When an order fails with `INSUFFICIENT_FUNDS`, an AI agent can top the account up
with the **user's card** by paying a Porkbun payment link over **MPP**, the
Machine Payments Protocol (an open standard from Stripe and Tempo, mpp.dev). The
card stays in the user's Stripe agent wallet (the Link Agent Wallet): no card
needs to be saved at Porkbun, and the user approves the spend there.

If the agent has a crypto wallet instead, see
[Add account credit with USDC (x402)](https://porkbun.com/llms/guides/pay-with-usdc-x402).

## How it works

1. Ask Porkbun for a payment link (`POST /account/topupMpp`). Nothing is charged.
2. The agent's MPP client requests the link and gets HTTP **402** with a
   `WWW-Authenticate: Payment` challenge: the amount, `method="stripe"`,
   `intent="charge"`, and Porkbun's Stripe profile.
3. The agent's wallet mints a **Shared Payment Token** for the user's card,
   limited to that amount, and the client retries with it as the credential.
4. Porkbun charges the token and adds the credit immediately. The response has
   the new balance and a `Payment-Receipt` header; the account holder gets a
   receipt email.

## 1. Get a payment link

```
POST /api/json/v3/account/topupMpp
{"apikey":"pk1_...","secretapikey":"sk1_...","amount":2000}
```

`amount` is integer US cents, from 500 ($5.00) to 50000 ($500.00). Send
`"dryRun": true` to check eligibility and limits without creating a link.

```json
{
  "status": "SUCCESS",
  "amount_cents": 2000,
  "payUrl": "https://porkbun.com/pay/topup/...",
  "expiresAt": "2026-10-02T01:10:41Z",
  "protocol": "mpp"
}
```

The link works once, for this account and amount, and expires after 15 minutes.

## 2. Pay it

Any MPP client with a Stripe agent wallet can pay it. With Stripe's Link CLI
(also available as an MCP server for agents):

```
npx @stripe/link-cli auth login
npx @stripe/link-cli mpp pay "<payUrl>" -X POST --context "Adding $20.00 of prepaid credit to my Porkbun account so my agent can register domains."
```

`--context` (at least 100 characters) is shown to the user when Link asks them
to approve the spend. Tell the user the dollar amount before paying.

A successful payment answers:

```json
{"status":"SUCCESS","credited_cents":2000,"credited":"$20.00","balance_cents":3480,"balance":"$34.80","paymentIntent":"pi_..."}
```

Then retry the order that needed the credit, unchanged.

## From the MCP server

On the full server (`https://mcp.porkbun.com/mcp`, or the npm package) the tool
is `top_up_with_card_mpp`: it returns the link, which the agent pays with its
MPP-capable wallet tool. It is not offered on the versions in the Claude and
ChatGPT app directories, which do not move money.

## Limits and errors

The same rules as card top-ups (`POST /account/topup`), because this is a card
charge too:

- $5 to $500 per top-up, up to the account's monthly ceiling (its monthly spend
  limit, or $100 a month when none is set), 5 a day and 20 a month
  (`TOPUP_LIMIT_EXCEEDED`).
- Email and phone verified (`VERIFICATION_REQUIRED`); not a bank-transfer-only
  account (`MPP_NOT_AVAILABLE`).
- Not on sandbox keys (`SANDBOX_UNSUPPORTED`): use `/sandbox/topup`.

When the link itself answers 402 a second time, its `detail` says why (the card
was declined, the link was already used, a limit was reached) and nothing was
charged.

## Other ways to add credit

- `POST /account/topup` charges a card already saved at Porkbun (ask first).
- `POST /account/topupCrypto`: USDC on Base, payable over x402.
- On porkbun.com, Account Credit: card, bank transfer or crypto.


---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api