# 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.

Source: https://tamr.link/docs/api/start-payment

`POST https://tamr.link/api/v1/pay`

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](https://tamr.link/docs/api/start-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:

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

Node:

```js
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);
```

Python:

```python
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

```json
{
  "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](https://tamr.link/docs/errors).

| `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. |
