Payments

Create owner-isolated exact-decimal payment requests and AUTHORIZATION_REQUIRED payment intents, reconcile their commitments and control-plane state, and cancel an intent before any separately authorized value-movement workflow begins.

BUSINESS CASES

Where this module fits

direct payment intent creation
payment request issuance and collection
request-bound payer authorization
pre-submission cancellation
payment and rail status reconciliation
merchant and invoice payment evidence

PRIMARY CONSUMERS

Who integrates it

payment applications
merchant agents
accounts-payable teams

PREREQUISITES

What must exist first

payments:read or payments:write as named by the exact operation
the correct payer, payee, or request-owner workspace relationship
RFC 9421 request signing plus a stable Idempotency-Key for each implemented mutation
a caller-owned rule that treats control-plane intent state as distinct from reservation, rail, ledger, settlement, refund, and fulfillment state

RECOMMENDED WORKFLOW

Compose the module safely.

01
resolve the bearer-derived workspace, counterparty workspace, exact amount, currency, optional payment request, and owner-safe source reference
02
create one idempotent OPEN request or AUTHORIZATION_REQUIRED payment intent
03
re-read request and payment versions and explicit safety flags before every dependent action
04
complete customer authorization, compliance, source reservation, signing, rail submission, confirmation, and settlement only through future separately owned operations
05
cancel only an exact latest AUTHORIZATION_REQUIRED intent and reconcile its linked request

AGENT INTEGRATION

Machine-use boundaries

Request creation, intent creation, authorization, reservation, submission, confirmation, settlement, refund, and fulfillment are distinct states; no state implies another.
Preserve every amount as an exact decimal string and bind dependent mutations to last-read versions, amounts, currencies, and commitments.
The current mutation surface records and cancels pre-authorization intent only. Every response explicitly says whether authorization is required and whether a reservation, rail submission, balance mutation, or settlement authority exists.
Never send raw wallet or account selectors, passwords, seeds, private keys, MPC shares, banking credentials, caller-authored paid flags, or settlement assertions.
After an ambiguous response, re-read the owner-scoped request and payment before retrying the same Idempotency-Key and byte-equivalent body.
Treat legacy /api/v2/pay/* mutations as bodyless 501 migration markers and use only canonical replacements present in live OpenAPI.

Register only production-listed routes as executable tools, and re-fetch the deployed OpenAPI before generating or sending a request. Source-ready routes awaiting deployment are preparation references; planned contracts are non-executable.

MODULE CONTRACTS

Every mapped endpoint

Each operation states whether its request shape is authoritative in OpenAPI, reviewed as a planning profile, or intentionally left as an outline pending an owner schema.

POSTGet payment request details/api/v2/pay/get_payment_request_detailsPlanned capability: apply the requested transition to payment request details through the authoritative payment service boundary.›POSTGet all payment requests/api/v2/pay/get_payment_requestsPlanned capability: apply the requested transition to all payment requests through the authoritative payment service boundary.›POSTInitiate a mass multi currency payment/api/v2/pay/new_multi_paymentPlanned capability: apply the requested transition to initiate a mass-multi-currency payment through the authoritative payment service boundary.›POSTCreate new payment request/api/v2/pay/new_payment_requestPlanned capability: apply the requested transition to new payment request through the authoritative payment service boundary.›POSTTop up with pix payment system/api/v2/pay/new_pix_payment_requestPlanned capability: apply the requested transition to top-up with pix payment system through the authoritative payment service boundary.›POSTPay payment request/api/v2/pay/pay_payment_requestPlanned capability: apply the requested transition to pay payment request through the authoritative payment service boundary.›GETList payment requests/api/v2/payment-requestsFind payment requests involving the active workspace and reconcile whether each request is open, awaiting a later authorization, cancelled, satisfied, or expired.›POSTCreate payment request/api/v2/payment-requestsCreate a durable exact-decimal request for another workspace—or an intentionally shareable request—without creating an invoice or moving money.›POSTCreate request bound payment intent/api/v2/payment-requests/{request_uuid}/paymentsBind an OPEN payment request to the payer’s chosen source and method, creating a pre-settlement intent that still requires a separate future authorization workflow.›GETList payment intents/api/v2/paymentsList payment intents involving the active workspace and distinguish proposed, cancelled, future execution, and settlement states without inferring money movement.›POSTCreate direct payment intent/api/v2/paymentsCreate a direct workspace-to-workspace payment intent with exact terms and a selected source reference, without first creating a payment request.›GETGet payment intent/api/v2/payments/{payment_uuid}Read one payer- or payee-visible payment intent with exact terms, lifecycle version, commitments, cancellation evidence, and non-settlement flags.›POSTCancel payment intent/api/v2/payments/{payment_uuid}/cancellationsStop an outgoing payment intent before any value-moving authority exists and retain why it was cancelled.›POSTReserve payment wallet/api/v2/merchant/reserve_walletPlanned capability: apply the requested transition to reserve payment wallet through the authoritative commerce service boundary.›