Date	Author	Comments
2011-05-18	Vince	The Initial release only supports pinless topup using two-step process
2011-10-15	Vince	Added PinRequest, GetBalanceSt. Available in 2011.10 release.
2012-03-13	Vince	Added Process() for 2012.03 release
2012-05-25	Grant	Updated overview, layout and descriptions, no coding changes
2012-06-15	Vince	Added 2.2 HTTP GET Protocol. Added <AdditionalInfo> field in PinlessRequest response.
2015-01-12	Vince	Added 12 Query function. Made <Sequence> optional. Refer details in section 3.1
2015-02-04	Grant	Added request parameters TransMID, TransTID, TransLID
2015-06-15	Vince	Added <RefNo> Revised <ReceiptNo>
2015-06-19	Vince	Added <OriginalRequestNo> in Query function to support querying an Order Revised <RequestNo> to support cancelling an Order
2015-07-21	Vince	Renamed doc name to PSIcomm API SDK - 2015. Removed <Sequence>.
2017-12-05	Vince	Move section 4.1 PIN Return to 5.4 Reversal

2 Overview

Public link of this document is: paysrc.ca/pcapi

PSIcomm API provides an interface for transacting PINs (Prepaid Refill PINs), POSA (Point-Of-Sale-Activation), and Pinless Topup & Reload (instant top-ups without needing a PIN) by a Client application from the PSInet server. This document was written for third party system integrators planning to write client applications compatible with PSInet system.

For POS (Point-Of-Sale) terminals, we use script commands to configure user screen flows for different products. For example, pinless topup requires showing a screen for entering the customer’s phone number.

The StoreGUI field defines different types of products and defines the screen flows that will be used for the product as follows:

EP - PIN voucher with Fixed Amount

Traditional PIN transaction where the clerk selects the product and value.

VP - PIN voucher with Variable Amount (ie. surecash)

PIN transaction where the clerk selects the product and enters a variable amount.

TF - Topup a Phone Number using Fixed Amounts

After selecting the Topup product, the user enters the area code and phone number to topup and then picks from a list of fixed values.

TV- Topup a Phone Number using Variable Amounts

After selecting the Topup product, the user enters the optional area code and phone number twice for confirmation. Then types a variable amount for the topup value.

B1- Billpay using Variable Amounts

After selecting the Billpay product, the user enters the account number twice for confirmation. Then types a variable amount for the topup value.

PS- POSA Card Swipe with Single Fixed Amount

After selecting the POSA product, the user swipes the card and the card will be activated with the single fixed amount.

PF- POSA Card Swipe with a list of Fixed Amounts

After selecting the POSA product, the user swipes the card and then selects from a list of fixed amounts.

PV- POSA Card Swipe with Enter a Variable Amount

After selecting the POSA product, the user swipes the card and then enters the amount to load.

LH- LoadHub Express

Allows customers to directly and instantly load funds to an account using a customized, personal barcode or QR code.

PSInet supports multiple distribution channels, including self-serve kiosks, attended POS terminals (POS), and Host to Host. The billing system supports postpaid accounts and prepaid eCash accounts. You should know which kind of billing account you will be using before completing your development integration.

Integration development of your client application can be done to various levels or completed in phases. For example:

PIN products only
Real time reload / topup products only
Hard coded receipt layouts
Manual product file transfer and updating
Automated product file transfer and updating

POSA Gift Cards are only supported with fixed amount activation, no reloads or voids.

It is recommended the client side have a response timeout of 30 seconds.

You should discuss the integration and launch plan with your PSInet sales or admin contact.

2.1 HTTP GET Protocol

PSIcomm API provides an HTTP GET protocol. This protocol uses HTTP requests to a specific URL and passing URL parameters as arguments to the API. The function returns data as XML for processing by your application.

https://Server Address:Port/Web/Get?RequestXml=xml string(URL encoded)

For example: Get version on test server is:

https://api.paymentsource.co:444/Web/Get?RequestXml=%3CRequestXml%3E%3CType%3EVersion%3C/Type%3E%3C/RequestXml%3E

2.2 SOAP Protocol

Alternatively, PSIcomm API provides SOAP 1.1 Web Services. These Web Services are implemented following the SOAP document style convention. This is the default style for clients based on .NET framework.

The definition of the SOAP function is:

Public Function Process(RequestXml As String) As String

WSDL can be viewed by Internet browser directly on the test server at https://api.paymentsource.co:444/EcSoap

Screen Shot 2016-03-23 at 13.44.51.png

3 Request Parameters

Request parameters comprise a list of common fields and a list that varies for different types of products. You will be assigned a group of product codes and this list is provided in an XML file, see File Download.

Each product code has a StoreGUI associated with it that defines the type of product.

