Agent payments

Spending limits for agents, set by people

In APS a delegation can set how much an agent may spend. The limit belongs to the delegation and applies in the unit it names, whichever payment network carries the payment.

Status. The payment code in the open source gateway is experimental. In this release the server refuses send requests, and turning payments on needs a separate review and a release decision.

The limit comes from the delegation

A person or an organization delegates authority to an agent and can set a spending limit in that delegation. A bounded limit names a unit, an amount for one action and a cumulative amount. An agent that passes authority on cannot give a larger limit than it received. APS converts no currencies, so a limit applies in the unit it names.

What the gateway checks before a payment

In the wallet code a send has to pass the three checks below, next to the operator switches that turn sending on or off.

  1. The wallet is active. A frozen or revoked wallet cannot send.
  2. The delegation covers spending. A send needs an active delegation that carries the commerce scope and whose chain is still valid. An agent that was delegated only to review cannot pay.
  3. The amount fits the limit. The gateway counts what was already spent against the spending limit in the delegation.

The wallet service records send attempts and their outcomes in its database. The send route does not issue a signed APS decision receipt.

Payment networks are adapters

The gateway reaches a payment network through an adapter. The source has two today. One is for Nano. The other is a reference adapter for Stripe Issuing that accepts only test keys and is not wired into the server. Another currency or network can be added as a new adapter.

Why Nano came first

Nano came first because its transfers carry no network fee. The spending limit in a delegation is not specific to Nano. A limit can name any unit.

Wallets

A registered agent can request a Nano wallet. Provisioning needs an active delegation and passes further checks, and each wallet has its own Nano address.

Where the code is

The wallet routes, the payment adapters and their tests are in the gateway repository under Apache 2.0. Passing tests do not make the code ready to hold funds.

Routes in the gateway source

These routes are listed in src/server.ts of the gateway at commit 4784153. In this release the server refuses send requests. Each wallet address is derived from a master seed, one address per agent.

RouteWhat it does
POST /api/v1/wallets/provisionCreate a wallet for an agent
GET /api/v1/wallets/:id/balanceRead the balance from the network
POST /api/v1/wallets/sendSend, checked against the delegation
POST /api/v1/wallets/:id/receivePocket pending funds
GET /api/v1/wallets/:id/txsTransaction history
POST /api/v1/wallets/:id/freezeFreeze a wallet
POST /api/v1/wallets/:id/unfreezeReactivate a wallet
GET /api/v1/walletsList all wallets
GET /api/v1/wallets/dashboardWallet overview for a tenant
POST /api/v1/pay/nano/invoiceCreate a Nano payment request
GET /api/v1/pay/nano/status/:idCheck the status of an invoice
POST /api/v1/pay/nano/settle/:idExecute a settlement
GET /api/v1/pay/nano/balanceBalance of the gateway wallet
GET /api/v1/pay/nano/historyRecent Nano transactions
POST /api/v1/pay/nano/verifyVerify a transaction on the network

Read the gateway documentation Read how spending limits narrow