---
title: Auto top-up
description: Mantenha as carteiras dos clientes com saldo automático via cartão salvo ou PayPal — modos por uso e fixo, limites globais e tratamento de falhas.
url: https://nexcmp.com/pt/docs/billing/auto-top-up/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Auto top-up {#auto-top-up}

> **Onde encontrar no admin:** Finance › Payment channels › Fees & limits (`/payments/fees`), card **Wallet & top-up (Billing › Policy)**, section **Auto top-up (Stripe / PayPal)**. **Onde encontrar no portal:** Billing › Settings (`/billing?settings=1`).

## O que faz {#what-it-does}

Quando o saldo da carteira de um cliente fica muito baixo, o NexCMP cobra o seu [saved payment method](https://nexcmp.com/pt/docs/billing/saved-payment-methods/) e credita a carteira, para que os serviços em execução não sejam suspensos por falta de fundos. Uma tarefa em segundo plano verifica todos os clientes habilitados **a cada 5 minutos**.

## Requisitos {#requirements}

| Item | Requisito |
|---|---|
| Canal | [Stripe](https://nexcmp.com/pt/docs/billing/stripe/) e/ou [PayPal](https://nexcmp.com/pt/docs/billing/paypal/) configurados. |
| Método salvo | O cliente possui um cartão ou conta do PayPal salvos. |
| Site | Site principal ou site de revendedor cujo canal do Stripe/PayPal é coletado pela plataforma. |
| Chave global | **Auto top-up enabled** está ativado (ativado por padrão). |

## Como funciona {#how-it-works}

Após a **primeira recarga no Stripe ou PayPal** do cliente, o servidor salva a forma de pagamento e ativa a recarga automática no modo **By usage** — apenas se o próprio cliente nunca tiver configurado a recarga automática. Não há nenhuma caixa de seleção extra na tela de depósito; o servidor registra o horário, o endereço IP e o método como comprovação. Se o cliente desativar a recarga automática mais tarde, ela nunca será reativada automaticamente.

| Modo | Gatilho (quando o saldo estiver abaixo de...) | Valor cobrado |
|---|---|---|
| **By usage** (padrão após a primeira recarga) | o custo das próximas 24 horas de serviços em execução (VMs por hora mais renovações pré-pagas vencidas em 24 horas), mas nunca abaixo de **$5** | o custo de 24 horas arredondado para cima para o dólar inteiro, pelo menos a [minimum top-up](https://nexcmp.com/pt/docs/billing/minimum-top-up/), no máximo a recarga máxima e o limite diário |
| **Fixed amount** | o limite próprio do cliente ($1 a $500) | o valor do próprio cliente (do valor mínimo de recarga até $1,000, e superior ao limite) |

Sem nenhum serviço em execução no modo **By usage**, nada é cobrado.

O saldo comparado com o limite é o **dinheiro real na carteira**. Os créditos de serviço de códigos promocionais são mantidos separadamente e não contam (consulte [Promotions](https://nexcmp.com/pt/docs/billing/promotions/)).

A taxa é tratada como uma recarga normal: com **Customer pays top-up fee** ativado, o cartão é cobrado no valor mais a taxa e a carteira recebe o valor total; com ele desativado, a carteira recebe o valor menos a taxa.

## Configurar os limites globais {#configure-the-global-limits}

1. Abra **Finance › Payment channels › Fees & limits** (`/payments/fees`).
2. Em **Auto top-up (Stripe / PayPal)**, defina:

   | Configuração | Padrão | Intervalo | Significado |
   |---|---|---|---|
   | Auto top-up enabled | On | ativado ou desativado | Desativado interrompe todas as cobranças em segundo plano imediatamente. |
   | Limite padrão de recarga automática (USD, fallback do modo fixo) | $5.00 | $0 a $10,000 | Usado apenas como o limite inicial no modo fixo. |
   | Máximo de recargas automáticas por 24 h por cliente | 3 | 1 a 50 | Conta tentativas bem-sucedidas e pendentes. |
   | Teto do valor de recarga automática por 24 h por cliente (USD) | $500.00 | $0 a $1,000,000 | Total de cobranças automáticas em um dia contínuo. |

3. Clique em **Save Wallet & top-up**.

![Seção Auto top-up da página Fees and limits com o botão global e limites diários](https://nexcmp.com/pt/docs/images/billing/auto-top-up-01-limits.webp)

## O que o cliente vê {#what-the-customer-sees}

1. No portal, o cliente abre **Billing** e clica em **Settings**.
2. O painel mostra os métodos salvos, o botão de ligar/desligar, o modo (**By usage** ou **Fixed amount**), o uso atual estimado, a próxima cobrança e as **Recent automatic top-ups**.
3. Mudar para **Fixed amount** permite que eles insiram o limite e o valor. Desativar a chave interrompe as cobranças.

![Configurações de faturamento do cliente com recarga automática no modo By usage e as recargas automáticas recentes](https://nexcmp.com/pt/docs/images/billing/auto-top-up-02-portal.webp)

## Verificar {#verify}

1. Como cliente de teste, faça uma primeira recarga com um cartão de teste ([Stripe](https://nexcmp.com/pt/docs/billing/stripe/#verify)). Abra **Billing › Settings**: a recarga automática está ativada.
2. Execute uma pequena VM para que haja uso e reduza o saldo abaixo do limite (por exemplo, com **Customers › customer › Credit / debit**).
3. Em cerca de 5 minutos, uma cobrança é realizada. No cartão **Overview › Payment** do cliente, **Auto top-up history** mostra a tentativa com o status *Done*, e uma notificação de *Top-up received* é enviada.

## Limites e notas {#limits-notes}

- **Uma cobrança por queda.** Após uma cobrança, o job aguarda até que o saldo suba novamente acima do limite ou o tempo de espera termine: 1 hora após um sucesso, 24 horas após uma cobrança pendente, 30 minutos após um erro do sistema.
- **Limites diários.** Quando qualquer um dos limites diários é atingido, nenhuma cobrança é feita e uma linha *Daily limit reached* é registrada (no máximo uma vez a cada 6 horas).
- **Falhas.** Um cartão recusado, cartão expirado ou fundos insuficientes conta como falha no cartão. O job tenta novamente após 1 hora, depois 6 horas, depois 24 horas. **Após 3 falhas consecutivas no cartão, a recarga automática é desativada** e o cliente é notificado (*Auto top-up failed*). Um pagamento que exija a confirmação do cliente (por exemplo, 3-D Secure) não é contado como falha; o cliente é orientado a confirmá-lo.
- **Sem cobranças duplicadas.** Cada cobrança é solicitada de forma atômica por queda abaixo do limite e usa uma chave de idempotência no gateway.
- **Remover o cartão** desativa a recarga automática.
- **Revendedores.** Se um revendedor usar seu próprio canal de pagamento, o cliente não poderá ativar a recarga automática (HTTP 403 `feature_disabled`).

## Resolução de problemas {#troubleshooting}

| Sintoma | Causa | Correção |
|---|---|---|
| O cliente não consegue ativá-la: "Top up once with a card or PayPal" | Nenhum método salvo | Faça uma primeira recarga com cartão ou PayPal. |
| Erro `no_card` (422) | O gateway escolhido não possui método salvo | Escolha o gateway que possui um ou salve um método. |
| Erro `invalid_argument` no valor | Modo fixo fora dos intervalos permitidos | Limite de $1 a $500, valor entre a recarga mínima e $1,000, valor superior ao limite. |
| Nada é cobrado, embora o saldo esteja baixo | Botão global desligado, nenhum serviço em execução no modo By usage, limite diário atingido ou a cobrança anterior ainda está aguardando | Verifique o botão, o histórico e os limites. |
| "N tentativas consecutivas com falha — a recarga automática é desativada após 3" | O cartão continua falhando | O cliente substitui o cartão por um novo depósito. |
| Status *Precisa da sua confirmação* | O banco exige 3-D Secure | O cliente conclui uma recarga normal uma vez. |