Positive Integration

👍

POSitiveLib provides an easy-to-use API interface to initiate card transactions, in a java library.

Positive is an Android Based Payment Application integrated to Hips Payment Gateway. You can integrate with positive in two ways to launch a payment request window.

1. Via API (weblink RESTi) start payments from another device (POS System) API Swagger Postman collection
2. Via App-to-App commands (IPC comms) start payment from another App in the terminal.

Demo app

Download a demo app here

A920 / IM30 3rd Party Integration

This guide provides the instructions for the POSitiveLauncher demo application required for 3rd party developers to write applications that integrate with POSitive on the Pax A920 / IM30 payment terminal.

Prerequisites

• A Pax A920 / IM30 payment terminal.
• A USB cable (USB-A to USB micro-B).
• The terminal must be installed with at least version of the POSitive payment application, ideally configured in demo mode to assist development.
• The terminal must be put into debug mode using the Pax Engine (ask Hips for access)

POSitive Launcher–Sample Application

• Unzip and import the POSitiveLauncher package into Android Studio.
• The application provides a very simple program that will allow you to see how a transaction and a reversal should be performed. Test buttons are provided on the main activity (see MainActivity.java)
• Comments have been added in the code to explain how it works, but it should be quite self-explanatory
• The code relies on a library that is included called POSitivelib-X.X- release.aar. Look at the manifest and the build.gradle files to see how it is integrated.
• The IPC comms rely on a BroadcastReceiver being used to send/receive the messages. Look at the manifest to see how this should be declared. The example implementation is in TestLaunchReceiver.java
• It is the responsibility of the calling app to return itself to the foreground once the transaction is completed (The sample app also does this in the POSitiveLauncReceiver by calling startActivity() once the result has been received)

📘

In Summary: you should be able to declare a receiver and use the included library to do IPC comms to and from the POSitive app (Using this app as a working example)

Terminal Profile

There is a config file on the terminal called profile.json. This file determines which
apps are on display from the main menu. This file is delivered to the terminal through the resource packages.

The app being developed must be added to the resource package for each customer.

{
"displayName": "POSitive Demo", "packageName": "com.eft.positivelauncher"
}

Please provide this information to Hips and ask for an updated resource package to be sent to the development terminal.

Integration Rules

1. The apps must not bring down the network stack. Both the payment application and the paxstore app require internet connectivity to upload transactions in the background.

2. New applications must not install themselves as a launcher process

Transaction Initiation

To initiate a transaction, call the API functions on the PosIntegrate class. The
methods take additional configuration, passed in as a HashMap to the function.

The HashMap is populated with additional values identified by the enum CONFIG_TYPE on PosIntegrate.java

Declarations:

PositiveError executeTransaction(Context context, TRANSACTION_TYPE transType, HashMap<CONFIG_TYPE, String> args)

PositiveError executeReversal(Context context, HashMap<CONFIG_TYPE, String> args)

Example:

This will add an amount to the hashmap of 100 (minor units):

HashMap<CONFIG_TYPE, String> args = new HashMap<CONFIG_TYPE, String>(); args.put(CT_AMOUNT, "100");

PosIntegrate . executeTransaction (this, TRANSACTION_TYPE_SALE, args);

PosIntegrate . executeTransaction (this, 100, TRANSACTION_TYPE_REFUND, args);

PosIntegrate .executeReversal(this, args);

PosIntegrate . executeTransaction (this, TRANSACTION_TYPE_SALE, args);

PosIntegrate.queryTransaction(this.args);

Reverse transactions based on their UTI, or just reverse the last transaction by passing in a receipt number of 0.

Pass additional arguments to disable printing, and keep the reversal silent (in the background)

Cancel Transaction takes CT_CANCELLED_TIMEOUT as part of argument to cancel the transaction after the entered time.

Purchase With Cashback: The sale transaction will offer cashback where the terminals configuration indicates that cashback is supported for the card type presented. If you want to enable\disable this feature use paxstore to update your terminals settings. You can also pass in a cashback or gratuity amount and the app will use it if allowed by the card.

