In-App Payment Library

For use with Ogone payment backend services

Android version

Developer's Manual

Revisions
Version

Date

Author

Comment

Library
version

1.0

19.06.2012

Initial revision

1.0

1.1

21.06.2012

Minor Changes

1.0

1.2

27.06.2012

Minor Changes

1.0

1.3

20.07.2012

Minor Changes

1.0

1.4

15.01.2012

Andreas
Stehl
Andreas
Stehl
Andreas
Stehl
Daniel
Spitzer
Andreas
Stehl

New features / changes:

Saved payment data can be modified in recurring payments. (see Chapter 3.3.3)
Only one single alias will be generated/used
for recurring payments. (see Chapter 3.3.3 ff.)
Paymethod PostFinance integrated.
Payment details view:
Changed text pay button for german localization.

1.0.21

1.5

17.04.2013

Dieter
Wurm

Bugfixes:
Payment details view:
Fix line wrapping label text of save paydata
checkbox.
Fix problem with editability of input elements in
HTML forms of web based 3D secure workflow under Android 4.x.
Changes:

1.0.19-

rename activity
com.op.android.activities.OP3DSecureA
ctivity to
com.op.android.activities.OPWebflowActi
vity (see Chapter 2)

1.0.21

18.05.2013

Dieter
Wurm

Document Version sync to Library Version

1.0.21

1.0.73

03.07.2013

Stefanie
Groll

Typo fixed (OPL-59)

Wording changed (OPL-70)

1.0.73

1.0.76

26.09.2013

A. Wirth

1.0.76

1.0.81

10.10.2013

A. Wirth

Fix alias payment for brand "BCMC" -> is renamed to "Bancontact/Mister Cash"
Fix alias payment for brand "Maestro" -> CVC is
now optional
Bugfix library:
Fix 3DSecure payment issues for consecutive
payments with the same OrderID, but different
PayIDs (generated by the backend), e.g. when
first payment attempt fails due to wrong PIN the
next payment attempt will no longer fail if authori-

Ogone In-App-Payment-library manual Android

1.0.81

Page 2 of 25

zation was successful.

1.0.82

19.11.2013

A. Wirth

1.0.85

21.11.2013

A. Wirth

1.0.87

26.11.2013

A. Wirth

1.0.120

23.01.2015

A. Wirth

1.0.120

02.02.2015

O. Gillin

Change:
Max allowed cardnumber length for BCMC and
Maestro brand is now 20.
Bugfix library:
Fixed an internal crash of payment request tasks
within the library on Android 4.3 and up. This fix
works w/o any code changes on the host applications side.
Bugfix library:
When an existing alias was being reused for a
new payment and the user has changed the card
number or the card brand for the new payment,
and the backend was not able to process the
payment successfully (e.g. wrong card details),
and the user re-triggered the payment by hitting
the Pay Button, the payment was processed
using the original card data from the alias. This
error has been fixed.
Bugfix library:
- Fixed debit card payments using existing aliases, payments are now processed without errors if
card details are correct.
- Fixed return value of "masked" card number in
alias for debit cards DE + AT (cardNumber +
"BLZ" + blz).
- Fixed alias payment for JCB cards when user
does not change displayed card number from
alias.
- Update library to Android SDK 5.0 (API level
21)
- Improved logging
- Fix for alias in URL-encoded format
- Fix parameters for PostFinance in DirectLink
call
- Additional parameter in DirectLink call to identify client (ORIG)
- Add support for '3DSecure' and 'WebAuth' authorization flows in 'Hidden Mode'
- Fix for BCMC brand in 'Hidden Mode', no CVC
needed
- Fix for payment type 'PaymentWithAlias' in
'Hidden Mode': if CVC is missing in pay data and
the card brand needs CVC, now the card detail
screen is presented for CVC entry
- Update known limitation for Direct Debit NL and
Direct Debit DE.

Ogone In-App-Payment-library manual Android

1.0.82

1.0.85

1.0.87

1.0.120

1.0.120

Page 3 of 25

Table of Contents
1

Payment process and general functionality ................................................................................ 6

1.1

OverviewPayment Methods ............................................................................................... 6

1.2

Supported Platforms ........................................................................................................... 6

1.3

Standard versus hidden mode ........................................................................................... 6

1.4

Payment Process ............................................................................................................... 7

Integrating payment library in Android project ............................................................................ 8

Using the payment library ........................................................................................................... 9

3.1

Initializing payment library .................................................................................................. 9

3.2

