Skip to main content

​
Pagar a cobrança do número extra de um número

Um número extra é um número de WhatsApp acima da capacidade que o seu workspace já pagou. Ele é cobrado quando o número conecta pela primeira vez — veja Números extras. Quando essa cobrança é recusada (cartão recusado, sem saldo), o número continua conectado, mas o envio por ele fica bloqueado até o pagamento. POST /v1/numbers/{id}/pay cobra na hora — primeiro os créditos da carteira, o restante no cartão salvo — e libera o envio.
Resposta:
Exige uma chave com escopo de tenant — a mesma regra de POST /v1/subscription/extra-numbers. Com um token OAuth / MCP, só o Proprietário do workspace pode pagar (billing:manage) — caso contrário, 403 PERMISSION_DENIED.
Esta chamada cobra. Com créditos na carteira ou um cartão salvo, o valor proporcional de um número extra é cobrado na hora.

​
Quando usar

  • Quando GET /v1/numbers ou GET /v1/numbers/{id} mostra extraChargeUnpaidSince preenchido em um número.
  • Quando POST /v1/messages/send responde 409 NUMBER_BLOCKED com reason: "extra_charge_unpaid".
  • Logo depois de corrigir o que recusou a cobrança — um cartão novo, por exemplo — sem querer esperar.
Você não precisa chamar este endpoint. Em um plano pago, uma recarga da carteira ou um cartão recém-salvo retentam, automaticamente, a cobrança de todos os números bloqueados do workspace. No plano Free esta chamada não consegue pagar — veja PLAN_NUMBER_LIMIT_REACHED abaixo. No painel, o proprietário do workspace também pode usar Pagar agora na página Números.

​
Como saber que um número está bloqueado

GET /v1/numbers e GET /v1/numbers/{id} trazem dois campos em cada número: Esses campos não fazem parte de health. Um número bloqueado mantém o seu state, pode ter health.sendable: true, e extra_charge_unpaid nunca aparece em health.code. Veja Listar e obter números.

​
Parâmetros da requisição

Sem corpo.

​
Resposta

​
Sucesso (200)

​
Erros

Decida pelo code, nunca pelo status HTTP: três das recusas são 402. Corpo do erro: { "error": "<mensagem>", "code": "<CÓDIGO>", … }.
  • Os corpos de PAYMENT_FAILED e INSUFFICIENT_FUNDS trazem também proratedTotal e currency — o valor que foi tentado. O INSUFFICIENT_FUNDS acrescenta walletReason. O error deles é uma mensagem legível, em português.
  • Os corpos de PLAN_NUMBER_LIMIT_REACHED, 502, 409 e 404 trazem só error e code. O error deles é uma frase bilíngue, English | Português.
Depois de um 402, o número continua bloqueado. Depois de um 502, nada muda: um número que já estava bloqueado continua bloqueado até uma retentativa passar, e uma falha do processador nunca bloqueia um número por si só.
502 PAYMENT_PROVIDER_ERROR não quer dizer “nada foi cobrado”. A requisição ao processador falhou ou a resposta dele se perdeu, então a cobrança pode ter se concluído do lado dele. A retentativa automática repete o mesmo pedido de cobrança, o que permite ao processador reconhecer uma cobrança que já fez em vez de fazê-la de novo. Confira seu extrato antes de pagar de novo.

​
O que acontece se continuar sem pagamento

  • Um número conectado por QR Code que fica 7 dias sem pagamento é desconectado em extraChargeDisconnectAt: o aparelho é deslogado e o número deixa de contar na sua capacidade. Você recebe um lembrete 2 dias antes. Conectá-lo de novo é uma nova primeira conexão, cobrada como qualquer outra.
  • Um número da Meta Cloud API nunca é desconectado. Ele fica bloqueado para envio até o pagamento.

​
Notas

  • A chamada é idempotente: quando não há mais nada a pagar, ela responde not_required e não cobra nada.
  • As mensagens que estavam na fila antes do bloqueio não são enviadas: elas falham e aparecem com NUMBER_BLOCKED em Códigos de Erro do Log. Envie de novo depois de pagar.
  • O recebimento não é afetado. O bloqueio é só de envio.