Transaction Results

Different results can come back from the POSitive app based on the transaction
result.

The following method is used to unpack the results into an object.

PositiveTransResult unpackResult(Context context, Intent intent)

The results on the object are split into four separate lists, with a flag that can be
checked on the object to indicate if the list is present.

Examples:

• For a successful CTLS (contactless) transaction, lists 1-3 would be returned.
• For a successful MSR (magnet swipe) transaction, lists 1 and 2 would be returned.
• For a critical failure resulting from a crash or a programming error then list 4 would be returned.
• List One is returned when the transResponse boolean = true
• List Two is returned when the transDetails boolean = true
• List Three is returned when the cardType String = “EMV” or “CTLS”
• List Four is returned when there is a serious failure and transResponse = false;

The broadcast receiver has code to demonstrate extracting the results for the calling app to use.

List One - Standard Response Details (transResponse = true)

List Two (transDetails = true)

List Three - EMV Details

List Four – Error Details

Transaction Reports

To initiate a report, call the following API function on the PosIntegrate class.
The HashMap is populated with the report type

PositiveError executeReport(Context context, TRANSACTION_TYPE transType, HashMap<CONFIG_TYPE, String> args)

PositiveError unpackReport(Context context, Intent intent)

HashMap<CONFIG_TYPE, String> args = new HashMap<CONFIG_TYPE, String>(); args.put(CT_XREPORT, "TRUE");

PosIntegrate.executeReport(this, TRANSACTION_TYPE_RECONCILIATION, args);

PosIntegrate . executeReport (this, args);

PosIntegrate . unpackReport (content, intent);

📘

The report should be printed by the terminal and the results returned to the broadcast receiver. The unpackreport method can be used to extract the results into an object.

Status Events

There are different status events declared in POSitive app.

Different events can come back from the POSitive app based on the transaction events.

Filter TRANSACTION_STATUS_EVENT in onReceive() of the PositiveLaunchReceiver and receive the status events using below code:

String statusEvent = intent.getStringExtra("StatusEvent");

List of Status events:

1. Transaction started
2. Transaction Approved
3. Transaction Declined
4. Card type = MSR
5. Card type = EMV
6. Card type = CTLS
7. Card type = manual
8. Transaction Cancelled
9. Transaction Referred
10. Transaction Finished
11. GetCard Screen Displayed
12. Manual Pan Screen Displayed
13. Pin Requested(Offline)
14. Pin Requested(Online)
15. Host Approved
16. Reversal Approved
17. Reversal Declined
18. Transaction Declined
19. Card User Cancelled
20. Printer General Error
21. Printer Out Of Paper
22. Amount High
23. Amount Low
24. Card Blocked
25. Card Expired
26. Pin Invalid Retry
27. Pin Invalid Last Try
28. Cashback Too High
29. Pin Cvm Required
30. Signature Cvm Required
31. Locally Declined
32. Host Declined
33. Issuer Declined
34. Issuer Unavailable
35. Update In Progress Error
36. Update Required Error
37. Reversal Not Possible Error
38. Transaction Type Not Allowed
39. Login Failed
40. Chip Unreadable
41. Chip App Unsupported Please Swipe
42. Chip Rid Unsupported Please Swipe
43. Chip Invalid Please Swipe
44. Chip not allowed Please swipe
45. Chip detected Please Insert
46. Chip detected Please Insert OR Force Fallback
47. Insert Or Swipe Card
48. Magnetic Strip Unreadable
49. Magnetic Stripe Invalid
50. Magnetic Stripe Not Allowed
51. Manual Input Invalid
52. Manual Input Invalid Length
53. Manual Input Invalid Date
54. Cashback Only Allowed Online
55. Transaction Only Allowed Online
56. Approval Code Invalid
57. Password Invalid
58. Close Batch Required
59. Close Batch Not Required
60. Technical Error
61. Hardware Error

After getting results back from the POSitive app , there are options to view transaction results and status events.