PoS Bridge

Pelecard PoS-Bridge is a service that enables transaction processing between Electronic Cash
Registers (ECR) and Pelecard’s EMV-compliant gateway (the switch). It acts as a bridge between the
ECR and the terminal equipment (PAX S300, for example).

Requirements

• Terminal device with “ASHRAIT” software on board
• Windows environment (Windows 7 or later)
• .NET Framework 4.5
• Internet connection

Payment modes

The payment process can be performed in two steps or in one step.

Two-step mode

1. The customer swipes, inserts, or taps the card on the PinPad. After several checks, the PinPad
   returns the card-related information to the cash register — stage 1 is complete.
   At this point the merchant may choose payment options appropriate to the card type (for example,
   splitting the payment into 3 equal settlements).
2. The PinPad finalises the payment: it verifies the card is valid and that sufficient funds are
   available in the cardholder’s account. The system then returns the transaction status and details.

One-step mode — equivalent to the second step of the two-step process,
performed in a single call.

Method overview

Two-step payment:

These transport conventions apply to every method. Each payment must begin with
CreateSession.

Creates a new session on the PoS-Bridge service and defines the PinPad connection. Returns the
session ID used by all subsequent methods.

Request

{
    "TerminalNumber": "0882577012",
    "UserName": "PeleTest",
    "Password": "XXXXXX",
    "PinpadSerial": "53218917",
    "AshraitType": "1",
    "DeviceVendorCode": "1234:0101",
    "PinpadType": "19",
    "PinpadIpPort": "192.168.0.45:8080",
    "SpIpAddress": "82.80.233.69",
    "SpPort": "4109",
    "Lang": "En",
    "PinpadSecCode": "1321"
}

Response

Returns a session ID, or an error description.

{
    "Data": "",
    "Error": "",
    "SessionId": "d5b48ecb-9606-4cf4-8dec-a7dae48fbf5c",
    "Status": "OK"
}

Once a session is established, starts the two-stage payment flow.

Request

{
"RequestProperties": {
"AdditionalData": "",
"Amount": 220,
"AuthNum": "",
"CreateToken": true,
"Currency": "376",
"EcrId": "",
"JParam": 4,
"KupaNo": 1,
"TranType": 1
},
"SessionId": "823121fa-e3e9-4cbb-aa59-d86e0a99bde9"
}

Response

{
"AvilibleCreditTerms": [1, 8, 6, 2],
"Error": "",
"Manpik": 1,
"Mutag": 1,
"PAN": "532612***0200",
"Solek": 2
}

<!– ROW 6 — “1.3 PaymentEnd” — paste into the HTML field –>

Completes the payment initialised by <code>PaymentStart</code>. At this stage the merchant sets
additional transaction parameters such as credit terms or the number of settlements.

<strong>Both <code>PaymentStart</code> and <code>PaymentEnd</code> must be called within the same
session, using the same session ID.</strong>
<div class=”pb-endpoint”><span class=”pb-method”>POST</span>
<code>http://127.0.0.1:8019/PosBridge/<span class=”pb-path”>PaymentEnd</span></code></div>
<h3>Request</h3>
<pre class=”line-numbers”><code class=”language-json”>{
“RequestProperties”: {
“Amount”: 0,
“CreditTerms”: 1,
“FirstPayment”: 0,
“IndexPayment”: 0,
“NoOfPayments”: 1,
“Tip”: 0
},
“SessionId”: “823121fa-e3e9-4cbb-aa59-d86e0a99bde9”
}</code></pre>
<div class=”table-container”>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Max</th>
<th class=”pb-c”>Req.</th>
<th>Description</th>
<th>Remarks</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Amount</code></td>
<td>Num</td>
<td>8 dt</td>
<td class=”pb-c”>No</td>
<td>Updated total amount. Must be <strong>less than or equal to</strong> the original amount</td>
<td>In CENTS</td>
</tr>
<tr>
<td><code>CreditTerms</code></td>
<td>Num</td>
<td>1 dt</td>
<td class=”pb-c”>No</td>
<td>Type of crediting</td>
<td><code>1</code> Regular · <code>2</code> Isracredit · <code>6</code> Credit · <code>8</code> Payments</td>
</tr>
<tr>
<td><code>NoOfPayments</code></td>
<td>Num</td>
<td>2 dt</td>
<td class=”pb-c”>No</td>
<td>Number of payments. For <code>CreditTerms</code> 6, 8</td>
<td>1–36</td>
</tr>
<tr>
<td><code>FirstPayment</code></td>
<td>Num</td>
<td>8 dt</td>
<td class=”pb-c”>No</td>
<td>Amount of the first payment. For <code>CreditTerms</code> 8</td>
<td>In CENTS</td>
</tr>
<tr>
<td><code>IndexPayment</code></td>
<td>Num</td>
<td>1 dt</td>
<td class=”pb-c”>No</td>
<td>Payments linking</td>
<td><code>0</code> not linked · <code>1</code> CPI-linked · <code>2</code> USD-linked</td>
</tr>
<tr>
<td><code>Tip</code></td>
<td>Num</td>
<td>8 dt</td>
<td class=”pb-c”>No</td>
<td>The part of the total amount defined as a tip</td>
<td>In CENTS</td>
</tr>
</tbody>
</table>
</div>
<h3>Response</h3>
<div class=”pb-callout pb-warn”>