Implementing callback methods ......................................................................................... 9

3.2.1

Handling the result of payment request.......................................................................... 9

3.2.2

Customizing the payment librarys visual style ............................................................... 9

3.3
3.3.1

Handling the result of payment request........................................................................ 11

3.3.2

Dealing with saved payment data ................................................................................ 12

3.3.3

Reusing saved payment data ....................................................................................... 12

3.3.4

Alias handling within paymethod PostFinance ............................................................. 13

3.3.5

Error handling ............................................................................................................... 13

3.4

Using payment library in hidden mode ............................................................................. 13

3.4.1

Creating an alias ........................................................................................................... 13

3.4.2

Submit payment data in hidden mode .......................................................................... 14

3.5
4

Using payment library in standard mode ............................................................................ 9

Performing UI customizations .......................................................................................... 15

Class documentation API objects ............................................................................................. 15

4.1

com.op.android.activities.OPActivity ................................................................................ 15

4.1.1

Public fields .................................................................................................................. 16

4.1.2

Constructors ................................................................................................................. 16

4.1.3

Methods ........................................................................................................................ 16

4.2

com.op.android.card.OPPayData ..................................................................................... 16

4.2.1

Public fields .................................................................................................................. 16

4.2.2

Constructors ................................................................................................................. 17

4.2.3

Methods ........................................................................................................................ 17

4.3

com.op.android.card.OPPayType .................................................................................... 18

Ogone In-App-Payment-library manual Android

Page 4 of 25

4.4

com.op.android.card.OPCardPrototype ........................................................................... 18

4.4.1

Public fields .................................................................................................................. 18

4.4.2

Constructors ................................................................................................................. 18

4.4.3

Methods ........................................................................................................................ 18

4.5

com.op.android.card.OPCredentials ................................................................................ 20

4.5.1

Public fields .................................................................................................................. 21

4.5.2

Constructors ................................................................................................................. 21

4.5.3

Methods ........................................................................................................................ 21

4.6

com.op.android.card.OPCardListItem .............................................................................. 21

4.6.1

Public fields .................................................................................................................. 21

4.6.2

Constructors ................................................................................................................. 21

4.6.3

Methods ........................................................................................................................ 22

4.7

com.op.android.net.OPServerResponse ......................................................................... 22

4.7.1

Public fields .................................................................................................................. 22

4.7.2

Constructors ................................................................................................................. 22

4.7.3

Methods ........................................................................................................................ 22

4.8

com.op.android.utils.OPVisualMaster .............................................................................. 23

4.8.1

Public fields .................................................................................................................. 23

4.8.2

Constructors ................................................................................................................. 24

4.8.3

Methods ........................................................................................................................ 24

4.9

com.op.android.utils.OPTextStyle .................................................................................... 25

4.9.1

Public fields .................................................................................................................. 25

4.9.2

Constructors ................................................................................................................. 25

4.9.3

Methods ........................................................................................................................ 25

Tracking..................................................................................................................................... 25

Known limitations ...................................................................................................................... 25

6.1

Direct Debit DE (Germany) .............................................................................................. 25

6.2

Direct Debit NL ................................................................................................................. 25

Known issues ............................................................................................................................ 25

Ogone In-App-Payment-library manual Android

Page 5 of 25

Payment process and general functionality

1.1

OverviewPayment Methods

The library currently supports the following payment methods:

1.2

American Express
Visa
Diners Club
Master Card
Direct Debit NL (see 6 Known limitations, page 25)
Direct Debit DE (see 6 Known limitations, page 25)
Direct Debit AT
BCMC
Maestro
JCB
PostFinance

Supported Platforms

Devices running Android 2.1 (API 7) or higher are supported, including new 64-bit devices on
Android 5.0 Lollipop (API 21).
The library has been localized for English, French, German and Dutch.

1.3

Standard versus hidden mode

The payment library can be used in a standard or hidden mode. Within the standard mode a layout
with credit card information is provided whereas in the hidden mode credit card information is not
gathered by the payment librarys payment workflow but by the host app. In this case, only web
flows are shown for e.g. 3D authentications. Other views are provided by the host app.

Ogone In-App-Payment-library manual Android

Page 6 of 25

1.4

Payment Process

Ogone In-App-Payment-library manual Android

Page 7 of 25

Integrating payment library in Android project

The delivered Zip file contains the core library jar (Ogonepayment.jar) file and an archive named
res which contains the resource artefacts the payment library depends on.
To embed payment library functionality into your hosting app please process the following steps:

