PayLinks

Create a PayLink

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

string

What the budget is for, e.g. "Retainer mensual data". Shown to the agent before accepting.

integer

required

Total ceiling in USD cents across all draws.

integer

Max size of any single draw.

integer

Max number of draws.

integer

Lifetime of the 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"
}

Public view

Everything an agent needs to decide. No auth required.

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

Accept a PayLink (agent)

Creates the grant, the auditable human authorization. Idempotent per (link, agent) pair.

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

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

Fires paylink.accepted to the merchant’s webhooks.

Charge against a grant

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

string

required

Which agent’s grant to draw from. The agent must have accepted first.

integer

required

Draw amount in USD cents.

string

What this draw pays for.

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

List your PayLinks (merchant)

Everything for the console dashboard: budget consumed by grants, remaining and accepted agents.

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 and remainingMinor are computed from the active grants, not from a per-request counter. grantsCount is the number of agents that currently hold an active grant.

List grants of a PayLink (merchant)

Which agents accepted a link and how much each has drawn. Useful to pick the agentId for a charge or to surface per-agent usage in your console.

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

Error catalog

Status	`error`	Meaning
`402`	`excede_presupuesto_restante_<N>`	Draw exceeds the agent’s remaining budget (`N` = cents left).
`402`	`excede_tope_por_uso`	Draw larger than `perChargeUsdCents`.
`402`	(policy reason)	The agent’s hard policy limits blocked it (daily cap, category…).
`409`	`paylink_exhausted`	Budget fully used. A `budget.exhausted` webhook already fired.
`409`	`max_uses_alcanzado`	Draw count limit reached.
`409`	`paylink_expired` / `sin_grant_del_agente`	Link expired, or this agent never accepted.
`404`	`paylink_not_found`	Wrong code or link belongs to another merchant.

The remaining budget is enforced before the wallet is touched; a rejected draw never leaves a partial charge behind.

​PayLinks

​Create a PayLink

​Public view

​Accept a PayLink (agent)

​Charge against a grant

​List your PayLinks (merchant)

​List grants of a PayLink (merchant)

​Error catalog

PayLinks

Create a PayLink

Public view

Accept a PayLink (agent)

Charge against a grant

List your PayLinks (merchant)

List grants of a PayLink (merchant)

Error catalog