Praecise Platform
Menu

Skerry/ Reference/ Agents paying

Agent payments create

post/agent-payments

Send the agent's request to a merchant and, when it answers 402, pay one offer and send the request once more. Returns the merchant's status, an excerpt of its body and what was paid. max_amount is a ceiling in US cents; the merchant's exact amount is what is paid. Under the agent's mandates and the customer's controls: it may be refused, or held for approval (202). Pays at most once per key. Needs an Idempotency-Key.

Before you call

Credential
Authorization: Bearer $KEY
Scope
agent-payments:write
Moves money
yes
Idempotency
required
Untrusted
response.body, reason, merchant.url, external_ref

Parameters

  • Idempotency-Keystringrequired
    Header. A repeat with the same key and body returns the first answer instead of acting twice.

Request bodyapplication/json, required

  • agent_idstringrequired
    The registered agent that pays. At most 100 characters.
  • wallet_idstring
    The agent's wallet to sign from. Left out, its newest active wallet is used. At most 100 characters.
  • urlstring (uri)required
    The merchant's address: public, https, a host name. At most 2000 characters.
  • methodstring
    One of: GET, POST, PUT, PATCH, DELETE.
  • headersobject
    Headers sent to the merchant. The ones a payment is carried in may not be set.
  • bodystring or object
    Sent to the merchant as it is; an object is sent as JSON. Up to 64 KB.
  • max_amountintegerrequired
    The most that may be paid, in US cents. What is paid is the merchant's exact amount. At least 1.
  • currencystringrequired
    One of: usd.
  • payment_method_idstring
    A saved payment method a delegated payment token is issued on, for a merchant that takes one. At most 200 characters.
  • external_refstring
    The document this belongs to in your own system. At most 200 characters.
  • external_kindstring
    One of: invoice, bill, order, booking, other.
  • dry_runboolean
    Check the request and report what would happen, without doing it.

Responses

  • 200
    Success.
  • 202
    requires_approval — Not an error: the operation is held for a person. The body names the approval.
  • 400
    price_below_minimum — The price is below the smallest single payment for a method (detail.method, detail.minimum), or has a part of a cent. Set credit_only, raise the price, or drop the method.
  • 401
    dpop_invalid — The token is bound to a key and the DPoP proof was missing, wrong for this request, or already used.
  • 402
    payment_failed — The payer's bank or card refused. detail.reason says why in plain terms.
  • 403
    agent_payment_over_max — The merchant asks for more than max_amount. Nothing was signed. detail.asked_minor is the lowest price asked, in US cents.
  • 404
    not_found — No such object in this project — including one that belongs to somebody else.
  • 409
    token_not_issued — A delegated payment token could not be issued ready to use, for instance because the payer would have to act. Nothing was sent to the merchant.
  • 429
    too_many_waiters — This key already has as many requests waiting (?wait=) as it may. Let one finish, or read without wait.
  • 500
    internal_error — Ours. Quote the request_id and we can find the call.
  • 502
    platform_error — A provider failed. Safe to retry with the same Idempotency-Key.
  • 503
    oauth_unavailable — The authorisation server's keys could not be read, so tokens cannot be checked. API keys still work.

This page as Markdown