PAYWISER MINIPOS INTEGRATION GUIDE

Transcription

1 PAYWISER MINIPOS INTEGRATION GUIDE TECHNICAL DOCUMENTATION Developed by: CEBASEK Denmark s.r.o. CVR-nr: Industriområdet Hovedgård Denmark Slovenian sales and developlent partner: OMNIPOS d.o.o. Štajerska ulica Slovenske Konjice INTECH d.o.o. Vrhovčeva Ljubljana ČEBAŠEK d.o.o. Polje pri Vodicah 30b 1217 Vodice Powered by: *All brands listed are a property of their respective owners P a g e 1 15

2 DOCUMENT STATUS Reference: PAYWISER MiniPOS 2015 Status: Active Version: 1.3 Version date: Confidentiality level: For internal use and partners Previous editions: Edition Validity start date Documentation creation Addendum added parameters to PWPaymentRequest and PWPaymentResponse Addendum added PWVoidRequest Added new reponse status Printer offline. Added important note to chapter 3 and It it a sole responsibility of the user to check this version for the latest update P a g e 2 15

3 TABLE OF CONTENT 1. General remarks Importing integration library into your own project Handling PayWiser MiniPOS login and credentials Integration library objects and structures PWPaymentRequest PWPaymentCredentials PWPaymentResponse PWMonetaCheck PWVoidRequest PWMiniPosIntegration PWPaymentType PWPaymentStatusCode Using integration library Recieve payment Void payment Integration usage cases You do not wish to handle any PayWiser MiniPOS credentials data You wish to handle PayWiser MiniPOS credentials data yourself Payment with credit card Payment with Moneta Payment with any supported payment method Getting Moneta Token, customer can pay later Voiding payments Support...15 P a g e 3 15

4 1. General remarks PayWiser MiniPOS integration library provides you with a simple solution for integrating payments into your own Android application. PayWiser MiniPOS and PayWiser MiniPOS integration library require at least Android version Integration is done using intents, which facilitate proprietary PayWiser MiniPOS objects for passing/returning data. Integration library is implemented as AAR (Android Archive Library) and can be imported into your existing Android Studio or Eclipse projects. In the following sections, required parameters are bold, optional parameters are italic. Fully working sample/demo project with source code is provided. P a g e 4 15

5 2. Importing integration library into your own project Integration library can be easily imported into your existing Android Studio project using the following steps: 1. download/copy pwminipos.integration.aar to your computer 2. open Android Studio and load your existing project 3. click File->New->New module 4. select Import.JAR/.AAR Package 5. browse pwminipos.integration.aar location and select it 6. click»finish«7. open build.gradle for your application and add the following line into dependencies section compile project(':pwminipos.integration') 8. sync project Integration library is now added to your existing project as a module and is ready to use. If you're using Eclipse, please refer to Eclipse documentation for instructions. P a g e 5 15

6 3. Handling PayWiser MiniPOS login and credentials Normally PayWiser MiniPOS requires setup to be fully completed before using it to process payments. Setup consists of entering the following data: PayWiser MiniPOS API key Selecting card reader type pairing bluetooth reader Furthermore, PayWiser MiniPOS requires user to be logged-in to process payments (using username and password). With integration library, there are two ways of handling user login: 1. Company and user login is handled entirely in the PayWiser MiniPOS application itself, your application does not handle any PayWiser MiniPOS credentials 2. Company and user login is handled through integration library from your application, PayWiser MiniPOS setup must only be made for selecting credit card reader and pairing Detailed explanation of each option: 1. Full PayWiser MiniPOS setup is completed: a. company API key is entered b. card reader type is selected and the reader is paired c. username and password is entered (»Remember password«is checked at the login screen) d.»login«button is clicked User is now logged in and PayWiser MiniPOS will use stored credentials for all further usage, including integration library calls. PayWiser MiniPOS can be normally used separately from your application. 2. Partial PayWiser MiniPOS setup is made: a. card reader type is selected and the reader is paired No company and user credentials are stored within paywiser MiniPOS. PayWiser MiniPOS cannot be used as a stand-alone application, with every integration library call PWPaymentCredentials object must be specified (containing company API key and username and password). IMPORTANT NOTE: Partial setup is not always allowed! This currently applies to card payment through PayPlaza, where full PayWiser MiniPOS setup is required. P a g e 6 15

