Take payments

November 07, 2024

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.

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.

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.

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

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.

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.

Choose the type of card on the screen.

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.

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

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.

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.

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

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