Start a payment
Start paying the table's tab, a typed amount or a pickup with Tamr Pay, and get the provider's payment page.
POST
/api/v1/payClient APIStarts a payment and answers the provider's page to open. Open it in the platform's in-app browser (a new tab on the web), never inside a webview, and only for an https link. A test key can't pay: it answers pay_refused.
Authentication
Client API. Send your publishable key in x-tamr-key and the diner's session in x-tamr-session, from Start a session. For a guest's session, also send its device id in x-tamr-device. A browser may call it only from an origin listed on the key.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-tamr-device | string | No | Guest sessions only: the device id the session was exchanged with. Matches ^[A-Za-z0-9_-]{8,128}$. |
x-tamr-app | string | No | Native apps only: the app's iOS bundle id or Android package name. A key used from an app it doesn't list is logged, never refused. Matches ^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
branch | string | No | An address: lower-case letters, digits and dashes. |
provider | string | Yes | 1 to 40 characters. |
pay | string | Yes | One of tab, amount, order, unknown. An open list: read a value you don't know as unknown. |
amount | string | Yes | An amount in minor units, as a string. |
orderId | string | No | 1 to 200 characters. |
tip | string | No | An amount in minor units, as a string. |
tablePaidConfirmed | boolean | No | |
locale | string | No | A language tag, such as ar or en-GB. |
Response
| Field | Type | Description |
|---|---|---|
payment | object | |
payment.paymentId | string | 1 to 200 characters. |
payment.reference | string | 1 to 40 characters. |
payment.status | string | One of open, paid, failed, expired, refunded, unknown. An open list: read a value you don't know as unknown. |
payment.amount | string | An amount in minor units, as a string. |
payment.tip | string | An amount in minor units, as a string. |
payment.total | string | An amount in minor units, as a string. |
payment.currency | string | A three-letter currency code (ISO 4217). |
payment.expiresAt | string (date-time) or null | |
payment.provider | string | May be absent. 1 to 40 characters. |
payment.pay | string | May be absent. One of tab, amount, order, unknown. An open list: read a value you don't know as unknown. |
url | string | At most 2,048 characters. |
resumed | boolean |
Example
curl https://tamr.link/api/v1/pay \
-H "x-tamr-key: $TAMR_APP_KEY" \
-H "x-tamr-session: $TAMR_SESSION" \
-H "content-type: application/json" \
-d '{
"branch": "achrafieh",
"provider": "whish",
"pay": "tab",
"amount": "2400",
"tip": "240",
"locale": "ar"
}'import { createClient } from "@tamr/api";
const tamr = createClient({ appKey: process.env.TAMR_APP_KEY });
// Sign the diner in first, with a token your backend signed (or a launch code).
await tamr.startSession({ token: dinerToken });
const result = await tamr.payStart({
branch: "achrafieh",
provider: "whish",
pay: "tab",
amount: "2400",
tip: "240",
locale: "ar",
});
console.log(result);import os
import requests
API = "https://tamr.link/api/v1"
headers = {
"x-tamr-key": os.environ["TAMR_APP_KEY"],
"x-tamr-session": os.environ["TAMR_SESSION"], # from POST /api/v1/sdk/session
}
response = requests.post(
f"{API}/pay",
headers=headers,
json={
"branch": "achrafieh",
"provider": "whish",
"pay": "tab",
"amount": "2400",
"tip": "240",
"locale": "ar",
},
timeout=30,
)
response.raise_for_status()
print(response.json())Example response
{
"payment": {
"paymentId": "pay_0002",
"reference": "TP-7K2M9QXA",
"status": "open",
"amount": "2400",
"tip": "240",
"total": "2640",
"currency": "USD",
"expiresAt": "2026-11-05T20:05:00.000Z"
},
"url": "https://pay.whish.money/checkout/7f3a9c21",
"resumed": false
}Errors
Every error has the same body; switch on data.code. See Errors and rate limits.
data.code | Status | What to do |
|---|---|---|
app_key_invalid | 401 | The key is wrong, revoked or of another kind. Check it in the dashboard. |
sdk_disabled | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
origin_not_allowed | 403 | A browser called from an origin the key doesn't list. Add the origin to the key. |
session_expired | 401 | Start a new session with a fresh token or code, then send the call again once. |
invalid_request | 400 | A field doesn't match the spec. The message says which. |
rate_limited | 429 | Wait retryAfter seconds (also in the Retry-After header), then try again. |
pay_refused | 409 | A payment couldn't start. payRefusal says why. |