codespar_checkout

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.

Sell-sideYour agent is the merchant: it collects from, invoices, ships to, or verifies a counterparty.

Assemble a cart and dispatch it as a charge with a hosted payment page.

tool codespar_checkoutone operationmoves no moneyalways required items

As a merchant, you assemble a cart and create a charge for a shopper to pay you. Use codespar_shop when the agent is the buyer, codespar_charge for a bare inbound charge, and codespar_pay for an outbound transfer.

Actions

Operation	What it does	Money	Needs
single call, no selector	Sum a cart into an inbound charge on your connected rail and return a hosted payment page (charge_url) plus, on Pix, the copia-e-cola	no	—

Names come from the published tool document (/v1/meta-tools.json, the same list the MCP server answers to tools/list); the one-line summaries and the money class are kept in the docs repository and checked against it on every build.

Example

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

Call · tools/call

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" }
  }
}

Result · fields the tool document names

result

{
  "charge_url": "https://example.com/pay/checkout_0000",
  "pix_copy_paste": "..."
}

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.
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`.

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.

codespar_shop: buy-side, the agent is the shopper
codespar_charge: a bare inbound charge, with card and boleto lines
codespar_crypto_pay: on-chain settlement
codespar_pay: a bare outbound transfer
E-Commerce Checkout cookbook: 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(), just like codespar_charge. @codespar/types does not carry a copy of this schema.

codespar_checkout

On this page