GUI	DESCRIPTION	NOTES
EP	Sell a Product with a PIN	Traditional PIN transaction where the clerk selects the product and value.
TF	Topup a Phone Number using Fixed Amounts	After selecting Topup product, the user enters the area code and phone number to topup and then picks from a list of fixed values.
TV	Topup a Phone Number using Variable Amounts	After selecting Topup product, the user enters the optional area code and phone number twice for confirmation. Then types a variable amount for the topup value.
B1	Billpay using Variable Amounts	After selecting Billpay product, the user enters the account number twice for confirmation, then types a variable amount for the value.
PS	POSA Card Swipe with Single Fixed Amount	After selecting POSA product, the user swipes the card and the card will be activated with the single fixed amount.
PF	POSA Card Swipe with list of Fixed Amounts	After selecting POSA product, the user swipes the card and then selects from a list of fixed amounts.
PV	POSA Card Swipe with Variable Amount	After selecting POSA product, the user swipes the card and then enters the amount to load.

3.1 Common Request Parameters

RequestXml is an html encoded xml string. All requests must include these common parameters.

Note:All tags in xml string are case sensitive.

<TerminalId>_TerminalId_</TerminalId>

<Password>_Password_</Password>

<Language>_Language_</Language>

<SoftVer>_SoftVer</SoftVer>

<ProductVer>_ProductVer</ProductVer>

<PaymentType>_PaymentType</PaymentType>

<TransMID>_TransMID</TransMID>

<TransTID>_TransTID</TransTID>

<TransLID>_TransLID</TransLID>

<ClientIP>_ClientIP_</ClientIP>

…...

<!-- Function specific xml fields →

.…..

</RequestXml>

Field	Size	Description
Type		A string identifying the function type: PinRequest - Retrieve one pin in a real time delivery scenario. PinlessRequest - POSA activation, real time reload supported of external service providers such as long distance card operators or mobile phone carriers. PinlessRequest2ndStep - 2nd step in Pinless process to confirm the activation or reload. GetBalanceSt - Retrieve the current eCash Balance for the merchant associated with the specified Terminal ID. This function type is not necessary if your billing is not prepaid eCash. It can also be used as a 'heart beat' message to test host system availability. FileDownload - Download product file containing product list and voucher layouts, see section 4. File Download
TerminalId	max 20	A unique identifier assigned to the Client supplied by the PSInet System Administrator. You may use one Terminal ID for all your transactions or if your system is supporting multiple clients you might choose to send different Terminal ID’s based on the source of your request.
Password	max 20	The Password assigned to TerminalId, supplied by the PSInet System Administrator. A single password shared by all terminals is supported, but a password per terminal is recommended.
Language	max 3	(Optional) Prefer language in response message. ISO 639-3 three-letter language code. If this field is not set, server’s response is in English. ISO 639‑3 language code for the text used in response message. Currently supported: “eng” = English, “fra”=French, “spa”= Spanish, “zho”=Chinese, “por” = Portuguese, others default to English. 2020-02-25 Added for PsiNet Store: en,fr
SoftVer	Max 20	Optional. If this field is sent, PSIcomm will store the value in stations.soft_ver.
ProductVer	Max 7	Optional.If this field is sent, PSIcomm will store the value in stations.gproductver.
PaymentType	Max 1	"C" - credit card sale "A" - cash sale "D" - debit "U" - Unknown
TransMID	Max 30	If you need to send an identification of your site to the product service provider, then include it in this field and if this tag exists, PSIcomm will forward the value to the service provider Required for: Ukash, paysafecard
TransTID	Max 30	If you need to send an identification of your terminal or user to the product service provider, then include it in this field and if this tag exists, PSIcomm will forward the value to the service provider. Required for: paysafecard
TransLID	Max 30	If you need to send an identification of your location to the product service provider, then include it in this field and if this tag exists, PSIcomm will forward the value to the service provider. Required for: paysafecard
ClientIP	Max. 45	Report the IP address of client

3.2 Common Response Fields

Response is an html encoded xml string

<StatusCode>_StatusCode_<StatusCode>

<StatusDescription>_StatusMessage_</StatusDescription>

…...

<!-- Function specific fields →

.…..

</ResponseXml>

NOTE: Some fields returned in the response can be viewed as optional by the Client, such as: MerchantID, Company, CompanyCity, CompanyPhone, CompanyDbaName, TransDate & TransTime. This data can be ignored if the Client has similar data already. Settlement or reconciliation should be based on the unique PSInet transaction number and not these fields.

Field	Size	Description
StatusCode	max 5	“0” Success non-0 The product request has failed. e.g. "1"
StatusDescription	max 255	Contains an explanation of the Status Code.
MerchantId		A unique string identifying the merchant.
Company		The merchant’s company legal name
CompanyCity		The merchant’s city from their address.
CompanyPhone		The merchant’s contact phone number.
CompanyDbaName		The merchant’s common business name.
TransDate		Local terminal date in yyyy-mm-dd format.
TransTime		Local terminal time in hh:mm:ss format.
ProductVer		Product file version
PromoVer		Promotion file version
SoftVer		Software version
InvoiceNum		Invoice number
NSM		Network short message that is displayed on the login screen or prominently as a banner in the client application.

4 PIN Request

These parameters are used for products where StoreGUI = EP. The PinRequest function type is used to retrieve one pin at a time in a real time delivery scenario.

RequestXml Fields

