PC-Eftpos

Plugin icon

PC-Eftpos

Accept Zip payment on you PC-Eftpos software following this configuration steps.

If you require a smoother in-store integration and you use PC-EFTPOS for your in-store EFTPOS then you’re in luck. Zip integrates with PC-EFTPOS in a seamless fashion for in-store purchases.\

This extension adds to the core EFTPOS payment API that is provided to the POS by the PC-Eftpos EFT Client and allows the POS to perform the proprietary Zip transactions outlined here.

This guide assumes an existing understanding of the PC-Eftpos solution and core API’s as covered by the “PC-Eftpos EFTClient TCP Specification” and “PC-Eftpos ActiveX Control for EFTClient” documents


Overview

To successfully integrate with PC-Eftpos is important to understand the following

Installation and Configuration


🚧

Download the Zip PCEFTPOS plugin


The ZipMoney extension file TPP_ZipMoney.bcx must be installed to the same folder as the EFTClient executable EftClnt.exe on the POS (by default this is the C:\PC_EFT folder). It does not need to be installed on the PCEFTPOS Server, if this is separate for your installation - only the client(s).

This extension should work with Windows XP or above (32 and 64 bit versions).

In addition to the basic TPP lane configuration, the zip extension requires various identifiers provided by the zip team to be configured in the Registry.

The TPP ZipMoney extension can be configured by pushing values directly to the registry. The following table summarises the registry values that should be set for the TPP ZipMoney extension.


Registry Key or Value

Type

Description