Copy Ogonepayment.jar into the libs folder of your project.

Add Ogonepayment.jar to your projects java build path.

Unpack res.zip and copy the expanded folders into your projects res directory.
Warning: The library resource names cant be changed. So if there is any naming conflict
relating resource filenames its necessary that host apps files will be changed.

Add the following activity entries inside your host apps AndroidManifest.xml:

<!-- Library activities -->

<activity
android:name="com.op.android.activities.OPNewOrderActivity"
android:label="@string/activity_payment_selection"
android:screenOrientation="portrait">
</activity>
<activity
android:name="com.op.android.activities.OPCreditCardActivity"
android:label="@string/activity_credit_debit"
android:screenOrientation="portrait">
</activity>
<activity
android:name="com.op.android.activities.OPDirectDebitActivity"
android:label="@string/activity_direct_debit"
android:screenOrientation="portrait">
</activity>
<activity
android:name="com.op.android.activities.OPAliasCreditConfirmActivity"
android:label="@string/activity_credit_debit"
android:screenOrientation="portrait">
</activity>
<activity
android:name="com.op.android.activities.OPHiddenActivity"
android:screenOrientation="portrait">
</activity>
<activity
android:name="com.op.android.controls.OPDialogDateExpire"
android:screenOrientation="portrait"
android:theme="@android:style/Theme.Dialog">
</activity>
<activity

Ogone In-App-Payment-library manual Android

Page 8 of 25

android:name="com.op.android.activities.OPWebflowActivity"
android:label="@string/dialog_3D_secure"
android:screenOrientation="portrait">
</activity>

3 Using the payment library

The following steps describe a typical process of using the payment library inside a host application.

3.1

Initializing payment library

In order to work with the payment library you have to extend the abstract API activity class
com.op.android.OPActivity.
OPActivity is the central class for configuring and initiating payments library functionality.

3.2

Implementing callback methods

OPActivity defines several abstract methods which are called by the library for customization of the
librarys visual style and notifying regarding the result of a payment operation. The host application
has to implement these methods in order to provide proper behavior.
3.2.1

Handling the result of payment request

protected abstract void onResultSucces(OPServerResponse response);

protected abstract void onResultError(OPPayType actionType, OPErrorAction
error);
protected abstract void onResultCancel();
3.2.2

Customizing the payment librarys visual style

protected abstract OPVisualMaster getVisualMaster();

3.3

Using payment library in standard mode

The central method for initiating payments in standard mode is

com.op.android.OPActivity.sendNewRequest(OPPayData payData, OPCredentials
credentials, List<OPCardListItem> allowedPayments, backend environment)
By calling sendNewRequest the host application performs a new payment request and initiates
the library internal workflow for capturing paydata and authorizing payment against Ogone backend
services.
payData
The host application must provide the order information order reference, amount and currency inside an com.op.android.card.OPPayData object. Amount must be provided in the currencys
smallest subunit, for example in Eurocent for EUR currency. The Currency string must be provided
as ISO 4217 currency code.
credentials

Ogone In-App-Payment-library manual Android

Page 9 of 25

OPCredentials instance that holds the necessary user and account data to fulfill order requests or
alias generation against Ogone backend services.
allowedPayments
Via the allowedPayments parameter the host app provides all relevant paymethods, which should
be offered inside the payment selection view of the payment library. The order of presented
paymethods correspond to the order of OPCardItemList elements of the list. Paymethods are represented by the class OPCardItemList, which offers factory methods for instantiation of every supported paymethod.
public
public
public
public
public
public
public
public
public
public
public

static
static
static
static
static
static
static
static
static
static
static

OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem
OPCardListItem

createVisaCard();
createAmericanExpress();
createMasterCard();
createDinersClub();
createMaestro();
createJcb();
createPostFinance();
createBcmc();
createDirectdebitsDe();
createDirectdebitsAt();
createDirectdebitsNl();

If only one payment method is provided, in the later workflow / screenflow the payment method
selection view will be skipped and the payment detail view of the provided payment method will be
displayed instantly.
If no payment method is provided inside the returned array, the payment library will use as a
default all implemented payment methods in the implemented order.

environment
With the environment parameter host app configures if the payment library works against the
Ogone production or test backend services.
The following code snippet demonstrates the usage of the above mentioned parameters:
import
import
import
import
...

com.op.android.card.OPCardListItem;
com.op.android.card.OPCredentials;
com.op.android.card.OPPayData;
com.op.android.card.OPPayType;

