# Your First Terminal Integration

> Push a payment request to a Paystack Terminal device and handle the resulting charge — end to end.

This tutorial walks through the most common Paystack Terminal flow: your POS completes an order, your server pushes a payment request to a specific terminal, and the customer pays on the device.

You will:

- find the terminal to target
- confirm that it is online
- push the payment request to the device
- poll the event until delivery completes
- handle the final `charge.success` webhook

## Step 1: Gather the prerequisites

Before you start, make sure you have:

1. A physical Paystack Terminal device, or a test simulation that can receive terminal events.
2. Your Paystack secret key.
3. A payment request already created for the order, with:

  - `id`: the payment request ID you want the terminal to process
  - `offline_reference`: the reference you use to reconcile the charge in your system

If your POS creates the payment request at checkout time, store those values before you push anything to the terminal.

## Step 2: List your terminals

Use `GET /terminal` to see every terminal connected to your integration and identify the one you want to target.

<code-tabs>
<template v-slot:curl="">

```bash
curl https://api.paystack.co/terminal \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
```

</template>

<template v-slot:nodejs="">

```js
const response = await fetch('https://api.paystack.co/terminal', {
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY'
  }
})

const terminals = await response.json()
console.log(terminals)
```

</template>
</code-tabs>

Look for the terminal your cashier is using and note its `terminal_id`.

## Step 3: Check the terminal status

Before you push a payment request, confirm that the terminal is available to receive it.

<code-tabs>
<template v-slot:curl="">

```bash
curl https://api.paystack.co/terminal/TERM_123456 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
```

</template>

<template v-slot:nodejs="">

```js
const terminalId = 'TERM_123456'

const response = await fetch(`https://api.paystack.co/terminal/${terminalId}`, {
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY'
  }
})

const terminal = await response.json()
console.log(terminal)
```

</template>
</code-tabs>

Treat the terminal as ready only when it is online and available.

<callout type="warning">

The terminal must be online and awake before you push an event. If it is offline, sleeping, or busy with another payment, the customer will not see the prompt.

</callout>

## Step 4: Push the payment request to the terminal

When the customer is ready to pay, send a terminal event to the target device with:

- `type: "invoice"`
- `action: "process"`
- `data.id`: your payment request ID
- `data.reference`: the payment reference for this order

This tells Paystack to display the payment prompt on that terminal so the customer can tap, insert, or swipe their card.

<code-tabs>
<template v-slot:curl="">

```bash
curl https://api.paystack.co/terminal/TERM_123456/event \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "action": "process",
    "data": {
      "id": "INV_3s9xLxZKx5n1",
      "reference": "order_10452_pos"
    }
  }'
```

</template>

<template v-slot:nodejs="">

```js
const terminalId = 'TERM_123456'
const invoiceId = 'INV_3s9xLxZKx5n1'
const paymentReference = 'order_10452_pos'

const response = await fetch(`https://api.paystack.co/terminal/${terminalId}/event`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'invoice',
    action: 'process',
    data: {
      id: invoiceId,
      reference: paymentReference
    }
  })
})

const event = await response.json()
console.log(event)
```

</template>
</code-tabs>

A successful API response means Paystack accepted the event and forwarded it for delivery. It does not yet mean the terminal completed payment. Save the returned `event_id` and track it.

## Step 5: Poll for event status

Use `GET /terminal/{terminal_id}/event/{event_id}` to confirm what happened to the pushed event.

<code-tabs>
<template v-slot:curl="">

```bash
curl https://api.paystack.co/terminal/TERM_123456/event/EVT_8h2kQ9m1 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
```

</template>

<template v-slot:nodejs="">

```js
const terminalId = 'TERM_123456'
const eventId = 'EVT_8h2kQ9m1'

const response = await fetch(`https://api.paystack.co/terminal/${terminalId}/event/${eventId}`, {
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY'
  }
})

const status = await response.json()
console.log(status)
```

</template>
</code-tabs>

Expect the event to move through states such as:

1. `pending` — Paystack has accepted the event.
2. `processing` — the terminal is receiving or acting on it.
3. `success` or `failed` — delivery and processing completed.

Use this endpoint for operational visibility, but treat the payment webhook as the final payment signal.

## Step 6: Handle the webhook

When the customer completes payment on the terminal, Paystack sends a `charge.success` webhook. Verify the signature first, then confirm the charge came from the terminal by checking `data.channel === 'pos'`.

```js
import crypto from 'crypto'
import express from 'express'

const app = express()
app.use(express.json())

app.post('/api/paystack/webhook', (req, res) => {
  const signature = req.headers['x-paystack-signature']
  const hash = crypto
    .createHmac('sha512', 'YOUR_SECRET_KEY')
    .update(JSON.stringify(req.body))
    .digest('hex')

  if (hash !== signature) {
    return res.sendStatus(401)
  }

  if (req.body.event === 'charge.success' && req.body.data.channel === 'pos') {
    const reference = req.body.data.reference
    const status = req.body.data.status

    if (status === 'success') {
      console.log('Terminal payment confirmed:', reference)
      // mark the POS order as paid
    }
  }

  return res.sendStatus(200)
})
```

Process the webhook as your source of truth for fulfilment, receipts, and reconciliation. The pushed terminal event starts the payment. The `charge.success` webhook confirms that money actually moved.

## What you built

You built a complete first Terminal flow that:

1. finds the right device with `GET /terminal`
2. confirms it is online with `GET /terminal/{terminal_id}`
3. pushes a payment request with `POST /terminal/{terminal_id}/event`
4. monitors delivery with `GET /terminal/{terminal_id}/event/{event_id}`
5. confirms payment with a `charge.success` webhook where `data.channel === 'pos'`

Use this pattern whenever a cashier or operator needs to send a payment from your backend straight to a Paystack Terminal at checkout.
