Chile
Colombia
Ecuador
Peru
Take payments
November 07, 2024Accept 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.
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. |
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.
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.