// providing credentials for Ogone alias gateway and directlink access

OPCredentials credentials = new OPCredentials();
credentials.initOPParams("psp_id", "user_id", "password", "passphrase");
// providing merchant's payment data
OPPayData payData = new OPPayData();
payData.setPayType(OPPayType.NewPayment);
payData.setOrderId("20120518001"); // the merchant's order reference
payData.setAmount(50050);
payData.setCurrency("EUR");
// providing paymethods

Ogone In-App-Payment-library manual Android

Page 10 of 25

ArrayList<OPCardListItem> paymethods = new ArrayList<OPCardListItem>();

paymethods.add(OPCardListItem.createAmericanExpress());
paymethods.add(OPCardListItem.createVisaCard());
paymethods.add(OPCardListItem.createDinersClub());
// alternatively provide all paymethods defined by payment library
// paymethods = OPActivity.getAllCards();
// initiate payment against Ogone test environment
sendNewRequest(payData, credentials, paymethods, backend.TEST);

3.3.1 Handling the result of payment request

After the payment library finished the payment process the host application is notified regarding the
result (success or error or cancellation) of the payment.
If the payment was successful the following method of is called.
void onResultSucces(OPServerResponse response)

The response parameter contains following payment detail properties:

Alias

The (optional) generated alias

Brand

Cards brand

payMethod

Pay method

payId

Payment reference in Ogone system

acceptance

Acceptance code returned by acquirer

If the payment was not successful and the error was not caused by invalid user input or temporary
unavailability of the services (these problems are handled by the library itself) the method
void onResultError(OPPayType, OPErrorAction)
is called.
The status parameter contains detailed error informations.
Status

Transaction status.

ncErrorId

The field NCERROR of order requests response.

ncErrorPlusId

The field NCERRORPLUS of order requests response.

errorDetails

Dictionary that contains detail error codes NCERRORCN,

NCERRORCARDNO, NCERRORCVC, NCERRORED
if present as key/value map.

If the user canceled the payment process by tabbing the Back button on the payment selection
screen, the host app will be notified via the callback cancel method.

Ogone In-App-Payment-library manual Android

Page 11 of 25

void onResultCancel()

3.3.2 Dealing with saved payment data

