> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a payment

Send money to an agent, email, phone number, or Natural party ID. For new parties, Natural creates a payment link, delivers the link by email or SMS, and onboards the new party.

<Info>
  If an AI assistant is operating Natural for you, use the **MCP** examples. Python, TypeScript,
  CLI, and cURL examples are for application developers building an integration.
</Info>

## 1. Set up Natural

### If you are using an AI assistant

Ask your assistant to load Natural's playbook and connect with OAuth:

```text theme={null}
Read https://www.natural.co/skill.md and set up Natural for me.
Connect my assistant to Natural with OAuth.
Then follow the Create a payment guide and help me send a payment.
```

The assistant should configure Natural's hosted MCP server, start the browser OAuth flow, and tell
you when to approve the Natural authorization page. You still sign up at
[natural.co/signup](https://natural.co/signup) and complete verification yourself; the assistant
does not need an API key for the primary MCP path.

### If you are building an integration

Sign up at [natural.co/signup](https://natural.co/signup), complete verification, then create a
developer API key in the dashboard. The key is shown once; store it in a secret manager and never
commit it.

```bash theme={null}
export NATURAL_API_KEY=sk_ntl_prod_abc123...
```

Install the SDK or CLI for the surface you are building with:

<CodeGroup>
  ```bash Python theme={null}
  pip install naturalpay
  ```

  ```bash TypeScript theme={null}
  npm install @naturalpay/sdk
  ```

  ```bash CLI theme={null}
  curl -fsSL https://natural.co/install.sh | bash
  ```
</CodeGroup>

No SDK for your language? Use the REST examples with the same API key.

After setup, use the MCP examples for an OAuth-connected AI assistant, or use the SDK, CLI, and
cURL examples when you are building an integration.

## 2. Create an agent

Agents execute transactions. Create one in the **Agents** tab of the dashboard, or:

<CodeGroup>
  ```text MCP theme={null}
  Create an agent called "Carrier Payment Agent" for paying delivery carriers.
  ```

  ```python Python theme={null}
  import uuid
  from naturalpay import Natural

  client = Natural()  # reads NATURAL_API_KEY

  agent = client.agents.create(
      name="Carrier Payment Agent",
      description="Pays delivery carriers",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  const client = new Natural(); // reads NATURAL_API_KEY

  const agent = await client.agents.create({
    name: "Carrier Payment Agent",
    description: "Pays delivery carriers",
    "Idempotency-Key": crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agents create --name "Carrier Payment Agent" --description "Pays delivery carriers" --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.co/agents \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "name": "Carrier Payment Agent",
          "description": "Pays delivery carriers"
        }
      }
    }'
  ```
</CodeGroup>

The response includes the agent's `id` (`agt_*`), store it to associate your agent for future requests.

## 3. Connect a bank account and fund your wallet

Fund your wallet from a linked bank account so your agent can transact autonomously.

### Connect a bank account

Link a bank account from the **Wallet** tab of your dashboard — Natural connects it securely through Plaid. Once linked, list your external accounts to get the `eac_*` ID to deposit from:

<CodeGroup>
  ```text MCP theme={null}
  List my linked bank accounts.
  ```

  ```python Python theme={null}
  accounts = client.external_accounts.list()
  ```

  ```typescript TypeScript theme={null}
  const accounts = await client.externalAccounts.list();
  ```

  ```bash CLI theme={null}
  natural external-accounts list
  ```

  ```bash cURL theme={null}
  curl https://api.natural.co/external-accounts \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

Each linked account has an `id` (`eac_*`) — you'll pass it to the deposit call below.

### Fund your wallet

Pull funds from the linked account into your wallet:

<CodeGroup>
  ```text MCP theme={null}
  Deposit $50,000 into my wallet from my linked bank account.
  ```

  ```python Python theme={null}
  deposit = client.transfers.initiate_deposit(
      amount=5_000_000,
      currency="USD",
      external_account_id="eac_550e8400e29b41d4a716446655440000",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const deposit = await client.transfers.initiateDeposit({
    amount: 5_000_000,
    currency: "USD",
    externalAccountId: "eac_550e8400e29b41d4a716446655440000",
    "Idempotency-Key": crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural transfers initiate-deposit \
    --amount 5000000 \
    --currency USD \
    --external-account-id eac_550e8400e29b41d4a716446655440000 \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.co/transfers/deposit \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "amount": 5000000,
          "currency": "USD",
          "externalAccountId": "eac_550e8400e29b41d4a716446655440000"
        }
      }
    }'
  ```
</CodeGroup>

Confirm the funds landed before paying. Each wallet's `balance.available` is the spendable balance after pending holds:

<CodeGroup>
  ```text MCP theme={null}
  What's my wallet's available balance?
  ```

  ```python Python theme={null}
  wallets = client.wallet.list()
  balance = wallets.data[0].attributes.balance
  ```

  ```typescript TypeScript theme={null}
  const wallets = await client.wallet.list();
  const balance = wallets.data[0].attributes.balance;
  ```

  ```bash CLI theme={null}
  natural wallet list
  ```

  ```bash cURL theme={null}
  curl https://api.natural.co/wallets \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

## 4. Send the payment

<CodeGroup>
  ```text MCP theme={null}
  Using my Carrier Payment Agent, pay terri@contractor.com $5,000 for Q4 development work.
  ```

  ```python Python theme={null}
  payment = client.payments.create(
      amount=500_000,
      currency="USD",
      counterparty={"type": "email", "value": "terri@contractor.com"},
      description="Q4 development work for contractor Terri",
      x_agent_id=agent.data.id,
      x_instance_id=str(uuid.uuid4()),
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const payment = await client.payments.create({
    amount: 500_000,
    currency: "USD",
    counterparty: { type: "email", value: "terri@contractor.com" },
    description: "Q4 development work for contractor Terri",
    "X-Agent-ID": agent.data.id,
    "X-Instance-ID": crypto.randomUUID(),
    "Idempotency-Key": crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural payments create \
    --amount 500000 \
    --currency USD \
    --counterparty '{type: email, value: terri@contractor.com}' \
    --description "Q4 development work for contractor Terri" \
    --x-agent-id agt_019cd1798d637a4da75dce386343931d \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.co/payments \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
    -H "X-Instance-ID: $(uuidgen)" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "amount": 500000,
          "currency": "USD",
          "counterparty": { "type": "email", "value": "terri@contractor.com" },
          "description": "Q4 development work for contractor Terri"
        }
      }
    }'
  ```
</CodeGroup>

The response includes the payment's `id` (`pay_*`) and an initial `status`.

## 5. Track the payment

Check the payment's status with the `id` from step 4:

<CodeGroup>
  ```text MCP theme={null}
  Check the status of that payment.
  ```

  ```python Python theme={null}
  tx = client.payments.get(payment.data.id)
  ```

  ```typescript TypeScript theme={null}
  const tx = await client.payments.get(payment.data.id);
  ```

  ```bash CLI theme={null}
  natural payments get --payment-id pay_01a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6
  ```

  ```bash cURL theme={null}
  curl https://api.natural.co/payments/pay_01a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6 \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

Statuses move `CREATED` → `PROCESSING` → `COMPLETED`. A payment can also sit at `PENDING_CLAIM` (awaiting the recipient) or `IN_REVIEW` (compliance hold), or end at `FAILED`, `CANCELED`, or `APPROVAL_DENIED`. List and filter with `GET /transactions`, or subscribe to [webhooks](/guides/webhooks-integration) instead of polling.

## Paying on behalf of a customer

To pay from a *customer's* wallet, the customer first delegates payment authority to your agent. Invite them:

<CodeGroup>
  ```text MCP theme={null}
  Invite bruce@propertymanagement.com to my Carrier Payment Agent.
  ```

  ```python Python theme={null}
  customer = client.agents.create_customer(
      "agt_019cd1798d637a4da75dce386343931d",
      recipients=[{"type": "email", "value": "bruce@propertymanagement.com"}],
      permissions=["payments.create"],
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const customer = await client.agents.createCustomer("agt_019cd1798d637a4da75dce386343931d", {
    recipients: [{ type: "email", value: "bruce@propertymanagement.com" }],
    permissions: ["payments.create"],
    "Idempotency-Key": crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agents create-customer \
    --agent-id agt_019cd1798d637a4da75dce386343931d \
    --recipient '{type: email, value: bruce@propertymanagement.com}' \
    --permission payments.create \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.co/agents/agt_019cd1798d637a4da75dce386343931d/customers \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "recipients": [{ "type": "email", "value": "bruce@propertymanagement.com" }],
          "permissions": ["payments.create"]
        }
      }
    }'
  ```
</CodeGroup>

The customer gets an email, completes onboarding, and approves the agent-customer relationship. After that, add their party ID as `customerPartyId` when sending — the payment then draws from their wallet instead of yours.

Find a customer's `customerPartyId` via `GET /customers` — each customer resource's `id` is the party ID.