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 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.

PropertyTypeRequiredDescription
deviceStringYesTerminal serial number.
amountIntegerYesTransaction amount.
dteTypeInteger-Type of Documento Tributario Electrónico (DTE):
  • 0: unknown type.
  • 33: Factura afecta.
  • 48: Boleta afecta.
  • 99: Exempt document.
extraDataObject-Object with additional information.
extraData.taxIdnValidationString-Merchant’s Rol Único Tributario (RUT).
extraData.netAmountInteger-Transaction amount (IVA included) that will be used to report to the Servicio de Impuestos Internos (SII).
extraData.exemptAmountInteger-Exempt amount of the sale that will be used to report to the Servicio de Impuestos Internos (SII).
extraData.sourceNameString-Package name of your app.
extraData.sourceVersionString-Version number of your application.
extraData.customFieldsArray[Object]-Object array to add additional information that is stored for reporting and that can be printed on the ticket.
extraData.customFields.nameString-Custom field name. Maximum 28 characters.
extraData.customFields.valueString-Custom field value. Maximum 28 characters.
extraData.customFields.printBoolean-Set whether or not to print the custom property on the ticket.

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://integrations.payment.haulmer.com/PaymentRequest/Create \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: apiKey' \
--data '{
"amount": 1900,
"device": "TJ71246J27718",
"dteType": 0,
"extraData": {
"netAmount": 1900,
"sourceName": "com.example.app123",
"customFields": [
{
"name": "Mesa",
"print": true,
"value": "idMesa"
},
{
"name": "Mesero",
"print": true,
"value": "idMesero"
}
],
"exemptAmount": 0,
"sourceVersion": "1.10.4"
}
}'

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.

Cloud terminal API propina - CL

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.

Cloud terminal API diferidos - CL

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.

{
"amount": 1900,
"status": "Pending",
"dteType": 0,
"deviceId": "TJ71246J27718",
"extraData": {
"sourceName": "com.example.app123",
"customFields": [
{
"name": "Mesa",
"print": true,
"value": "idMesa"
},
{
"name": "Mesero",
"print": true,
"value": "idMesero"
}
],
"sourceVersion": "1.10.4",
"taxIdnValidation": "1234567-2"
},
"paymentRequestId": 9876
}

Payment app flow

In order to receive a request and initiate the payment process, the terminal must be set to Modo integración within the payment application settings.

Cloud terminal API integration mode - CL

When a request is received at the terminal, the payment screen will be displayed with the established amount. Click on the Aceptar button to continue with the payment process or click on the Rechazar button to cancel the request.

Cloud terminal API pantalla de pago - CL

If the Tip option is enabled within the payment app settings, the tipping screen will be displayed. Choose an option on the screen to continue.

Cloud terminal API propina - CL

Choose the type of card on the screen.

Cloud terminal API método de pago - CL

In case the Cashback option is enabled within the payment app settings, the cashback screen will be displayed. Choose an option on the screen to continue.

Cloud terminal API cashback - CL

The Opera tu tarjeta screen will then appear, indicating when the payment method must be entered.

Cloud terminal API card - CL

The PIN entry screen will appear according to the following security rules:

  • Debit cards: PIN entry will be requested for all debit card transactions.
  • Credit cards:
    • Contactless: PIN entry will be requested for amounts greater than $20,000.
    • Chip: PIN entry will be requested regardless of the transaction amount.

Cloud terminal API - PIN - CL

After authentication by the cardholder, an animation will appear indicating that the information submitted is being processed.

An animation will appear indicating that the information sent is being processed.

Cloud terminal API procesando pago - CL

Finally, you will get the result of the request on the response screen.

Cloud terminal API respuesta - CL

When the transaction is completed in the terminal, you will receive a webhook with useful information about the result of the operation.


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.