Overview

A payee (or payment destination) represents a recipient that your AI Agent can send funds to. Payman supports three types of payees:

  • US ACH bank accounts
  • Cryptocurrency addresses
  • Other Payman AI Agents

Payment Destination Types

  • US_ACH - US Bank Account
  • AGENT_TO_AGENT - Another Payman AI Agent
  • CRYPTO_ADDRESS - Cryptocurrency Address (Coming Soon)

Create an ACH Payee

Create a payment destination for US bank accounts using ACH:

const achPayee = await payman.payments.createPayee({
  type: 'US_ACH',
  name: 'John Doe Checking',
  accountHolderName: 'John Doe',
  accountNumber: '1234567890',
  routingNumber: '011000138',
  accountType: 'checking',
  contactDetails: {
    contactType: 'individual',
    email: 'john@example.com',
    phoneNumber: '+1234567890',
    address: '123 Main St',
    taxId: '123-45-6789'
  },
  tags: ['employee', 'primary']
});

Required Parameters for ACH

ParameterDescription
typeMust be 'US_ACH'
accountHolderNameLegal name on the bank account
accountNumberBank account number
routingNumber9-digit ABA routing number
accountTypeEither 'checking' or 'savings'

Create a Crypto Payee

Create a payment destination for cryptocurrency addresses:

const cryptoPayee = await payman.payments.createPayee({
  type: 'CRYPTO_ADDRESS',
  name: 'ETH Wallet',
  address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  currency: 'ETH',
  contactDetails: {
    email: 'wallet@example.com'
  },
  tags: ['crypto']
});

Required Parameters for Crypto

ParameterDescription
typeMust be 'CRYPTO_ADDRESS'
addressValid cryptocurrency wallet address
currencyBlockchain identifier (e.g., ‘ETH’, ‘BTC’)

Create an Agent Payee

Create a payment destination for another Payman AI Agent. You can find agent IDs in the Payman Dashboard.

const agentPayee = await payman.payments.createPayee({
  type: 'PAYMAN_AGENT',
  paymanAgentId: 'agent_xyz789', // Get this ID from the Payman Dashboard
  name: 'Trading Bot',
  contactDetails: {
    email: 'bot@example.com'
  },
  tags: ['agent', 'trading']
});

Required Parameters for Agent

ParameterDescription
typeMust be 'PAYMAN_AGENT'
paymanAgentIdUnique identifier of the receiving agent (found in Dashboard)

Agent IDs can be found in the Payman Dashboard under the Agents section. Each agent has a unique identifier that starts with agt-.

Common Optional Parameters

ParameterDescription
nameFriendly name for the payee
tagsArray of strings for categorization
contactDetailsContact information object
customerIdYour system’s customer ID

Response

{
  id: string,           // Unique payee identifier
  name: string,         // Friendly name
  type: string,         // Payment destination type
  organizationId: string,
  status: 'ACTIVE' | 'ARCHIVED' | 'DELETED',
  contactDetails?: {
    email?: string,
    phoneNumber?: string,
    address?: string,
    taxId?: string
  },
  tags?: string[],
  createdAt: string,    // ISO timestamp
  updatedAt: string     // ISO timestamp
}

Error Handling

try {
  const payee = await payman.payments.createPayee({
    type: 'US_ACH',
    // ... other parameters
  });
} catch (error) {
  if (error.code === 'invalid_routing_number') {
    console.error('Invalid routing number provided');
  } else if (error.code === 'invalid_account_number') {
    console.error('Invalid account number provided');
  } else {
    console.error('Failed to create payee:', error.message);
  }
}

For security reasons, bank account numbers are never returned in full in API responses.