Skip to main content
Payment logic should be embedded within your agent orchestration workflow. Natural operates both APIs and embeddable SDKs with a local MCP server for Python and TypeScript.

​
Install SDK

pip3 install naturalpay

​
Find customer party ID

First, retrieve the party_id of the customer you want to pay on behalf of. List all customers who have delegated payment authority to your agents. This can be saved for future use: 
curl https://api.natural.co/customers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "data": [
    {
      "type": "customer",
      "id": "pty_019cd1798d617f65a79cb965dda9eac3",
      "attributes": {
        "party_type": "ORG",
        "legal_name": "Natural",
        "display_name": "Natural",
        "party_status": "ACTIVE",
        "permissions": ["payments:read", "payments:write", "wallets:read"],
        "delegation_status": "ACTIVE",
        "created_at": "2026-01-04T15:30:00Z"
      },
      "relationships": {
        "party": {
          "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
        },
        "delegation": {
          "data": { "type": "delegation", "id": "dlg_019cd3444a717a9ab3313badaaebb30b" }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "next_cursor": null
    }
  }
}
Use the party.id value as the party_id query parameter (for balance) or customer_party_id body field (for payments).

​
Check wallet balance

Before creating payments, verify the customer has sufficient funds. Pass the customer’s party_id as a query parameter to check their balance. You’ll want to check the operating_funded amount.
Insufficient funds will throw an error but will not incur any costs.
curl "https://api.natural.co/wallet/balance?party_id=pty_019cd1798d617f65a79cb965dda9eac3" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d"
Response: 
{
  "data": {
    "type": "wallet_balance",
    "id": "wal_019cd3444a6f73db8ef1f4afd074c166",
    "attributes": {
      "balances": [
        {
          "asset_code": "USD",
          "breakdown": {
            "operating_funded": {
              "amount_minor": 1000000,
              "amount_dollars": "10000.00"
            },
            "operating_advanced": {
              "amount_minor": 0,
              "amount_dollars": "0.00"
            },
            "escrow_funded_settled": {
              "amount_minor": 0,
              "amount_dollars": "0.00"
            },
            "escrow_advanced": {
              "amount_minor": 0,
              "amount_dollars": "0.00"
            },
            "holds_outbound": {
              "amount_minor": 50000,
              "amount_dollars": "500.00"
            }
          },
          "available": {
            "amount_minor": 950000,
            "amount_dollars": "9500.00"
          }
        }
      ],
      "pending_claim_amount_minor": 0,
      "pending_claim_count": 0
    },
    "relationships": {
      "party": {
        "data": {
          "type": "party",
          "id": "pty_019cd1798d617f65a79cb965dda9eac3"
        }
      }
    }
  }
}

​
Create payment

You’ll need an API key, customer ID, and agent ID to execute a payment.
Amounts are in minor units (cents). For example, 100.00 USD is 10000 and 5,000.00 USD is 500000.

​
Local integration (direct MCP)

Add the Natural MCP server to your Claude Desktop config or MCP client: 
{
  "mcpServers": {
    "natural-payments": {
      "command": "uvx",
      "args": ["naturalpay", "mcp", "serve"],
      "env": {
        "NATURAL_API_KEY": "sk_ntl_prod_abc123..."
      }
    }
  }
}

​
Direct API call

curl -X POST https://api.natural.co/payments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amount": "500000",
        "currency": "USD",
        "counterparty": "terri@contractor.com",
        "customer_party_id": "pty_019cd1798d617f65a79cb965dda9eac3",
        "description": "Payment for Q4 2025 development work"
      }
    }
  }'
The counterparty attribute accepts a party ID (pty_*), email address, or phone number as a string. The customer_party_id attribute identifies the party making the payment.
Response: 
{
  "data": {
    "type": "payment",
    "id": "pay_019cd3444a6d765890d021717a39bf97",
    "attributes": {
      "amount": "500000",
      "currency": "USD",
      "status": "PENDING",
      "description": "Payment for Q4 2025 development work",
      "claim_link": "https://natural.co/claim/abc123",
      "created_at": "2026-01-05T10:00:00Z",
      "updated_at": "2026-01-05T10:00:00Z"
    },
    "relationships": {
      "customer_party": {
        "data": {
          "type": "party",
          "id": "pty_019cd1798d617f65a79cb965dda9eac3"
        }
      },
      "counterparty": {
        "data": {
          "type": "party",
          "id": "pty_019cd1798d627ad9bc302511c4f2c115"
        }
      }
    }
  }
}

​
Next step

Monitor Payment

Track payment status and completion