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 ValueTypeDescription
[##\CullenSoftwareDesign\PCEFTPOS_BRIDGE\TPP-ZIPMONEY]keyZipMoney Registry Key
API_KEYstringAPI Key provided by zip. Your zipMoney account is looked up using only this key
LOCATION_IDstringLocation 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 ValueTypeDescription
[##\PC-EFTPOS\LaneInfo]keyLane Information Registry Key
MerchantIdstringA unique 5-7 character label that is unique per Merchant/Brand (contact PC-EFTPOS for this)
StoreIdstringA five digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. “01234”
LaneIdstringA three digit lane number (pad to three digits). Eg “005”
StoreAddressstringOptional 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

FieldDescription
Command CodeSet to ‘M’ to indicate a Transaction request
Merchant Set to ‘89’ to indicate a ZipMoney transaction
Txn TypeSet to ‘P’ to indicate a Purchase
Amount PurchaseSet to the amount to pay with ZipMoney
Card NumberZipMoney code if provided by the POS, otherwise blank
Card Number SourceCode capture method if captured by the POS
Txn Ref NumberUnique transaction reference number
csdReservedString2Set to ‘APP_1’ (ActiveX Only)
AppSet to ‘02’ (IP Interface Only)

PurchaseAnalysisData (PAD)

FieldDescription
OPROperator info in the format: RefCode
BFTBasket Format. Default NCV
BSKBasket values, see section - Basket.
AMTTotal transaction amount (must be >= Amount Purchase)
TAXTax Amount (optional)
SHPShipping Amount (optional)

Response

FieldDescription
Success Flag‘1’ if the transaction was successful
Response Code‘00’ if the transaction was approved
Response TextResponse message

PurchaseAnalysisData (PAD)

FieldDescription
HRCResponse code from ZipMoney – no need to store or use this value
REFZipMoney transaction Id

Technical Specification for a Refund


This transaction can be used to refund a Zip purchase.


Request

FieldDescription
Command CodeSet to ‘M’ to indicate a Transaction request
MerchantSet to ‘89’ to indicate a ZipMoney transaction
Txn TypeSet to ‘R’ to indicate a Refund
Amount PurchaseSet to the refund amount
Txn Ref NumberUnique transaction reference number
csdReservedString2Set to ‘APP_1’ (ActiveX Only)
AppSet to ‘02’ (IP Interface Only)

PurchaseAnalysisData (PAD)

OPROperator info in the format: RefCode|Name
REFZipMoney Id of the transaction to refund

Response

FieldDescription
Success Flag‘1’ if transaction was successful
Response Code‘00’ if the transaction was approved
Response TextResponse message

PurchaseAnalysisData (PAD)

FieldDescription
HRCResponse 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 ParameterSample LengthSample Value
OPR0100001|Brent (Operator ID + Operator name, pipe separated )
AMT00510000 ($100.00)
SHP003500 ($5.00)
TAX003500 ($5.00)
BFT009CSGNVDTIL (Describes positioning and order of each basket parameter passed in BSK, refer to next section - Basket - for description of each of these parameters)
BSK1452 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 ParameterSample LengthSample Value
OPR0100001|Brent (Operator ID + Operator name, pipe separated)
REF00531267

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.