Field	Size	Description
Type		“PinRequest”
ProdCode	6	6 character code identifying product. List of codes is in the product file.
ValueCode	8,2	Product value reference, part of the product list provided by Payment Source. This value is in dollars and cents (100.00 represents $100)
ReceiptNo	5	Receipt number from Station. If the actual receipt number contains more than five characters, the last 5 characters (from the right) are recorded in the e-Fresh table. (Optional)
RefNo	20	A unique number identifying the transaction request.
ClerkId	10	ID of the clerk who sold the product. (Optional)

Example:

<Type>PinRequest</Type>

<TerminalId>Assigned</TerminalId>

<Password>Assigned</Password>

<ProdCode>ECTEST</ProdCode>

</RequestXml>

Response Fields

Field	Size	Description
TransNo	13	Returns the transno created for this transaction on the store PC’s system
<PinData>		PIN data block
PinData/Pin	31	The secret code of the Product to be given to the customer. This field is sent as clear text, not encrypted.
PinData/Custom1	80	Can contain information that should be delivered to the customer with the product. Most PIN products do not have data in this field.
PinData/Custom2	33	Can contain information that should be delivered to the customer with the product. Most PIN products do not have data in this field.
PinData/PinSerial	80	Serial number of the pin
PinData/PinBatch	15	Batch number of the pin (optional)
PinData/ExpiryDate	10	Expiry date of the pin format yyyy/mm/dd (optional)
</PinData>		block ends
TransDate	10	Local date of the transaction in format: yyyy-mm-dd
TransTime	8	Local time of the transaction in format: hh:mm:ss

Example:

<StatusDescription>PIN is on receipt. New eCash balance is 973.16.</StatusDescription>

</PinData>

<MerchantId>WenchengTesting</MerchantId>

<Company>Company has a very long name here</Company>

<CompanyCity>Sao Paulo</CompanyCity>

<CompanyDbaName>TestCompany</CompanyDbaName>

<NSM />

</ResponseXml>

5 POSA and Pinless

These parameters are used for products where StoreGUI=BP, TF, TV, B1, PS, PF, PV.

5.1 PinlessRequest

The PinlessRequest function type is used to perform activation or load supported by external service providers such as mobile phone carriers. This is the first function type call of a two-step process: PinlessRequest and PinlessRequest2ndStep. The second step is only needed if there is no <AuthorizationCode> value or <AuthorizationCode> is blank in PinlessRequest response. Most service providers use the two step process as it improves transaction reliability, especially during client-host communication abnormal scenarios. Thus, some service providers or PSIcomm may choose to use the one-step process depending on the requirements of individual service providers. Clients should support both one-step and two-step scenarios.

Note: If client does not receive a response for PinlessRequest, client should consider transaction as not processed and keep retrying until a response is received from server.

5.1.1 RequestXml Fields

Field	Size	Description
Type		“PinlessRequest”
ReceiptNo	5	Receipt number from Station. If the actual receipt number contains more than five characters, the last 5 characters (from the right) are recorded in the e-Fresh table.
RefNo	20	A unique number identifying the transaction request.
AccountNo (optional)	max 255	For topup send full phone number with area code. This data should be sent only as numeric. If the user enters (604) 555-1212 it must be sent as 6045551212 For POSA cards send the full track data in this field (including Track 1 and Track 2) Track1 and Track2 data separated by ~~ (two tildes) e.g. For card swiped with track1 and track2: B6011905571586247^/WINGS^10011011242368600000~~6011905571586247=10011011242368600000 For card swiped with only track1: N1952^DWMYPH000500^6393610326000062^~~ For card swiped with only track2: ~~=10101960010133332323 For bill pay, this is the confirmation account number if required by service provider. For Refund, This is the TransNo For Barcode scan, send the full barcode in this field
Amount	max 10.2	The value to be loaded to the account, such as the topup amount in dollars or bill pay fee.
ClerkId	max 10	(optional) ID of the clerk who sold the product.
PayloadAmount	max 10.2	(optional) Bill balance
ProdCode	6	6 character code identifying product. List of codes is in the product file. “EFRDEP” for eCash Transfer
TerminalOption		(optional) Activate Load
TerminalParameter		(optional) For Loadhub: this contains the extended QR Code data For Redeem Pin: Pin number.
TransRef		(optional) This field is not mandatory but is recommended. If the client application has a unique reference number and it is sent then it will be stored in the PSInet transaction database and can be used for cross reference reporting. For eCash Transfer: the toMerchantId
FirstName		This field is the end customer name and is not required for PIN products but is required for some billpay products. The developer needs to know what products they will be offering in order to determine if they need to fill this field.
LastName		This field is the end customer name and is not required for PIN products but is required for some billpay products. The developer needs to know what products they will be offering in order to determine if they need to fill this field.
EntryMode		011 (Manual) 021 (Card swipe) 031 (Barcode scan) 041 (Online)

Example:

<Type>PinlessRequest</Type>

<TerminalId>Assigned</TerminalId>

<Password>Assigned</Password>

<ProdCode>GWCLRS</ProdCode>

</RequestXml>

5.1.2 Response Fields

