LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Pagamento na Meta

Usar com IA

A Meta cobra o uso do WhatsApp do negócio dono do número, no método de pagamento dele. Quando esse método falta ou tem problema, a Meta recusa os envios com o erro 131042. A Luna marca o número, avisa por evento e diz o que fazer. Quem resolve é o dono da conta, na Meta.

O que acontece quando falta#

A Meta recusa o envio com o erro 131042. O número continua conectado e registrado, e a Luna não o desliga. Nada disso é falha da plataforma: falta algo do lado do negócio dono da conta.

O quêCom o número em espera
Mensagem livre ou templateA Meta recusa com 131042. A mensagem vira failed, e o erro chega em message.status e em GET /v1/messages/{id}.
Mensagem recusadaA Luna não tenta de novo e não a reenvia sozinha. Quem reenvia é o seu sistema, depois que o pagamento for regularizado.
O que a Meta enviar para o númeroA Luna entrega como sempre. A espera não desliga o número nem a assinatura de eventos do lado da Luna.
O estado do númerostate continua REGISTERED. O que muda é awaitingPaymentSince, que passa a ter a data.
A assinatura da LunaNão muda. A Luna cobra a capacidade de números do plano, e o número em espera continua sendo capacidade configurada.

Saber antes da primeira falha#

Desde 1º de outubro de 2026 a Meta entrega as mensagens de serviço de cada número até a franquia gratuita de 1.000 por mês, e, se a conta de WhatsApp do negócio não tem forma de pagamento, deixa de entregar as seguintes. Descobrir isso pelo erro 131042 é descobrir com o agente já mudo. Por isso a Luna lê, da conta de negócio, o primary_funding_id e a currency: na conexão e depois de hora em hora, dentro do limite de chamadas da Meta. Ausência de primary_funding_id é a regra da própria Meta para "a conta não tem forma de pagamento".

O resultado está em GET /v1/business-accounts e no objeto waba de cada número (GET /v1/numbers e GET /v1/numbers/{id}): paymentMethodOnMeta é true, false ou null enquanto a Luna ainda não leu, e currency é a moeda que a Meta informou para a conta. Com false, peça ao dono da conta que cadastre a forma de pagamento no WhatsApp Manager da Meta, como em Como resolver. O console mostra o aviso "Sem forma de pagamento na Meta" a partir desse campo.

O aviso por webhook, sem esperar a recusa. Quando a leitura acha a conta sem forma de pagamento, a Luna publica number.action_required para cada número da conta, com o motivo payment_method_missing na lista reasons; quando a forma de pagamento aparece, publica number.action_resolved. O evento sai em até alguns minutos da leitura, uma vez por passagem. Não é o number.payment_required: este só sai quando a Meta recusa um envio (131042, abaixo). Se as duas coisas acontecem, reasons traz só payment_required, o motivo mais forte, e você não recebe dois avisos pelo mesmo fato.

Conferir agora. O seu cliente disse que cadastrou o cartão? POST /v1/business-accounts/{id}/payment-method/check lê na Meta na hora, sem esperar a próxima leitura (o id é o de GET /v1/business-accounts; a chave precisa do escopo numbers:read). A resposta traz paymentMethodOnMeta, currency, checkedAt e reason: checked (leu agora), recent (a última leitura tem menos de 60 segundos e foi devolvida sem chamar a Meta), busy (o orçamento de chamadas da Meta para esta conta está no limite; tente de novo em alguns minutos) ou failed (a Meta não respondeu; o valor é o anterior). O limite existe porque estas leituras saem do mesmo orçamento de chamadas da conta que a conexão usa. O console tem o botão "Conferir agora" no cartão "Pagamento na Meta" e no detalhe do número. O evento sai pelo caminho de sempre, na leitura seguinte do laço de avisos.

Como detectar#

A Meta não tem campo nem webhook de pagamento, e a Luna não consulta o estado dele: o único sinal é o erro na resposta a um envio. A Luna transforma esse sinal em três coisas que você pode ler.

  1. O campo do número. awaitingPaymentSince em GET /v1/numbers e em GET /v1/numbers/{id} traz o instante da primeira recusa, ou null quando não há espera.
  2. O evento number.payment_required. Sai uma vez, quando o número entra na espera, e não a cada mensagem recusada. Veja Receber eventos.
  3. O erro na mensagem. Cada mensagem recusada chega em message.status com status: "failed" e error_code: 131042, e GET /v1/messages/{id} devolve o erro com a explicação e a acaoRecomendada. Veja Erros.