7 4. Integration library objects and structures 1. PWPaymentRequest Main object for instantiating payment request with the PayWiser MiniPOS. Every PWPaymentRequest results with PWPaymentResponse. Member name Type Description Credentials PWPaymentCredentials Must be specified if only partial MiniPOS setup was made. If specified, it always overrides MiniPOS setup and its stored credentials. ReferenceID string Your own unique reference ID PaymentType integer See PWPaymentType for list of possible values. If not specified, PayWiser MiniPOS presents user with a list of possible payment types, depending on PayWiser MiniPOS account setup. Amount integer Amount in minor units of given currency (e.g. cents if in Euro) Currency string ISO letter currency code Description string Payment description MonetaJustReturnToken boolean Valid only when Moneta payment is selected (either with PaymentType or from PayWiser MiniPOS payment type, if applicable) Initiates Moneta payment and immediately returns token. CardStartReader boolean Valid only when Card payment is selected (either with PaymentType or from PayWiser MiniPOS payment type, if applicable). Card reader is connected immediately. 2. PWPaymentCredentials Object containing company and user credentials for PayWiser MiniPOS login. Must be specified if only partial PayWiser MiniPOS setup was made. Can be specified even if full PayWiser MiniPOS setup was made. If specified, it always overrides PayWiser MiniPOS setup and its stored credentials. Member name Type Description ApiKey string Valid PayWiser MiniPOS api key Username string Valid PayWiser MiniPOS user name Password string Valid PayWiser MiniPOS user password P a g e 7 15

8 3. PWPaymentResponse Return object for PWPaymentRequest and PWMonetaCheck. Member name Type Description PaymentType integer See PWPaymentType for list of possible values. If not PaymentType was specified with PWPaymentRequest and user selects payment type within PayWiser MiniPOS app, selected payment type is returned. If PaymenType was specified with PWPaymentRequest, it is returned unchanged. Amount integer Amount in minor units of given currency (e.g. cents if in Euro) AdditionalAmount integer Amount in minor units of given currency (e.g. cents if in Euro) of any additional chargec that might have occured Currency string ISO letter currency code StatusCode integer See PWPaymentStatusCode for possible values. StatusDescription string Description of StatusCode. It may contain additional data (especially if StatusCode is -1 General error). ReferenceID string Payment description ReferenceID string Your own reference ID, as specified with PWPaymentRequest PWReferenceID string PayWiser reference ID of transaction BankReferenceID string Bank reference ID of transaction (only for credit card payments) MonetaReferenceID string Moneta reference ID (only for Moneta payments). Can be later on used with PWMonetaCheck MonetaToken string Moneta token (only for Moneta payments, if MonetaJustReturnToken was specified with PWPaymentRequest) CardNumber string Number of card used for payment (only for credit card payments) CardExpDate string Expiration date of card used for payment (only for credit card payments) CardType string Type of card used for payment (only for credit card payments) CardRegion string Region of card used for payment (only for credit card payments) CardCountryCode string Country code of card used for payment (only for credit card payments) TransactionDateTime string Timestamp of transaction 4. PWMonetaCheck Object for checking Moneta payment status, if MonetaJustReturnToken was selected with PWPaymentRequest (and Moneta payment way specified with PWPaymentRequest or selected in PayWiser MiniPOS app). Every PWMonetaCheck results with PWPaymentResponse. Member name Type Description Credentials PWPaymentCredentials Must be specified if only partial MiniPOS setup was made. If specified, it always overrides MiniPOS setup and its stored credentials. MonetaReferenceID string MonetaReferenceID from PWPaymentResponse P a g e 8 15

9 P a g e 9 15

10 5. PWVoidRequest Object for voiding already completed payments. Every PWVoidRequest results with PWPaymentResponse. Member name Type Description Credentials PWPaymentCredentials Must be specified if only partial MiniPOS setup was made. If specified, it always overrides MiniPOS setup and its stored credentials. PWReferenceID string PWReferenceID from PWPaymentResponse PaymentType int See PWPaymentType for list of possible values. 6. PWMiniPosIntegration Main class for calling PayWiser MiniPOS app. Each call results in PWPaymentResponse. Method name Parameters Description RequestPayment Activity activity PWPaymentRequest request int requestcode Instantiates PayWiser MiniPOS with PWPaymentRequest. Activity is your calling activity requestcode is your desired request code (later on used in your onactivityresult) can be ommitted CheckMoneta Activity activity PWMonetaCheck int requestcode Instantiates PayWiser MiniPOS with PWMonetaCheck. Activity is your calling activity requestcode is your desired request code (later on used in your onactivityresult) can be ommitted 7. PWPaymentType Class containing payment types. Name Value Description ANY 0 Payment type is not specified. PayWiser MiniPOS will present user with a list of possible payment types, depending on PayWiser MiniPOS account setup. CREDIT_CARD 1 Credit card. User cannot select any other payment type. MONETA 2 Moneta. User cannot select any other payment type. P a g e 10 15

11 8. PWPaymentStatusCode Class containing status codes for PWPaymentResponse. Status code -1 often contains useful information about error in StatusDescription. Request parameters Name Value Description PAYMENT_COMPLETED 3 Payment completed MONETA_NOT_CONFIRMED 2 Moneta payment not yet confirmed PAYMENT_CANCELED 1 Payment canceled OK 0 Ok GENERAL_ERROR -1 General error INVALID_DATA -2 Invalid data CREDENTIALS_MISSING -3 Credentials missing DEVICE_OFFLINE -4 Device is offline NOT_ALLOWED_CREDIT_CARD -5 Credit card payments not allowed NOT_ALLOWED_MONETA -6 Moneta payments not allowed INVALID_PARAMETERS -7 Invalid parameters, check documentation VOID_ERROR -8 Unable to void (possibly already voided or missing) NOT_ALLOWED_WIWA -9 wiwapay payments not allowed PRINTER_OFFLINE -10 Printer is offline (receipt of last payament must be printer before new payment can be made) P a g e 11 15