NOTE: Some fields returned in the response can be viewed as optional by the Client, such as: MerchantId, Company, CompanyCity, CompanyPhone, TransDate & TransTime. This data can be ignored if the Client has similar data already. Settlement or reconciliation should be based on the unique PSInet transaction number and not these fields.

Field	Size	Description
StatusCode	1	0=Success (check AuthorizationCode) non 0=Failed. Do not send PinlessRequest2ndStep.
TransNo	13	PSInet generated unique transaction number.
AuthorizationCode	max 50	Authorization code for successful transaction. Important: If this field is blank in “PinlessRequest”, Client should proceed with sending “PinlessRequest2ndStep”. If this field is not blank and StatusCode=0, consider transaction success, print receipt, do not send “PinlessRequest2ndStep”. This field may be blank in “PinlessRequest2ndStep” (consider success).
AdditionalInfo	xml node	Additional information per service provider. Product file uses <PSFP=m,c,"n"> script command to output the values. For example, in response, <AdditionalInfo> <Item fs=”18”>Value</Item> …. </AdditionalInfo> On product file voucher layout, use script command <PSFP=1,N,”18”>
TransDate	10	Local date of the transaction in format: yyyy-mm-dd
TransTime	8	Local time of the transaction in format: hh:mm:ss

Example:

<StatusDescription>Approved Transaction</StatusDescription>

</StatusDesc>

<USN>TestVoucherUsn</USN>

<ReferenceNo>TestVoucherBranchUsn</ReferenceNo>

<Item fs="30">TestVoucherBonus</Item>

<Item fs="31">TestVoucherBonusInPoints</Item>

<Item fs="33">TestVoucherValidatePeriod</Item>

<Item fs="34">TestVoucherCost</Item>

<Item fs="35">TestVoucherUsn</Item>

<Item fs="36">TestVoucherBranchUsn</Item>

<Item fs="37">TestVoucherValueMessage</Item>

<Item fs="39">TestVoucherGeneralMessage</Item>

</AdditionalInfo>

<MerchantId>WenchengTesting</MerchantId>

<Company>Company has a very long name here</Company>

<CompanyCity>Toronto</CompanyCity>

<CompanyDbaName>TestDBA</CompanyDbaName>

<NSM />

</ResponseXml>

5.2 PinlessRequest2ndStep

The PinlessRequest2ndStep function type is used to confirm the activation. Client should only send PinlessRequest2ndStep after receiving <StatusCode>0</StatusCode> and <AuthorizationCode> is blank in PinlessRequest response.

Note: If the client application does not receive a response for PinlessRequest2ndStep, then the client should consider the transaction as processed and must keep retrying the second step until a response is received from server.

5.2.1 RequestXml Fields

Field	Size	Description
Type		“PinlessRequest2ndStep”
Same fields as in PinlessRequest packet

Example:

<Type>PinlessRequest2ndStep</Type>

<TerminalId>Assigned</TerminalId>

<Password>Assigned</Password>

<ProdCode>GWCLRS</ProdCode>

</RequestXml>

5.2.2 Response Fields

Same response data as described in 5.1.2 Response Fields.

Example:

<StatusDescription>Approved Transaction</StatusDescription>

<USN>TestVoucherUsn</USN>

<ReferenceNo>TestVoucherBranchUsn</ReferenceNo>

<Item fs="30">TestVoucherBonus</Item>

<Item fs="31">TestVoucherBonusInPoints</Item>

<Item fs="33">TestVoucherValidatePeriod</Item>

<Item fs="34">TestVoucherCost</Item>

<Item fs="35">TestVoucherUsn</Item>

<Item fs="36">TestVoucherBranchUsn</Item>

<Item fs="37">TestVoucherValueMessage</Item>

<Item fs="39">TestVoucherGeneralMessage</Item>

</AdditionalInfo>

<MerchantId>WenchengTesting</MerchantId>

<Company>Company has a very long name here</Company>

<CompanyCity>Sao Paulo</CompanyCity>

<CompanyDbaName>TestDBA</CompanyDbaName>

<NSM />

</ResponseXml>

5.3 eCash Transfer

This function allows terminal transfer eCash balance from its merchant to another merchant.

5.3.1 RequestXml Fields

Field	Size	Description
Type		“PinlessRequest”
ReceiptNo	5	Receipt number from Station. If the actual receipt number contains more than five characters, the last 5 characters (from the right) are recorded in the e-Fresh table.
RefNo	20	A unique number identifying the transaction request.
Amount	max 10.2	The dollar value to be transferred.
ClerkId	max 10	(optional) ID of the clerk who sold the product.

ProdCode	6	Fixed “EFRDEP” for eCash Transfer
TerminalParameter		(optional) For RedemPin: Pin number
TransRef		The merchant id of merchant will receive eCash. For eCash Transfer: the toMerchantId

5.3.2 Response Fields

Field	Size	Description
TransNo	13	PSInet generated unique transaction number.
AuthorizationCode	max 50	Authorization code for successful transaction. Important: If this field is blank in “PinlessRequest”, Client should proceed with sending “PinlessRequest2ndStep”. This field may be blank in “PinlessRequest2ndStep”.

TransDate	10	Local date of the transaction in format: yyyy-mm-dd
TransTime	8	Local time of the transaction in format: hh:mm:ss

