POS API

The HiPay POS API allows you to process in store payments and create a transaction on HiPay Console.

The payment workflow is the following one:

      1. Your POS Software calls the POS API

      2. HiPay Platform uses the POS Device to display the amount

      3. Once the client has completed the payment, the HiPay platform contacts the acquirer to process the payment

      4. Once the payment has been processed, the payment result is displayed on the POS Device, and sent to your POS Software.

      5. If the payment is successful, a transaction will be created on HiPay Console.

      6. A day later, the HiPay Platform will receive the financial information of the acquirer, and update the transactions.

 

Requirements

Terminal Compatibility

 

Network

 

HiPay Account

You need to have an active HiPay account in order to be able to call this API.

Payment

In order to request a payment you will need to call the POS API. The POS API is divided in four main objects:

ORDER mandatory

Object containing all the basic information of a given transaction. The only two mandatory fields on this object are order_id and amount.

POS_TECHNICAL_INFO mandatory

Object containing the technical parameters about the order and the POS Device. The only two mandatory fields on this object are host and contract_array.

CUSTOMER optional

Object containing the information of the customer. For helping you have more insights and better handle the fraud, it is useful to send any relevant information about the customer.

SHIPPING optional

Object containing the information of the shipping. This information is useful when the customer buys a product that is out of stock on the store, and it is going to be delivered to the customer’s place or to a store.  Having this information will help you have more insights.

ENDPOINT

Production: POST https://cloudrun-api-n3l7nqotca-ew.a.run.app/v1/connector/order

Stage: POST https://cloudrun-api-yugcnet4yq-ew.a.run.app/v1/connector/order

Here you have an example of a payment request.

{
  "order": {
    "order_id": "ORDER_1537532589263",
    "transaction_type": "Debit",
    "initialize_payment_terminal": true,
    "price": {
      "amount": 100,
      "currency": "EUR",
      "tax_fees": 1.1,
      "shipping_fees": 1.3
    },
    "basket": [
      {
        "european_article_numbering": "4711892728946",
        "product_reference": "NF-a1690",
        "type": "good",
        "quantity": 1,
        "name": "My first product",
        "unit_price": 8.99,
        "tax_rate": 0,
        "discount": 0,
        "total_amount": 8.99,
        "product_category": 2,
        "url": "https://image.example.com/image_180x180.jpg"
      }
    ],
    "description": "A super short description here...",
    "long_description": "A super long description here...",
    "custom_data": {
      "internal_reference": "ORD_987465",
      "customer_first_order": true,
      "other_sample_parameter": "Other sample value"
    }
  },
  "customer": {
    "customer_id": "283749291",
    "email": "[email protected]",
    "phone": "33012345678",
    "first_name": "Cathy",
    "last_name": "Doe",
    "birthdate": "1988-06-12",
    "gender": "U",
    "additional_customer_information": "Dr.",
    "customer_location": {
      "country": "FR",
      "state": "string",
      "city": "Paris",
      "zip_code": "75001",
      "street_address": "101 Rue de Rivoli",
      "street_additional_details": "Immeuble B",
      "house_number": "101"
    }
  },
  "shipping": {
    "delivery_date": "2022-12-20",
    "delivery_method": "CARRIER",
    "carrier_description": "La Poste, 27 Rue des Francs Bourgeois",
    "recipient_information": {
      "first_name": "Cathy",
      "last_name": "Doe",
      "additional_info": "Dr.",
      "gender": "U",
      "phone": "33112345678"
    },
    "delivery_address": {
      "country": "FR",
      "state": "string",
      "city": "Paris",
      "zip_code": "75001",
      "street_address": "101 Rue de Rivoli",
      "street_additional_details": "Immeuble B",
      "house_number": "101"
    }
  },
  "pos_technical_info": {
    "notify_url": "https://hipay.com/notify",
    "device_information": {
      "serial_number": "17196WL25395813",
      "manufacturer": "INGENICO"
    },
    "host_information": {
      "host": "192.168.1.10",
      "port": 8888
    },
    "terminal_transaction_display": {
      "contract_array": [
        {
          "merchant_contract": "1234567",
          "rank": "001",
          "payment_application": "001"
        }
      ],
      "push_to": "POS",
      "protocol": "ConcertV3.2",
      "force_authorization": true
    }
  }
}

Response

Once the payment has been processed, you will receive the POS API response. 

Here you have an example of a response for a successful payment:

{
  "error": {
    "paymentStatus": "success",
    "errorCode": "1003",
    "errorDescription": "The network is unavailable",
    "receipt": "UkVDRUlQVCA5OSBFVVI==",
    "order": {
      "order_id": "ORDER_1537532589263",
      "transaction_type": "Debit",
      "initialize_payment_terminal": true,
      "price": {
        "amount": 100,
        "currency": "EUR",
        "tax_fees": 1.1,
        "shipping_fees": 1.3
      },
      "basket": [
        {
          "european_article_numbering": "4711892728946",
          "product_reference": "NF-a1690",
          "type": "good",
          "quantity": 1,
          "name": "My first product",
          "unit_price": 8.99,
          "tax_rate": 0,
          "discount": 0,
          "total_amount": 8.99,
          "product_category": 2,
          "url": "https://image.example.com/image_180x180.jpg"
        }
      ],
      "description": "A super short description here...",
      "long_description": "A super long description here...",
      "soft_descriptor": "Dell Inspiron 15 3583 (i3583-3112BLK-PFR)",
      "custom_data": {
        "internal_reference": "ORD_987465",
        "customer_first_order": true,
        "other_sample_parameter": "Other sample value"
      }
    },
    "customer": {
      "customer_id": "283749291",
      "email": "[email protected]",
      "phone": "33012345678",
      "first_name": "Cathy",
      "last_name": "Doe",
      "birthdate": "1988-06-12",
      "gender": "U",
      "additional_customer_information": "Dr.",
      "customer_location": {
        "country": "FR",
        "state": "string",
        "city": "Paris",
        "zip_code": "75001",
        "street_address": "101 Rue de Rivoli",
        "street_additional_details": "Immeuble B",
        "house_number": "101"
      }
    },
    "shipping": {
      "delivery_date": "2022-12-20",
      "delivery_method": "CARRIER",
      "carrier_description": "La Poste, 27 Rue des Francs Bourgeois",
      "recipient_information": {
        "first_name": "Cathy",
        "last_name": "Doe",
        "additional_info": "Dr.",
        "gender": "U",
        "phone": "33112345678"
      },
      "delivery_address": {
        "country": "FR",
        "state": "string",
        "city": "Paris",
        "zip_code": "75001",
        "street_address": "101 Rue de Rivoli",
        "street_additional_details": "Immeuble B",
        "house_number": "101"
      }
    },
    "pos_technical_info": {
      "notify_url": "https://hipay.com/notify",
      "device_information": {
        "serial_number": "17196WL25395813",
        "manufacturer": "INGENICO"
      },
      "host_information": {
        "host": "192.168.1.10",
        "port": 8888
      },
      "terminal_transaction_display": {
        "contract_array": [
          {
            "merchant_contract": "1234567",
            "rank": "001",
            "payment_application": "001"
          }
        ],
        "push_to": "POS",
        "protocol": "ConcertV3.2",
        "force_authorization": true
      }
    }
  }
}