---
title: codespar_checkout
description: Sell-side merchant checkout. Assemble a cart and create a charge for a shopper to pay you, returned with a hosted payment page and, on Pix, the copia-e-cola. Pix in Brazil is the live rail today.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

<MetaToolHeader tool="codespar_checkout" />

As a merchant, you assemble a cart and create a charge for a shopper to pay **you**. Use [`codespar_shop`](/docs/concepts/meta-tools/shop) when the agent is the buyer, [`codespar_charge`](/docs/concepts/meta-tools/charge) for a bare inbound charge, and [`codespar_pay`](/docs/concepts/meta-tools/pay) for an outbound transfer.

## Actions

<MetaToolActions tool="codespar_checkout" />

## Example

A one-item cart on the Pix rail. Prices are in **major** units (`249.9`, not `24990`).

<Split min={380}>
<SplitPane label="Call · tools/call">

```json title="arguments"
{
  "name": "codespar_checkout",
  "arguments": {
    "items": [{ "title": "Example item", "price": 249.9, "quantity": 1 }],
    "paymentMethod": "pix",
    "currency": "BRL",
    "buyer": { "name": "Example Buyer", "email": "buyer@example.com" }
  }
}
```

</SplitPane>
<SplitPane label="Result · fields the tool document names">

```json title="result"
{
  "charge_url": "https://example.com/pay/checkout_0000",
  "pix_copy_paste": "..."
}
```

</SplitPane>
</Split>

`charge_url` is the hosted payment page; `pix_copy_paste` is present on the Pix rail. Settlement is asynchronous, correlated like `codespar_charge` (see Notes).

## When to use

- **A cart with several items** where you want CodeSpar to sum the total, describe it to the shopper and hand back one payment page. For a single amount with no cart, `codespar_charge` is the bare primitive.
- **Pix in Brazil.** That is the rail with catalog lines today. `paymentMethod: "boleto"` and `"card"` pass argument validation and then fail at routing with `no_eligible_providers`: no provider is called, nothing is charged. Reach card and boleto through `codespar_charge`, which has lines for both. For USDC, call [`codespar_crypto_pay`](/docs/concepts/meta-tools/crypto-pay).
- **Guest shoppers.** `buyer` is optional; omitted (or with no `name`) the charge falls back to a guest placeholder and the Pix rail charges against the connection's customer id.

## Arguments

The published schema declares the fields below. Two of them (`due_date`, `country`) are read by the dispatch and not declared in the schema; they are marked.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | `array` | Yes | Non-empty. Each item `{ title?, price, quantity? }`, `price` in major units, `quantity` default 1. The total is the sum of price × quantity unless `amount` is passed. `unit_price` / `unitPrice` / `value` are accepted aliases for `price`, `qty` for `quantity`, `name` / `description` for `title` |
| `amount` | `number` | No | Explicit cart total in major units; wins over the items sum. When absent every item needs a `price` |
| `paymentMethod` | `string` | No | `pix` (default) \| `boleto` \| `card`. Only `pix` routes today (see When to use) |
| `currency` | `string` | No | Defaults to `BRL` |
| `description` | `string` | No | Shown to the shopper; defaults to a summary of the items |
| `buyer` | `object` | No | `{ name, email?, document?, phone? }`; defaults to a guest checkout |
| `metadata` | `object` | No | Provider metadata, e.g. `customer_id` for PSPs that require a pre-created customer |
| `recipient` | `string` | No | Published in the schema but not read by the checkout dispatch. Attribute the charge through `buyer` or `metadata.customer_id` instead |
| `due_date` | `string` | No | Charge due date passed through to the provider (`dueDate` accepted as an alias). Read by the dispatch, **not declared in the published schema** (ent#1181) |
| `country` | `string` | No | ISO 3166-1 alpha-2 for the eligibility rail, default `BR`. Honoured by the router, **not declared in the published schema** (ent#1181) |

## Errors and what to do

| Error | Cause | What to do |
|---|---|---|
| `invalid_args` | `items` missing or empty, an item without a usable `price` and no top-level `amount`, a non-positive quantity, or a `paymentMethod` outside `pix` / `boleto` / `card` (`usdc` included). | Fix the call against the Arguments table; for USDC use `codespar_crypto_pay`. |
| `no_eligible_providers` | The intent resolved to a rail with no `codespar_checkout` catalog line (`boleto`, `card`), or none of its providers is connected on this project. Nothing was dispatched. | Use `codespar_charge` for card and boleto, or connect a Pix provider via [`codespar_manage_connections`](/docs/concepts/meta-tools/manage-connections). |

## Money and mandate

No money moves on this call. It issues an inbound charge the shopper settles on the hosted page or by Pix; the merchant's connected rail authorizes issuance, and there is no consumer mandate on the sell side. Completion arrives asynchronously, the same way as `codespar_charge`.

## Related

- [`codespar_shop`](/docs/concepts/meta-tools/shop): buy-side, the agent is the shopper
- [`codespar_charge`](/docs/concepts/meta-tools/charge): a bare inbound charge, with card and boleto lines
- [`codespar_crypto_pay`](/docs/concepts/meta-tools/crypto-pay): on-chain settlement
- [`codespar_pay`](/docs/concepts/meta-tools/pay): a bare outbound transfer
- [E-Commerce Checkout cookbook](/docs/cookbooks/ecommerce-checkout): cart → checkout → fulfillment

## Notes

**Rails.** `paymentMethod` picks the rail, and the router's eligibility set is the catalog for `codespar_checkout` intersected with the providers your project has connected, so a rail with no catalog line can never route, however the call is spelled. Pix × BRL × BR has lines on Asaas and Mercado Pago and returns `charge_url` plus the copia-e-cola. `boleto` and `card` have no `codespar_checkout` line. `usdc` is rejected by argument validation before routing.

**From the SDK.** There is no typed wrapper; `session.execute("codespar_checkout", arguments)` takes the same arguments as the MCP call and returns a `tool_call_id` plus the charge under `data`. Correlate completion with [`session.paymentStatus()`](/docs/api/sdk/session#paymentstatustoolcallid-promisepaymentstatusresult), just like `codespar_charge`. `@codespar/types` does not carry a copy of this schema.