12 5. Using integration library Integrating PayWiser MiniPOS into you Android application is done in a few easy steps. 1. create new PWPaymentRequest object 2. call PWMiniPosIntegration 3. recieve PayWiser MiniPos PWPaymentResponse 1. Recieve payment Example call: PWPaymentRequest request = new PWPaymentRequest(); request.setreferenceid(referenceid); request.setpaymenttype(paymenttype); request.setamount(amount); request.setcurrency(currency); request.setdescription(description); request.setmonetajustreturntoken(monetajusttoken); if (!apikey.isempty() &&!username.isempty() &&!password.isempty()) { PWPaymentCredentials credentials = new PWPaymentCredentials(); credentials.setapikey(apikey); credentials.setusername(username); credentials.setpassword(password); request.setcredentials(credentials); } PWMiniPosIntegration.RequestPayment(MainActivity.this, request); Example recieve result: public void onactivityresult(int requestcode, int resultcode,intent data) { super.onactivityresult(requestcode, resultcode, data); } PWPaymentResponse response=pwminiposintegration.getresponse(data); if (response!=null) { response.getstatuscode(); response.getstatusdescription(); response.getpaymenttype(); response.getamount(); response.getcurrency(); response.getreferenceid(); response.getpwreferenceid(); response.getbankreferenceid(); response.getmonetareferenceid(); response.getmonetatoken(); response.gettransactiondatetime(); } Please see provided demo application for fully working example. 2. Void payment Example call: PWVoidRequest request = new PWVoidRequest(); request.setpwreferenceid(pwreferenceid); request.setpaymenttype(paymenttype); if (!apikey.isempty() &&!username.isempty() &&!password.isempty()) { PWPaymentCredentials credentials = new PWPaymentCredentials(); P a g e 12 15

13 } credentials.setapikey(apikey); credentials.setusername(username); credentials.setpassword(password); request.setcredentials(credentials); PWMiniPosIntegration.VoidPayment(MainActivity.this, request); Example recieve result: public void onactivityresult(int requestcode, int resultcode,intent data) { super.onactivityresult(requestcode, resultcode, data); } PWPaymentResponse response=pwminiposintegration.getresponse(data); if (response!=null) { response.getstatuscode(); response.getstatusdescription(); } Please see provided demo application for fully working example. P a g e 13 15

14 6. Integration usage cases 1. You do not wish to handle any PayWiser MiniPOS credentials data User must make full PayWiser MiniPOS setup and login with»remember password«checked at login screen. All payments from your own application will be made using the same PayWiser MiniPOS user. 2. You wish to handle PayWiser MiniPOS credentials data yourself Specify PWPaymentCredentials with PWPaymentRequest or PWMonetaCheck. Even if user made full PayWiser MiniPOS setup, all calls from your own application will be made using specified credentials. This way every payment from your own application can be made using different PayWiser MiniPOS user. IMPORTANT NOTE: This use case is not always allowed! This currently applies to card payment through PayPlaza, where full PayWiser MiniPOS setup is required. 3. Payment with credit card Specify PaymentType=PWPaymentType.CREDIT_CARD with PWPaymentRequest. User will not have the ability to change payment type within PayWiser MiniPOS. 4. Payment with Moneta Specify PaymentType=PWPaymentType.MONETA with PWPaymentRequest. User will not have the ability to change payment type within PayWiser MiniPOS. 5. Payment with any supported payment method Specify PaymentType=PWPaymentType.ANY (or even leave PaymentType blank) with PWPaymentRequest. PayWiser MiniPOS will present user with a list of possible payment types, depending on PayWiser MiniPOS account setup. Selected payment type will be returned in PaymentType with PWPaymentResponse. 6. Getting Moneta Token, customer can pay later Specify PaymentType=PWPaymentType.MONETA and MonetaJustReturnToken=true with PWPaymentRequest. PayWiser MiniPOS will return MonetaToken and MonetaReferenceID. You can check status of Moneta payment later using CheckMoneta. 7. Voiding payments Use PWVoidPayment. PayWiser MiniPOS will refund your customer and will return status code. P a g e 14 15

15 7. Support In case you need additional help or questions, please direct all your inqueries to your local implementation partner. Api documentation: International support: International sales: Technology and sales partners for Slovenia: INTECH d.o.o. Vrhovčeva Ljubljana ČEBAŠEK d.o.o. Polje pri Vodicah 30b 1217 Vodice P a g e 15 15