Sign in

Payments

Your First Terminal Integration

View as Markdown

In a nutshell

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

Copy linkStep 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.

Copy linkStep 2: List your terminals

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

GETapi.paystack.co/terminal

curl https://api.paystack.co/terminal \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
const response = await fetch('https://api.paystack.co/terminal', {
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY'
  }
})

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

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

Copy linkStep 3: Check the terminal status

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

GETapi.paystack.co/terminal/TERM_123456

curl https://api.paystack.co/terminal/TERM_123456 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
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)

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

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.

Copy linkStep 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.

POSTapi.paystack.co/terminal/TERM_123456/event

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

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.

Copy linkStep 5: Poll for event status

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

GETapi.paystack.co/terminal/TERM_123456/event/EVT_8h2kQ9m1

curl https://api.paystack.co/terminal/TERM_123456/event/EVT_8h2kQ9m1 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
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)

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.

Copy linkStep 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'.

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.

Copy linkWhat 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.

Was this page helpful?