> ## 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. # Pagar número extra > Paga, na hora, a cobrança pendente do número extra de UM número e libera o envio por ele. Um número extra — um número acima da capacidade que o workspace já pagou — é cobrado quando o número conecta pela PRIMEIRA vez, e não quando é criado. Quando essa cobrança é recusada (cartão recusado, sem saldo), o número continua conectado, mas o envio por ele fica bloqueado: `POST /v1/messages/send` responde `409 NUMBER_BLOCKED` com `reason: "extra_charge_unpaid"`, e o `extraChargeUnpaidSince` vem preenchido no número em `GET /v1/numbers` e `GET /v1/numbers/{id}`. Esta chamada compra esse número extra — primeiro os créditos da carteira, o restante no cartão salvo — e responde `status: "paid"`. Quando não há nada a pagar pelo número, responde `status: "not_required"` e não cobra nada, então pode ser repetida sem risco. Sem corpo. Uma recarga da carteira ou um cartão recém-salvo retentam a cobrança sozinhos, sem esta chamada. Efeito colateral real: ela cobra. No plano Grátis esta chamada nunca cobra: responde `402 PLAN_NUMBER_LIMIT_REACHED` até o número extra ser comprado de forma explícita ou o plano ser trocado. **Exige uma chave com escopo de tenant.** Com um token OAuth / MCP, só o Proprietário do workspace pode chamá-la (`billing:manage`). ## OpenAPI ````yaml openapi.pt.json POST /v1/numbers/{id}/pay openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `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: Pagar cobrança do número extra description: >- Paga, na hora, a cobrança pendente do número extra de UM número e libera o envio por ele. Um número extra — um número acima da capacidade que o workspace já pagou — é cobrado quando o número conecta pela PRIMEIRA vez, e não quando é criado. Quando essa cobrança é recusada (cartão recusado, sem saldo), o número continua conectado, mas o envio por ele fica bloqueado: `POST /v1/messages/send` responde `409 NUMBER_BLOCKED` com `reason: "extra_charge_unpaid"`, e o `extraChargeUnpaidSince` vem preenchido no número em `GET /v1/numbers` e `GET /v1/numbers/{id}`. Esta chamada compra esse número extra — primeiro os créditos da carteira, o restante no cartão salvo — e responde `status: "paid"`. Quando não há nada a pagar pelo número, responde `status: "not_required"` e não cobra nada, então pode ser repetida sem risco. Sem corpo. Uma recarga da carteira ou um cartão recém-salvo retentam a cobrança sozinhos, sem esta chamada. Efeito colateral real: ela cobra. No plano Grátis esta chamada nunca cobra: responde `402 PLAN_NUMBER_LIMIT_REACHED` até o número extra ser comprado de forma explícita ou o plano ser trocado. **Exige uma chave com escopo de tenant.** Com um token OAuth / MCP, só o Proprietário do workspace pode chamá-la (`billing:manage`). operationId: post_numbers_id_pay parameters: - name: id in: path required: true description: ID do número WhatsApp — o `id` devolvido por `GET /v1/numbers`. schema: type: string example: num_01HZX... responses: '200': description: >- Não há mais nada a pagar por este número. `paid`: um número extra foi comprado e o bloqueio de envio foi removido. `not_required`: não havia nada a pagar por este número (nunca foi bloqueado, já foi pago, ou a sua capacidade passou a cobri-lo) e nada foi cobrado. 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: Header `x-api-key` / `x-api-key-id` ausente ou inválido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '402': description: >- A cobrança foi recusada e o número continua bloqueado para envio. Decida pelo `code`, não pelo status. `INSUFFICIENT_FUNDS`: a carteira não cobre o `proratedTotal` e não há cartão salvo utilizável; nada é cobrado e os créditos já descontados são devolvidos. `PAYMENT_FAILED`: a cobrança foi tentada e não se concluiu; o `declineCode` só vem quando o emissor do cartão recusou. O `error` é uma mensagem legível, em português. `PLAN_NUMBER_LIMIT_REACHED`: o workspace está no plano Grátis, que nunca compra um número extra sozinho — nada foi tentado; compre o número extra de forma explícita (`POST /v1/subscription/extra-numbers` com `confirm: true`, ou pelo painel) ou suba de plano, e chame de novo: a resposta será `not_required`. Esse corpo traz só `error` (uma frase bilíngue `English | Português`) e `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: O valor proporcional que foi tentado. currency: type: string example: BRL walletReason: type: string enum: - NO_CARD description: Só em INSUFFICIENT_FUNDS. declineCode: type: string description: >- Só em PAYMENT_FAILED, e só quando o emissor do cartão recusou: o próprio código de recusa da bandeira, literal. 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 (plano Grátis) 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: >- A credencial não pode pagar. `NUMBER_SCOPE_NOT_ALLOWED`: uma chave com escopo de número foi usada neste endpoint exclusivo de tenant. `PERMISSION_DENIED`: um token OAuth / MCP de um usuário que não é o Proprietário do workspace (`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: >- Este número não existe neste workspace. O `error` é uma frase bilíngue `English | Português`. 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: >- Outro pagamento dos números deste workspace está em andamento, então esta chamada não fez nada. Chame de novo em alguns segundos — a resposta pode ser `not_required` se aquele pagamento já cobriu este número. O `error` é uma frase bilíngue `English | Português`. 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: Limite de taxa excedido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Too many requests '502': description: >- Não foi possível confirmar a cobrança com o processador de pagamento (falha de rede, um 5xx, uma resposta perdida). Nada foi recusado: a cobrança fica pendente e é retentada automaticamente a cada 15 minutos. Um número que já estava bloqueado continua bloqueado até uma retentativa passar; uma falha do processador nunca bloqueia um número por si só. A cobrança pode ter sido concluída no processador com a resposta perdida — confira seu extrato antes de pagar de novo. O corpo traz só `error` (uma frase bilíngue `English | Português`) e `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: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.