If the user performed the payment with activated save option, the payment library will create a new
alias at Ogone Alias Gateway for the current payment data.
The generated alias is returned by the library and can be used for future recurring payments instead of the concrete cardnumber. payment data.
Therefore it is secure for the host app to persist the returned paymethod data with the alias information.
protected void onResultSucces(OPServerResponse response)
If a payment with a new generated alias was successfully performed, the response parameter of
the onResultSuccess callback method contains an action type of
OPPayType.NewPaymentWithSavedAlias. Furthermore it contains all payment data except the real
card or bankaccount numbers and the generated alias.
protected void onResultSucces(OPServerResponse response) {
switch (response.getActionType()) {
case NewPayment:
...
case NewPaymentWithSaveAlias:
openDialog("The payment has been accepted and the alias has been
saved.");
addAliasToList(new Alias (response.getBrand(),
response.getMaskedCard(), response.getCardHolder(),
response.getAlias(), response.getExpireDate(),
response.getAddress(), response.getCity(),
response.getZip()));
break;
...
}
}

Even if alias generation fails, the payment process continues using the real card or bank account
number instead of an alias.
3.3.3 Reusing saved payment data
To reuse saved payment data for the next payment process, the host application needs to provide
the saved data within a com.op.android.card.OPCardPrototype instance.
OPCredentials credentials = new OPCredentials();
credentials.initOPParams("psp-id", "user-id", "pwd", "passphrase");
OPPayData payData = new OPPayData();
payData.setPayType(OPPayType.PaymentWithAlias);
payData.setAmount(100);
payData.setCurrency("USD");
payData.setOrderId("order id");
Alias = getPersistedAliasFromSomewhere();
OPCardPrototype card = new OPCardPrototype();
card.setAlias(alias.getAlias());

Ogone In-App-Payment-library manual Android

Page 12 of 25

card.setBrand(alias.getBrand());
card.setCardHolder(alias.getCardholder());
card.setCardNumber(alias.getMaskedCard());
card.setExpireDate(alias.getExpireDate());
payData.setCard(card);
sendNewRequest (payData,credentials, backend.TEST);
If the payment library is called with saved payment data, the payment method selection screen will
be skipped and the payment details view with prefilled payment data will be displayed directly. Depending on the type of the paymethod the user must enter the CVC before continuing with the
payment process.
All prefilled payment data can be overwritten by the user. In the case of changed payment data, the
alias relevant payment data will be updated accordingly at Ogone Alias Gateway.
3.3.4 Alias handling within paymethod PostFinance
When using the PostFinance paymethod, the alias handling and workflow is different.
After initiating the payment workflow from within the payment librarys payment details view, the
user has to fulfill a web based authorization process in the first step. If authorization succeeds, a
unique alias is generated and returned by PostFinance backend services. This alias will be used in
the subsequent payment process. Please note that this workflow is mandatory for PostFinance
payments and will be performed regardless of whether the save option was activated or not.
3.3.5 Error handling
In standard mode the payment library itself handles upcoming errors within normal payment workflow as far as possible.
In cases of technical errors (i.e. problems with network connectivity) while processing a payment
request the user is presented an error message and encouraged to retry the request later.
In cases of authentication or authorization failures the user is presented an appropriate information
view and rerouted to the paymethod selection screen to retry with another paymethod.
In cases of invalid data edited by the user, the user is requested to correct the input data and retry
the payment request.

3.4

Using payment library in hidden mode

In hidden mode, credit card information is not gathered by the payment librarys payment workflow
but is also provided by the app. The payment method selection screens are then skipped and authentication and/or authorization takes place immediately.
Performing payments in hidden mode is always a two step process. As with standard mode payments all relevant methods for payment submission in hidden mode are provided by the
OPActivity class.
3.4.1

Creating an alias

With the sendHiddenNewRequest method the host application can obtain a new alias from
Ogone Alias Gateway without performing a payment request directly.

OPCredentials credentials = new OPCredentials();

credentials.initOPParams("psp-id", "user-id", "pwd", "passphrase");
OPPayData payData = new OPPayData();

Ogone In-App-Payment-library manual Android

Page 13 of 25

payData.setPayType(OPPayType.NewAlias);
...
OPCardPrototype card = new OPCardPrototype();
card.setCardHolder("Cardholder");
card.setBrand(OPBrand.VISA);
card.setCardNumber("4111111111111111");
card.setCVC("121");
card.setExpiryDate("1212");
payData.setCard(card);
sendHiddenNewRequest(payData,credentials, backend.TEST);

In cases of successful alias generation the callback method

protected abstract void onResultSucces(OPServerResponse response);
is called by the payment library. The response parameter contains all relevant paymethod
informations but the real cardnumber. Based on that you can build an appropriate alias object.
new Alias(
response.getBrand(),
response.getMaskedCard(),
response.getCardHolder(),
response.getAlias(),
response.getExpireDate()));
3.4.2 Submit payment data in hidden mode
After creating a concrete Alias instance with alias information, the payment request will be performed via the OPActivity method
Alias alias = getGeneratedAlias();
OPCredentials credentials = new OPCredentials();
credentials.initOPParams("psp-id", "user-id", "pwd", "passphrase");
payData.setPayType(OPPayType.PaymentWithAlias);
payData.setAmount(100);
payData.setCurrency("USD");
payData.setPaymentId("order-id");
OPCardPrototype card = new OPCardPrototype();
card.setCVC("121");
card.setAlias(alias.getAlias());
payData.setCard(card);
sendHiddenNewRequest(payData,credentials, backend.TEST);

If paymethod is a credit card and the host app does not provide the cards CVC inside
OPPaymentCard, also in hidden mode the payment details view will be shown by the library to
obtain the CVC.

Ogone In-App-Payment-library manual Android

Page 14 of 25

3.5

Performing UI customizations

In order to provide customization of fonts, background images and colors the host app has to implement the method:
OPVisualMaster getVisualMaster()

and provide an instance of the class com.op.android.utils.OPVisualMaster.

All needed customizations are to be transported through an intents extended data. The valid keys
are defined inside OPVisualMaster. Alternatively OPVisualMaster defines some convenience setter
methods for the most common customizations.
//@Override
protected OPVisualMaster getVisualMaster() {
// Do some customizations
OPVisualMaster visual = new OPVisualMaster();
// set background color via convenience method
visual.setBackgroundColor(Color.BLUE);
// set label color via intent
OPTextStyle style = new OPTextStyle();
style.color = Color.RED;
visual.getVisualScheme().putExtra(OPVisualMaster.CARD_TEXT_STYLE,
style);
return visual;
}

The following UI customizations can be performed:

4
4.1

