Recarga automática de subcuentas (proveedor de pagos personalizado) #

Si prefiere gestionar los pagos de crédito de las subcuentas a través de su propio proveedor en lugar de Stripe (transferencias bancarias, pasarelas de pago locales, sistemas de facturación personalizados), la plataforma expone un par de webhook + API para que pueda ejecutar usted mismo todo el ciclo de cobro y concesión. La descripción general no técnica se encuentra en la página de Cuentas de agencia; esta página cubre la carga útil exacta del webhook y la llamada a la API que debe realizar para conceder créditos posteriormente.

El webhook es solo una de las formas en que se pagan las recargas automáticas. Si conectó Stripe o PayPal en modo SaaS, la plataforma cobra directamente a la tarjeta guardada o a la cuenta de PayPal del cliente y otorga los créditos, por lo que no hay nada que deba construir en esta página. Siga leyendo solo si desea gestionar el pago usted mismo.

El flujo de un vistazo #

1. El saldo de crédito de una subcuenta cae por debajo de su umbral de recarga automática.
2. La plataforma llama a su URL de webhook con los detalles de la subcuenta y cuántos créditos necesita.
3. Su servidor cobra al cliente a través del proveedor que utilice.
4. Su servidor llama a la API de concesión de créditos para añadir créditos a esa subcuenta.
5. Su servidor responde 200 para confirmar la recepción del webhook.

1. Webhook: agency_sub_account_auto_recharge #

Configure la URL del webhook haciendo clic en SaaS Mode en la barra lateral principal, seleccionando Use a Custom Payment Provider Instead (o, una vez configurado, abriendo la tarjeta Custom Payment Provider) y completando el campo Auto-Recharge Webhook.

Cuándo se activa #

Cuando el saldo de crédito de una subcuenta cae por debajo de su umbral de recarga automática configurado.

Carga útil #

{
  "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 #

• Tiempo de espera de 5 minutos — Después de un intento de recarga para una subcuenta, la plataforma no enviará otro webhook para esa subcuenta durante al menos 5 minutos, incluso si su saldo cae aún más. Esto evita cargos duplicados durante el procesamiento.
• Utilice la clave de idempotencia — Compruebe siempre idempotency_key antes de conceder créditos. Si su servidor falló después de conceder créditos pero antes de responder, la plataforma puede volver a enviar el webhook en la siguiente caída de crédito.
• Los fallos son seguros y se autorreparan — Si su URL de webhook no es accesible o devuelve un error, no se conceden créditos. La plataforma sigue enviando el webhook (una vez por cada tiempo de espera de 5 minutos) mientras la subcuenta permanezca por debajo del umbral; no requiere que el saldo vuelva a subir por encima del umbral y caiga de nuevo primero. Un solo cargo perdido ya no puede dejar a una subcuenta permanentemente sin recargar.
• Establezca su cantidad de recarga en o por encima del umbral — Su cantidad de recarga configurada debe ser mayor o igual que el umbral de recarga automática, de modo que una recarga siempre restablezca el saldo por encima del umbral. (Si alguna vez necesita arreglar una subcuenta que se desvió mucho por debajo del umbral, la plataforma la recarga automáticamente por el déficit total; consulte credits_requested arriba).

2. API de concesión de créditos #

Después de que su servidor haya procesado el pago, llame a este endpoint para añadir los créditos a la subcuenta.

Solicitud #

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"
}

Autenticación: Envíe su clave de API en un encabezado de solicitud, ya sea X-API-Key: YOUR_API_KEY o Authorization: Bearer YOUR_API_KEY. Los encabezados son la forma recomendada, ya que una clave en la URL termina en el historial del navegador, en los registros del proxy y en los registros de acceso del servidor. El parámetro de consulta ?apiKey=YOUR_API_KEY y un campo apiKey en el cuerpo JSON también siguen funcionando, por lo que las integraciones más antiguas seguirán ejecutándose sin cambios.

Respuesta #

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

Qué sucede con los créditos concedidos en el reinicio mensual #

Esto depende de cómo esté configurada la subcuenta:

• Reventa (la subcuenta le paga a usted por los créditos): los créditos que usted concede aquí se registran como créditos comprados y se acumulan cada mes. Todo lo que la subcuenta no haya gastado permanece en el saldo.
• Asignación (usted le da a la subcuenta una asignación mensual): el saldo se rellena hasta alcanzar la asignación mensual en la fecha de reinicio, por lo que cualquier cantidad no gastada no se acumula. Esto es intencional: la asignación se concede de nuevo cada mes.

Si desea que el saldo restante de una subcuenta se añada a su nueva asignación mensual en lugar de reemplazarla, active la acumulación 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 }
}

Si la subcuenta (o el plan en el que se encuentra) también tiene un límite de transferencia o una fecha de caducidad establecida, el restablecimiento es el momento en que estos se aplican: la asignación transferida se recorta a los meses que usted permita, y la asignación que no se haya utilizado durante más tiempo que el periodo de caducidad se elimina antes de que se añada la nueva asignación. Los créditos otorgados a través de este endpoint, las recargas automáticas y las propias recargas del cliente son créditos únicos y nunca se recortan. Consulte Limitar lo que se transfiere.

Ejemplo de extremo a extremo #

Un controlador típico se ve así:

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