5.4 Reversal

The typical scenarios for reversals happen when terminal cannot receive the transaction response or when the end user requests a product, it is printed at the terminal but for some reason the end user refuses to accept the PIN.

Client can also use this function to reverse a Pinless transaction if it is supported by the product provider.

Each PSInet operator has implemented specific procedures for returning and refunding the eVouchers. These procedures typically involve:

Merchant contacts the call center to request refund
Customer support validates the transaction information
PSInet operator makes the PIN available for resale at the server
PSInet operator refunds the merchant.

The API functionality provides automated PIN return and refund. It must be enabled by the PSInet administrator for your account by adding a special product code to your configuration.

The message type is PinlessRequest which is a flexible packet to allow specifying the original transaction number for the PIN purchase. The method is to send the TransNo that requires reversal and then the PIN transaction will be reversed and the merchant will be refunded.

5.4.1 RequestXml Fields

Field	Size	Description
Type		“PinlessRequest” (note this refers to the message type and is used for all reversals including PIN reversals.
ReceiptNo	5	Receipt number from Station. If the actual receipt number contains more than five characters, the last 5 characters (from the right) are recorded in the e-Fresh table. (Optional)
RefNo	20	A unique number identifying the transaction request.
CardData	max 255	This is the original TransNo of the transaction that needs reversal. Or the original OrderNo of the Order that needs reversal. In the event of a timeout where you don’t know the TransNo or OrderNo, you should issue a Query of the transaction using the RefNo of the original transaction request or RequestNo of the original Order request. This will return the TransNo or OrderNo and the transaction result so you can determine if you need to do the reversal.
Amount	max 10.2	Fixed “0”.
ProdCode	6	6 character code used to identify a pin return Code is in the product file. Typically RETURN is used. .

Example:

To reverse the original transaction number 0070000200641:

<Type>PinlessRequest</Type>

<TerminalId>Assigned</TerminalId>

<Password>Assigned</Password>

<ProdCode>RETURN</ProdCode>

</RequestXml>

5.4.2 Response Fields

Field	Size	Description
TransNo	13	PSInet generated unique transaction number.
AuthorizationCode	max 50	Authorization code for successful transaction.
TransDate	10	Local date of the transaction in format: yyyy-mm-dd
TransTime	8	Local time of the transaction in format: hh:mm:ss

Example:

<StatusDescription>Successful refund</StatusDescription>

<AuthorizationCode>testing8946</AuthorizationCode>

<MerchantId>WenchengTesting</MerchantId>

<Company>Company has a very long name here</Company>

<CompanyCity>Toronto</CompanyCity>

<CompanyDbaName>PaymentSource</CompanyDbaName>

<NSM />

</ResponseXml>

6 GetBalanceSt

The GetBalanceSt function type retrieves the current eCash Balance for the merchant associated with the specified Terminal ID.

This function type is not necessary if your billing is not prepaid eCash. It can also be used as a 'heartbeat' message to test host system availability.

RequestXml Fields

Field	Size	Description
Type	Fixed	“GetBalanceSt”

Response Fields

Field	Size	Description
Balance	max 10.2	Current eCash Balance for the merchant associated with the specified Terminal ID
MerchantID	max 20	Merchant ID in PSInet system
Company	max 256	Merchant’s company name
CompanyCity	max 256	Merchant’s city
CompanyPhone	max 256	Merchant’s phone number

7 File Download (Product, Invoice)

This function type provides download for current product file. Which contains product list and voucher layouts for the terminal group.

RequestXml Fields

Field	Size	Description
Type	Fixed	“FileDownload”
FileType	Fixed	“FileCode” + [ “,” + “Format” ] FileCode = 0 is a proprietary hexadecimal binary format product file and not recommended for Integrators. FileCode = 1 will download latest product file in xml format. FileCode = 2 Download Current Invoice FileCode = 3 Download Dated Invoice FileCode = 4 Download Promo File FileCode = 5 Download New Invoices FileCode = 6 Download Last 2nd Downloaded Invoice FileCode = 7 Download Last 3rd Downloaded Invoice FileCode = 8 Download Last Downloaded Invoice FileCode = 9 Order PIN file FileCode = 10 BH eGift Configuration File in hexadecimal encoded xls format FileCode = sd Download Software Format = 0 PSInet Mobile specific invoice format Format = 1 Special invoice format (see response)
OrderNo		when FileCode=9,to download PIN file.

Response Fields

Field	Size	Description
FileData	Variable	Product File: When FileCode = 0, this field contains product file in binary format. When FileCode = 1, this is latest product file in xml format. See Product File Tags description below. Invoice File: When FileCode is invoice download (codes 2,3,5,6,7,8), this contains formatted invoice text. Data in CDATA section starts with "<![CDATA[" and ends with "]]>" Format 0: Amount - rr.total+rr.bankfees Text layout: Invoice: Invoice# Due Date: yyyy/MM/dd Amount: amount Numeric Code: Boleto code Format 1: PRODU - Product Name (first 5 characters) VALOR - RevAmount+NRevAmount LIQUI - Merchant Cos (commission) Text layout: PRODU VALOR LIQUI Claro 12,00 11,64 Vivo 12,00 11,64 Level 12,00 11,64 TOTAL GERAL VALOR LIQUI 36,00 34,92
ReportMenu	Variable	Terminal menu list for Server Based Reports
BoletoString	Variable	Full Boleto string including “~”s. Wrap in CDATA.

Product File Tags

Tag	Description
GroupNumber	GroupNumber=806 ProductVersion=0037 If either of these changed then it is a new prodfile.
ProductVersion	GroupNumber=806 ProductVersion=0037 If either of these changed then it is a new prodfile.
Category Name="Wireless A-M" Products="7"	Products can be organized in categories. You can categorize them in your interface or present them as a simple list.
Product Name="Access Wireless" ProductCode="ACSWUE" AmountLimit="0" StoreGUI="EP" Amounts="3" Category="Wireless A-M" Description	StoreGUI=EP so this is a sample PIN based product with 3 amounts.
<Amount Value="10" Display="$ 10.00" UpcNumber="628478000164" />	A product can have up to 7 face value amounts with an optional display string to show in the user interface. It may also include the UPC code.
Product Name="Boost PayGo RTR" ProductCode="BSTRUE" AmountLimit="99.99" StoreGUI="TV"	StoreGUI=TV so this is a sample RTR topup product. Amount limit is only used for variable amount products and it is the upper limit. Don’t allow the user to enter an amount higher than the limit.
Product Name="T-Mobile RTR" ProductCode="TMBRUE" AmountLimit="100" StoreGUI="TF" Amounts="4" Category="Wireless N-Z"	StoreGUI=TF so this is a sample RTR topup product with fixed amounts. The user will select from a list of amounts to load.
<Voucher Lines="87"> {UPC1="831096007044"}\|{UPC2="831096007051"}\|{c}{UPCG}\|{c}{UPCN}\|{c}{d}{SERV}\|{c}{d}{AMNT}\|\|\|\|{PPRT}\|{c}{BMAP=1}\|{c}{d}{SERV}\|{c}{d}{AMNT}\|\|{c}Este es su NIP/\|{c} This is your PIN:\|\|{d}{c}{PNUM}\|{c}{CST1}\|{c}{CST2}\|Para hacer su llamada:\|1. Marque 1-800-679-5130\|2. Marque su NIP\|3. Marque codigo del area + \|numero telefonico, para \|llamadas internacionales \|marque 011 + codigo del \|pais + codigo de la cuidad + \|numero telefonica\|\|Para hacer otra llamada \|presione # por 2 sequndos. \|Si se equivoco, presione * \|para corregir. Para llamadas \|por cobrar con tarifas reducida,\|marque 1-877-777-0797 desde \|cualquier telefono.\|\|Tarifas y otros cargos estan\|sujetos a cambio sin previo \|aviso. Cargo por mantenimiento\|puede aplicar. Esta tarjeta \|expira 180 dias despues del \|ultimo uso. No habra cambios \|o reembolsos.\|\|Servicio al cliente:\|1-800-483-1169\|\|--------------------------------\|\|To Place a Call:\|1. Dial access number\| 1-800-679-5130\|2. Enter the above PIN\|3. Dial Area Code + Telephone \|Number or for International \|calls dial 011 + Country Code +\|City Code + Telephone number.\|\|To place another call, press # \|for 2 seconds. If you make a \|mistake, press * to reset. For \|a collect call at a discounted \|rate,dial 1-877-777-0797 from \|any phone. \|\|Rates and surcharges are subject\|to change without notice. \|Maintenance fee may apply. This\|voucher expires 180 days from \|last use. No refund or exchange.\|\|Customer Service:\|1-800-483-1169\|{c}{d}{REPT}\|Trans: {TNUM}\|Serial: {PSER}\|Batch: {PBCH}\|Date: {Date=10} Time: {Time}\|Term: {SSER}\|Rec. #: {RECP=8} Clerk: {CLID}\|Expiry: {PEXP=10}\|\|{BMAP=2}\|{c}{UPCG}\|{c}{UPCN}\|</Voucher>	Script commands are included that can be used for layout of the printed voucher where \| is the line feed. Link to Script Commands Documentation
<Picture>	Contains base64 encoded data of the bmp file in its preceding BMAP tag. e.g. <BMAP index="1">\\efreshshare\s\Graphics\nowprepay2002printer.bmp</BMAP> <Picture> ... base64 encoded data of nowprepay2002printer.bmp … </Picture>

Download Sample XML Product File

8 Order

This function type is not supported for 3rd party integration. It is only included for complete documentation purposes. The reader does not need to understand or implement this.

8.1 Request PIN File in Binary Format

8.1.1 Order Request

Field	Size	Description
Type		“Order”
RequestNo	max 20	Client’s unique order number.
PRODUCTSTRING	max 2048	See below

ProductString

FDOMAT

ETSWSL

</PRODUCTSTRING>

FIELDNAME	SIZE	DESCRIPTION
<VERSION>	5	Version of the message packet, current is 1.0
<CONFIRM>	10	CONFIRM is an optional field to store the client’s unique order number. If the client sends it, terminal will send the same number during download.
<ALLOWPARTIAL>	5	If true, will allow partial pinstock returns when insufficient stock is available on the PSInet server. True-allow partial,False-not allow partial. This allows the client to control whether they will accept partial orders.
<P>		Tag to start the list of products for this order.
<P>	6	6 character code identifying each store’s unique products. The list of available products will be provided by the PSInet System Administrator.
<A>	8,2	Product value reference, part of the product list provided by the PSInet System Administrator.
<Q>	5	Quantity requested.

8.1.2 Order Response

Field	Size	Description
OrderNo	13	EC generates unique transaction number when EC successfully created Order PIN File.

8.1.3 Order Download Request

The Order Download Request function is used in applications where an order download was previously sent. The client application sends Order Download Request and then downloads the pins.

Field	Size	Description
Type	fixed	“FileDownload”
FileType	fixed	“9”
OrderNo	13	The OrderNo received in Order Response.
Confirm	13	Optional. If sent, this must match Order Request.
StartBlock	int	The block number to resume file download. 0 is the first block.

8.1.4 Order Download Response

Field

Size

Description

FileData

Variable

Binary PIN file data in HEX string format.

https://docs.google.com/spreadsheets/d/1qrw4o5gTahPH5MWfGsH-21FDcDvIPMY1JB35bS9wNQU/edit#gid=403449895

8.2 Request Comma-Separated PIN File

8.2.1 Order Request

Field	Size	Description
Type		“Order”
RequestNo		Client’s unique order number.
PRODUCTSTRING	max 2048	See below example
VERSION	fixed	4.0
CONFIRM	10	CONFIRM is an optional field to store the client’s unique order number. If the client sends it, terminal will send the same number during download.
ALLOWPARTIAL	5	If true, will allow partial pinstock returns when insufficient stock is available on the PSInet server. True-allow partial,False-not allow partial. This allows the client to control whether they will accept partial orders.
<P>		Tag to start the list of products for this order.
<P>	6	6 character code identifying each store’s unique products. The list of available products will be provided by the PSInet System Administrator.
<A>	8,2	Product value reference, part of the product list provided by the PSInet
<Q>	5	Quantity requested.

ProductString

FDOMAT

ETSWSL

</PRODUCTSTRING>

8.2.2 Order Response

Field	Size	Description
OrderNo	13	EC generates unique transaction number when EC successfully created Order PIN File.

8.2.3 Order Download Request

The Order Download Request function is used in applications where an order download was previously sent. The client application sends Order Download Request and then downloads the pins.

Field	Size	Description
Type	fixed	“FileDownload”
FileType	fixed	“9,1”
OrderNo	13	The OrderNo received in Order Response.
Confirm	13	Optional. If sent, this must match Order Request.

8.2.4 Order Download Response

Field	Size	Description
StatusCode	max. 5	0 = success, 1 = fail
StatusDescription	max. 255	Contains an explanation of the Status Code.
OrderNo	13	The OrderNo received in Order Response.
FileData	Variable	HTML encoded Pin file data: <Product ProdCode=”ProdCode” Amount=”Amount”> <![CDATA[ PinBatch,PinSerial,FaceValue,PinNumber,PinExpiry,Custom1,Custom2,TransNo … ]]> </Product> ... ProdCode = requested product code Amount = requested product amount PinBatch = pinstock.pinbatch PinSerial = pinstock.pinserial FaceValue = pinstock.amount PinNumber = pinstock.pin in plain text PinExpiry = pinstock.expiry in yyyy-MM-dd Custom1 = pinstock.custom1 Custom2 = pinstock.custom2 TransNo = pinstock.transno See in below example.

Order Download Response example:

<StatusDescription>4110~Proceed to download.</StatusDescription>

<MerchantId>WenchengTesting</MerchantId>

<Company>There is a very long name here</Company>

<NSM />

</ResponseXml>

9 ChangeStPass

This function is used to change a client terminal password

Request Fields

Field

Size

Description

NewPassword

Min 4

Max 20

Password should be all numeric.

Response Fields

Field	Size	Description
StatusCode	1	0=success, 1=fail
StatusDescription	Varies	A message describes the StatusCode

10 GetLastTrans

The GetLastTrans function is used to retrieve last transaction information.

Request Fields

Field	Type	Size	Description
Type	string	fixed	“GetLastTrans”

a) Function Response for last Voucher