Background color for views

Background image for views
Logo
Background color table cells (even / odd)
Background color selected table cells
Font in table cells
Text shadow in table cells
Font in input fields
Font color in input fields

Class documentation API objects

com.op.android.activities.OPActivity

This is the main entry point for Ogone Payment system.

You start interacting with Ogone payment system from this class' methods. This class must be
subclassed by your activity.

Ogone In-App-Payment-library manual Android

Page 15 of 25

4.1.1 Public fields

static enum backend {TEST, PRODUCTION}
Tells the payment library to work against Ogone test or production system
4.1.2
-

Constructors

4.1.3

Methods

4.1.3.1 static List<OPCardListItem> getAllCards()

Provides list of all defined payment methods
4.1.3.2 void sendNewRequest(OPPayData payData, OPCredentials credentials, backend env)
Perform a new payment request against Ogone backend in standard mode.
Parameters
Paydata

contains the merchants pay data.

Credentials

contains the Ogone account credentials

Cards

list of maymethods for paymethod selection screen

Env

Backend.TEST or Backend.PRODUCTION

4.1.3.3

void sendHiddenNewRequest(OPPayData payData, OPCredentials credentials, backend

env)
Perform a new payment request against Ogone backend in hidden mode.
Parameters
Paydata

contains the merchants pay data.

Credentials

contains the Ogone account credentials

Env

Backend.TEST or Backend.PRODUCTION

4.2

com.op.android.card.OPPayData

Container to pass merchants payment information within the library. Used to transport saved payment informations from host app to library.
4.2.1

Public fields

Ogone In-App-Payment-library manual Android

Page 16 of 25

4.2.2

Constructors

4.2.2.1

OPPayData()

4.2.2.2

OPPayData(final Parcel in)

4.2.3

Methods

4.2.3.1 void setAmount(final int amount)

Sets the payment amount.
Parameters
Amount

Amount in currencys smallest subunit.

For example Eurocent for the EUR currency.

4.2.3.2 void setCard(final OPCardPrototype card)

Sets payment card or bank account information.
Parameters
Card

Credit card or bank account information to use for payment.

4.2.3.3 void setCurrency(final String currency)

Sets the currency to be used for the payment.
Parameters
currency

Currency string. Must be provided as ISO 4217 currency

code

4.2.3.4 void setOrderId(final String orderId)

Sets the merchants order reference.
Parameters
orderId

merchants order reference.

4.2.3.5 void setPayType(final OPPayType paytype)

Sets the payment type to be used for the payment.
(See OPPayType documentation for possible payment types.)
Parameters
Paytype

Payment Type

4.2.3.6 int getAmount()

Gets the payment amount.

Ogone In-App-Payment-library manual Android

Page 17 of 25

4.2.3.7 OPCardPrototype getCard()

Gets payment card or bank account information.
4.2.3.8 String getCurrency()
Gets the currency used for the payment.
4.2.3.9 String getOrderId()
Gets the merchants order reference.
4.2.3.10 OPPayType getPayType()
Gets the payment type used for the processed payment.
(See OPPayType documentation for possible payment types.)

4.3

com.op.android.card.OPPayType

Enumeration type for specifying the type of action to be performed against the payment library.
Following types are possible:
NewPayment

Perform a new payment without using existing alias data.

This is the default type for performing a payment in normal
mode.

NewPaymentWithSaveAlias

internal type. Dont use it for new payment requests.

PaymentWithAlias

Perform a new payment using existing alias data.

This type has to be used when recurring payment data
should be used.

NewAlias

Action type for only generating an alias without performing a

payment. Relevant for hidden mode only.

4.4

com.op.android.card.OPCardPrototype

Container to pass credit card or bank account data.

Used to transport saved payment informations within a OPPayData object from host app to library.
4.4.1

Public fields

4.4.2

Constructors

4.4.2.1

OPCardPrototype()

4.4.2.2

OPCardPrototype(final Parcel in)

4.4.3 Methods
From the host apps perspective OPCardPrototype is only used to provide existing Payment
informations to the payment library. Hence only the setter methods are relevant and described.
Ogone In-App-Payment-library manual Android

Page 18 of 25

1.1.1.1
void setAddress(final String address)
Sets the bank account holders address street and house number.
Relevant only for pay methods Direct Debit DE, Direct Debit AT, Direct Debit NL.
Parameters
Address

street and house number.

4.4.3.1 void setAlias(final String alias)

Sets the alias token to be used for the payment.
Parameters
Alias

