# Payments (/ai/reference/orders/payments)

Toolset `payments`, 14 tools.

## Records [#records]

### `payment` [#payment]

A payment on an order, with its captures and refunds. A payment is found through the order: get the order with include payments for its payment ids.

- Permission: `orders.read`
- Tools: `payment_list`, `payment_get`
- Sorts: `created_at`, `updated_at`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |
| `payment_session_id` | string |  |  |

### `payment_provider` [#payment_provider]

A payment provider installed in the store; its id is what mark_paid and the order payments name. Which regions offer it is a setting a person makes.

- Permission: `orders.read`
- Tools: `payment_provider_list`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `is_enabled` | boolean |  | Only enabled providers |

### `refund_reason` [#refund_reason]

A reason a refund can be filed under; pass its id to payment_refund.

- Permission: `orders.read`
- Tools: `refund_reason_list`, `refund_reason_get`
- Sorts: `created_at`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |

## Actions [#actions]

### `order_credit_line_create` [#order_credit_line_create]

Settle an order's pending difference with a credit line instead of a payment or refund.

Only valid while the order has a pending difference: a positive amount settles money the customer still owes, a negative one money owed back, and neither may exceed the difference. amount is in the order currency. reference says what the credit is for and reference_id points at it. Nothing is charged or paid out.

- Action key: `order_credit_line.create`
- Permission: `orders.refund`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `order_id` | string | yes | Order ID (order_…) |
| `amount` | number | yes | Credit in the order currency; negative when money is owed back |
| `reference` | string | yes | What the credit is for, such as "refund". at least 1 characters |
| `reference_id` | string | yes | ID of the thing the credit refers to. at least 1 characters |
| `metadata` | map of string or number or boolean or list of any value or map of any value or null |  |  |

Example input:

```json
{
  "order_id": "019bb3ef-6501-7dc3-a2e7-726e91520b7a",
  "amount": -1200,
  "reference": "refund",
  "reference_id": "refund_01J9"
}
```

### `payment_capture` [#payment_capture]

Capture an authorized payment, in full or in part.

Most card and wallet providers settle a payment once: they capture only everything still open, and a smaller amount is refused with payment_partial_capture_unsupported. Then capture in full and refund the difference instead.

- Action key: `payment.capture`
- Permission: `orders.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_id` | string | yes | Payment ID (pay_…) |
| `amount` | number |  | Omit to capture the full authorized amount. above 0 |

Example inputs:

```json
{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5"
}
```

```json
{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5",
  "amount": 4990
}
```

### `payment_collection_create` [#payment_collection_create]

Open a payment collection on an order for an amount still to be paid.

Nothing is charged: it only opens the amount for payment. Mark it paid with payment_mark_paid once the money arrived.

- Action key: `payment_collection.create`
- Permission: `orders.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `order_id` | string | yes |  |
| `amount` | number | yes | above 0 |

Example input:

```json
{
  "order_id": "019bb3ef-6501-7dc3-a2e7-726e91520b7a",
  "amount": 4990
}
```

### `payment_collection_delete` [#payment_collection_delete]

Delete a payment collection that holds no payment yet.

- Action key: `payment_collection.delete`
- Permission: `orders.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_collection_id` | string | yes | Payment collection ID from the order |

Example input:

```json
{
  "payment_collection_id": "019bb4e4-0993-7733-bdd6-6e58e38f7703"
}
```

### `payment_mark_paid` [#payment_mark_paid]

Record an order's payment as received outside the store, e.g. a bank transfer.

Takes the payment collection id from the order (get the order with include payments). Nothing is charged; the payment is only recorded as paid.

- Action key: `payment.mark_paid`
- Permission: `orders.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_collection_id` | string | yes | Payment collection ID (pay_col_…) from the order |
| `order_id` | string | yes |  |
| `provider_id` | string |  | Payment provider to record it under |

Example input:

```json
{
  "payment_collection_id": "019bb4e4-0993-7733-bdd6-6e58e38f7703",
  "order_id": "019bb3ef-6501-7dc3-a2e7-726e91520b7a"
}
```

### `payment_refund` [#payment_refund]

Refund part or all of a captured payment.

Omit amount to refund everything not yet refunded. Amounts are in the payment currency. A dry run reports how much is still refundable without refunding anything; list reasons with refund_reason_list.

- Action key: `payment.refund`
- Permission: `orders.refund`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.
- Dry run: supported, with `dry_run` set to true.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payment_id` | string | yes | Payment ID (pay_…) |
| `amount` | number |  | above 0 |
| `refund_reason_id` | string |  |  |
| `note` | string |  | Internal note |

Example inputs:

```json
{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5"
}
```

```json
{
  "payment_id": "019bb4b5-6430-7a01-8e17-6df1bfccb8e5",
  "amount": 1200,
  "note": "damaged on arrival"
}
```

### `refund_reason_create` [#refund_reason_create]

Add a reason a refund can be filed under.

- Action key: `refund_reason.create`
- Permission: `orders.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | yes | Shown in the refund form |
| `code` | string | yes | Short code, e.g. damaged |
| `description` | string or null |  |  |

Example input:

```json
{
  "label": "Damaged on arrival",
  "code": "damaged"
}
```

### `refund_reason_delete` [#refund_reason_delete]

Delete a refund reason; refunds already filed under it keep their record.

- Action key: `refund_reason.delete`
- Permission: `orders.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refund_reason_id` | string | yes | Refund reason ID from refund_reason_list |

Example input:

```json
{
  "refund_reason_id": "019bb65c-0f78-7003-af13-95ac276a7aeb"
}
```

### `refund_reason_update` [#refund_reason_update]

Change the label, code or description of a refund reason.

- Action key: `refund_reason.update`
- Permission: `orders.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refund_reason_id` | string | yes | Refund reason ID from refund_reason_list |
| `label` | string |  | Shown in the refund form |
| `code` | string |  | Short code, e.g. damaged |
| `description` | string or null |  |  |

Example input:

```json
{
  "refund_reason_id": "019bb65c-0f78-7003-af13-95ac276a7aeb",
  "label": "Arrived damaged"
}
```