[##\CullenSoftwareDesign\PCEFTPOS_BRIDGE\TPP-ZIPMONEY]

key

ZipMoney Registry Key

API_KEY

string

API Key provided by zip. Your zipMoney account is looked up using only this key

LOCATION_ID

string

Location ID provided by zip. This is the ID of your branch in the zip system, there will be a separate ID per store or branch


In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions and are not specific to the zipMoney extension.


Registry Key or Value

Type

Description

[##\PC-EFTPOS\LaneInfo]

key

Lane Information Registry Key

MerchantId

string

A unique 5-7 character label that is unique per Merchant/Brand (contact PC-EFTPOS for this)

StoreId

string

A five digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. “01234”

LaneId

string

A three digit lane number (pad to three digits). Eg “005”

StoreAddress

string

Optional store address information.


📘

## refers to the “SOFTWARE” registry key. On pre-Win7 this location is “HKEY_LOCAL_MACHINE\SOFTWARE”. On Win7 and later it is usually mapped to the location “HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node”. Ensure values are stored at the appropriate location for your POS


Technical Specification for a Purchase


🚧

You must modify your POS to:

  • Include a new tender type of Zip.

  • When the new tender type is selected - update the request that is sent to the PED (EFTPOS Device) to have a Merchant ID of 89 (instead of the usual 00 that is sent for a Card transaction).

  • Expect and be ready to process a response code of 00 for a successful transaction.

This transaction can be used to perform a purchase using Zip.

Request

Field

Description

Command Code

Set to ‘M’ to indicate a Transaction request

Merchant

Set to ‘89’ to indicate a ZipMoney transaction

Txn Type

Set to ‘P’ to indicate a Purchase

Amount Purchase

Set to the amount to pay with ZipMoney

Card Number

ZipMoney code if provided by the POS, otherwise blank

Card Number Source

Code capture method if captured by the POS

Txn Ref Number

Unique transaction reference number

csdReservedString2

Set to ‘APP_1’ (ActiveX Only)

App

Set to ‘02’ (IP Interface Only)

PurchaseAnalysisData (PAD)

Field

Description

OPR

Operator info in the format: RefCode

BFT

Basket Format. Default NCV

BSK

Basket values, see section - Basket.

AMT

Total transaction amount (must be >= Amount Purchase)

TAX

Tax Amount (optional)

SHP

Shipping Amount (optional)

Response

Field

Description

Success Flag

‘1’ if the transaction was successful

Response Code

‘00’ if the transaction was approved

Response Text

Response message

PurchaseAnalysisData (PAD)


Field

Description

HRC

Response code from ZipMoney – no need to store or use this value

REF

ZipMoney transaction Id


Technical Specification for a Refund


This transaction can be used to refund a Zip purchase.


Request

Field

Description

Command Code

Set to ‘M’ to indicate a Transaction request

Merchant

Set to ‘89’ to indicate a ZipMoney transaction

Txn Type

Set to ‘R’ to indicate a Refund

Amount Purchase

Set to the refund amount

Txn Ref Number

Unique transaction reference number

csdReservedString2

Set to ‘APP_1’ (ActiveX Only)

App

Set to ‘02’ (IP Interface Only)

PurchaseAnalysisData (PAD)


OPR

Operator info in the format: RefCode|Name

REF

ZipMoney Id of the transaction to refund

Response

Field

Description

Success Flag

‘1’ if transaction was successful

Response Code

‘00’ if the transaction was approved

Response Text

Response message

PurchaseAnalysisData (PAD)

Field

Description

HRC

Response code from ZipMoney – No need to use or store this value


Supplementary Field Data


Purchase Analysis Data (PAD)

This is a serialized string that follows the below rules:


  • 3-Digit Field Code
  • Proceeded by 3 numerical digits (0-padded) representing length in bytes
  • Proceeded by Field Value
  • Repeat from [1]

Example of PAD for Purchase:

OPR0100001|BrentAMT00510000SHP003500TAX003500BFT009CSGNVDTILBSK1452	ABCD	ABCDEF	Name	5000	Longer Description	Shoes	http://image	http://link	1	DCBA	DCBA	Name	1000	Longer Description	Shoes	http://image	http://link

Parameter List for Purchase Analysis Data (for Purchase):


PED Parameter

Sample Length

Sample Value

OPR

010

0001|Brent (Operator ID + Operator name, pipe separated )

AMT

005

10000 ($100.00)

SHP

003

500 ($5.00)

TAX

003

500 ($5.00)

BFT

009

CSGNVDTIL (Describes positioning and order of each basket parameter passed in BSK, refer to next section - Basket - for description of each of these parameters)

BSK

145

2 ABCD ABCDEF Name 5000 Longer Description Shoes http://image http://link 1 DCBA DCBA Name 1000 Longer Description Shoes http://image http://link


Example for Refund:


OPR0100001|BrentREF00531267

Parameter List for Purchase Analysis Data (for Refund):


PED Parameter

Sample Length

Sample Value

OPR

010

0001|Brent (Operator ID + Operator name, pipe separated)

REF

005

31267


Basket (BSK)

The ZipMoney TPP uses an extended PC-EFTPOS basket format (BFT), specifying the following fields:

  • C : Count, the quantity of the item purchased.
  • S : SKU, stock keeping unit code.
  • G : GTIN, global trade item number.
  • N : Name, short name for the item.
  • V : Value, total value of the items (i.e. count * individual price) including tax.
  • D : Description, a longer description of the item.
  • T : Type, the category of the item.
  • I : Image, a URL to the item image.
  • L : Link, a URL to the item store page.

If a basket is sent, as an absolute minimum the Value for each item must be specified, however it is recommended to specify at least the default of Name, Count and Value.

At a minimum - at least Name, Count and Value must be passed for each product in the basket.

All fields within the BSK are to be separated by a tab delimeter. If a value has a tab in it, replace it with a space prior to including in in the BSK.

For example: Shoes\t2\t15000\nSocks\t5\t5975\nGlow Laces\t1\t495

Would, assuming a basket format of NCV (Name Count Value), translate to: 2 pairs of Shoes for $150.00, 5 pairs of Socks for $59.75, and 1 pair of Glow Laces for $4.95\

📘

If more or less than the default fields are to be specified, or the order is changed, a custom BFT (basket format) tag must also be passed in the Purchase Analysis Data


Testing


You must perform testing of the Zip PCEFTPOS plugin with your POS, with the PCEFTPOS test gateway and the Zip Sandbox environment. To do this you must configure your EFT Server to point at the test gateway 59.167.228.3:443, and ensure that all EFT Clients are pointing at this server.


Once this is configured you can use the Sandbox API Key and Location ID from the Zip merchant dashboard in the requests that your POS passes to PCEFTPOS.


🚧

Test customer

Refer to the test customer guide to register yourself with a sandbox customer account


Once logged in on a mobile device you can select shop in-store to be presented with a store code, this code is to be entered into your PC-Eftpos terminal when testing. Whenever you need a new store code to test, simply ensure you are logged in to your sandbox customer account and click on the shop in-store option.

If you are trying to produce and in-store code on a desktop you will need to be in a mobile view. see video below on how to produce the in-store code on desktop.



Certification

When you believe your integration is complete before you go live it must first be certified by us.

❗️

To get certified, please complete the PC-Eftpos Certification Checklist and return it to [email protected] and one of our engineers will run through your integration.