<span class=”pb-label”>Note.</span> The response may contain <strong>more fields</strong> than
the example below — see the full table.

</div>
<pre class=”line-numbers”><code class=”language-json”>{
“Amount”: 0,
“CardExpirationDate”: “”,
“CardName”: “”,
“CreditTerms”: 0,
“Currency”: “”,
“CustomerRecipt”: “”,
“CustomerReciptDetailed”: null,
“FirstPayment”: 0,
“Manpik”: 0,
“ManpikAuthNum”: “”,
“MerchentRecipt”: “”,
“MerchentReciptDetailed”: null,
“Mutag”: 0,
“NoOfPayments”: 0,
“NonFirstPayment”: 0,
“PAN”: “”,
“PanEntryMode”: 0,
“ParamJ”: 4,
“RRN”: “”,
“Result”: 4,
“ResultDescription”: “unauthorized transaction”,
“Solek”: 0,
“SolekAuthNum”: “”,
“SwipeData”: “”,
“Tip”: 0,
“Token”: “”,
“TranType”: 0,
“UID”: “”,
“Voucher”: “”
}</code></pre>
<div class=”table-container”>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Max</th>
<th>Description</th>
<th>Remarks</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Result</code></td>
<td>Num</td>
<td>4 dt</td>
<td>Result code</td>
<td><code>0</code> = OK</td>
</tr>
<tr>
<td><code>ResultDescription</code></td>
<td>Text</td>
<td>256</td>
<td>Result description</td>
<td></td>
</tr>
<tr>
<td><code>Amount</code></td>
<td>Num</td>
<td>8 dt</td>
<td>Total amount of the transaction</td>
<td>In CENTS</td>
</tr>
<tr>
<td><code>NoOfPayments</code></td>
<td>Num</td>
<td>2 dt</td>
<td>Number of payments. <code>CreditTerms</code> 6, 8</td>
<td>1–36</td>
</tr>
<tr>
<td><code>FirstPayment</code></td>
<td>Num</td>
<td>8 dt</td>
<td>Amount of the first payment. <code>CreditTerms</code> = 8</td>
<td>In CENTS</td>
</tr>
<tr>
<td><code>NonFirstPayment</code></td>
<td>Num</td>
<td>8 dt</td>
<td>Amount of each subsequent payment. <code>CreditTerms</code> = 8</td>
<td>In CENTS</td>
</tr>
<tr>
<td><code>CreditTerms</code></td>
<td>Num</td>
<td>1 dt</td>
<td>Type of crediting</td>
<td>See the code tables</td>
</tr>
<tr>
<td><code>Currency</code></td>
<td>Text</td>
<td>3</td>
<td>ISO-4217 numeric code. Default <code>376</code></td>
<td><code>376</code> NIS · <code>840</code> USD · <code>978</code> EUR</td>
</tr>
<tr>
<td><code>ManpikAuthNum</code></td>
<td>Text</td>
<td>7</td>
<td>Issuer authorization number</td>
<td><code>1234567</code></td>
</tr>
<tr>
<td><code>SolekAuthNum</code></td>
<td>Text</td>
<td>7</td>
<td>Clearing authorization number</td>
<td><code>1234567</code></td>
</tr>
<tr>
<td><code>Manpik</code></td>
<td>Num</td>
<td>1 dt</td>
<td>Issuer code number</td>
<td>See the code tables</td>
</tr>
<tr>
<td><code>Solek</code></td>
<td>Num</td>
<td>1 dt</td>
<td>Clearing company code number</td>
<td>See the code tables</td>
</tr>
<tr>
<td><code>Mutag</code></td>
<td>Num</td>
<td>1 dt</td>
<td>Card brand code number</td>
<td>See the code tables</td>
</tr>
<tr>
<td><code>PAN</code></td>
<td>Text</td>
<td>19–20</td>
<td>Censored / masked card number — first 6 + last 4</td>
<td><code>458045***4580</code></td>
</tr>
<tr>
<td><code>PanEntryMode</code></td>
<td>Num</td>
<td>2 dt</td>
<td>How the card was applied</td>
<td>See the code tables</td>
</tr>
<tr>
<td><code>RRN</code></td>
<td>Text</td>
<td>12</td>
<td>ISO 8583 Retrieval Reference Number</td>
<td></td>
</tr>
<tr>
<td><code>UID</code></td>
<td>Text</td>
<td>23</td>
<td>Transaction unique ID</td>
<td><code>18021314342808830126284</code></td>
</tr>
<tr>
<td><code>SwipeData</code></td>
<td>Text</td>
<td>256</td>
<td>Track 2 data</td>
<td><strong>Only for non-credit cards.</strong> Empty string for credit cards.</td>
</tr>
<tr>
<td><code>Tip</code></td>
<td>Num</td>
<td>8</td>
<td>The part of the total amount defined as a tip</td>
<td>In CENTS</td>
</tr>
<tr>
<td><code>CardExpirationDate</code></td>
<td>Text</td>
<td>4</td>
<td>Card expiration date, <code>YYMM</code></td>
<td><code>2104</code></td>
</tr>
<tr>
<td><code>CardName</code></td>
<td>Text</td>
<td>256</td>
<td>Card name</td>
<td><span class=”pb-he”>אמריקן אקספרס</span></td>
</tr>
<tr>
<td><code>ParamJ</code></td>
<td>Num</td>
<td>1</td>
<td>Param “J” — operation type</td>
<td><code>4</code>, <code>0</code> debit · <code>5</code> obligo</td>
</tr>
<tr>
<td><code>CustomerRecipt</code></td>
<td>Text</td>
<td>1024</td>
<td>Customer receipt — raw data from the PinPad</td>
<td></td>
</tr>
<tr>
<td><code>CustomerReciptDetailed</code></td>
<td>Array</td>
<td></td>
<td>Customer receipt — key/value pairs</td>
<td>See below</td>
</tr>
<tr>
<td><code>MerchentRecipt</code></td>
<td>Text</td>
<td>1024</td>
<td>Merchant receipt — raw data from the PinPad</td>
<td></td>
</tr>
<tr>
<td><code>MerchentReciptDetailed</code></td>
<td>Array</td>
<td></td>
<td>Merchant receipt — key/value pairs</td>
<td>See below</td>
</tr>
<tr>
<td><code>Token</code></td>
<td>Text</td>
<td>14</td>
<td>Token</td>
<td><code>10006783786075</code></td>
</tr>
<tr>
<td><code>TranType</code></td>
<td>Num</td>
<td>1</td>
<td>Transaction type</td>
<td>See the code tables</td>
</tr>
<tr>
<td><code>Voucher</code></td>
<td>Text</td>
<td>7</td>
<td class=”pb-dim”><strong>Not supported</strong></td>
<td></td>
</tr>
</tbody>
</table>
</div>
<div class=”pb-callout pb-note”>

