PayXpert - User documentation

Call PayXpress via Android Intent

Owned by Technical Writer
Last updated: Nov 13, 2024 by Rémi DEROM
6 min read

Version History

Version

Date

Changes

Author

Version

Date

Changes

Author

1.0

11 April 2024

Initial Documentation for V4

Anne-Claire Femia

1.1

14 Oct 2024

Added Json Ticket Example

David Guignard

1.2

28 Oct 2024

Added Process Flow

Tim MacGowan

1.3

13 Nov 2024

Added link of official Android intent documentation + sample app

Rémi DEROM

Introduction

This document lists all the PayXpress V4 features available in order to make an Inter-application (‘app-to-app’) integration between mobile apps installed on the same mobile device.

The following features are available:

  • Debit transaction

  • Cancellation transaction

  • Refund transaction

  • Deferred debit transaction

  • Printing the last saved ticket (client & merchant)

Requirements:

  • The PayXpress v4 app must be installed in the terminal.

  • It is possible to call PayXpress with our parameters only via Intent calls. (For detailed information on the android intent api, please consult the official Android documentation : https://developer.android.com/training/basics/intents, here is a sample application with examples of how to get started : )

Process Flow

Your mobile application can call the PayXpress mobile application in order to handle the payment on the same device. This is done via Android Intent API.

The diagram bellow outlines the relationship and process flow between the systems involved in the Intent communication.

Intent_workflow.png
Process flow for Debit transaction

The steps of the above process flow are explained below:

  1. The Merchant Mobile App initiates a transaction by sending a payment request to PayXpress Payment App.

  2. PayXpress Payment App will display screen to Customer in order to present card / insert card.

  3. Once the end customer completes the transaction and the POS operation concludes, the POS displays the transaction outcome (Payment accepted or refused).

  4. Optional: PayXpress can offer the posibility to the customer to either retrieve his ticket via QR, or send it by Email.

    1. In this case a screen is displayed requesting this information.

    2. If no ticket is required in a electronic format (QR, Email), then the process to finalize the transaction is realized by PayXpress.

  5. Upon the finalization of the transaction, PayXpress Payment app will export in the Android Intent Reponse the transactions details including the client and merchant ticket.

Calling PayXpress from another Android Mobile application

To call PayXpress, you should use an Intent with a Component.

The package should be com.payxpert.merchant and the class com.payxpert.merchant.ui.transaction.TransactionActivity.

There are 2 possible actions for this Intent:

  • Perform a transaction

  • Ticket printing

Here is an example for an Intent starting a transaction:

val intent = Intent() intent.component = ComponentName("com.payxpert.merchant", "com.payxpert.merchant.ui.transaction.TransactionActivity ") intent.putExtra("transaction_bundle_key_action", "PERFORM") //TODO add more extras to specify your needs. See next sections

Parameter

Description

Format

Type

Mandatory

transaction_bundle_key_action

The action you want to perform in PayXpress

PERFORM: Start a transaction

PRINT_LAST: Print a ticket

String

Yes

You should go to the next section to know which extras you should add depending on the action.

Transactions

To trigger a transaction in PayXpress, you should pass to the Intent some extra parameters with the description of the transaction you want to do.

intent.putExtra("transaction_bundle_key_amount", 1500) intent.putExtra("transaction_bundle_key_transaction_type", 1) intent.putExtra("transaction_bundle_key_print_ticket", false) intent.putExtra("transaction_bundle_key_reference", "test")

Parameter

Description

Format

Type

Mandatory

transaction_bundle_key_amount

Amount of the transaction.

100: 1,00 €

1050: 10,50 €

Integer

Yes

transaction_bundle_key_transaction_type

Type of the transaction.

1: Debit

2: Cancellation

3: Refund by Credit (not linked to a original Sale Transaction)

4: Deferred debit

Integer

No

transaction_bundle_key_print_ticket

Decide if the ticket should be printed or not.

true: The ticket should be printed in the POS and the DEMAT page is displayed (QRCode, Email)

false: The ticket should not be printed in the POS and DEMAT page is not displayed (QRCode, Email).

Boolean

No

transaction_bundle_key_reference

Your id for the transaction

 

String

Yes

Ticket printing

You can print merchant or client tickets directly in the POS of the last performed transaction.

intent.putExtra("transaction_bundle_key_action", "PRINT_LAST") intent.putExtra("transaction_bundle_key_type_print_ticket", 0)

Parameter

Description

Format

Type

Mandatory

transaction_bundle_key_type_print_ticket

Defines which ticket you want to print

0: Merchant & client ticket

1: Client ticket only

2: Merchant ticket only

Integer

Yes

Retrieve Intent’s result

For a transaction

When a transaction is triggered via Intent, it is possible to wait for the transaction result to know the outcome of it.

The result is a JSON that is formatted as a String. It can be found in the extras under the name result. Inside you will find a IntentTransactionOutcome object with the following parameters:

Parameter

Description

Format

Type

Mandatory

status

Outcome of the transaction

0: Accepted

1: Denied

Integer

Yes

transaction

Transaction’s infos

See table below

Transaction

No

tickets

Client & merchant tickets

JSON description. See bellow

String

No

The Transaction object can have several parameters:

Parameter

Description

Format

Type

Mandatory

id

Id of the transaction

/

String

Yes

transactionType

Type of the transaction

0: Debit

1: Refund / Credit
2: Cancellation

8: Deferred debit

Integer

Yes

mode

Type of transaction / Payment method

0: Contact

1: Contactless

Integer

Yes

date

Date’s timestamp

171017239300

Long

Yes

reference

Reference of the transaction transmitted as input

/

String

No

amount

Amount of the transaction

100: 1,00 €

1050: 10,50 €

Integer

Yes

currency

Currency of the transaction

/

String

Yes

aid

Selected AID during the transaction

/

String

No

isDegradedMode

Transaction without network / offline ?

true: Transaction without network / offline

false: Transaction with network / online

Boolean

No

error

Outcome of the transaction

0: Accepted

1: Denied

2: Invalid parameters

3: Transaction already in progress

4: Application in background

5: Error

6: Reference already exists

7: Cancelled

8: Not finished

9: Timeout

 

Yes

maskedPan

Masked PAN of the card

/

String

No

cardLabel

Type of card used

/

String

No

expirationDate

Expiration date of the card

250630

Integer

Yes

amountTips

Amount of the tips (in case the functionality is activated)

100: 1,00 €

1050: 10,50 €

Integer

No

panType

Type of PAN (Partial PAN when nothing returned)

0: Full PAN

1: Partial PAN

2: Token

Integer

No

numAuthorization

Authorization number if provided by the bank

/

String

No

 

Client & Merchant Tickets

Client and Merchant Tickets are restituted in a JSON Structure.

Each ticket is formatted in ASCII mode and encoded in Base64. This is recommended in order to handle non-alphanumeric data (in alphanumeric), handle carriage returns and small images.

Currently, it is not possible by PayXpress to export only the client or merchant ticket in the JSON Structure. Both tickets are exported. It is up to the merchant/integrator to filter, based on PayXpress' response, for the ticket that is desired.

Please find below an example/snippet of Client and Merchant Tickets in JSON Structure:

Example of JSON Intent’s Return

Status Accepted

Status Denied

For a ticket print on the POS

When the instruction to print a ticket is triggered via Intent, it is possible to wait for the result to know the outcome of it.

The result is a JSON that is formatted as a String. It can be found in the extras under the name result. Inside you will find a IntentTransactionOutcome object with the following parameters:

Parameter

Description

Format

Type

Mandatory

status

Outcome of the print

0: Printing is successful

1: Printing has failed

Integer

Yes

tickets

Client & merchant tickets

see JSON description.

String

No

Note:

  • For the device without integrated printer, the status will be always 0 (successful).

  • Tickets data returned from intent call will always return client and merchant ticket in base64.



 

© PayXpert Services Ltd, 2024