Cloud Terminal API

The Cloud Terminal API lets your POS send payment requests directly to a Billpocket terminal over the internet. No physical connection is needed — your system communicates with the terminal via REST, and the terminal handles card reading, EMV processing, and receipt printing.

Beta

Cloud Terminal API is currently in beta. Contact your account manager for access.

INFO

Available in Mexico only.

Base URLs

Environment	Base URL
Dev	`https://kushkicollect.billpocket.dev`
Live	`https://kushkicollect.billpocket.com`

Authentication

All requests require a valid user token in the X-BP-AUTH header.

Use the token that corresponds to the environment (Dev or Live). Get your user token →

Available endpoints

Operation	Endpoint	Description
Collect payments	`billpocket/card-present/cloud-terminal-api/collect-payments`	Send a payment push notification to a terminal (v1)
Collect payments v2	`billpocket/card-present/cloud-terminal-api/collect-payments-v2`	Send a payment push notification to a terminal (v2 — camelCase fields)
Print ticket	`billpocket/card-present/cloud-terminal-api/print-ticket`	Send a print request to a terminal
Cancel push	`billpocket/card-present/cloud-terminal-api/cancel-push`	Cancel a pending push notification before the customer taps the terminal
Status	`billpocket/card-present/cloud-terminal-api/status`	Check the status of a push notification or transaction

How it works

1. Your POS → POST /push-notifications   (send payment request with serial number + amount)
2. Terminal receives push notification   (customer taps to open POS app)
3. Customer presents card                (EMV / contactless)
4. Terminal processes transaction        (approves or declines)
5. Kushki → POST your webhook URL        (transaction result)

Collect a payment

Send a payment request to the terminal identified by its serial number.

v1:

{
  "serial_number": "TERM1TEST",
  "amount": 500,
  "identifier": "ORDER-20260611-001"
}

v2 (recommended):

{
  "serialNumber": "TERM1TEST",
  "amount": 500,
  "identifier": "ORDER-20260611-001"
}

To include a tip, add the tip field:

{
  "serialNumber": "TERM1TEST",
  "amount": 500,
  "tip": 50,
  "identifier": "ORDER-20260611-001"
}

A successful request returns HTTP 201 Created. The terminal must be online to receive the push notification.

Requirements

Ultra, Ultra P, or Ultra SE terminal

POS app version 4.3.26 or higher installed on the terminal

Stable internet connection on both POS and terminal

Firewall rules allowing communication with the Billpocket domains above

Next steps

Webhooks

Receive the transaction result once the terminal processes the payment.

Transaction List

Query processed transactions for reconciliation.

Cancel Payments

Cancel an authorized transaction on the same business day.

Got a suggestion on this documentation? Contact us.

Base URLs#

Authentication#

Available endpoints#

How it works#

Collect a payment#

Requirements#

Next steps#

Base URLs

Authentication

Available endpoints

How it works

Collect a payment

Requirements

Next steps