Worlds / Payments and billing

Square API

A local Square seller with locations, payments, orders, catalog items and Terminal checkouts. Test the agent that refunds in-person sales, fixes catalog prices and works within refund windows.

Base path: /v2
Auth: Bearer access token, the world key
Endpoints: 21
Status: Active today

This reference previews the surface the Square world serves in the closed beta. Paths mirror the public Square API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_SQUARE_URL`	This world's origin followed by `/v2`
`WORLDS_API_KEY`	The world key, accepted wherever Square expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · square

import { SquareClient } from "square";

const client = new SquareClient({
  token: process.env.WORLDS_API_KEY,
  baseUrl: process.env.WORLDS_SQUARE_URL,
});

const { payment } = await client.payments.create({
  idempotencyKey: "pay-1",
  sourceId: "cnon:card-nonce-ok",
  amountMoney: { amount: 1000n, currency: "USD" },
});

API reference

21 of 21

Payments

Card and cash payments taken at a location.

POST/v2/paymentsCreate a payment
GET/v2/payments/{payment_id}Get a payment
POST/v2/payments/{payment_id}/completeComplete an approved payment
POST/v2/payments/{payment_id}/cancelCancel a payment
GET/v2/paymentsList payments

Fields · 5

`id`	string	Payment id
`status`	string	APPROVED, COMPLETED, CANCELED or FAILED
`amount_money`	object	Amount and currency
`order_id`	string	Linked order id
`customer_id`	string	Linked customer id

Refunds

Return money for a completed payment.

POST/v2/refundsRefund a payment
GET/v2/refunds/{refund_id}Get a refund
GET/v2/refundsList refunds

Fields · 4

`id`	string	Refund id
`payment_id`	string	Original payment id
`amount_money`	object	Refunded amount
`status`	string	PENDING, COMPLETED, REJECTED or FAILED

Orders

Line items, taxes and totals for a sale.

POST/v2/ordersCreate an order
GET/v2/orders/{order_id}Retrieve an order
PUT/v2/orders/{order_id}Update an order
POST/v2/orders/{order_id}/payPay for an order
POST/v2/orders/searchSearch orders

Fields · 5

`id`	string	Order id
`location_id`	string	Location id
`line_items`	array	Items sold
`total_money`	object	Order total
`state`	string	OPEN, COMPLETED or CANCELED

Customers

Customer directory for a seller.

POST/v2/customersCreate a customer
GET/v2/customers/{customer_id}Retrieve a customer
PUT/v2/customers/{customer_id}Update a customer
POST/v2/customers/searchSearch customers

Fields · 4

`id`	string	Customer id
`given_name`	string	First name
`family_name`	string	Last name
`email_address`	string	Email address

Invoices

Bills sent to customers for an order.

POST/v2/invoicesCreate an invoice
POST/v2/invoices/{invoice_id}/publishPublish an invoice
POST/v2/invoices/{invoice_id}/cancelCancel an invoice
GET/v2/invoicesList invoices

Fields · 4

`id`	string	Invoice id
`order_id`	string	Linked order id
`status`	string	DRAFT, UNPAID, PAID, CANCELED and more
`primary_recipient`	object	Customer receiving it

Test workflow

Prepare. Select the Square setup for your workflow and review its starting records, including payments, refunds, orders.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Refund on the 10:40 order is $28.00
No other refunds on the catering order
Oat latte variation price $6.25 at Mission St
Oat latte price unchanged at the other two locations
No Terminal checkout canceled on device MS-02

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Square
version: 2
connector: square
seed: square-starter
mode: isolated
policy: >
  A catering customer was missing one $28 tray. Refund only that tray on the
  10:40 order. Raise the oat latte price to $6.25 at Mission St only.
tasks:
  - id: refund-a-payment-or-part-of-an-order
    prompt: Refund a payment or part of an order
  - id: update-item-variation-prices-in-the-catalog
    prompt: Update item variation prices in the catalog
  - id: cancel-a-stuck-terminal-checkout
    prompt: Cancel a stuck Terminal checkout
expected:
  - "Refund on the 10:40 order is $28.00"
  - No other refunds on the catering order
  - Oat latte variation price $6.25 at Mission St
  - Oat latte price unchanged at the other two locations
  - No Terminal checkout canceled on device MS-02
scenarios:
  - idempotency-reused
  - version-mismatch
  - rate-limited

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`idempotency-reused`	A refund with a reused idempotency_key and new amount is rejected
`version-mismatch`	Catalog upsert returns VERSION_MISMATCH after a concurrent edit
`rate-limited`	Payments API returns 429 RATE_LIMITED
`refund-pending`	The refund stays PENDING before turning COMPLETED
`token-expired`	The OAuth access token expires and calls return 401

Starting data

Start each run from the same records and relationships. The overview below describes the Square starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
locations	3 stores with their own devices
payments	300 COMPLETED, 6 CANCELED, 4 FAILED
orders	300 with line items and tenders
catalog	85 ITEM objects, 140 ITEM_VARIATION objects
terminal checkouts	2 stuck IN_PROGRESS

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Payments records

Payments

Card and cash payments taken at a location.

Field	Type	Meaning / relationship
`id`	string	Payment id
`status`	string	APPROVED, COMPLETED, CANCELED or FAILED
`amount_money`	object	Amount and currency
`order_id`	string	Linked order id
`customer_id`	string	Linked customer id

json · illustrative record shape

{
  "id": "<Payment id>",
  "status": "<APPROVED, COMPLETED, CANCELED or FAILED>",
  "amount_money": {},
  "order_id": "<Linked order id>",
  "customer_id": "<Linked customer id>"
}

See payments operations

Refunds records

Refunds

Return money for a completed payment.

Field	Type	Meaning / relationship
`id`	string	Refund id
`payment_id`	string	Original payment id
`amount_money`	object	Refunded amount
`status`	string	PENDING, COMPLETED, REJECTED or FAILED

json · illustrative record shape

{
  "id": "<Refund id>",
  "payment_id": "<Original payment id>",
  "amount_money": {},
  "status": "<PENDING, COMPLETED, REJECTED or FAILED>"
}

See refunds operations

Orders records

Orders

Line items, taxes and totals for a sale.

Field	Type	Meaning / relationship
`id`	string	Order id
`location_id`	string	Location id
`line_items`	array	Items sold
`total_money`	object	Order total
`state`	string	OPEN, COMPLETED or CANCELED

json · illustrative record shape

{
  "id": "<Order id>",
  "location_id": "<Location id>",
  "line_items": [],
  "total_money": {},
  "state": "<OPEN, COMPLETED or CANCELED>"
}

See orders operations

Customers records

Customers

Customer directory for a seller.

Field	Type	Meaning / relationship
`id`	string	Customer id
`given_name`	string	First name
`family_name`	string	Last name
`email_address`	string	Email address

json · illustrative record shape

{
  "id": "<Customer id>",
  "given_name": "<First name>",
  "family_name": "<Last name>",
  "email_address": "person@example.test"
}

See customers operations

Invoices records

Invoices

Bills sent to customers for an order.

Field	Type	Meaning / relationship
`id`	string	Invoice id
`order_id`	string	Linked order id
`status`	string	DRAFT, UNPAID, PAID, CANCELED and more
`primary_recipient`	object	Customer receiving it

json · illustrative record shape

{
  "id": "<Invoice id>",
  "order_id": "<Linked order id>",
  "status": "<DRAFT, UNPAID, PAID, CANCELED and more>",
  "primary_recipient": {}
}

See invoices operations

See the Square world in the catalog