O evento de entrada na esperaJSON
{
  "version": "2026-11-10",
  "event_id": "50a49cee4b216c529e3f7cdd0be525f8902ff6aff66439e004dfe34a0c979fcf",
  "event_type": "number.payment_required",
  "occurred_at": "2026-10-13T12:00:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841",
    "awaiting_payment_since": "2026-10-13T12:00:00.000Z"
  }
}
O campo no númeroJSON
{
  "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
  "metaPhoneNumberId": "123456789012345",
  "state": "REGISTERED",
  "ready": true,
  "awaitingPaymentSince": "2026-10-13T12:00:00.000Z"
}
O erro na mensagemJSON
{
  "id": "ae60f288-7565-4315-a440-3663e9c231e1",
  "status": "failed",
  "erros": [
    {
      "codigo": 131042,
      "categoria": "estado_de_produto",
      "mensagem": "Há um problema com o método de pagamento da conta comercial do negócio final na Meta. O número segue configurado; o que falta é do lado do negócio final.",
      "acaoRecomendada": "O negócio dono da conta de WhatsApp precisa cadastrar ou regularizar o método de pagamento no WhatsApp Manager da Meta (Billing Hub). A Luna não intermedeia esse pagamento e não consulta a situação dele: a Meta não oferece essa consulta. Depois que ele regularizar, envie de novo: a mensagem recusada não é reenviada sozinha, e o número volta ao normal quando um envio for aceito.",
      "original": { "error": { "code": 131042, "type": "OAuthException", "fbtrace_id": "AbCdEfGhIjK" } }
    }
  ]
}

Causas#

O erro 131042 da Meta cobre mais de uma situação, e a Meta não diz qual delas é a do seu cliente. As causas que ela lista:

  • Não há método de pagamento ligado à conta de WhatsApp do negócio.
  • A conta de pagamento existe, mas não está ligada à conta de WhatsApp.
  • A linha de crédito da conta está inativa ou acima do limite.
  • A conta de WhatsApp foi apagada ou suspensa.
  • Fuso horário ou moeda da conta de pagamento não estão definidos.
  • Um pedido de pagamento em nome de outra empresa está pendente ou foi negado.

Como resolver#

Quem resolve é o negócio dono da conta de WhatsApp, e ninguém mais: o pagamento é entre ele e a Meta. Peça ao seu cliente para entrar no WhatsApp Manager da Meta, abrir o Billing Hub da conta de WhatsApp dele e cadastrar ou regularizar o método de pagamento, conferindo as causas acima. Um texto que você pode mandar a ele:

Sugestão de mensagem ao cliente finalTexto
O envio de mensagens do seu WhatsApp foi pausado pela Meta porque a conta não tem um método de pagamento válido. Entre no WhatsApp Manager da Meta, abra o Billing Hub da sua conta de WhatsApp e cadastre ou regularize o cartão ou a forma de pagamento. Avise a gente quando terminar.

Depois que ele regularizar, envie de novo. As mensagens recusadas durante a espera não são reenviadas sozinhas: reenvie as que ainda interessam.

Como saber que voltou#

A Meta não avisa quando o pagamento é regularizado, e não existe consulta. O único sinal é um envio que volta a ser aceito. Quando isso acontece, awaitingPaymentSince volta a null e a Luna publica number.payment_resolved, uma vez.

O evento de volta ao normalJSON
{
  "version": "2026-11-10",
  "event_id": "6a956161dd17bb975533e63286e811ae62b77b3350107945952b2e53f0a9d1e2",
  "event_type": "number.payment_resolved",
  "occurred_at": "2026-10-13T15:30:00.000Z",
  "phone_number_id": "123456789012345",
  "number": {
    "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
    "phone_number_id": "123456789012345",
    "display_number": "+55 11 90000-0000",
    "external_id": "cliente-8841"
  }
}

O que a Luna não faz#

  • Não cobra esse pagamento, não o adianta e não o intermedeia. A Luna é Tech Provider e não tem linha de crédito: essa linha é requisito de Solution Partner da Meta, e não é o caso.
  • Não consulta o estado do pagamento: a Meta não oferece essa consulta.
  • Não marca o número como resolvido por conta própria. A marca só sai quando um envio é aceito.
  • Não reenvia as mensagens recusadas.
  • Não tem rota de crédito, recarga nem pagamento. O que a Meta cobra está em Custos da Meta.

Os campos e os eventos citados estão na referência da API.