Take payments

December 05, 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.

Idempotency

Idempotency ensures that duplicate transactions are not created by sending multiple requests at the same time. The idempotency process is handled automatically by the system and does not require any action on the part of the client.

Generating Idempotency

To create a new payment request the customer must send the idempotency key (required). The idempotencyKey must be unique for each request and can be used to track the status of the transaction.

The following is the data required for a collection request with idempotency:

How are duplicate requests prevented?

• If the same payment request is sent several times (e.g. due to a network problem or a timeout), the system checks if there is an idempotencyKey associated to a previous request within the last 10 minutes.
• If the idempotencyKey already exists and the prior request is in the completed or sent status, the system will not process the transaction again.
• If the prior request is in the processing status, the system will indicate that the transaction is still in process, avoiding multiple payment attempts.
• Idempotency Timeout: The system retains idempotency for 10 minutes from the time the request is created. If a duplicate request is detected within this period, additional attempts are ignored to prevent duplicates.

Request Limits

To prevent system and terminal overload, there is flow control for payment requests.

Each terminal has the following restrictions:

• Maximum pending requests: A terminal can have up to 5 pending requests in queue.
• Requests per minute limit: Only 1 request can be sent per minute. Exceeding this limit will result in a 429 Too Many Requests error.

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/RemotePayment/v2/Create \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: apiKey' \
  --data '{
  {
  "idempotencyKey": "string",
  "amount": 0,
  "device": "string",
  "description": "string",
  "dteType": 0,
  "extraData": {
    "exemptAmount": 0,
    "customFields": [
      {
        "name": "string",
        "value": "string",
        "print": true
      }
    ],
    "sourceName": "string",
    "sourceVersion": "string"
  }
}
}'

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.

{
  "idempotencyKey": "ef59617f-7633-4aca-965e-e9993f66bdbc",
  "status": "pending",
  "amount": 1600,
  "deviceId": 690,
  "description": "Servicio de afiliación",
  "extraData": {
    "exemptAmount": 1600,
    "customFields": [
      {
        "name": "Contacto",
        "value": "9 51221345",
        "print": true
      }
    ]
  }
}

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.