alias token from a previous payments saved data to be used

for a new payment.

4.4.3.2 void setBlz(final String blz)

Sets the bank code number.
Relevant only for pay methods Direct Debit DE, Direct Debit AT.
Parameters
Blz

the bank code number.

4.4.3.3 void setBrand(final OPBrand brand)

Sets the defined brand type for the payment.Following brands are supported:
OPBrand.AMERICAN_EXPRESS
OPBrand.VISA
OPBrand.DINERS_CLUB
OPBrand.MASTER_CARD
OPBrand.JCB
OPBrand.MAESTRO
OPBrand.BCMC
OPBrand.POSTFINANCE
OPBrand.DIRECTDEBITS_DE
OPBrand.DIRECTDEBITS_AT
OPBrand.DIRECTDEBITS_NL

Parameters
Brand

the paymethods brand type.

4.4.3.4 void setCardHolder(final String cardholder)

Sets the card or bank account holders name.
Parameters

Ogone In-App-Payment-library manual Android

Page 19 of 25

Cardholder

card or bank account holders name

4.4.3.5 void setCardNumber(final String cardnumber)

Sets the card or bank account number.
Parameters
Cardnumber

card or bank account number

4.4.3.6 void setCity(final String city)

Sets the bank account holders address city.
Relevant only for pay methods Direct Debit DE, Direct Debit AT.
Parameters
City

city

4.4.3.7 void setCVC(final String cvc)

Sets the card validation code to use for the payment.
Relevant only for credit card pay methods
Parameters
Cvc

card validation code

4.4.3.8 void setExpiryDate(final String expirydate)

Sets the expiry date to use for the payment.
Relevant only for credit card pay methods
Parameters
Expirydate

expirydate. Format MMYY

4.4.3.9 void setZip(final String zipcode)

Sets the bank account holders address zip code.
Relevant only for pay methods Direct Debit DE, Direct Debit AT.
Parameters
Zipcode

4.5

zipcode

com.op.android.card.OPCredentials

Container to hold all relevant credential information for communication with Ogone backend services.

Ogone In-App-Payment-library manual Android

Page 20 of 25

4.5.1
-

Public fields

4.5.2

Constructors

4.5.2.1

OPCredentials(String pspid, String userid, String password, String passphrase)

Parameters
pspid

PSPID of Ogone account

userid

USERID of Ogone account

password

PASSWORD of Ogone account

passphrase

secret PASSPHRASE of Ogone account

4.5.3
-

4.6

Methods

com.op.android.card.OPCardListItem

Helper class to generate individual pay methods, which must be provided inside method
OPActivity.sendNewRequest(...) to define the relevant pay methods in the librarys payment selection view.
4.6.1
-

Public fields

4.6.2
-

Constructors

Ogone In-App-Payment-library manual Android

Page 21 of 25

4.6.3

Methods

4.6.3.1

static OPCardListItem createAmericanExpress()

4.6.3.2

static OPCardListItem createMasterCard()

4.6.3.3

static OPCardListItem createDinersClub()

4.6.3.4

static OPCardListItem createJcb()

4.6.3.5

static OPCardListItem createDirectdebitsDe()

4.6.3.6

static OPCardListItem createDirectdebitsAt()

4.6.3.7

static OPCardListItem createDirectdebitsNl()

4.6.3.8

static OPCardListItem createVisaCard()

4.6.3.9

static OPCardListItem createPostFinance()

4.6.3.10 static OPCardListItem createBcmc()

4.6.3.11 static OPCardListItem createMaestro()

4.7

com.op.android.net.OPServerResponse

Container object provided by the payment library as the result of a successful payment operation
inside the callback method OPActivity.onResultSuccess(..).
The OPServerResponse object contains all relevant payment data so that the host app can save
payment data for recurring payments.
4.7.1
-

Public fields

4.7.2
-

Constructors

4.7.3 Methods
From the host apps perspective OPServerResponse is only used to provide detail information of a
successful payment to the host app.
Hence only the getter methods are relevant and described.
4.7.3.1 String getAcceptance()
Gets the acquirers acceptance identifier.
4.7.3.2 String getAddress()
Gets the bank account holders address street and house number.
Provided only for pay methods Direct Debit DE, Direct Debit AT, Direct Debit NL.

Ogone In-App-Payment-library manual Android

Page 22 of 25

4.7.3.3 String getAlias()

