Paybrain
PricingDocs
(877) 235-0050Sign inGet started
⌘K
Docs/Developers

POS API

The POS API lets your own server read the data your Paybrain register collects. Use it to power an app your customers sign into, such as a branded loyalty app: look a customer up by their phone number, show their points and memberships, and list what they bought.

Premium only

API keys are a Premium feature. On Basic you can't create keys, and existing keys stop working until you upgrade again. See Plans and fees.

Before you start

  • Your Paybrain account is on Premium.
  • You have an API key. Create one under Settings›API Keys, the same way as for the Checkout API.
  • Your app has its own server. The key goes there, never in the app.
  • Amounts are in cents. Dates are ISO 8601 in UTC.
Your server proves who the customer is

These endpoints return any of your customers to anyone holding the key. Keep the key on your server and only look a customer up after your app has confirmed they own the phone number, for example with a code you text them. An API key in an app can be pulled out, and with it anyone could read every customer's history and create checkouts on your account.

Authentication

Send the key in the Authorization header on every request.

Authorization: Bearer pbk_…

All endpoints are on https://api.paybrain.io.

Find a customer by phone

GET /v1/pos/customers?phone=…

curl "https://api.paybrain.io/v1/pos/customers?phone=%2B13055550123" \
  -H "Authorization: Bearer pbk_…"

phone can be E.164 (+13055550123) or a 10-digit US number in any format, such as (305) 555-0123. Numbers outside the US need the + and country code.

{
  "customer": {
    "id": "6a6689d0c1e2f3a4b5c6d7e8",
    "name": "Dana Reyes",
    "phone": "+13055550123",
    "email": "dana@example.com",
    "visitCount": 12,
    "lastVisitAt": "2026-11-14T18:22:05.000Z",
    "loyalty": {
      "enabled": true,
      "points": 140,
      "pointsValueCents": 700,
      "pointsForOneDollarOff": 20,
      "redemptionThreshold": 100
    },
    "memberships": [
      { "planName": "Monthly Facial", "status": "active", "memberBarcode": "M-20431" }
    ]
  }
}
FieldMeaning
idThe customer's id. Use it to list their sales.
name, emailLeft out when you don't have them on file.
visitCount, lastVisitAtHow often they've bought from you, and when they last did.
loyalty.enabledWhether loyalty is turned on for your business.
loyalty.pointsTheir points balance now.
loyalty.pointsValueCentsWhat those points are worth as a discount at the register.
loyalty.pointsForOneDollarOff, loyalty.redemptionThresholdYour loyalty settings: how many points take $1 off, and the fewest points that can be redeemed (0 means no minimum). Customers earn 1 point per dollar spent.
membershipsTheir memberships, with each plan's name, status and the barcode staff scan at the register.

List a customer's sales

GET /v1/pos/customers/{id}/sales

curl "https://api.paybrain.io/v1/pos/customers/6a6689d0c1e2f3a4b5c6d7e8/sales?limit=20" \
  -H "Authorization: Bearer pbk_…"
ParameterDefaultMeaning
limit20How many sales to return, from 1 to 50
offset0How many to skip, for the next page

Sales come newest first. Only paid sales are listed; refunded ones stay in the list and say so.

{
  "sales": [
    {
      "id": "6a6702b1c1e2f3a4b5c6d7e9",
      "orderNumber": 1042,
      "createdAt": "2026-11-14T18:22:05.000Z",
      "status": "partially_refunded",
      "totalCents": 1080,
      "refundedCents": 540,
      "refundedAt": "2026-11-14T19:01:44.000Z",
      "itemsSummary": "2× Latte",
      "items": [{ "name": "Latte", "quantity": 2, "refundedQuantity": 1 }],
      "pointsEarned": 10,
      "pointsRedeemed": 0,
      "receiptUrl": "https://paybrain.io/receipt/…"
    }
  ],
  "total": 12,
  "hasMore": true
}
FieldMeaning
statuspaid, partially_refunded or refunded
totalCentsWhat the customer paid, tax and tip included
refundedCents, refundedAtHow much has been given back so far, and when the last refund was
itemsEach line sold, with how many of it were returned
pointsEarned, pointsRedeemedLoyalty points the sale earned and spent
receiptUrlThe customer's receipt page, the same one their emailed receipt links to. Not set on a sale paid in parts; each of its payments has its own
paymentsOnly on a sale paid in parts (say part cash, part card): each payment's method (cash or card), amountCents (tip included), tipCents, status (paid or refunded), refundedCents and receiptUrl
total, hasMoreHow many sales the customer has in all, and whether there's another page
Note

Bar tabs aren't listed yet. A tab's loyalty points still count in the customer's balance.

Errors

StatusWhen
400A request field is invalid, such as a phone that isn't a phone number or a limit over 50
404No customer with that phone number, or no customer with that id on your account
410The key is missing, malformed, inactive or deleted, or the account is on Basic. The body is a message saying which.
500Something went wrong on our side. Try again.

A 400, 404 or 500 body says why. param names the request field at fault, when there is one:

{ "error": "No customer with that phone number", "param": "phone" }

Related

Checkout API Loyalty Memberships
PreviousCheckout APINext WooCommerce plugin
Paybrain

Talk to a person

(877) 235-0050

Sales and support, Mon–Fri, 9am–6pm ET

Products

Paybrain RegisterTap to PayInvoicing & RecurringPaybrain MobilePaybrain ProviderAll hardware

Industries

Restaurants & cafésRetailSalons & med-spasGyms & clubsProfessionalsOnline

Company

PricingDocsSupport

Legal

WarrantyReturnsShippingTermsPrivacyAnti-fraud

© 2026 Paybrain. All rights reserved.

Payments powered by Stripe