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

# Record tender payment

> Record the result of one tender attempt on a placed order.

Records the result of one tender attempt. The same `attempt_reference` is idempotent: a retry does not create a second charge.

If `approved_amount` is present and lower than the tender total, the tender is stored as `FAILED`.

> [!NOTE]
>
> Requires a Storefront API access token from [Token
> exchange](https://firespark.cloud/docs/storefront-api/oauth/exchange/post.md).

`order.payIntent()` calls this after the payment package finishes. You only call it yourself when a channel reports the attempt outside the SDK.

## Path parameters

| Parameter | Required | Description |
| - | - | - |
| `id` | Yes | External order identifier |

## Request body

| Field | Required | Description |
| - | - | - |
| `tender_id` | Yes | Tender on the locked intent |
| `attempt_reference` | Yes | The tender's current attempt, 10–64 characters |
| `status` | Yes | `IDLE`, `PENDING`, `PAID`, `FAILED`, `CANCELLED`, or `REFUNDED` |
| `details` | No | Method-specific data. `details.method` must match the tender |
| `approved_amount` | No | Amount the provider approved |
| `provider_reference` | No | Provider id for this attempt, 1–128 characters |
| `error_message` | No | Up to 500 characters |
| `metadata` | No | Merged onto the tender |

```bash theme={null}
curl -X POST "https://firespark.cloud/api/storefront/v1/orders/ord-48291/payments" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tender_id": "tnd-card-1",
    "attempt_reference": "att-9f3c1a20b4",
    "status": "PAID",
    "details": { "method": "CARD", "brand": "visa", "last4": "4242" }
  }'
```

## Response

Returns `200` with the order. `payment_status` is derived from the live tenders of the current intent. When every live tender in the waiting `PAYING` node's scope is settled, fulfillment advances that node to `PAID`.

`DEVICE` tenders belong to a `digital` paying node, together with `REDEMPTION`. `COUNTER`, `KIOSK`, `DOOR`, and `OTHER` belong to an `in_person` paying node.

## Error responses

| Status | Description |
| - | - |
| `404` | Order or tender not found |
| `409` | The order changed while the payment was recorded |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.