# Payment method required

What a 402 payment_required response means, which requests trigger it, and how the user adds a card without leaving the dashboard.

Paid actions bill once they succeed, so Zernio first checks for a card.

Without one, the request returns `402` with `code: "PAYMENT_REQUIRED"` and creates nothing. Send the user to `dashboard_url` to add a card in the billing drawer and retry.

## Which requests return 402

| Request | `reason` | Why |
|---|---|---|
| Connecting a third social account (`GET /v1/connect/{platform}`, `POST /v1/connect/whatsapp/embedded-signup`, Discord, Slack and Bluesky connect) | `free_tier_exceeded` | The first 2 connected accounts are free; every further account bills per day of connection. |
| Connecting the first X account | `twitter_passthrough` | X bills every API call and Zernio passes that cost through, so a card is needed before the first X account, even inside the free tier. |
| Buying a phone number, submitting phone-number KYC, registering a sender ID or a 10DLC brand | none | These responses carry `code` and `error` only, no `reason`, `details` or `dashboard_url`. Treat them like `free_tier_exceeded` and send the user to `https://zernio.com/dashboard/billing?add_payment_method=1`. |
| Any connect request on an enterprise contract that has reached its negotiated account cap | `enterprise_required` | Not a card problem: the contract's limit has to be raised. |

The API reference lists `402` on every operation that can return it.

## The response

```json
{
  "error": "Add a payment method to connect more than 2 accounts.",
  "code": "PAYMENT_REQUIRED",
  "reason": "free_tier_exceeded",
  "documentation_url": "https://docs.zernio.com/billing/payment-method-required",
  "dashboard_url": "https://zernio.com/dashboard/billing?add_payment_method=1",
  "details": {
    "free_tier_account_limit": 2,
    "current_account_count": 3,
    "has_payment_method": false
  }
}
```

`reason` is the value to switch on.

`details` carries the numbers behind the message:

- `free_tier_account_limit` and `current_account_count` for the free tier.
- `has_payment_method` for both card reasons.
- `effective_account_limit` for `enterprise_required`.

## What to do

For `free_tier_exceeded` and `twitter_passthrough`, open `dashboard_url` for the user.

It lands on the Zernio billing page with the add-payment-method drawer already open. The drawer asks for:

- Card details (or Apple Pay, Google Pay and Link where available).
- The billing address for invoices.
- An optional VAT or tax ID.

Nothing is charged when the card is added. Usage bills at the end of the period, as described on the [billing page](/billing).

Once the drawer reports the card as saved, repeat the original request and it goes through.

**Inside the dashboard**, the same drawer opens by itself when the user hits one of these gates. The action they were doing (connecting the account, buying the number) continues once the card lands.

A team member can add the card too. It is attached to the team owner's billing profile.

For `enterprise_required`, `dashboard_url` points at the enterprise contact page instead. The team already has a card: the connected-account limit on its contract is what needs to change.

## If the card is declined

A declined card stays in the drawer, with the bank's message next to the card number. The user edits the number or tries another card. Nothing is saved until one is accepted.

A billing address that Stripe cannot match to a tax location is rejected in the drawer as well. So invoices can always be issued against the address on file.

## Related

- [Billing](/billing): when the card is charged, proration and the graduated ladder.
- [Pricing](/pricing): the rates and the $12 monthly credit.
- [Get billing](/usage/get-billing): the team's balance and payment status, including whether access is currently payment-blocked.