Back to Details

paystack-terminal

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Paystack Terminal

Paystack Terminal

The Terminal API lets you build in-person payment experiences with Paystack POS terminals.
Depends on: paystack-setup for the 
paystackRequest
helper.
Terminal API 可让你借助Paystack POS终端打造线下支付体验。
依赖：需通过paystack-setup获取
paystackRequest
工具函数。

Endpoints

端点

MethodEndpointDescription
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
方法端点描述
POST
/terminal/:terminal_id/event
向终端发送事件
GET
/terminal/:terminal_id/event/:event_id
查看事件投递状态
GET
/terminal/:terminal_id/presence
查看终端可用性
GET
/terminal
列出所有终端
GET
/terminal/:terminal_id
获取终端详情
PUT
/terminal/:terminal_id
更新终端信息
POST
/terminal/commission_device
激活终端
POST
/terminal/decommission_device
停用终端

Send Event to Terminal

向终端发送事件

ParamTypeRequiredDescription
type
stringYes
invoice
or 
transaction
action
stringYesFor invoice: 
process
or 
view
. For transaction: 
process
or 
print
data
objectYesEvent data (see examples)
typescript
// 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 },
  }),
});
参数类型是否必填描述
type
string是
invoice
（发票）或
transaction
（交易）
action
string是发票类型可选：
process
（处理）或
view
（查看）；交易类型可选：
process
（处理）或
print
（打印）
data
object是事件数据（详见示例）
typescript
// 向终端发送发票以进行处理
const event = await paystackRequest<{ id: string }>(
  `/terminal/${terminalId}/event`,
  {
    method: "POST",
    body: JSON.stringify({
      type: "invoice",
      action: "process",
      data: {
        id: 7895939,           // 发票ID
        reference: 4634337895939, // 离线参考号
      },
    }),
  }
);
// event.data.id → "616d721e8c5cd40a0cdd54a6"

// 打印交易凭证
await paystackRequest(`/terminal/${terminalId}/event`, {
  method: "POST",
  body: JSON.stringify({
    type: "transaction",
    action: "print",
    data: { id: transactionId },
  }),
});

Check Event Status

查看事件状态

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

Check Terminal Availability

查看终端可用性

Always check before sending events:
typescript
const presence = await paystackRequest<{
  online: boolean;
  available: boolean;
}>(`/terminal/${terminalId}/presence`);

if (presence.data.online && presence.data.available) {
  // Send event to terminal
}
发送事件前请务必先检查：
typescript
const presence = await paystackRequest<{
  online: boolean;
  available: boolean;
}>(`/terminal/${terminalId}/presence`);

if (presence.data.online && presence.data.available) {
  // 向终端发送事件
}

List Terminals

列出所有终端

Uses cursor pagination:
typescript
const terminals = await paystackRequest("/terminal?perPage=50");
// terminals.meta.next → cursor for next page
// terminals.meta.previous → cursor for previous page
使用游标分页：
typescript
const terminals = await paystackRequest("/terminal?perPage=50");
// terminals.meta.next → 下一页游标
// terminals.meta.previous → 上一页游标

Fetch Terminal

获取终端详情

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

Update Terminal

更新终端信息

typescript
await paystackRequest(`/terminal/${terminalId}`, {
  method: "PUT",
  body: JSON.stringify({
    name: "Front Desk Terminal",
    address: "123 Main Street, Lagos",
  }),
});
typescript
await paystackRequest(`/terminal/${terminalId}`, {
  method: "PUT",
  body: JSON.stringify({
    name: "前台终端",
    address: "拉各斯市主街123号",
  }),
});

Commission / Decommission

激活/停用终端

typescript
// 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" }),
});
typescript
// 激活新终端
await paystackRequest("/terminal/commission_device", {
  method: "POST",
  body: JSON.stringify({ serial_number: "1111150412230003899" }),
});

// 停用终端
await paystackRequest("/terminal/decommission_device", {
  method: "POST",
  body: JSON.stringify({ serial_number: "1111150412230003899" }),
});