> ## Documentation Index
> Fetch the complete documentation index at: https://doc.seerbit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate transaction

> Start a payment on a connected SeerBit POS terminal.

<Badge color="blue">POST</Badge>

```bash theme={null}
https://seerbitapi.com/isv-pos/api/v1/transactions
```

Starts a transaction on the terminal identified by `posid`, for the amount given in `transactionValue`, and pushes it directly to the terminal for processing.

## Required headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `PublicKey` | Your SeerBit public key |
| `Hash` | HMAC-SHA256(secretKey, requestBody) — see Authentication |

## Request sample

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://seerbitapi.com/isv-pos/api/v1/transactions' \
  --header 'Content-Type: application/json' \
  --header 'PublicKey: YOUR_PUBLIC_KEY' \
  --header 'Hash: YOUR_GENERATED_HASH' \
  --data '{
      "orderId": "112990000323",
      "posid": "2214HX01",
      "transactionValue": "50.00",
      "metadata": "{\"created_by\": \"john\", \"source\": \"odoo_pos_seerbit\", \"pos_config_id\": 5}",
      "webhookUrl": "https://webhook.site/97a4-b3d5-a9b9c7b7863b",
      "transactionRef": "A87EE5e51709977888779DAA4E05"
  }'
  ```

  ```json JSON theme={null}
  {
    "orderId": "112990000323",
    "posid": "2214HX01",
    "transactionValue": "50.00",
    "metadata": "{\"created_by\": \"john\", \"source\": \"odoo_pos_seerbit\", \"pos_config_id\": 5}",
    "webhookUrl": "https://webhook.site/97a4-b3d5-a9b9c7b7863b",
    "transactionRef": "A87EE5e51709977888779DAA4E05"
  }
  ```
</CodeGroup>

## Request fields

| Field | Required? | Description |
| - | - | - |
| `orderId` | Required | Merchant-assigned order identifier. |
| `posid` | Required | Identifier of the target POS terminal the transaction should be routed to. |
| `transactionValue` | Required | Transaction amount, as a decimal string (e.g. `"50.00"`). |
| `metadata` | Optional | Free-form JSON, passed as an escaped string, for any extra context you want to attach. |
| `webhookUrl` | Optional | Include this if you'd like a webhook notification sent once the transaction completes. |
| `transactionRef` | Optional | Client-supplied reference for retry/idempotency, generated by the server if omitted. |

## Response sample

```json 201 Created theme={null}
{
  "transactionRef": "A87EE5e51709977888779DAA4E05",
  "orderId": "112990000323",
  "status": "OPEN",
  "message": "Transaction initiated successfully",
  "createdAt": "2026-07-02T23:23:01Z"
}
```

## Response fields

| Field | Description |
| - | - |
| `transactionRef` | Server-confirmed transaction reference for this attempt. |
| `orderId` | Echoes the `orderId` submitted at initiation. |
| `status` | Initial transaction status — `OPEN` immediately after a successful initiation. |
| `message` | Human-readable confirmation message. |
| `createdAt` | UTC timestamp the transaction record was created. |

<Card title="Next: check the transaction status" icon="arrow-right" href="/in-store/transaction-status">
  Use the `orderId` returned above to poll for the outcome.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.