Field	Size	Description
ProductCode	1	Product code
Amount	Varies	Pin amount
PinData/Pin	31	The secret code of the Product to be given to the customer.
PinData/Custom1	80	Can contain information that should be delivered to the customer with the product. Most PIN products do not have data in this field.
PinData/Custom2	33	Can contain information that should be delivered to the customer with the product. Most PIN products do not have data in this field.
PinData/PinSerial	80	Serial number of the pin
PinData/PinBatch	15	Batch number of the pin (optional)
PinData/ExpiryDate	10	Expiry date of the pin format yyyy/mm/dd (optional)
PinData/DateSold		Transaction's date and time
PinData/ResponseMessage	50	Response message EC sends to terminal
</PinData>		block ends

b) Function response for last Order transaction

Field	Size	Description
OrderNo	13	EC generates unique transaction number when EC successfully created Order PIN File.
RequestNo	20	Refer to 8.2 Order Response
TotalOrderQuantity	6	Sum of the number of pins

c) Function response for last pinless transaction

Field	Size	Description
ProductCode	13	Product code
Amount	(8,2)	Amount
PSInetStatus	1	The status of the transaction
SptransStatus	1	Status of tranaction in Sptrans
ResponseMessage	50	Response message EC sends to terminal

11 eCashCollection

