LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Payment at Meta

Use with AI

Meta charges WhatsApp usage to the business that owns the number, on its payment method. When that method is missing or has a problem, Meta refuses sends with error 131042. Luna marks the number, announces it by event and says what to do. Whoever fixes it is the account owner, at Meta.

What happens when it is missing#

Meta refuses the send with error 131042. The number stays connected and registered, and Luna does not switch it off. None of this is a platform failure: something is missing on the side of the business that owns the account.

WhatWith the number waiting
Free-form message or templateMeta refuses with 131042. The message becomes failed, and the error arrives in message.status and in GET /v1/messages/{id}.
Refused messageLuna does not retry it and does not resend it on its own. Your system resends it, once the payment is fixed.
What Meta sends to the numberLuna delivers it as usual. The wait does not switch off the number or the event subscription on Luna’s side.
The number’s statestate stays REGISTERED. What changes is awaitingPaymentSince, which now carries the date.
Luna’s subscriptionIt does not change. Luna charges for the plan’s number capacity, and a waiting number remains configured capacity.

Know before the first failure#

Since October 1, 2026 Meta delivers each number’s service messages up to the free allowance of 1,000 a month, and, if the business’s WhatsApp account has no payment method, stops delivering the following ones. Finding that out through error 131042 means finding out with the agent already silent. So Luna reads the business account’s primary_funding_id and currency: at connection time and then every hour, within Meta’s call limit. A missing primary_funding_id is Meta’s own rule for "the account has no payment method".

The result is in GET /v1/business-accounts and in each number’s waba object (GET /v1/numbers and GET /v1/numbers/{id}): paymentMethodOnMeta is true, false, or null while Luna has not read it yet, and currency is the currency Meta reported for the account. With false, ask the account owner to register the payment method in Meta’s WhatsApp Manager, as in How to fix it. The console shows the "No payment method at Meta" warning from that field.

The webhook notice, without waiting for the refusal. When the read finds the account with no payment method, Luna publishes number.action_required for each number of the account, with the payment_method_missing reason in the reasons list; when the payment method shows up, it publishes number.action_resolved. The event goes out within a few minutes of the read, once per transition. It is not number.payment_required: that one only goes out when Meta refuses a send (131042, below). If both things happen, reasons carries only payment_required, the stronger reason, and you do not get two notices for the same fact.

Check now. Did your customer say they registered the card? POST /v1/business-accounts/{id}/payment-method/check reads from Meta right away, without waiting for the next read (the id is the one from GET /v1/business-accounts; the key needs the numbers:read scope). The response carries paymentMethodOnMeta, currency, checkedAt and reason: checked (read now), recent (the last read is under 60 seconds old and was returned without calling Meta), busy (the Meta call budget for this account is at its limit; try again in a few minutes) or failed (Meta did not answer; the value is the previous one). The limit exists because these reads come out of the same account call budget the connection uses. The console has the "Check now" button on the "Pagamento na Meta" card and on the number detail. The event goes out the usual way, on the next pass of the notices loop.

How to detect it#

Meta has no payment field or webhook, and Luna does not look the state up: the only signal is the error in the response to a send. Luna turns that signal into three things you can read.

  1. The number field. awaitingPaymentSince in GET /v1/numbers and in GET /v1/numbers/{id} carries the instant of the first refusal, or null when there is no wait.
  2. The number.payment_required event. It is sent once, when the number enters the wait, and not for every refused message. See Receive events.
  3. The error on the message. Each refused message arrives in message.status with status: "failed" and error_code: 131042, and GET /v1/messages/{id} returns the error with the explanation and the acaoRecomendada. See Errors.
The event for entering the waitJSON
{
  "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"
  }
}
The field on the numberJSON
{
  "id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
  "metaPhoneNumberId": "123456789012345",
  "state": "REGISTERED",
  "ready": true,
  "awaitingPaymentSince": "2026-10-13T12:00:00.000Z"
}
The error on the messageJSON
{
  "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" } }
    }
  ]
}

Causes#

Meta’s 131042 error covers more than one situation, and Meta does not say which one is your customer’s. The causes it lists:

  • There is no payment method linked to the business’s WhatsApp account.
  • The payment account exists, but it is not linked to the WhatsApp account.
  • The account’s credit line is inactive or above its limit.
  • The WhatsApp account was deleted or suspended.
  • The payment account’s time zone or currency is not set.
  • A request to pay on behalf of another company is pending or was denied.

How to fix it#

Whoever fixes it is the business that owns the WhatsApp account, and nobody else: the payment is between it and Meta. Ask your customer to open Meta’s WhatsApp Manager, go to the Billing Hub of their WhatsApp account, and register or fix the payment method, checking the causes above. A text you can send them:

Suggested message to the end customerTexto
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.

Once they have fixed it, send again. Messages refused during the wait are not resent on their own: resend the ones that still matter.

How to know it is back#

Meta does not announce when payment is fixed, and there is no lookup. The only signal is a send that is accepted again. When that happens, awaitingPaymentSince goes back to null and Luna publishes number.payment_resolved, once.

The event for being back to 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"
  }
}

What Luna does not do#

  • It does not charge that payment, does not advance it and does not intermediate it. Luna is a Tech Provider and has no credit line: that line is a requirement for Meta Solution Partners, which is not the case here.
  • It does not look the payment state up: Meta offers no such lookup.
  • It does not mark the number as fixed on its own. The mark only goes away when a send is accepted.
  • It does not resend the refused messages.
  • It has no credit, top-up or payment route. What Meta charges is in Meta costs.

The fields and events mentioned are in the API reference.