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.
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.
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" }
]
}
}
| Field | Meaning |
|---|---|
id | The customer's id. Use it to list their sales. |
name, email | Left out when you don't have them on file. |
visitCount, lastVisitAt | How often they've bought from you, and when they last did. |
loyalty.enabled | Whether loyalty is turned on for your business. |
loyalty.points | Their points balance now. |
loyalty.pointsValueCents | What those points are worth as a discount at the register. |
loyalty.pointsForOneDollarOff, loyalty.redemptionThreshold | Your 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. |
memberships | Their 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_…"
| Parameter | Default | Meaning |
|---|---|---|
limit | 20 | How many sales to return, from 1 to 50 |
offset | 0 | How 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
}
| Field | Meaning |
|---|---|
status | paid, partially_refunded or refunded |
totalCents | What the customer paid, tax and tip included |
refundedCents, refundedAt | How much has been given back so far, and when the last refund was |
items | Each line sold, with how many of it were returned |
pointsEarned, pointsRedeemed | Loyalty points the sale earned and spent |
receiptUrl | The 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 |
payments | Only 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, hasMore | How many sales the customer has in all, and whether there's another page |
Errors
| Status | When |
|---|---|
400 | A request field is invalid, such as a phone that isn't a phone number or a limit over 50 |
404 | No customer with that phone number, or no customer with that id on your account |
410 | The key is missing, malformed, inactive or deleted, or the account is on Basic. The body is a message saying which. |
500 | Something 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" }