Payments API

Financial Transactions: The Payments API provides a complete system for creating, approving, and tracking payments between agents on the blockchain.

Process and manage financial transactions between agents with automatic approval workflows and detailed tracking. Use these endpoints to initiate, approve/decline, and analyze payments within the Mage ecosystem.

In sandbox mode only agent-to-agent transactions are currently supported. Agent-to-bank account, agent-to-businesses, and agent-to-checkout pages are coming soon.

Payment Model

Approval Flow: Payments respect each agent’s configured rules, with transactions above certain thresholds requiring explicit approval before execution.

Each payment in the Mage system includes:

Identifiers: Unique ID, name, and type
Participants: Sender and receiver agent IDs
Status: Current processing and approval status
Financial Details: Amount, currency, and payment method
Metadata: Timestamps, tags, and contact information

Different approval statuses determine how payments are processed:

Payments requiring approval remain in “Waiting for Sender Approval” until authorized
Upon approval, payments move to blockchain processing
Declined payments are marked as “Confirmed” with a “Decline” approval status

Payment Structure

{
  "id": "payee_wDG5cavUCoK53uvFzTvkey",
  "name": "Vendor XYZ Payment",
  "type": "EXTERNAL",
  "senderagentid": "agent_eC6ZezevNsqxvoKmQrUuoU",
  "receiveragentid": "agent_k77NTwxp2Ym3JCmVsKtXQA",
  "status": "New",
  "approvalstatus": "Waiting",
  "approvalrequired": true,
  "paymentdetails": {
    "method": "CRYPTO_ADDRESS",
    "amount": 6,
    "currency": "USDC"
  },
  "contactdetails": {
    "email": "[email protected]",
    "phoneNumber": "+1234567890"
  },
  "tags": [
    "vendor",
    "regular"
  ],
  "createdat": "2025-04-17T10:28:18.512792+00:00",
  "approvedat": "2025-04-17T11:30:00.000000+00:00"
}

Available Endpoints

Register Payment

Create a new payment transaction between agents

Approve Payment

Approve a payment that requires authorization

Decline Payment

Decline a payment to prevent processing

Get Payment

Fetch details of a specific payment

List User Payments

Get all payments related to the user’s agents

Export Payments

Export payments data in various formats

Payment Lifecycle

The typical lifecycle of a payment includes:

Creation: A payment is registered with sender, receiver, and amount details
Approval Check: The system determines if approval is required based on agent rules
Approval/Decline: If required, the payment is approved or declined by an authorized user
Processing: For approved payments, funds are transferred on the blockchain
Completion: The payment status is updated to “Confirmed” when complete

Payment Types

Payment Classifications: Mage provides distinct payment types to clearly identify the relationship between transacting parties.

EXTERNAL: Payments to recipients outside your agent network
INTERNAL: Transfers between your own agents

Payment Status Flow

Status Progression: Payments move through several states from creation to completion, with different approval paths based on agent rules.

Status	Description
New	Created and awaiting approval or processing
Pending	In process of being executed on blockchain
Confirmed	Fully processed and completed

Approval Status	Description
Waiting	Initial state before approval check
Pending	Payment is awaiting additional confirmation
Approved	Payment has been explicitly approved
Decline	Payment has been explicitly declined
Waiting for Sender Approval	Payment requires explicit sender authorization

Best Practices

Use meaningful payment names and tags for better organization and reporting
Implement proper error handling for declined or failed payments
Set appropriate approval thresholds in agent configuration based on risk tolerance
Use the correct payment type based on recipient relationship (INTERNAL vs. EXTERNAL)
Regularly monitor payment statuses, especially those requiring approval
Check the approval status before assuming a payment has been processed
Include relevant contact details for external payments to facilitate communication

Users

Agents

Payments

Transactions

Savings

Introduction

Payments API

Payment Model

Payment Structure

Available Endpoints

Register Payment

Approve Payment

Decline Payment

Get Payment

List User Payments

Export Payments

Payment Lifecycle

Payment Types

Payment Status Flow

Best Practices

​Payments API

​Payment Model

​Payment Structure

​Available Endpoints

Register Payment

Approve Payment

Decline Payment

Get Payment

List User Payments

Export Payments

​Payment Lifecycle

​Payment Types

​Payment Status Flow

​Best Practices

Payments API

Payment Model

Payment Structure

Available Endpoints

Payment Lifecycle

Payment Types

Payment Status Flow

Best Practices