Cobro recurrente con PayLinks

Las tarjetas tienen el “guarda esta tarjeta y cóbrame cada mes”. Los agentes tienen algo mejor: los PayLinks son presupuestos que un humano aprueba una vez y contra los que tú vas cobrando a medida que entregas valor.

Cuándo usar un PayLink y cuándo cargos sueltos

Usa cargos sueltos cuando…	Usa PayLinks cuando…
Son compras puntuales (un paquete de llamadas a la API)	Son servicios recurrentes (iguala mensual, planes por puesto)
El monto es lo bastante pequeño como para autoaprobarse	Quieres una aprobación en vez de muchas
El agente te paga cuando le hace falta	Necesitas una exposición previsible y acotada para ambas partes

Recorrido completo

1. Crea el link

curl -X POST https://tu-host-payzor/merchant/paylinks \
  -H "Authorization: Bearer sk_mch_..." \
  -d '{
    "label": "Retainer mensual data",
    "budgetUsdCents": 500,
    "perChargeUsdCents": 150,
    "maxUses": 10,
    "expiresInHours": 720
  }'

Todas las restricciones son opcionales salvo el presupuesto:

budgetUsdCents: techo total sumando todos los cobros.
perChargeUsdCents: tamaño máximo de un cobro individual.
maxUses: número máximo de cobros.
expiresInHours: se explica solo.

Respuesta:

{
  "paylinkId": "pl_8eb56b59f563e9ed",
  "code": "h83YpjKQ",
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "perChargeMinor": 150,
  "maxUses": 10,
  "remainingMinor": 500,
  "status": "active"
}

2. Hazle llegar el código al agente de tu cliente

El agente consulta la vista pública y decide:

curl https://tu-host-payzor/pl/h83YpjKQ

{
  "code": "h83YpjKQ",
  "business": "Acme Digital Goods",
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "remainingMinor": 500,
  "status": "active"
}

Luego lo acepta (esto crea el grant, el “sí” auditable del lado humano):

curl -X POST https://tu-host-payzor/pl/h83YpjKQ/accept \
  -H "Authorization: Bearer pz_sk_..."

{
  "grantId": "plg_8045a45414bdb863",
  "paylink": { "...": "..." }
}

Recibirás un webhook paylink.accepted con el id del grant y la identidad del agente.

3. Cobra cada vez que entregues valor

curl -X POST https://tu-host-payzor/merchant/paylinks/h83YpjKQ/charge \
  -H "Authorization: Bearer sk_mch_..." \
  -d '{
    "agentId": "agent_6b75c0e895ba9c3d",
    "amountUsdCents": 150,
    "description": "Uso semanal"
  }'

{
  "paid": true,
  "charge": { "status": "paid", "method": "paylink", "...": "..." },
  "spentMinor": 150,
  "remainingMinor": 350,
  "exhausted": false
}

4. Maneja el agotamiento

Cuando el presupuesto restante llega a cero:

los siguientes cobros devuelven { "error": "paylink_exhausted" },
recibes un webhook final budget.exhausted,
los cobros que exceden el presupuesto se rechazan antes de tocar la billetera, con el monto restante exacto en el mensaje de error.

Patrones de diseño

Uso medido

Pon perChargeUsdCents a tu precio unitario y cobra una vez por periodo de facturación según el uso medido. El presupuesto acota el peor caso del cliente.

Planes por puesto

Un PayLink por cliente y por mes. Con expiresInHours: 720 se retira solo; emites el link del mes siguiente en la renovación.

Pruebas gratuitas

Presupuesto pequeño ($1), sin caducidad, suficiente para demostrar valor sin riesgo.

Primeros pasos

Conceptos clave

Guías

Cobro recurrente con PayLinks

Cobro recurrente con PayLinks

Cuándo usar un PayLink y cuándo cargos sueltos

Recorrido completo

1. Crea el link

2. Hazle llegar el código al agente de tu cliente

3. Cobra cada vez que entregues valor

4. Maneja el agotamiento

Patrones de diseño

​Cobro recurrente con PayLinks

​Cuándo usar un PayLink y cuándo cargos sueltos

​Recorrido completo

​1. Crea el link

​2. Hazle llegar el código al agente de tu cliente

​3. Cobra cada vez que entregues valor

​4. Maneja el agotamiento

​Patrones de diseño

Cobro recurrente con PayLinks

Cuándo usar un PayLink y cuándo cargos sueltos

Recorrido completo

1. Crea el link

2. Hazle llegar el código al agente de tu cliente

3. Cobra cada vez que entregues valor

4. Maneja el agotamiento

Patrones de diseño