Square

Each terminal can be linked to one Square merchant account. Once linked, Square sends payment events to MyNearStores, and MyNearStores can create orders and payments that show up in the merchant's Square Reports → Sales.

ConnectCopy Anchor Link

Open the authorize URL in a popup. MyNearStores redirects the merchant to Square's consent page and handles the callback.

const popup = window.open(
  `${MNS_API}/square/oauth/authorize?bu_id=${buId}&terminal_id=${terminalId}`,
  'square-connect',
  'width=600,height=700',
)

window.addEventListener('message', (event) => {
  if (event.data?.type === 'SQUARE_OAUTH_SUCCESS') {
    // { type, buId, terminalId, merchantId }
    markConnected(event.data.terminalId, event.data.merchantId)
  }
})

• The authorize link is valid for 10 minutes and can be used once.
• On success the popup shows a confirmation, posts SQUARE_OAUTH_SUCCESS to the opener, and closes itself after 2 seconds.
• If the merchant declines, the popup shows the error and posts nothing. Check the status after the popup closes.

MyNearStores requests these Square permissions: PAYMENTS_READ, PAYMENTS_WRITE, ORDERS_READ, ORDERS_WRITE, LOYALTY_READ, LOYALTY_WRITE, CUSTOMERS_READ, MERCHANT_PROFILE_READ.

Check the connectionCopy Anchor Link

curl "$MNS_API/square/oauth/status/1/31"

{ "connected": true, "merchantId": "MLR8XXXXXXXXX" }

Payments from SquareCopy Anchor Link

After connecting, payments taken on Square are delivered to MyNearStores by webhook and stored against the merchant:

Events for merchants that are not connected, or have disconnected, are ignored. Re-delivered events are stored once.

Record a sale in SquareCopy Anchor Link

POST /square/sales/record creates an order and an external payment in the merchant's Square account, so the sale appears in Square's sales reports.

curl -X POST "$MNS_API/square/sales/record" \
  -H "Content-Type: application/json" \
  -d '{
    "bu_id": 1,
    "terminal_id": 31,
    "items": [{ "name": "Coffee", "quantity": 2, "price": 350, "currency": "USD" }],
    "note": "Walk-in customer sale"
  }'

• price is the unit price in the smallest currency unit (cents): 350 is $3.50.
• location_id is optional. Without it, the merchant's first active Square location is used.

{
  "success": true,
  "square_order_id": "kq3XXXXXXXXXXXX",
  "square_payment_id": "bP9XXXXXXXXXXXX",
  "status": "COMPLETED",
  "total_amount": 700,
  "total_amount_display": "7.00 USD",
  "currency": "USD",
  "receipt_url": "https://squareup.com/receipt/preview/bP9XXXXXXXXXXXX",
  "dashboard_url": "https://app.squareup.com/dashboard/sales/reports/payment-methods"
}

DisconnectCopy Anchor Link

curl -X DELETE "$MNS_API/square/oauth/token/1/31"

MyNearStores revokes the token with Square, so Square stops sending events for that merchant, then deletes it. The call succeeds even if Square cannot be reached.