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

Listar tus PayLinks (comercio)

Todo lo que necesita el panel de la consola: presupuesto consumido por los grants, lo que queda y los agentes que aceptaron.

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

// 200 OK
{
  "paylinks": [
    {
      "paylinkId": "pl_65649270c3ae7c5a",
      "code": "B0JbT4Cc",
      "business": "Acme Digital Goods",
      "label": "Retainer mensual data",
      "budgetMinor": 5000,
      "perChargeMinor": 750,
      "maxUses": 10,
      "uses": 1,
      "spentMinor": 150,
      "remainingMinor": 4850,
      "expiresAt": null,
      "status": "active",
      "acceptUrl": "/pl/B0JbT4Cc/accept",
      "grantsCount": 1
    }
  ]
}

spentMinor y remainingMinor se calculan a partir de los grants activos, no de un contador por petición. grantsCount es el número de agentes que ahora mismo tienen un grant activo.

Listar los grants de un PayLink (comercio)

Qué agentes aceptaron un link y cuánto ha gastado cada uno. Sirve para elegir el agentId de un cobro, o para mostrar el consumo por agente en tu consola.

GET /merchant/paylinks/:code/grants
Authorization: Bearer sk_mch_...

// 200 OK
{
  "grants": [
    {
      "grantId": "plg_f46a8607c8b8cafd",
      "agentId": "agent_2c7f153865ffc2e9",
      "agentName": "Research Bot",
      "spentMinor": 150,
      "remainingMinor": 4850,
      "status": "active",
      "createdAt": "2026-08-23T09:45:52.336Z"
    }
  ]
}

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

​Listar tus PayLinks (comercio)

​Listar los grants de un PayLink (comercio)

​Catálogo de errores

PayLinks

Crear un PayLink

Vista pública

Aceptar un PayLink (agente)

Cobrar contra un grant

Listar tus PayLinks (comercio)

Listar los grants de un PayLink (comercio)

Catálogo de errores