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 API

Starts 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

NameTypeRequiredDescription
x-tamr-devicestringNoGuest sessions only: the device id the session was exchanged with. Matches ^[A-Za-z0-9_-]{8,128}$.
x-tamr-appstringNoNative 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

FieldTypeRequiredDescription
branchstringNoAn address: lower-case letters, digits and dashes.
providerstringYes1 to 40 characters.
paystringYesOne of tab, amount, order, unknown. An open list: read a value you don't know as unknown.
amountstringYesAn amount in minor units, as a string.
orderIdstringNo1 to 200 characters.
tipstringNoAn amount in minor units, as a string.
tablePaidConfirmedbooleanNo
localestringNoA language tag, such as ar or en-GB.

Response

FieldTypeDescription
paymentobject
payment.paymentIdstring1 to 200 characters.
payment.referencestring1 to 40 characters.
payment.statusstringOne of open, paid, failed, expired, refunded, unknown. An open list: read a value you don't know as unknown.
payment.amountstringAn amount in minor units, as a string.
payment.tipstringAn amount in minor units, as a string.
payment.totalstringAn amount in minor units, as a string.
payment.currencystringA three-letter currency code (ISO 4217).
payment.expiresAtstring (date-time) or null
payment.providerstringMay be absent. 1 to 40 characters.
payment.paystringMay be absent. One of tab, amount, order, unknown. An open list: read a value you don't know as unknown.
urlstringAt most 2,048 characters.
resumedboolean

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"
}'

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.codeStatusWhat to do
app_key_invalid401The key is wrong, revoked or of another kind. Check it in the dashboard.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.
origin_not_allowed403A browser called from an origin the key doesn't list. Add the origin to the key.
session_expired401Start a new session with a fresh token or code, then send the call again once.
invalid_request400A field doesn't match the spec. The message says which.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.
pay_refused409A payment couldn't start. payRefusal says why.