Paystack Terminal

The Terminal API lets you build in-person payment experiences with Paystack POS terminals.

Depends on: paystack-setup for the paystackRequest helper.

Endpoints

Method	Endpoint	Description
POST	/terminal/:terminal_id/event	Send event to terminal
GET	/terminal/:terminal_id/event/:event_id	Check event delivery status
GET	/terminal/:terminal_id/presence	Check terminal availability
GET	/terminal	List terminals
GET	/terminal/:terminal_id	Fetch terminal details
PUT	/terminal/:terminal_id	Update terminal
POST	/terminal/commission_device	Commission (activate) terminal
POST	/terminal/decommission_device	Decommission (deactivate) terminal

Send Event to Terminal

Param	Type	Required	Description
type	string	Yes	invoice or transaction
action	string	Yes	For invoice: process or view. For transaction: process or print
data	object	Yes	Event data (see examples)

// Send invoice to terminal for processing
const event = await paystackRequest<{ id: string }>(
  `/terminal/${terminalId}/event`,
  {
    method: "POST",
    body: JSON.stringify({
      type: "invoice",
      action: "process",
      data: {
        id: 7895939,           // Invoice ID
        reference: 4634337895939, // Offline reference
      },
    }),
  }
);
// event.data.id → "616d721e8c5cd40a0cdd54a6"

// Print a transaction receipt
await paystackRequest(`/terminal/${terminalId}/event`, {
  method: "POST",
  body: JSON.stringify({
    type: "transaction",
    action: "print",
    data: { id: transactionId },
  }),
});

Check Event Status

const status = await paystackRequest<{ delivered: boolean }>(
  `/terminal/${terminalId}/event/${eventId}`
);
// status.data.delivered → true

Check Terminal Availability

Always check before sending events:

const presence = await paystackRequest<{
  online: boolean;
  available: boolean;
}>(`/terminal/${terminalId}/presence`);

if (presence.data.online && presence.data.available) {
  // Send event to terminal
}

List Terminals

Uses cursor pagination:

const terminals = await paystackRequest("/terminal?perPage=50");
// terminals.meta.next → cursor for next page
// terminals.meta.previous → cursor for previous page

Fetch Terminal

const terminal = await paystackRequest(`/terminal/${terminalId}`);
// terminal.data: { id, serial_number, terminal_id, name, address, status }

Update Terminal

await paystackRequest(`/terminal/${terminalId}`, {
  method: "PUT",
  body: JSON.stringify({
    name: "Front Desk Terminal",
    address: "123 Main Street, Lagos",
  }),
});

Commission / Decommission

// Activate a new terminal
await paystackRequest("/terminal/commission_device", {
  method: "POST",
  body: JSON.stringify({ serial_number: "1111150412230003899" }),
});

// Deactivate a terminal
await paystackRequest("/terminal/decommission_device", {
  method: "POST",
  body: JSON.stringify({ serial_number: "1111150412230003899" }),
});