---
title: "Confirm a top-up"
method: POST
path: "/v1/balance/top-ups/{topupId}/confirm"
tags: ["Treasury"]
---

# Confirm a top-up

`POST /v1/balance/top-ups/{topupId}/confirm`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/balance/top-ups/{topupId}/confirm`
- Auth: HTTP bearer

Call after 3D Secure. Reads the payment from Stripe, then:

- `succeeded`: paid, the top-up is credited.
- `failed`: the bank refused it.
- `pending`: Stripe is still settling the charge.

Safe to repeat. Needs an owner, admin or billing admin, signed in or through a full-access key they created.

## Path parameters

- `topupId` string, required

## Response `200`

The top-up after confirming

- TreasuryTopup
  - `id` string
  - `method` 'card' | 'bank_transfer'
  - `purpose` 'balance' | 'payout_batch': `balance` funds your balance; `payout_batch` is the card payment of one payout batch, which pays its creators directly.
  - `payoutBatch` object, nullable: The payout batch this payment paid for; null for a balance top-up.
    - `id` string
    - `campaignId` string, nullable
  - `feeCoveredByZernio` boolean: True for a `payout_batch` payment: Zernio pays the Stripe processing fee out of its transfer fee, so you are credited the whole charge.
  - `amountCents` integer: Gross amount charged
  - `stripeFeeCents` integer, nullable: Stripe processing fee you paid; null until Stripe reports it, 0 when Zernio covers it
  - `netCents` integer, nullable: Amount credited to your balance: gross minus the Stripe fee, or the whole charge when Zernio covers the fee; null until Stripe reports it
  - `status` 'pending' | 'succeeded' | 'failed' | 'expired': `pending` until the card is charged (or 3D Secure is finished) and credited. `expired` means it ended unpaid: cancelled, or 3D Secure left unfinished for 30 minutes. Only `pending` counts toward pendingTopupCents.
  - `createdAt` string, date-time
  - `succeededAt` string, date-time, nullable

## Other responses

- `400`: Invalid request
- `402`: Payment method or enterprise contract required: the authenticated account hit a billing gate before the connection could proceed. Switch on `reason` to render the right prompt: - `free_tier_exceeded`: the team has connected more accounts than the free tier allows. Add a payment method to continue (billed per additional connected account). - `twitter_passthrough`: connecting an X account requires a card on file from day one, because X API calls incur real per-call pass-through costs. Applies to the 1st X account, not only the 3rd+. - `enterprise_required`: the team's enterprise contract sets a connected-account cap and it has been reached. Self-service teams have NO cap (the $1/account rate continues at any scale). The user already has a card on file; this gate is about contract terms. - `card_verification_required`: the card on file was flagged at add time (prepaid, or issued in a different country than the billing address). A one-time verification charge of `details.verification_amount_cents` (USD) is pending; it is credited to the team's usage balance, not a fee. **What to do:** redirect the end-user to `dashboard_url`. - `free_tier_exceeded`, `twitter_passthrough`, `card_verification_required`: it opens the Zernio billing page (the add-payment-method drawer, or the verification step). The request succeeds once the card is on file (or verified, or paid). - `enterprise_required`: it opens the enterprise contact form (not the billing tab), to adjust the contract's limit.
- `403`: Refused (`insufficient_permissions`). One of: - A restricted API key without the `money` resource group. - A profile-scoped API key. Money leaves the whole team's balance, so moving it needs a full-access key or a signed-in session ("Moving money needs a full-access key or a signed-in session."). - A member or viewer, signed in or through a key they created. Only an owner, admin or billing admin moves money.
- `404`: Resource not found

## Changes

- **2026-10-29** `dbfaa35515ac`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/balance/top-ups/:topupId/confirm/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/c319eb5d95b6?raw)