Cloud Terminal API
Overview
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.
The integration of your point of sale through REST API to Ultra terminals (Ultra, Ultra P and Ultra P2), allows you to send notifications to make a payment in the terminal regardless of the platform (Windows, Mac, Android, iOS,
etc.), as long as the terminal has an internet connection. This allows you to have greater control of your transactions from your point of sale software (POS) and offer new payment experiences to your customers.
Please also note:
All requests must be sent in JSON format.
All response payloads are in JSON format, except when noted.
It is necessary to use the correct API KEY according to the environment..
Requirements:
Ultra Terminal: it is necessary to have an Ultra terminal to carry out the integration and certification process. The terminal must have access to the Internet and not have communication blocked by a firewall or any other similar software with domains https://kushkicollect.billpocket.dev and https://kushkicollect.billpocket.com.
App: Billpocket application must be installed and have version 4.3.26 or higher.
Developer account for integration and certification or productive account for real transactions.
Login to the Billpocket app.
Integration process
Integrate payments through the API with the Ultra terminal by integrating the services listed below.
Note: To consume the API, it is necessary to have the token available from your dashboard.
Environments
During the integration and certification process, you will need to use your development credentials. When you're ready to make actual payments, change your developer credentials to live credentials.
Note: Developer and live credentials are different. Make sure you use the correct credentials at all times.
Base URL:
Sale
For a correct payment flow, the sales endpoint described below must be consumed with the required information, then the terminal receives a push notification and the payment process can begin in the terminal. If the transaction was successful, a webhook will be returned with information about it. The flow can be closed successfully if the result property returned in the webhook has the value of aprobada. A timeout should be set in case the webhook is not received (3 minutes, for example) to continue with the internal flow and avoid a bad user experience. The flow could continue, for example, by retrying the payment process.
HTTP Method | Base url | PATH |
|---|---|---|
POST | {{base_url}} | /push-notifications |
Headers
Authentication with the API is done using the token available in your dashboard. A header must be sent in the request with the name X-BP-AUTH and the token value.
Name | Type | Length | Required | Description |
|---|---|---|---|---|
String | 64 characters | Yes | Token obtained from the dashboard. |
Example of a request with X-BP-AUTH header
curl -XPOST -H 'X-BP-AUTH: 44d8bc2557ac01d4834e9cae3fd7385dfedf51194881b35f7a8acb13620da413' -H "Content-type: application/json" -d '{
"serial_number": "TERM1TEST",
"amount": 500.75,
"tip":25,
“identifier”: “identificador 1”,
"description":"Test case BP-610 - BP-611 - TC15 info con propina y descripcion"
}' '{{base_url}}/push-notifications'
Request body
The fields available in the body of the request, the data type of each field, the maximum length, if required in the request, and a description are detailed below.
Property | Type | Length | Required | Description |
|---|---|---|---|---|
| String | 64 characters | Yes | Terminal serial number. |
| Number | 999,999.99 | Yes | The sale amount must be greater than or equal to 1. |
| String | 256 characters | Yes | identifier per transaction generated on the client side. |
Idempotent_id | String | Max. 64 characters | No | Unique identifier per transaction generated on the client side. Authenticated by billpocket to avoid duplicates, only if the value is sent. |
| Number | 999,999.99 | No | If you need to send an additional amount for the tip, it must be sent in the |
| String | 64 characters | No | The text sent in this field will be displayed in the notification in the terminal. |
Sales request example
Example of a sales request with an amount of MXN 27 and a tip of MXN 1.5.
{
"serial_number": "TERM1TEST",
"amount": 27,
"tip":1.5,
"identifier": "identificador 1"
}
The terminal must have an internet connection to receive the push notification. The terminal can be on the home, onboarding, PIN, or any other screen.
If the request has been successful, a notification will be displayed in the terminal like the following.
The payment screen will be displayed with the information sent by clicking on the notification.
Click the COBRAR button and follow the instructions on the terminal screen to process the transaction.
Response body
Depending on whether the request has been successful with the API or there has been an error, it will return an HTTP response status code depending on the type of response. Below is the list of possible responses.
HTTP status code | Response body schema | Example |
|---|---|---|
201 | (empty) |
|
400 |
|
|
401 |
|
|
404 |
|
|
Transaction status
You will receive the status of the transaction through a webhook. You can also check its status with our transaction list service.
Error catalog
The possible errors that the API can return are of type HTTP Status code 400 when the information sent in the request contains errors, of type 401 when there are problems with the authentication token in the X-BP-AUTH header or of type 404 when the terminal is not found. The message field can be included in the response's body, which will contain the list of all errors at the time of the request.
HTTP Status code 400
Message | Description |
|---|---|
serial _number must not contain special characters | The serial number can contain only numbers (0-9) and letters (a-z, A-Z). |
serial_number must be a string | The data type of the |
serial_number should not be empty | The |
amount must be a number conforming to the specified constraints | The |
amount should not be empty | The |
amount must not be less than 1 | The |
amount must be a positive number | A positive number must be sent in the |
tip must not be less than 1 | The |
tip must be a positive number | The |
tip must be a number conforming to the specified constraints | The |
Description must contains any character and one blank space between words | The |
HTTP Status code 401
Message | Description |
|---|---|
Invalid header | The |
Invalid token | The token sent in the |
HTTP Status code 404
Message | Description |
|---|---|
Serial number not registered | The terminal is not found. It may be because the terminal does not have communication with the internet. |
© Billpocket, 2018