Recarregamento Automático de Subcontas (Fornecedor de Pagamento Personalizado) #

Se preferir gerir os pagamentos de crédito das subcontas através do seu próprio fornecedor em vez do Stripe (transferências bancárias, gateways de pagamento locais, sistemas de faturação personalizados), a plataforma disponibiliza um par de webhook + API para que possa executar todo o ciclo de cobrança e concessão por si próprio. A visão geral não técnica encontra-se na página Contas de Agência; esta página abrange o payload exato do webhook e a chamada de API que deve efetuar para conceder créditos posteriormente.

O webhook é apenas uma das formas de pagamento dos carregamentos automáticos. Se ligou o Stripe ou o PayPal no Modo SaaS, a plataforma cobra diretamente ao cartão ou conta PayPal guardada do cliente e atribui os créditos, pelo que não há nada nesta página que precise de configurar. Continue a ler apenas se pretender processar o pagamento por conta própria.

O fluxo num relance #

1. O saldo de crédito de uma subconta desce abaixo do seu limite de recarregamento automático.
2. A plataforma chama o seu URL de webhook com os detalhes da subconta e quantos créditos são necessários.
3. O seu servidor cobra ao cliente através do fornecedor que utilizar.
4. O seu servidor chama a API de Concessão de Créditos para adicionar créditos a essa subconta.
5. O seu servidor responde 200 para confirmar a receção do webhook.

1. Webhook: agency_sub_account_auto_recharge #

Configure o URL do webhook clicando em SaaS Mode na barra lateral principal, escolhendo Use a Custom Payment Provider Instead (ou, uma vez configurado, abrindo o cartão Custom Payment Provider) e preenchendo o campo Auto-Recharge Webhook.

Quando é acionado #

Quando o saldo de crédito de uma subconta desce abaixo do seu limite de recarregamento automático configurado.

Payload #

{
  "event": "agency_sub_account_auto_recharge",
  "sub_account_id": "<sub-account-id>",
  "sub_account_email": "customer@example.com",
  "sub_account_name": "John Doe",
  "agency_id": "<agency-id>",
  "credits_requested": 500,
  "current_balance": 42,
  "threshold": 100,
  "price_per_credit_cents": 10,
  "price_per_credit_currency": "usd",
  "total_amount_cents": 5000,
  "timestamp": "2026-04-13T12:00:00.000Z",
  "idempotency_key": "auto_recharge_abc123_1681387200000"
}

Notas importantes #

• Período de arrefecimento de 5 minutos — Após uma tentativa de recarregamento para uma subconta, a plataforma não enviará outro webhook para essa subconta durante pelo menos 5 minutos, mesmo que o saldo desça ainda mais. Isto evita cobranças duplicadas durante o processamento.
• Utilize a chave de idempotência — Verifique sempre idempotency_key antes de conceder créditos. Se o seu servidor falhar após conceder créditos mas antes de responder, a plataforma poderá reenviar o webhook na próxima descida de crédito.
• As falhas são seguras e autorreparáveis — Se o seu URL de webhook estiver inacessível ou devolver um erro, não são concedidos créditos. A plataforma continua a reenviar o webhook (uma vez por período de arrefecimento de 5 minutos) enquanto a subconta permanecer abaixo do limite — não requer que o saldo suba acima do limite e desça novamente primeiro. Uma única cobrança falhada já não pode deixar uma subconta permanentemente sem recarregamento.
• Defina o seu montante de recarregamento igual ou superior ao limite — O seu montante de recarregamento configurado deve ser maior ou igual ao limite de recarregamento automático, para que um recarregamento restaure sempre o saldo acima do limite. (Se precisar de corrigir uma subconta que ficou muito abaixo do limite, a plataforma completa o valor em falta automaticamente — veja credits_requested acima.)

2. API de Concessão de Créditos #

Após o seu servidor ter processado o pagamento, chame este endpoint para adicionar os créditos à subconta.

Pedido #

POST https://api.dmchamp.com/v1/subaccounts/credits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "email": "customer@example.com",
  "amount": 500,
  "description": "Auto-recharge via webhook"
}

Autenticação: Envie a sua chave de API num cabeçalho de pedido — seja X-API-Key: YOUR_API_KEY ou Authorization: Bearer YOUR_API_KEY. Os cabeçalhos são a forma recomendada, porque uma chave no URL acaba por ficar no histórico do navegador, nos registos de proxy e nos registos de acesso ao servidor. O parâmetro de consulta ?apiKey=YOUR_API_KEY e um campo apiKey no corpo JSON também continuam a funcionar, para que as integrações mais antigas continuem a funcionar sem alterações.

Resposta #

{
  "success": true,
  "sub_account_id": "abc123xyz",
  "credits_added": 500,
  "new_balance": 542
}

O que acontece aos créditos concedidos na reposição mensal #

Isto depende da forma como a subconta está configurada:

• Revenda (a subconta paga-lhe pelos créditos): os créditos que concede aqui são registados como créditos comprados e transitam todos os meses. Tudo o que a subconta não gastou permanece no saldo.
• Atribuição (atribui à subconta um plafond mensal): o saldo é reposto para o plafond mensal na data de reposição, pelo que qualquer montante não gasto não transita. Isto é intencional — o plafond é concedido de novo todos os meses.

Se pretender que o saldo remanescente de uma subconta seja adicionado ao seu novo plafond mensal em vez de o substituir, ative a transição de créditos:

PUT https://api.dmchamp.com/v1/subaccounts/{subAccountUid}/limits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "usageLimits": { "roll_over_to_next_month": true }
}

Se a subconta — ou o plano em que se encontra — também tiver um limite de transição ou uma data de validade definida, a reposição ocorre no momento em que estes se aplicam: o saldo transitado é reduzido para os meses permitidos e o saldo não utilizado durante mais tempo do que a janela de validade é eliminado, antes de o novo saldo ser adicionado. Os créditos concedidos através deste endpoint, os carregamentos automáticos e os carregamentos feitos pelo próprio cliente são créditos pontuais e nunca são reduzidos. Consulte Limitar o que transita.

Exemplo de ponta a ponta #

Um processador típico tem este aspeto:

on POST /your-recharge-webhook:
  payload = request.body

  if seen(payload.idempotency_key):
    return 200  // already processed, ack and exit

  charge_result = your_payment_provider.charge(
    email = payload.sub_account_email,
    amount_cents = payload.total_amount_cents,
    currency = payload.price_per_credit_currency,
  )

  if not charge_result.ok:
    return 500  // platform will retry on next balance drop

  api.post("/v1/subaccounts/credits", {
    email = payload.sub_account_email,
    amount = payload.credits_requested,
    description = "Auto-recharge via " + your_provider_name,
  })

  mark_seen(payload.idempotency_key)
  return 200