<span class=”pb-label”>Note the spelling.</span> The wire fields are <code>CustomerRecipt</code>,
<code>CustomerReciptDetailed</code>, <code>MerchentRecipt</code> and
<code>MerchentReciptDetailed</code> — spelled exactly as shown.

</div>
<h3>Detailed receipt format</h3>
<code>CustomerReciptDetailed</code> / <code>MerchentReciptDetailed</code> are arrays of alternating
key/value entries, where the key is the field name as printed on the receipt.
<pre class=”line-numbers”><code class=”language-json”>”CustomerReciptDetailed”: [
“תאריך”, “18/12/18 19:34”,
“מספר מסוף”, “0883012”,
“גרסת תוכנה”, “01.08.12”,
“מספר עסק”, “0071506”,
“כרטיס”, “אמריקן אקספרס”,
“מספר”, “1238”,
“מספר שובר”, “26013068”,
“מזהה”, “18121819342208830125047”,
“RRN”, “835219064609”,
“סוג עסקה”, “חובה”,
“מספר אישור”, “2064609”,
“גורם מאשר”, “חברה”,
“אופן ביצוע”, “זכה”,
“זיהוי יישום בשבב”, “A000000025010402”,
“סוג אשראי”, “רגיל”,
“סכום עסקה”, “2.20”,
“”, “Verified by device”,
“מזהה שרת”, “43184669911238”
]</code></pre>

PaymentFull

Performs the first and second step of the transaction in one go.

{
    "Stage1Input": {
        "// same fields as PaymentStart RequestProperties"
    },
    "Stage2Input": {
        "// same fields as PaymentEnd RequestProperties"
    },
    "SessionId": "4a86a285-1b58-4562-b170-7911d1249ee5"
}

The response format is the same as PaymentEnd.

---

Init

Initialises the PinPad to work with the terminal number specified in the session. Use
Init with IsPinpadInit = true when installing a new device.