The eCash Collection Request version 1.0 can be used to report the money collected from a merchant.

Request Fields

Field	Type	Size	Description
Type	string	fixed	“ecashcollection”
ReferenceNo	string	1..20	A reference number sent from terminal. EWS stores this number in CashTable.Reference field.
TerminalId	string	1..20	The POS reporting the collection.
Password	string	1..50	The password assigned to terminal supplied by PSInet System Administrator
Amount	decimal	8.2	Transferring amount.
Description	string	1..80	PSInet Mobile will send this description: Cash collection from merchant: 1234567, TerminalID: TA123423543, or Cheque collection from merchant: 1234567, TerminalID: TA123423543, Tid: is the terminal ID assigned to the PSInet Mobile client. by merchant: is the cash collector merchant ID, the person operating the phone. Oracle Cashtable table has a MerchantId field. EWS will stuff it with the "by merchant". That is the merchant ID that collected the payment.
ClerkId	string	1..13	The clerk id.
SourceMerchantId	string	1..20	The MerchantID of the merchant giving the money. The eCash balance will not be affected since Collection is a reporting feature.

Response Fields

Field	Type	Size	Description
StatusCode	int	1	0=success, 1=fail
StatusDescription	string	1..255	A message describes the StatusCode

IMPORTANT: When writing the status in CashTable for the Collection transaction set STATUS=L.

