# Pagamento na Meta

Fonte: https://lunahia.com.br/docs/pagamento-na-meta

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 template | A Meta recusa com `131042`. A mensagem vira `failed`, e o erro chega em `message.status` e em `GET /v1/messages/{id}`. |
| Mensagem recusada | A 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úmero | A 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úmero | `state` continua `REGISTERED`. O que muda é `awaitingPaymentSince`, que passa a ter a data. |
| A assinatura da Luna | Nã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](#solucao). O console mostra o aviso "Sem forma de pagamento na Meta" a partir desse campo.

> `true` quer dizer que há uma forma de pagamento ligada à conta, e não que ela está em dia: linha de crédito acima do limite e conta de pagamento sem moeda ainda causam o `131042`. A Luna não vê o cartão, não vê saldo e não intermedeia esse pagamento. O pagamento é do negócio com a Meta.

**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](https://lunahia.com.br/docs/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](https://lunahia.com.br/docs/erros#envio).

O evento de entrada na espera

```json
{
  "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úmero

```json
{
  "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
  "metaPhoneNumberId": "123456789012345",
  "state": "REGISTERED",
  "ready": true,
  "awaitingPaymentSince": "2026-10-13T12:00:00.000Z"
}
```

O erro na mensagem

```json
{
  "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" } }
    }
  ]
}
```

> `ready` não leva o pagamento em conta: ele diz que o número está registrado e com a inscrição confirmada. Um número com `ready: true` pode estar em espera por pagamento, e quem diz isso é `awaitingPaymentSince`.

## 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 final

```text
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 normal

```json
{
  "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"
  }
}
```

> **Não conte como resolvido antes de um envio passar.** Enquanto `awaitingPaymentSince` tiver data, o número segue em espera, mesmo que o seu cliente diga que já cadastrou. Para testar, envie uma mensagem: se a Meta aceitar, o evento sai. Se recusar de novo, o número continua em espera e nada novo é publicado.

## 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](https://lunahia.com.br/docs/custos-da-meta).

Os campos e os eventos citados estão na [referência da API](https://lunahia.com.br/docs/referencia).
