pay_service

io.github.nevermined-io/catalog · Verify this server

Pay for a catalog service from your spend-capped delegation and return the vendor response. This charges real funds. Call `get_service` FIRST: its `requestShape.endpoints[]` lists the callable paths with their HTTP method and price, and each `payServiceArgs` is the `slug`/`path`/`method` to pass here, after replacing any `pathParams` placeholder in `path` with a real value. A bare slug reaches the service base URL, which for a multi-endpoint API answers 404 instead of a payment challenge; only a single-endpoint service is called by slug alone. Send the endpoint's `payServiceArgs`: they carry an example only when it is `paid-run` or `challenge`. A `docs` example (and its `invokePath`) is unverified — use it only deliberately, filling any path parameter with the entity you want; otherwise build `body` from the endpoint description or the provider's docs. `method` may be omitted: it is taken from the catalog endpoint matching `path` (POST when the catalog names none) and echoed back under `request`. To accept a live quote, pass its `quoteId` before `expiresAt` with the exact same call arguments; the Router uses that cached challenge and exact fee-inclusive total. Keep `maxTotalCents` as an independent ceiling. Repeating an identical call (same arguments, no `fresh`) charges nothing new: on a deployment running API 1.48 or later it is answered within 24 hours from the first call's stored result, or its `pending` answer; on an older deployment it comes back as `already_paid`. For an ASYNC service, where you submit once and then poll a status endpoint with the same id, set `fresh: true` on every poll INCLUDING THE FIRST: otherwise each later poll reuses the first poll's idempotency key and gets the first poll's stored answer (or `already_paid`) back, so the status never advances. `fresh` makes each poll a distinct, separately billed call (the merchant charges per status call). Leave `fresh` off the submit and off any retry of a call whose outcome is unsure, because with `fresh` a retry is not de-duplicated and is charged again. A completed call returns `paid`, `upstreamStatus` (the vendor's HTTP status) and `response` (its body); `paid: true` with a non-2xx `upstreamStatus` may still have cost the merchant price. Outcomes to act on: `{"status":"pending"}` means the payment was made and the service is still working; call `get_payment_result` with its `paymentId` every few seconds instead of calling pay_service again. `{"status":"already_paid"}` means this call's idempotency key already carries a payment whose result is not replayed here (the original call failed, its 24-hour result expired, the `requestId` was reused for a different request, or the deployment predates result replay, API 1.48); nothing new was charged, and it does not by itself say whether the original succeeded. Read the original with `get_payment_result` (`paymentId`) or `list_payments`. A new `requestId` starts a separate, separately charged purchase: use one only after that read shows the original failed and the human still wants the result. `{"error":"payment_indeterminate"}` means the charge may or may not have landed: check `list_payments` first, and to retry reuse the returned `requestId` verbatim without `fresh` so the retry stays idempotent. `{"error":"per_call_max_exceeded"}` means no charge; raise `maxTotalCents` only after a deliberate decision and retry with the same requestId. `quote_not_found`, `quote_expired`, and `quote_mismatch` are named no-charge quote refusals; quote again rather than paying unpinned. `{"error":"payment_failed"}` is a definite decline (see `code`, `message` and `retryable`). These charge nothing: `{"payable":false}` (not payable via the Router; no upstream URL is ever returned), `service_not_found` (wrong slug), `catalog_unavailable` and `delegation_lookup_failed` (transient; retry later), `no_delegation` (call `setup_delegation`), `router_controls_unavailable` (the API behind this server is too old to enforce `search`, `quoteId` or `maxTotalCents`; tell the human instead of retrying without them) and `credential_refused` (re-authorize). A paid result also carries `delegationId` and `budget`, the spending budget after this call (`capCents`/`spentCents`/`remainingCents`, cents with up to four decimals), so to say what has been spent or what is left, repeat `budget` rather than adding up your calls yourself; `budget: null` means it could not be read this time, not that it is zero (call `get_budget`). FUNDING (`funding`): omit it and the call is paid with your Nevermined Subscription credits when you hold an active subscription and the endpoint carries a subscription tariff (Nevermined pays the merchant; the call costs the tariff in credits, returned if the service does not answer successfully), otherwise from your delegation; pass `"subscription"` or `"delegation"` to choose. The credits left in your monthly allowance and the price ceiling are checked only when the call is made: a credits call refused for them (`insufficient_credits`, `subscription_cap_reached`, `subscription_ceiling_exceeded`) charges nothing and is NOT switched to your delegation, so follow its `alternative`. Every result that mentions funding states which paid it: a subscription call returns `funding: "subscription"` with `creditsCharged` and `creditsStatus` (`Committed` = spent, `Reserved` = held or marked for refund, `Refunded` = returned) and no `budget`; `quoteId`, `maxTotalCents` and `delegationId` apply only to a delegation. Subscription refusals charge nothing and no credits: `subscription_unavailable`, `no_active_subscription`, `subscription_not_eligible` (see `reason`), `subscription_rail_unsupported`, `subscription_ceiling_exceeded`, `insufficient_credits`, `subscription_cap_reached` and `subscription_payment_refused`; each says in `alternative` when the delegation can pay instead. `funding_undetermined` means the funding could not be decided; nothing was charged, so retry. Requires your Nevermined API key on the Authorization header.