Cloud Terminal API

Product in beta version 🔐

We are working on our beta version. Stay tuned for its official release! You can also contact your account manager for more information.

Create new card payment experiences in your business. Cloud Terminal API allows you to integrate a terminal to your point of sale (POS) system easily and securely through a REST API, giving you direct control from your system when making a card payment. No physical connection is needed: your POS communicates with the terminal over the internet, and the terminal handles card reading, EMV processing and receipt printing.

This guide covers everything you need to process card payments in the terminal.

INFO

Service available in Mexico 🇲🇽 only.

Main features

Easy to integrate: integrate a terminal across any platform and any device that allows HTTP requests.

Scalable: the API architecture allows you to scale, adding terminals according to your needs, without major difficulty.

Control: manage your entire operation from your POS. Delegate payment operations through your POS to our terminals.

Security: communication with our terminals is encrypted at all times to protect sensitive information, according to the strictest industry standards.

Requirements

Before you can perform an integration, you must meet the following requirements:

An Ultra, Ultra P or Ultra SE reader

A valid account

POS app installed on the terminal, version 4.3.26 or higher

A stable internet connection

Firewalls and similar services configured to allow communication with the domains described below

Environments

You can simulate tests in the Dev environment to make the necessary adjustments to your system. Remember that no real transactions are processed in this environment. Choose the right environment to send notifications to the terminal from your POS.

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:

Check out our guide to get your user token.

Note

Remember to use the correct user token according to the environment.

Important

Store your user token in a safe place. Never share it or expose it to third parties.

Available endpoints

Method	Path	Operation
`POST`	`/push-notifications`	Collect card payments
`POST`	`/v2/push-notifications`	Collect card payments v2
`POST`	`/print-ticket`	Print ticket
`POST`	`/cancel-transaction`	Cancel push notification
`GET`	`/get-status/?uniqueReference`	Get transaction status

How it works

Your POS sends the payment request to the Cloud Terminal API with the terminal's serial number and the amount.

The API processes the request and relays it to the terminal as a push notification.

The customer presents their card; the terminal reads and encrypts the card information and sends it to be processed.

Kushki processes the transaction and approves or declines it.

Kushki notifies the response to your POS through a webhook, so you can continue the payment flow in your store.

Process a payment

Follow these steps to process payments through Cloud Terminal API.

Collect a payment

To send a payment request to the terminal from your POS, consume the Collect card payments or Collect card payments v2 endpoint, sending:

The serial number of the selected terminal.

An amount greater than $1 MXN.

An identifier of up to 256 characters, generated on your side, that gives you traceability of the transaction. This value is returned to you through the webhook.

v1:

{
   "serial_number": "TERM1TEST",
   "amount": 27,
   "identifier": "identificador 1"
}

v2:

{
   "serialNumber": "TERM1TEST",
   "amount": 27,
   "identifier": "identificador 1"
}

Collect a payment with tip

You can also collect tip payments by submitting the tip property at the time of the request:

v1:

{
   "serial_number": "TERM1TEST",
   "amount": 27,
   "tip": 1.5,
   "identifier": "identificador 1"
}

v2:

{
   "serialNumber": "TERM1TEST",
   "amount": 27,
   "tip": 1.5,
   "identifier": "identificador 1"
}

Visit the Collect card payments and Collect card payments v2 endpoints to see more details about the properties available at the time of a request, and to try the call from your browser.

Response

If the information sent is correct, you get an HTTP status code 201 Created, indicating that the notification was successfully sent to the terminal.

Note

Remember that the terminal must be connected to the internet to receive notifications.

On the terminal

You receive a notification with the information sent. Slide down the notification bar and tap the notification to open the POS application.

The payment screen appears in the POS application. If the information displayed is correct, tap the COBRAR button to proceed with the payment.

Follow the on-screen steps to read and process the card information. After the transaction is processed, a webhook is sent with its status.

Next steps

Find out how to set up a webhook so you can receive the status of the transaction once it has been processed.

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.

Main features#

Requirements#

Environments#

Authentication#

Available endpoints#

How it works#

Process a payment#

Collect a payment#

Collect a payment with tip#

Response#

On the terminal#

Next steps#

Main features

Requirements

Environments

Authentication

Available endpoints

How it works

Process a payment

Collect a payment

Collect a payment with tip

Response

On the terminal

Next steps