Physical Pinpad/Terminal

Physical pinpad terminals allow customers to complete payments using a physical point-of-sale (PoS) device paired with the Hyp payment page. This payment method is ideal for retail locations, self-service kiosks, and mobile payment scenarios where customers prefer to interact with familiar physical payment hardware.

Here's what the payment page looks like when pinpad pairing is enabled:

Pinpad Pairing view in the payment page

How it works

With pinpad pairing (also called Cloud Pairing), the Hyp payment page doesn't collect card information directly. Instead, it initiates a transaction on your paired physical terminal, allowing customers to complete payment by tapping or inserting their card.

Common use cases:

• Retail checkout: Store employees initiate payments through a web interface while customers use the physical terminal

• Self-service kiosks: Customers interact with a touchscreen that hands off payment to a nearby terminal

• Mobile payments: Delivery or service personnel use tablets to initiate payments completed on portable pinpads

Key benefits:

• Simple integration with existing payment page setup

• No additional client-side development required

• Familiar payment experience for customers

• Seamless workflow that preserves existing transaction handling

Prerequisites and terminal configuration

Before you can use physical pinpad terminals with your payment page, you'll need to complete the following setup:

Contact your Hyp representative to enable pinpad pairing in your terminal. They will handle the necessary configuration on the Hyp side.

Hardware requirements:

• A physical כספית (Caspit) pinpad that supports Hyp's API

• Network connection for the pinpad

• Terminal configured for Full EMV-CP transactions

Technical requirements:

• Payment page integration (PPS-based payment pages only - JSP pages are not supported)

• Modern browser support (Internet Explorer is not supported)

• Supplier numbers that allow smart card transactions, not just internet transactions

Payment page integration

The payment page integration process is covered in Integrating Hyp's Payment Page and Accepting Payment.

As soon as pinpad pairing is enabled in your terminal, the Pay with PINPAD button will show on your payment pages by default, without any extra effort, unless you have chosen to hide this payment method.

Payment experience

The payment flow with physical pinpad terminals follows these steps:

1. Merchant Request: You send a payment page request to get a payment page URL

2. Payment Page: The customer sees the payment page with a "Pay with PINPAD" button

3. Initiate Transaction: Customer clicks the PINPAD button to start the transaction

4. PINPAD Interaction: Customer inserts or taps their card on the physical terminal

5. Transaction Processing: The system processes the payment and returns results

6. Completion: Customer is redirected to the success or error page based on the result

Payment flow summary: Merchant → Payment Page → Pinpad Terminal → Customer → Transaction Complete

User interface progression

Here's what customers see during the payment process:

Payment page

Waiting screen

Pinpad screen

Configuration options

Making pinpad pairing the default payment method

In most cases when using physical pinpad terminals, you'll want to disable all other payment methods to streamline the payment flow. You could disable them one by one, but a better approach is to make pinpad pairing the default payment method.

When you set pinpad pairing as the default, the payment page skips the initial view with credit card fields and payment method selection, opening the pinpad-specific view immediately.

To make pinpad pairing the default payment method, add a JSON configuration object to your payment page request similar to when you change the default payment page appearance. In the configuration object, under uiCustomData, set defaultPaymentMethod to pcp:

{
  "uiCustomData": {
    "defaultPaymentMethod": "pcp"
  }
}

Required API parameters

For pinpad pairing transactions, you need to include the slaveTerminalNumber parameter in your doDeal request:

• slaveTerminalNumber: The POS station number (001-999) that matches the configuration on your physical pinpad. This ensures the correct pinpad is activated for the transaction.

Example request

Here's an example doDeal request for pinpad pairing:

<ashrait>
  <request>
    <version>2000</version>
    <language>ENG</language>
    <command>doDeal</command>
    <doDeal>
      <terminalNumber>{terminalNumber}</terminalNumber>
      <cardNo>CGMPI</cardNo>
      <transactionType>Debit</transactionType>
      <creditType>RegularCredit</creditType>
      <transactionCode>Regular</transactionCode>
      <currency>ILS</currency>
      <total>7600</total>
      <mid>{mid}</mid>
      <validation>TxnSetup</validation>
      <mpiValidation>AutoComm</mpiValidation>
      <successUrl>https://mymerchantwebsite.com/success/</successUrl>
      <errorUrl>https://mymerchantwebsite.com/error/</errorUrl>
      <slaveTerminalNumber>XXX</slaveTerminalNumber>
    </doDeal>
  </request>
</ashrait>

Activation options

Once your physical pinpad is paired with Hyp's system, you have two activation options:

1. Manual activation: The merchant clicks the pinpad button to activate the terminal for the current transaction

2. Automatic activation: The pinpad activates automatically when the transaction starts (common in most modern PoS systems)

The pinpad processes transactions independently of the payment page. Once the customer completes payment on the terminal, the result is returned to the payment page and the customer is redirected accordingly.

Additional considerations

Transaction identification

Pinpad pairing transactions can be identified by the extendedTranCode tag in the transaction response, which has the value "broker".

Hardware support

Hyp currently supports כספית (Caspit) physical pinpads only.

Error handling

Pinpad pairing uses standard transaction error codes. Common issues include:

Error Code	Description
1047	Declined - Invalid balance code
1048	Declined - Missing benefit
1053	Invalid transaction details
1054	Terminal was not setup
1061	No permission for transaction
2000	Application error

Setup process

The setup process involves coordination between Hyp and Caspit:

Hyp handles:

• API account and terminal configuration

• Payment page setup

• Pinpad button activation in terminal settings

Caspit handles:

• Hardware installation and configuration

• Terminal registration with their systems

• On-site technical setup and testing

Your Hyp representative will coordinate this process to ensure everything works together properly.