Overview

For semi-integrated solutions, bluefin provides clients with a local network websocket solution.

Bluefin's Ingenico Bluechip application provide clients with a semi-integrated solution via the utilization of localized websocket communication.

Websocket Request Flow

  1. The ISV's POS reaches out to the Ingenico machine over websocket with the payment request.
  2. The Ingenico device running in Semi-Integrated (Server Mode) receives the receives the request and prompts for payment. Once the customer insert/swipes/taps or manual enters their card number, the device will send the encrypted card data to the Payconex Gateway
  3. The Payconex Gateway receives the payment request and sends it over to the processor
  4. The processor will process the payment and send the payment outcome back to the Payconex Gateway
  5. The Payconex gateway will return a response to the Ingenico device advising of the payment outcome.
  6. The Ingenico device will send a response back to the POS advising of a successful or failed transaction.

JSON Request Format

All messages to the Ingenico terminal will follow the same format.

  • Each request must include a unique flow_id
  • Each request will have a resource field (“resource” is a TSI payment transaction object instance)
  • The required and optional parameters are set in the parameters list section
{
"flow_id":"12345",
"resource":
{
<parameters list>
}

}

Transaction Message-Flow


The WebSocket integration follows an event-driven request/response model. Each request sent to the Ingenico terminal must include a unique flow_id to track the transaction lifecycle.

Upon receiving a valid request with no errors, the terminal initiates the corresponding transaction service and immediately returns a response indicating that the service has started successfully.

After the initial response, the communication transitions into an event message flow. During this phase, the terminal sends one or more event messages to report the current status of the transaction.

  • If the status attribute in the event message is "ok", the payload will include the full transaction result.
  • If the status indicates an error, the event will include error details instead.

Once the POS system receives the event, it must respond with an event_ack message to confirm receipt and acceptance of the event.

  1. The POS sends a payment request to the terminal via WebSocket.
  2. The terminal returns a response indicating that the request has been received and the payment process is being initiated. The device will activate (e.g., screen prompt, lights) to accept customer input.
  3. Once the transaction is completed, the terminal sends an event message containing the transaction outcome and relevant details.
  4. The POS sends an event_ack message to confirm receipt and acceptance of the transaction response.