Square

​

At a glance

npx @deploybaseline/cli start --service square

import { createEmulator } from "@deploybaseline/cli";

const square = await createEmulator({ service: "square" });
// square.url is http://localhost:4000

{
  "square": {
    "merchant": {
      "business_name": "Baseline Coffee",
      "currency": "USD"
    },
    "locations": [
      {
        "name": "Baseline Coffee Downtown"
      }
    ],
    "apps": [
      {
        "name": "My app",
        "application_id": "sandbox-sq0idb-my-app",
        "application_secret": "sandbox-sq0csb-my-app-secret",
        "redirect_uris": ["http://localhost:3000/square/callback"],
        "personal_access_token": "EAAAl-baseline-square-token"
      }
    ],
    "customers": [
      {
        "given_name": "Ada",
        "family_name": "Lovelace",
        "email_address": "[email protected]"
      }
    ],
    "catalog": [
      {
        "type": "CATEGORY",
        "id": "#drinks",
        "category_data": {
          "name": "Drinks"
        }
      },
      {
        "type": "TAX",
        "id": "#sales-tax",
        "tax_data": {
          "name": "Sales tax",
          "percentage": "8.5"
        }
      },
      {
        "type": "ITEM",
        "id": "#latte",
        "item_data": {
          "name": "Latte",
          "categories": [
            {
              "id": "#drinks"
            }
          ],
          "tax_ids": ["#sales-tax"],
          "variations": [
            {
              "type": "ITEM_VARIATION",
              "id": "#latte-regular",
              "item_variation_data": {
                "name": "Regular",
                "price_money": {
                  "amount": 450,
                  "currency": "USD"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service square

import { SquareClient } from "square";

const square = new SquareClient({
  token: "EAAAl-baseline-square-token",
  baseUrl: process.env.SQUARE_EMULATOR_URL ?? "http://localhost:4000",
});

const { payment } = await square.payments.create({
  sourceId: "cnon:card-nonce-ok",
  idempotencyKey: crypto.randomUUID(),
  amountMoney: { amount: BigInt(1000), currency: "USD" },
});

​

URL mapping

​

Auth

• A token the CLI accepts (for example test_token_admin) acts as the first application’s personal access token, with every scope.
• apps[].personal_access_token acts as that application, with every scope.
• tokens[] seeds extra tokens. With scopes it behaves like an OAuth access token limited to those scopes; without them it is a personal token.
• OAuth access tokens carry the scopes the seller approved.

​

OAuth

• GET /oauth2/authorize?client_id=...&scope=PAYMENTS_WRITE+ORDERS_READ&state=... — Authorize: shows a consent page with the requested permissions. Approving redirects to the application’s redirect URL with code, response_type=code, and state; declining sends error=access_denied.
• POST /oauth2/token — Obtain token: with grant_type=authorization_code, client_id, client_secret, and code. Public clients send code_verifier instead of the secret (PKCE, S256 or plain). Access tokens last 30 days, or 24 hours with short_lived: true.
• The same call with grant_type=refresh_token refreshes a token. In the code flow the refresh token stays the same; in the PKCE flow it is single use, rotated on every refresh, and expires after 90 days. scopes narrows a refresh.
• POST /oauth2/revoke — Revoke token: with Authorization: Client <secret> and an access_token or merchant_id, it revokes the grant (revoke_only_access_token keeps the refresh token) and sends oauth.authorization.revoked.
• POST /oauth2/token/status — Retrieve token status: reports a token’s scopes, expiry, client, and merchant.

​

Requests

​

Square-Version

​

Idempotency

​

Pagination

​

Payments

• POST /v2/payments — Create payment: source_id, idempotency_key, amount_money, and optionally tip_money, app_fee_money, autocomplete, delay_duration, delay_action, order_id, customer_id, location_id, reference_id, note, and buyer_email_address
• GET /v2/payments — List payments: filters by begin_time, end_time, sort_order, location_id, total, last_4, and card_brand, and pages with cursor and limit
• GET /v2/payments/:id — Get payment
• PUT /v2/payments/:id — Update payment: amounts and tip of an APPROVED payment, with version_token
• POST /v2/payments/:id/complete — Complete payment
• POST /v2/payments/:id/cancel — Cancel payment
• POST /v2/payments/cancel — Cancel payment by idempotency key

​

Test values

​

Refunds

• POST /v2/refunds — Refund payment: all or part of a completed payment
• GET /v2/refunds — List payment refunds
• GET /v2/refunds/:id — Get payment refund

​

Orders

• POST /v2/orders — Create order: line items (catalog variations or ad hoc), taxes (ADDITIVE or INCLUSIVE), discounts (FIXED_PERCENTAGE, FIXED_AMOUNT, at order or line item scope), service charges, and fulfillments. Every total is computed on the server
• POST /v2/orders/calculate — Calculate order: prices an order without saving it
• POST /v2/orders/clone — Clone order: copies one into a new DRAFT
• GET /v2/orders/:id — Retrieve order
• POST /v2/orders/batch-retrieve — Batch retrieve orders
• PUT /v2/orders/:id — Update order: with the current version (VERSION_MISMATCH otherwise): a sparse update that merges lists by uid and honors fields_to_clear
• POST /v2/orders/search — Search orders: location_ids, state_filter, date_time_filter, customer_filter, source_filter, fulfillment_filter, and sort (the sort field must match the date filter field), return_entries, cursor, and limit
• POST /v2/orders/:id/pay — Pay order: payment_ids that cover the amount due

​

Customers

• GET /v2/customers — List customers
• POST /v2/customers — Create customer
• DELETE /v2/customers/:id — Delete customer: the same path takes GET and PUT, all with version checks
• POST /v2/customers/bulk-create — Bulk create customers: also bulk-retrieve, bulk-update, and bulk-delete
• POST /v2/customers/search — Search customers: email_address, phone_number, reference_id, created_at, updated_at, and creation_source filters and a sort

​

Catalog

• POST /v2/catalog/object — Upsert catalog object
• POST /v2/catalog/batch-upsert — Batch upsert catalog objects
• GET /v2/catalog/list — List catalog: filtered by types
• GET /v2/catalog/object/:id — Retrieve catalog object: include_related_objects
• POST /v2/catalog/batch-retrieve — Batch retrieve catalog objects
• DELETE /v2/catalog/object/:id — Delete catalog object: deleting an item deletes its variations
• POST /v2/catalog/batch-delete — Batch delete catalog objects: deleting an item deletes its variations
• POST /v2/catalog/search — Search catalog objects: exact_query, set_query, prefix_query, range_query, text_query, items_for_tax_query, and sorted_attribute_query
• POST /v2/catalog/search-catalog-items — Search catalog items
• POST /v2/catalog/update-item-taxes — Update item taxes
• GET /v2/catalog/info — Catalog info

​

Locations and merchants

• POST /v2/locations — Create location: GET on the same path lists them
• PUT /v2/locations/:id — Update location: GET on the same path retrieves one
• GET /v2/merchants — List merchants
• GET /v2/merchants/:id — Retrieve merchant: me works

​

Webhooks

• GET /v2/webhooks/event-types — List webhook event types
• POST /v2/webhooks/subscriptions — Create webhook subscription: GET on the same path lists them
• DELETE /v2/webhooks/subscriptions/:id — Delete webhook subscription: the same path takes GET and PUT
• POST /v2/webhooks/subscriptions/:id/signature-key — Update webhook signature key: rotates the key
• POST /v2/webhooks/subscriptions/:id/test — Test webhook subscription: sends a test event and returns the receiver’s answer

import { WebhooksHelper } from "square";

const valid = await WebhooksHelper.verifySignature({
  requestBody: rawBody,
  signatureHeader: req.headers["x-square-hmacsha256-signature"],
  signatureKey: "whsec-baseline",
  notificationUrl: "http://localhost:3000/square/webhooks",
});

​

Seed config

{
  "square": {
    "merchant": {
      "business_name": "Baseline Coffee",
      "country": "US",
      "currency": "USD"
    },
    "locations": [
      {
        "name": "Baseline Coffee Downtown"
      },
      {
        "name": "Baseline Coffee Uptown"
      }
    ],
    "apps": [
      {
        "name": "My app",
        "application_id": "sandbox-sq0idb-my-app",
        "application_secret": "sandbox-sq0csb-my-app-secret",
        "redirect_uris": ["http://localhost:3000/square/callback"],
        "personal_access_token": "EAAAl-baseline-square-token"
      }
    ],
    "tokens": [
      {
        "token": "EAAAl-read-only-token",
        "scopes": ["PAYMENTS_READ", "ORDERS_READ"]
      }
    ],
    "customers": [
      {
        "given_name": "Ada",
        "family_name": "Lovelace",
        "email_address": "[email protected]"
      }
    ],
    "catalog": [
      {
        "type": "TAX",
        "id": "#sales-tax",
        "tax_data": {
          "name": "Sales tax",
          "percentage": "8.5"
        }
      },
      {
        "type": "ITEM",
        "id": "#latte",
        "item_data": {
          "name": "Latte",
          "tax_ids": ["#sales-tax"],
          "variations": [
            {
              "type": "ITEM_VARIATION",
              "id": "#latte-regular",
              "item_variation_data": {
                "name": "Regular",
                "price_money": {
                  "amount": 450,
                  "currency": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "webhooks": [
      {
        "url": "http://localhost:3000/square/webhooks",
        "event_types": ["payment.created", "payment.updated"],
        "signature_key": "whsec-baseline"
      }
    ],
    "refund_delay_ms": 1000
  }
}

• name: the first location is the main one

​

Inspector

​

Limits

​

Conformance