Version History
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 |
Introduction
This document lists all the PayXpress V4 features available in order to make a 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.
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.
The steps of the above process flow are explained below:
The Merchant Mobile App initiates a transaction by sending a payment request to PayXpress Payment App.
PayXpress Payment App will display screen to Customer in order to present card / inser card.
Once the end customer completes the transaction and the POS operation concludes, the POS displays the transaction outcome (Payment accepted or refused).
Optional: PayXpress can offer the posibility to the customer to either retrieve his ticket via QR, or sent it by Email.
In this case a screen is displayed requesting for this information.
If no ticket is required in a electronic format (QR, Email), then process to finalize the transaction is realized by PayXpress.
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 |
| The action you want to perform in PayXpress |
| 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 |
| Amount of the transaction. |
| Integer | Yes |
| Type of the transaction. |
| Integer | No |
| Decide if the ticket should be printed or not. |
| Boolean | No |
| 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_type_print_ticket", 0)
Parameter | Description | Format | Type | Mandatory |
| Defines which ticket you want to print |
| 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 |
| Outcome of the transaction |
| Integer | Yes |
| Transaction’s infos | See table below | Transaction | No |
| Client & merchant tickets | Json description. See bellow | String | No |
The Transaction object can have several parameters:
Parameter | Description | Format | Type | Mandatory |
| Id of the transaction | / | String | Yes |
| Type of the transaction |
| Integer | Yes |
| Type of transaction / Payment method |
| Integer | Yes |
| Date’s timestamp |
| Long | Yes |
| Reference of the transaction transamitted as input | / | String | No |
| Amount of the transaction |
| Integer | Yes |
| Currency of the transaction | / | String | Yes |
| Selected AID during the transaction | / | String | No |
| Transaction without network / offline ? |
| Boolean | No |
| Outcome of the transaction |
| Yes | |
| Masked PAN of the card | / | String | No |
| Type of card used | / | String | No |
| Expiration date of the card |
| Integer | Yes |
| Amount of the tips (in case the functionality is activated) |
| Integer | No |
| Type of PAN |
| Integer | No |
| Authorization number if provided by the bank | / | String | No |
Client & Merchant Tickets
Client and Merchant Tickets are restitued 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 reponse what is the desired ticket that you want to use.
Please find bellow example/snipped of Client and Merchant Tickets in JSON Structure:
{
"tickets": [
{
"type": "CLIENT",
"ticket": "Q0FSVEUgQkFOQ0FJUkUKU0FOUyBDT05UQUNUCkJvbmpvdXIgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgCkEwMDAwMDAwNDIxMDEwCkNCCkxFIDI5LzEwLzI0IEEgMTI6Mzk6MzAKRzcgVEVTVCAgICAgICAgICAyMSAKRElKT04gICAgICAgICAgICAgICAKICAgICAgICAgICAgICAgICAgICAKMDg5OTAxMwoyMDA0MQozMjQzNzk4NjYwMDAxOQpYWFhYWFhYWFhYWFgyODU2CjZDM0U1NEE5N0ZCOENFNzAKODk2IDAwMSAwMDAwMDEgIDAxICBDICAKTrAgQVVUTyA6IApSRUYuIDogCk1PTlRBTlQKNCwwMKBFVVIKREVCSVQKQ0FSVEUgREUgVEVTVApUSUNLRVQgQ0xJRU5UCkEgQ09OU0VSVkVSCk1lcmNpLCBhdSByZXZvaXIuICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgCg=="
},
{
"type": "MERCHANT",
"ticket": "Q0FSVEUgQkFOQ0FJUkUKU0FOUyBDT05UQUNUCkJvbmpvdXIgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgCkEwMDAwMDAwNDIxMDEwCkNCCkxFIDI5LzEwLzI0IEEgMTI6Mzk6MzAKRzcgVEVTVCAgICAgICAgICAyMSAKRElKT04gICAgICAgICAgICAgICAKICAgICAgICAgICAgICAgICAgICAKMDg5OTAxMwoyMDA0MQozMjQzNzk4NjYwMDAxOQoyMDEwCjUwNzEwMDQxNTAxMjI4NTYKNkMzRTU0QTk3RkI4Q0U3MApmaW4gMzAvMDYvMjUKODk2IDAwMSAwMDAwMDEgIDAxICBDICAKTrAgQVVUTyA6IApSRUYuIDogCk1PTlRBTlQKNCwwMKBFVVIKREVCSVQKQ0FSVEUgREUgVEVTVApUSUNLRVQgQ09NTUVSQ0FOVApBIENPTlNFUlZFUgpNZXJjaSwgYXUgcmV2b2lyLiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIAo="
}
]
}
Example of JSON Intent’s Return
Status Accepted
{
"status":0,
"transaction":{
"id":"45a07d7e-7080-49a5-aa15-0885ef16ab98",
"transactionType":0,
"mode":0,
"date":1730904863000,
"reference":"test",
"amount":1500,
"currency":"EUR",
"aid":"A0000000421010",
"isDegradedMode":false,
"error":"0",
"maskedPan":"497414XXXXXX5960",
"cardLabel":"CB",
"expirationDate":"260531"
},
"tickets":"{"tickets":[{"type":"CLIENT","ticket":"Q0FSVEUgQkFOQ0FJUkUKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAKQTAwMDAwMDA0MjEwMTAKQ0IKTEUgMDYvMTEvMjQgQSAxNTo1NDoyMwpQQVlYUEVSVCBGUkFOQ0UgIDY5IApMWU9OICAgICAgICAgICAgICAgIAogICAgICAgICAgICAgICAgICAgIAowMDAxNjk2CjE2ODA4CjU0MDAzMjgxMDAwMDQxClhYWFhYWFhYWFhYWDU5NjAKM0M1NTNERjJCOUM3QzQwRAoxNjMgMDAxIDAwMDAxMCAgMDEgIEMgIApOsCBBVVRPIDogClJFRi4gOiAKTU9OVEFOVAoxNSwwMKBFVVIKREVCSVQKVElDS0VUIENMSUVOVApBIENPTlNFUlZFUgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIAo="},{"type":"MERCHANT","ticket":"Q0FSVEUgQkFOQ0FJUkUKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAKQTAwMDAwMDA0MjEwMTAKQ0IKT04gMDYvMTEvMjQgQVQgMTU6NTQ6MjMKUEFZWFBFUlQgRlJBTkNFICA2OSAKTFlPTiAgICAgICAgICAgICAgICAKICAgICAgICAgICAgICAgICAgICAKMDAwMTY5NgoxNjgwOAo1NDAwMzI4MTAwMDA0MQoyMDEwClhYWFhYWFhYWFhYWDU5NjAKM0M1NTNERjJCOUM3QzQwRAplbmQgMzEvMDUvMjYKMTYzIDAwMSAwMDAwMTAgIDAxICBDICAKQVVUSE8gTlVNIDogClJFRi4gOiAKQU1PVU5UCjE1LDAwoEVVUgpERUJJVApNRVJDSEFOVCBUSUNLRVQKVE8gQkUgS0VQVAogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIAo="}]}"
}
Status Denied
{
"status":1,
"transaction":{
"id":"c5a4ba46-e52a-4550-af4e-154d5244ea4e",
"transactionType":0,
"mode":0,
"date":1730907374000,
"reference":"test",
"amount":1500,
"currency":"EUR",
"aid":"A0000000041010",
"isDegradedMode":false,
"maskedPan":"526557XXXXXX2897",
"cardLabel":"Debito",
"expirationDate":"300531"
},
"tickets":"{"tickets":[{"type":"CLIENT","ticket":"VEFSSkVUQSBCQU5DQVJJQQogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIApBMDAwMDAwMDA0MTAxMApEZWJpdG8KIDA2LzExLzI0IC0gMTY6MzY6MTQKUEFZWFBFUlQgRlJBTkNFICA2OSAKTFlPTiAgICAgICAgICAgICAgICAKICAgICAgICAgICAgICAgICAgICAKVkVOVEEgUkVDSEFaQURBCjAwMDE2OTYKMTY4MDgKNTQwMDMyODEwMDAwNDEKWFhYWFhYWFhYWFhYMjg5NwoxNjMgMDAxIDAwMDAxMiAgMDEgIEMgIEAKTlVNRVJPIEFVVE9SSVpBQ0nTTjogClJFRi4gOiAyTURTSU5FUUxPMTEwNiAgbjVnYTNVS2ZRTVM4bzdpN3hybW9ZdwpJTVBPUlRFCjE1LDAwoEVVUgpSRUNJQk8gUEFSQSBFTCBDTElFTlRFCkEgQ09OU0VSVkFSCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgCg=="},{"type":"MERCHANT","ticket":"Q0FSVEUgQkFOQ0FJUkUKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAKQTAwMDAwMDAwNDEwMTAKRGViaXRvCk9OIDA2LzExLzI0IEFUIDE2OjM2OjE0ClBBWVhQRVJUIEZSQU5DRSAgNjkgCkxZT04gICAgICAgICAgICAgICAgCiAgICAgICAgICAgICAgICAgICAgCkRFQklUIERFQ0xJTkVECk1PVElGIFROQSA6IDIxIDEyCjAwMDE2OTYKMTY4MDgKNTQwMDMyODEwMDAwNDEKMjAxMApYWFhYWFhYWFhYWFgyODk3CmVuZCAzMS8wNS8zMAoxNjMgMDAxIDAwMDAxMiAgMDEgIEMgIEAKQVVUSE8gTlVNIDogClJFRi4gOiAyTURTSU5FUUxPMTEwNiAgbjVnYTNVS2ZRTVM4bzdpN3hybW9ZdwpBTU9VTlQKMTUsMDCgRVVSCk1FUkNIQU5UIFRJQ0tFVApUTyBCRSBLRVBUCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgCg=="}]}"
}
For a ticket print in 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 |
| Outcome of the print |
| Integer | Yes |