---
name: natural-create-payment
description: Create a payment from a customer's wallet to a recipient on the Natural platform. Use when you have a customerPartyId and need to create a payment. Use natural-list-customers to discover customers and natural-check-balance for pre-flight balance checks.
metadata:
  author: Natural
  version: "1.0"
---

# Create Payment

Create a payment from a customer's wallet to a recipient (email, phone, or party ID) on the Natural platform.

This skill handles only payment creation. For related operations, see:

- **[List Customers](https://natural.com/skills/list-customers.md)** — discover customers with delegated payment authority
- **[Check Balance](https://natural.com/skills/check-balance.md)** — pre-flight balance check
- **[Get Transaction](https://natural.com/skills/get-transaction.md)** — verify payment status after creation

## Prerequisites

- A Natural credential with payment creation access is configured
- You have a `customerPartyId` (`pty_xxx`) with delegated payment authority
- For agent-attributed payment creation, you have a stable `instanceId`
- If your credential is not agent-bound and you want claimed agent attribution, you also know the existing `agentId` (`agt_xxx`)

## Parameters

Required:

| Parameter         | Format                     | Description                      |
| ----------------- | -------------------------- | -------------------------------- |
| `customerPartyId` | `pty_xxx`                  | The customer's party ID          |
| `recipient`       | email, phone, or `pty_xxx` | Who receives the payment         |
| `amount`          | integer (minor units)      | Amount in cents. $50.00 = `5000` |
| `description`     | string (max 500)           | Description of the payment       |
| `idempotencyKey`  | string (max 256)           | Unique key for this request      |

Agent attribution:

| Parameter    | Format           | Description                                                                                                                                             |
| ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentId`    | `agt_xxx`        | Only for claimed attribution with an unbound credential such as a party API key or user-scoped OAuth grant. Omit for agent keys and agent-scoped OAuth. |
| `instanceId` | free-form string | Session or conversation ID (e.g., a UUID or your own identifier). Required for agent-attributed money movement.                                         |

Optional:

| Parameter  | Default | Description   |
| ---------- | ------- | ------------- |
| `currency` | `USD`   | Currency code |

## Workflow

### 1. Validate inputs

- **Amounts are always in minor units (cents).** Convert dollar amounts before sending: `$50.00` becomes `5000`, `$1.50` becomes `150`.
- **Recipient format:** email must contain `@`, phone must start with `+` or be 10+ digits, party ID must start with `pty_`.
- **Idempotency:** Generate a unique `idempotencyKey` per payment intent. If you need to retry a failed request, reuse the same key to prevent duplicate payments. Generate a new key for each distinct payment.

### 2. Send the payment

Execute the payment creation using the CLI or MCP adapter below.

### 3. Confirm submission

The response includes a `transactionId` (`txn_xxx`) and initial `status`. Use [Get Transaction](https://natural.com/skills/get-transaction.md) to check the final status if needed.

## Error handling

When a payment fails, categorize by cause:

- **Insufficient funds:** Inform the user of the shortfall — use [Check Balance](https://natural.com/skills/check-balance.md) to show the current balance
- **Invalid recipient:** Verify the recipient format
- **Auth error:** API key is missing, invalid, or lacks permission for this customer
- **Rate limit / server error:** Wait and retry with the same `idempotencyKey`

## Agent attribution

Agent attribution has two modes:

- **Bound agent credential**: agent keys and agent-scoped OAuth grants already identify the agent. Do not pass `agentId`; do pass `instanceId` for money-moving calls.
- **Unbound credential**: party API keys and user-scoped OAuth grants act as user/party actions by default. Pass `agentId` only when the user intentionally wants claimed attribution to an existing agent; also pass `instanceId`.

`instanceId` is required whenever the payment is agent-attributed: agent key, agent-scoped OAuth grant, or claimed `agentId`.

---

## CLI Adapter

Execute the create-payment workflow using the `natural` CLI. All commands should use `--format json` for structured output that agents can parse.

### Command

```bash
natural payments create \
  --customer-party-id pty_xxx \
  --counterparty bob@example.com \
  --amount 5000 \
  --description "Invoice #789" \
  --x-instance-id conv-abc-123 \
  --format json
```

If you are using a party API key or user-scoped OAuth grant and intentionally claiming attribution to an existing agent, also pass `--x-agent-id agt_xxx`. Omit `--x-agent-id` for agent keys and agent-scoped OAuth grants. The `--idempotency-key` flag is optional — the CLI auto-generates a UUID if omitted. Pass it explicitly when retrying a failed request.

Response shape:

```json
{
  "transactionId": "txn_xxx",
  "status": "PROCESSING",
  "amount": 5000,
  "currency": "USD",
  "description": "Invoice #789",
  "senderName": "John Doe",
  "recipientName": "bob@example.com",
  "direction": "OUTBOUND",
  "isDelegated": true,
  "createdAt": "2026-04-03T12:00:00Z",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Exit codes

| Code | Meaning                                              | Action                           |
| ---- | ---------------------------------------------------- | -------------------------------- |
| 0    | Success                                              | Parse JSON response              |
| 1    | Business error (insufficient funds, invalid request) | Read error message, do not retry |
| 2    | Usage error (missing flags, bad arguments)           | Fix the command                  |
| 3    | Auth error (missing or invalid API key)              | Check credentials                |
| 4    | Network/server error (timeout, rate limit)           | Retry with same idempotency key  |

### Notes

- Always pass `--format json` — human-formatted output is not designed for agent parsing
- Amounts are always minor units (cents) in both input and output
- Pass the format flag explicitly for clarity, even when stdout is piped

---

## MCP Adapter

Execute the create-payment workflow using Natural MCP server tools. The MCP server authenticates via Bearer token in the session.

### Tool

Tool: `create_payment`

```json
{
  "amount": 5000,
  "customerPartyId": "pty_xxx",
  "recipient": "bob@example.com",
  "description": "Invoice #789",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "instanceId": "conv-abc-123"
}
```

Include `"agentId": "agt_xxx"` only when using a party API key or user-scoped OAuth grant and intentionally claiming attribution to an existing agent. Omit `agentId` for agent keys and agent-scoped OAuth grants.

Unlike the CLI, the MCP tool requires `idempotencyKey` explicitly — it does not auto-generate one.

The response includes the payment fields and status. Claim links are never returned: when status is `PENDING_CLAIM`, Natural delivers the claim link to the recipient directly.

### Error handling

MCP tool errors are returned as tool call failures with an error message. Categorize by the message content:

- Authentication errors: API key issues
- Validation errors: missing or invalid parameters (for example, `instanceId is required for agent-attributed money movement`)
- Business errors: insufficient funds, invalid recipient
- Server errors: retry with the same `idempotencyKey`

### Notes

- `idempotencyKey` is required — always generate and provide one
- `agentId` is only for claimed attribution with unbound credentials
- `instanceId` is required for agent-attributed money movement: agent keys, agent-scoped OAuth grants, or calls that provide `agentId`