{
    "IsPinpadInit": true,
    "SessionId": "4a86a285-1b58-4562-b170-7911d1249ee5"
}

{
    "Data": "",
    "Error": "",
    "SessionId": "4a86a285-1b58-4562-b170-7911d1249ee5",
    "Status": "OK"
}

---

AbortTransaction

Breaks the transaction after step 1 and releases the PinPad.

{
    "SessionId": "4a86a285-1b58-4562-b170-7911d1249ee5"
}

{
    "Data": "",
    "Error": "",
    "SessionId": "4a86a285-1b58-4562-b170-7911d1249ee5",
    "Status": "OK"
}

---

DebitByToken

Performs a CNP (card-not-present) transaction. Does not require a PinPad —
typically used in back-office systems.

{
    "SessionId": "833a3125-2e66-44c4-bb8e-52ce1d0c8830",
    "terminal": "0882577012",
    "userName": "PeleTest",
    "password": "XXXXXX",
    "token": "80227153610200",
    "amount": 230,
    "currency": "376",
    "jParam": 4,
    "creditTerms": 1,
    "tranType": 1,
    "paymentsNumber": 0,
    "firstPayment": 0,
    "CVV2": "",
    "id": "",
    "kupaNumber": "1",
    "authNum": "",
    "paramX": "TEST_01"
}

The response format is the same as PaymentEnd.

---

DebitObligo

Makes a payment (J4) using funds obliged by a previous J5 transaction.

{
    "SessionId": "9b12b7f3-412b-4d15-9508-cc40d44dc120",
    "UID": "XXXXXXXXXXXXXXXX",
    "currency": "376",
    "ecr": "",
    "newAmount": 220
}

The response format is the same as PaymentEnd.

---

ReleaseObligo

Breaks (releases) an obligo — the opposite of DebitObligo. Cancels the approval
and releases the obligation on the customer’s credit card.

{
    "SessionId": "9b12b7f3-412b-4d15-9508-cc40d44dc120",
    "UID": "XXXXXXXXXXXXXXXX",
    "ecr": ""
}

The response format is the same as PaymentEnd.

---

UpdateParameters

Starts the parameter-updating sequence on the PinPad. Also used when the PinPad device does not
support scheduled broadcasting.

{
    "SessionId": "4a86a285-1b58-4562-b170-7911d1249ee5"
}

{
    "Data": "",
    "Error": "",
    "SessionId": "4a86a285-1b58-4562-b170-7911d1249ee5",
    "Status": "OK"
}

Best practice is to install the PoS-Bridge and the ECR on the same PC. The service
requires Windows 7 or later with .NET Framework 4.5, and needs an internet connection.

Command-line options

Run PelecardPosBridgeService.exe /? for help.

PeleCard POS Service
----------------------------------------
Copyright (C) 2018 - Mabat DS Ltd
----------------------------------------
Command line options:
   PelecardPosBridge.exe             - with no args, starts in local server mode
   PelecardPosBridge.exe /install    - installs and starts the service
   PelecardPosBridge.exe /unisntall  - stops and uninstalls the service
   PelecardPosBridge.exe /start      - starts the previously installed service
   PelecardPosBridge.exe /stop       - stops the previously installed service
   PelecardPosBridge.exe /restart    - restarts the previously installed service

Installation steps

1. Install the service:

   PelecardPosBridgeService.exe /install

2. Open the Services console:

   %windir%\system32\services.msc

3. In PelecardPosBridge Properties:
   • Log On tab — assign a user account with sufficient credentials.
   • Recovery tab — set the recovery options as below.

   Setting	Value
   First failure	Restart the Service
   Second failure	Restart the Service
   Subsequent failures	Restart the Service
   Reset fail count after	0 days
   Restart service after	1 minute

4. Start the service.

Verifying the service

Browse to http://localhost:8019/PosBridge/GetServiceStatus:

Ok. Sessions list: a9be239d-499d-4c96-94f6-49e632487617;

Testing

PelecardPosEmulator.exe lets you test all the methods described in
this document with different parameters. The emulator provides a Create Session panel, a PaymentFull /
Two-Step Transaction tab, quick selectors for Amount, JParam, TranType, Currency and Credit Terms, and
an output pane showing the raw JSON response.

Support

For additional information or support, contact
op@pelecard.co.il.

TranType (request)

Only 01 and 53 are supported by the current version of the bridge.
The remaining values are documented but not supported.

Default: 01

TranType (response)

JParam

Default: 0

CreditTerms

IndexPayment

Currency (ISO-4217)

Manpik — issuer

Solek — clearing company

Mutag — card brand

PanEntryMode

AshraitType

PinpadType

Lang