​
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 MageBank 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 MageBank 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": "contact@vendorxyz.com",
    "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:

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

​
Payment Types

Payment Classifications: MageBank 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.

StatusDescription
NewCreated and awaiting approval or processing
PendingIn process of being executed on blockchain
ConfirmedFully processed and completed
Approval StatusDescription
WaitingInitial state before approval check
PendingPayment is awaiting additional confirmation
ApprovedPayment has been explicitly approved
DeclinePayment has been explicitly declined
Waiting for Sender ApprovalPayment 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