PayLinks

Crear un PayLink

POST /merchant/paylinks
Authorization: Bearer sk_mch_...

string

Para qué es el presupuesto, por ejemplo "Retainer mensual data". Se le muestra al agente antes de aceptar.

integer

requerido

Techo total en centavos de USD sumando todos los cobros.

integer

Tamaño máximo de un cobro individual.

integer

Número máximo de cobros.

integer

Vida útil del link.

// 201 Created
{
  "paylinkId": "pl_8eb56b59f563e9ed",
  "code": "h83YpjKQ",
  "business": null,
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "perChargeMinor": null,
  "maxUses": null,
  "uses": 0,
  "remainingMinor": 500,
  "expiresAt": null,
  "status": "active",
  "acceptUrl": "/pl/h83YpjKQ/accept"
}

Vista pública

Todo lo que un agente necesita para decidir. No requiere autenticación.

GET /pl/h83YpjKQ

{
  "paylinkId": "pl_...",
  "code": "h83YpjKQ",
  "business": "Acme Digital Goods",
  "label": "Retainer mensual data",
  "budgetMinor": 500,
  "perChargeMinor": null,
  "maxUses": null,
  "uses": 0,
  "remainingMinor": 500,
  "expiresAt": null,
  "status": "active"
}

Aceptar un PayLink (agente)

Crea el grant, la autorización humana auditable. Es idempotente por par (link, agente).

POST /pl/h83YpjKQ/accept
Authorization: Bearer pz_sk_...

{
  "grantId": "plg_8045a45414bdb863",
  "paylink": { "...": "vista pública..." }
}

Dispara paylink.accepted hacia los webhooks del comercio.

Cobrar contra un grant

POST /merchant/paylinks/:code/charge
Authorization: Bearer sk_mch_...

string

requerido

De qué grant de agente se cobra. El agente tiene que haber aceptado antes.

integer

requerido

Monto del cobro en centavos de USD.

string

Qué paga este cobro.

// 200 OK
{
  "paid": true,
  "charge": {
    "chargeId": "chg_610149bd78ab4857",
    "status": "paid",
    "method": "paylink",
    "reference": "PAY_82A95A672F30D580"
  },
  "spentMinor": 150,
  "remainingMinor": 350,
  "exhausted": false
}

Catálogo de errores

Estado	`error`	Significado
`402`	`excede_presupuesto_restante_<N>`	El cobro supera el presupuesto restante del agente (`N` = centavos que quedan).
`402`	`excede_tope_por_uso`	El cobro es mayor que `perChargeUsdCents`.
`402`	(motivo de política)	Los límites duros del agente lo bloquearon (tope diario, categoría…).
`409`	`paylink_exhausted`	Presupuesto consumido por completo. Ya se disparó un webhook `budget.exhausted`.
`409`	`max_uses_alcanzado`	Se alcanzó el número máximo de cobros.
`409`	`paylink_expired` / `sin_grant_del_agente`	El link caducó, o este agente nunca lo aceptó.
`404`	`paylink_not_found`	Código equivocado, o el link pertenece a otro comercio.

El presupuesto restante se hace cumplir antes de tocar la billetera; un cobro rechazado nunca deja atrás un cargo a medias.

​PayLinks

​Crear un PayLink

​Vista pública

​Aceptar un PayLink (agente)

​Cobrar contra un grant

​Catálogo de errores

PayLinks

Crear un PayLink

Vista pública

Aceptar un PayLink (agente)

Cobrar contra un grant

Catálogo de errores