The amount collected is set in the amount field.

No commissions can be calculated because there will be no PSInet record for this Cashtable collection records.

12 Query

The Query function is used to retrieve the status of a transaction request.

Request Fields

Field	Type	Size	Description
Type	string	fixed	“Query”
OriginalRefNo	string	20	RefNo in original request packet. (Only applicable for PIN and Pinless transactions)
OriginalRequestNo	string	20	RequestNo in original Order request. (Only applicable for Order transactions)
OriginalReceiptNo (Deprecated)	string	5	ReceiptNo in original request packet
OriginalDateTime (Deprecated)	string	19	Date and time of the original transaction request. in format: yyyy-MM-dd HH:mm:ss

Response Fields

a) Function Response for Voucher

Field	Size	Description
ProductCode	1	Product code
Amount	Varies	Pin amount
TransNo	13	Original PSInet transaction number.
PinData/Pin	31	The secret code of the Product to be given to the customer.
PinData/Custom1	80	Can contain information that should be delivered to the customer with the product. Most PIN products do not have data in this field.
PinData/Custom2	33	Can contain information that should be delivered to the customer with the product. Most PIN products do not have data in this field.
PinData/PinSerial	80	Serial number of the pin
PinData/PinBatch	15	Batch number of the pin (optional)
PinData/ExpiryDate	10	Expiry date of the pin format yyyy/mm/dd (optional)
PinData/DateSold		Transaction's date and time
PinData/ResponseMessage	50	Response message EC sends to terminal
</PinData>		block ends

b) Function response for Order transaction

Field	Size	Description
OrderNo	13	EC generates unique transaction number when EC successfully created Order PIN File.
RequestNo	20	Refer to 8.2 Order Response
TotalOrderQuantity	6	Sum of the number of pins

c) Function response for pinless transaction

Field	Size	Description
ProductCode	13	Product code
Amount	(8,2)	Amount
TransNo	13	Original PSInet transaction number
PSInetStatus	1	The status of the transaction
SptransStatus	1	Status of transaction in Sptrans
ResponseMessage	50	Response message EC sends to terminal

13 Version

This function returns the version of PSIcomm.

Request Fields

Field	Type	Size	Description
Type	string	fixed	“Version”

Response Fields

Field	Type	Size	Description
Version	string		PSIcomm version

14 Cash Passport (Access Prepaid)

This section is moved into pComm Internal SDK section 20:

https://docs.google.com/document/d/1DgPg0CXwzxzVi6jXxrqJyZI0EtTh0q0uLyLT2TrTs7s/edit#heading=h.fwv98fqli3g0

15 CP Visa (FIS)

This section is moved into pComm Internal SDK section 21:

https://docs.google.com/document/d/1DgPg0CXwzxzVi6jXxrqJyZI0EtTh0q0uLyLT2TrTs7s/edit#heading=h.616arky95jno

14 Test Server

The test server allows maximum 250 simultaneous transactions.

You can use the following information for development and testing:

SOAP APIs: https://api.paymentsource.co:444/EcSoap

EMSWeb is an optional online tool to check transaction reports:

https://paymentsource.co/eMSWeb/RC

http://paysrc.ca/pcapi