> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Pay extra-number charge > Pays, now, the pending extra-number charge of ONE number and lifts its sending block. An extra number — a number past the capacity the workspace has paid for — is charged when the number FIRST connects, not when it is created. When that charge is refused (card declined, no funds) the number stays connected but sending from it is blocked: `POST /v1/messages/send` answers `409 NUMBER_BLOCKED` with `reason: "extra_charge_unpaid"`, and `extraChargeUnpaidSince` is set on the number in `GET /v1/numbers` and `GET /v1/numbers/{id}`. This call buys that one extra number — wallet credits first, the remainder on the saved card — and answers `status: "paid"`. When nothing is owed for the number it answers `status: "not_required"` and charges nothing, so it is safe to repeat. No request body. A wallet top-up or a newly saved card retries the charge on its own, without this call. Real side effect: it charges. On the Free plan this call never charges: it answers `402 PLAN_NUMBER_LIMIT_REACHED` until the extra number is bought explicitly or the plan is upgraded. **Requires a tenant-scoped key.** With an OAuth / MCP token, only the workspace Owner may call it (`billing:manage`). ## OpenAPI ````yaml openapi.json POST /v1/numbers/{id}/pay openapi: 3.1.0 info: title: Pilot Status API version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- Public REST API for Pilot Status. Authenticate with the `x-api-key: ps_...` header (or `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/numbers/{id}/pay: post: tags: - Numbers summary: Pay extra-number charge description: >- Pays, now, the pending extra-number charge of ONE number and lifts its sending block. An extra number — a number past the capacity the workspace has paid for — is charged when the number FIRST connects, not when it is created. When that charge is refused (card declined, no funds) the number stays connected but sending from it is blocked: `POST /v1/messages/send` answers `409 NUMBER_BLOCKED` with `reason: "extra_charge_unpaid"`, and `extraChargeUnpaidSince` is set on the number in `GET /v1/numbers` and `GET /v1/numbers/{id}`. This call buys that one extra number — wallet credits first, the remainder on the saved card — and answers `status: "paid"`. When nothing is owed for the number it answers `status: "not_required"` and charges nothing, so it is safe to repeat. No request body. A wallet top-up or a newly saved card retries the charge on its own, without this call. Real side effect: it charges. On the Free plan this call never charges: it answers `402 PLAN_NUMBER_LIMIT_REACHED` until the extra number is bought explicitly or the plan is upgraded. **Requires a tenant-scoped key.** With an OAuth / MCP token, only the workspace Owner may call it (`billing:manage`). operationId: post_numbers_id_pay parameters: - name: id in: path required: true description: WhatsApp number id — the `id` returned by `GET /v1/numbers`. schema: type: string example: num_01HZX... responses: '200': description: >- Nothing is owed for this number any more. `paid`: one extra number was bought and the sending block is lifted. `not_required`: nothing was owed for this number (it was never blocked, it was already paid, or your capacity now covers it) and nothing was charged. content: application/json: schema: type: object properties: ok: type: boolean status: type: string enum: - paid - not_required examples: paid: summary: paid value: ok: true status: paid notRequired: summary: not_required value: ok: true status: not_required '401': description: Missing or invalid `x-api-key` / `x-api-key-id` header content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '402': description: >- The charge was refused and the number stays blocked for sending. Branch on `code`, not on the status. `INSUFFICIENT_FUNDS`: the wallet does not cover `proratedTotal` and there is no usable saved card; nothing is charged and any credits taken are put back. `PAYMENT_FAILED`: the charge was attempted and did not complete; `declineCode` is present only when the card issuer declined. `error` is a human-readable message in Portuguese. `PLAN_NUMBER_LIMIT_REACHED`: the workspace is on the Free plan, which never buys an extra number by itself — nothing was attempted; buy the extra number explicitly (`POST /v1/subscription/extra-numbers` with `confirm: true`, or the dashboard) or move up a plan, then call again and it answers `not_required`. This body carries only `error` (a bilingual `English | Português` sentence) and `code`. content: application/json: schema: type: object properties: error: type: string code: type: string enum: - INSUFFICIENT_FUNDS - PAYMENT_FAILED - PLAN_NUMBER_LIMIT_REACHED proratedTotal: type: number description: The prorated amount that was attempted. currency: type: string example: BRL walletReason: type: string enum: - NO_CARD description: Only on INSUFFICIENT_FUNDS. declineCode: type: string description: >- Only on PAYMENT_FAILED, and only when the card issuer declined: the card network's own decline code, verbatim. example: insufficient_funds examples: insufficientFunds: summary: INSUFFICIENT_FUNDS value: error: >- Saldo insuficiente na carteira e cartão indisponível para cobrar o número extra. Adicione créditos ou um cartão. code: INSUFFICIENT_FUNDS proratedTotal: 14.95 currency: BRL walletReason: NO_CARD paymentFailed: summary: PAYMENT_FAILED value: error: Seu cartão não tem saldo suficiente. code: PAYMENT_FAILED proratedTotal: 14.95 currency: BRL declineCode: insufficient_funds freePlan: summary: PLAN_NUMBER_LIMIT_REACHED (Free plan) value: error: >- The Free plan includes one number. Buy an extra number or upgrade the plan to use this one. | O plano Grátis inclui um número. Compre um número extra ou faça upgrade do plano para usar este. code: PLAN_NUMBER_LIMIT_REACHED '403': description: >- The credential may not pay. `NUMBER_SCOPE_NOT_ALLOWED`: a number-scoped key was used on this tenant-only endpoint. `PERMISSION_DENIED`: an OAuth / MCP token whose user is not the workspace Owner (`billing:manage`). content: application/json: schema: type: object properties: error: type: string code: type: string examples: numberScopedKey: summary: NUMBER_SCOPE_NOT_ALLOWED value: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED permissionDenied: summary: PERMISSION_DENIED value: error: >- Your workspace role does not allow this action (billing:manage). code: PERMISSION_DENIED '404': description: >- No such number in this workspace. `error` is a bilingual `English | Português` sentence. content: application/json: schema: type: object properties: error: type: string code: type: string enum: - NUMBER_NOT_FOUND example: error: Number not found. | Número não encontrado. code: NUMBER_NOT_FOUND '409': description: >- Another payment for this workspace's numbers is running, so this call did nothing. Call again in a few seconds — it may answer `not_required` if that payment covered this number. `error` is a bilingual `English | Português` sentence. content: application/json: schema: type: object properties: error: type: string code: type: string enum: - PAYMENT_IN_PROGRESS example: error: >- A payment for this workspace's numbers is already being processed. Try again in a few seconds. | Um pagamento dos números deste workspace já está em andamento. Tente de novo em alguns segundos. code: PAYMENT_IN_PROGRESS '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Too many requests '502': description: >- The charge could not be confirmed with the payment processor (network failure, a 5xx, a lost response). Nothing was refused: the charge stays pending and is retried automatically every 15 minutes. A number that was already blocked stays blocked until a retry goes through; a processor failure never blocks a number by itself. The charge may have completed on the processor's side with the response lost — check your statement before paying again. The body carries only `error` (a bilingual `English | Português` sentence) and `code`. content: application/json: schema: type: object properties: error: type: string code: type: string enum: - PAYMENT_PROVIDER_ERROR example: error: >- We could not confirm the charge with the payment processor. It is retried automatically; check your statement before paying again. | Não conseguimos confirmar a cobrança com o processador de pagamento. Ela é retentada automaticamente; confira seu extrato antes de pagar de novo. code: PAYMENT_PROVIDER_ERROR components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your ps_ API key apiKeyId: type: apiKey in: header name: x-api-key-id description: API key id (alternative to x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.