Take payments

Accept payments with a POS terminal from your point of sale through Cloud Terminal API. Cloud Terminal API allows you to send requests to an Ultra or Ultra P terminal from any compatible application to process a payment.

With Cloud Terminal API you can control your operation from your system and use a terminal as a peripheral (pinpad) to read the card information to process a payment.

All requests must be made from your back end.

Request data model

These are all the parameters you can configure when making a request.

V1:

Property	Type	Required	Description
serial_number	String	Yes	Terminal serial number.
amount	Number	Yes	Transaction amount.
identifier	String	Yes	Unique identifier per transaction generated on your side.
tip	Number	-	Tip amount.
description	String	-	Send a text that will appear in the terminal notification.

V2:

Property	Type	Required	Description
serialNumber	String	Yes	Terminal serial number.
amount	Number	Yes	Transaction amount.
identifier	String	Yes	Unique identifier per transaction generated on your side.
tip	Number	-	Tip amount.
description	String	-	Send a text that will appear in the terminal notification.
uniqueReference	String	-	Unique identifier per transaction generated on your side to avoid duplicates. Application version 5.0.3 or higher is required to use this property.
showNotification	String	-	If set to `true`, a push notification will be received on the terminal for each request, otherwise the payment app will be automatically opened to process the payment.
ttl	Number	-	Number of seconds for the payment request to expire.
msi	Number	No	Only valid for transactions over 300 MXN. The Months Without Interest option must be enabled from the Billpocket app.
deviceToken	Number	-	Device ID. It can be viewed from the Billpocket dashboard, section My devices. .
`extras`	Object	No	Additional configurations in the payment request
`extras.autoPaymentEnabled`	Boolean	No	When this parameter is sent as `true`, the payment process will be triggered automatically without waiting for confirmation via the Pay button.
`extras.timerFinishTRX`	Numeric (integer)	No	Number of seconds before the checkout summary screen closes after the purchase is completed.
`extras.enableDialogTip`	Boolean	No	If sent as `true`, a dialog will appear to enter the tip amount during the payment process.

Operations

Discover all the operations available through Cloud Terminal API integrations.

Sale

The sales process begins when a customer wants to purchase a product or service at your establishment through a physical or digital payment method. During the process, your point of sale system sends a payment request with the necessary configuration to the payment application, which communicates with the terminal in a secure way to read, encrypt and send your customer's credit or debit card information to Kushki to be processed. You will receive the response to the request in the payment application. If the transaction has been successfully authorized, the authorized amount will be deducted from your customer's account immediately and will subsequently be settled to your bank account according to the settlement process. In case of an error, you will get more information in the payment app and the request can be retried again with a valid payment method

Send a request with the payment configuration from your point of sale system to the endpoint Collect card payments to perform a sales operation.

curl --request POST \
  --url https://kushkicollect.billpocket.dev/push-notifications \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-BP-AUTH: bpAuth' \
  --data '{
  "amount": 37,
  "identifier": "c68522bd-bfc1-4b08-bf99-30300806c25a",
  "serial_number": "TERM123"
}'

Tipping

Add an additional tip amount during a sale transaction in the payment app during checkout. Choose from a predefined amount or enter a custom amount. If you do not require adding a tip, click outside the dialog to continue.

You need to activate the option within the payment app settings to receive tips.

Deferred payments

Increase your customers' average purchase amount at your establishment by offering the option to defer payment over a fixed number of installments. The transaction must meet certain requirements in order to be deferred. Review the requirements with your account manager.

To defer a payment, enable the option within the payment app settings and select the desired option during the checkout process.

Please review the Cloud Terminal API Reference for more detailed information.

Response

If the information sent is valid, you will get an HTTP status code 201 indicating that the request was successfully sent to the terminal.

Payment app flow

You will receive a push notification on the terminal which you must select to start the payment process.

By selecting the notification, the payment application will be displayed with the information sent. Click on the COBRAR button to start reading the card.

Follow the steps on the screen to complete the process.

Check the result of the operation using the result property received via a webhook. If it has the value aprobada, the transaction was processed successfully, otherwise there was an error processing the transaction.

Webhooks

Receive notifications in your system with the events of the operations carried out. Discover all the available events.

Test data

Make any necessary adjustments to your system using the test data.

Request data model#

Operations#

Sale#

Tipping#

Deferred payments#

Response#

Payment app flow#

Request data model

Operations

Sale

Tipping

Deferred payments

Response

Payment app flow