Gets the alias token used for the payment.
4.7.3.4 String getBlz()
Gets the bank code number.
Provided only for pay methods Direct Debit DE, Direct Debit AT.
4.7.3.5 OPBrand getBrand()
Gets the brand type for the payment.
4.7.3.6 String getCardHolder()
Gets the card or bank account holders name.
4.7.3.7 String getCardNumber()
Gets the card or bank account number.
4.7.3.8 String getCity()
Gets the bank account holders address city.
Relevant only for pay methods Direct Debit DE, Direct Debit AT.
4.7.3.9 String getCurrency()
Gets the currency oft he previous payment.
4.7.3.10 String getExpiryDate()
Gets the expiry date to use for the payment in the format MMYY.
4.7.3.11 String getMaskedCard()
Gets the x-masked card or bank account number (not the real number).
4.7.3.12 String getOrderId()
Gets the merchants order id.
4.7.3.13 String getPayId()
Gets the Ogone payment id for the payment.
4.7.3.14 String getZip()
Gets the bank account holders address zip code.
Relevant only for pay methods Direct Debit DE, Direct Debit AT.

4.8

com.op.android.utils.OPVisualMaster

The host app can perform UI customizations by providing a customized instance of

OPVisualMaster inside the delegate method OPActivity.getVisualMaster().
Colors are represented as packed ints, made up of 4 bytes: alpha, red, green, blue.
(See android.graphics.Color documentation for convenience methods.)

4.8.1
-

Public fields

Ogone In-App-Payment-library manual Android

Page 23 of 25

4.8.2
4.8.2.1
4.8.3

Constructors
OPVisualMaster()
Methods

4.8.3.1 void setBackgroundBitmap(android.graphics.Bitmap bgBitmap)

Sets the background image for all views inside the payment library.
4.8.3.2 void setBackgroundColor(int color)
Sets the background color for all views inside the payment library.
4.8.3.3 void setCardTextStyle(OPTextStyle style)
Sets the text style for all labels inside payment details views.
4.8.3.4 void setEditTextStyle(OPTextStyle style)
Sets the text style for all input fields inside payment details views.
4.8.3.5 void setEvenColor(int color)
Sets the background color of the table rows in payment details view with even rownum.
4.8.3.6 void setOddColor(int color)
Sets the background color of the table rows in payment details view with odd rownum.
4.8.3.7 void setLabelBitmap(android.graphics.Bitmap bgBitmap)
Sets the image ressource for the logo on the payment selection view.
4.8.3.8 void setLabelVisibility(Boolean visible)
Toggles if the logo on payment selection view should be visible or not.
4.8.3.9 void setLabelGravity(android.view.Gravity gravity)
Sets the alignment of the logo on payment selection view.
Possible values:
Gravity.LEFT

Left alignment

Gravity.RIGHT

Right alignment

Gravity.CENTER

Center alignment

4.8.3.10 void setPaymentSelectionEvenColor(int color)

Sets the background color of the table rows in payment selection view with even rownum.
4.8.3.11 void setPaymentSelectionOddColor(int color)
Sets the background color of the table rows in payment selection view with odd rownum.
4.8.3.12 void setTableCelltextStyle(OPTextStyle)
Sets the text style for the labels on payment selection view.

Ogone In-App-Payment-library manual Android

Page 24 of 25

4.9

com.op.android.utils.OPTextStyle

Customization class to provide font specific text styles.

4.9.1
-

Public fields

4.9.2

Constructors

4.9.2.1
4.9.3

OPTextStyle()
Methods

4.9.3.1 void setBold(boolean bold)

Toggles bold font.
4.9.3.2 void setItalic(boolean bold)
Toggles italic font.
4.9.3.3 void setColor(int color)
Sets the fonts color.
4.9.3.4 void setTextSize(int size)
Sets the fonts size.

Tracking

In order to differentiate inApp transactions on DirectLink the library uses the ORIG Field listed in
the Direct Link and transfers the value IAOGA + the current version number of the library.

6
6.1

Known limitations
Direct Debit DE (Germany)

For acquirer EasyCash and Telego, the configuration oft he payemnt method needs to set the
switch SEPA-Mode to NO.
In Germany transactions cal still be accepted using the domestic account format. The mandate is
not mandatory.

6.2

Direct Debit NL

No longer supported
The processing of DD NL transaction processed via Equens requires multiple data points including
data provided by the buyer (IBAN bank account number, BIC) and by the merchants (Unique Mandate ID, SEC Type, signature date)

Known issues

Ogone In-App-Payment-library manual Android

Page 25 of 25