Android intents

Open the point of sale (POS) app from your Android mobile app to process payments with a terminal.

INFO

Service available in Mexico 🇲🇽 only.

Requirements

In order to call the POS app from your app within an Android device, you must meet the following requirements:

A valid account

The latest available version of the Billpocket POS app installed from the Google Play Store

Be logged in within the POS app

A supported POS terminal

Adding the SDK to your project

Add the SDK in your project's build.gradle file.

Add the following necessary dependencies:

Building the Intent

Make sure to include the following import in your project:

Create an instance of the BPIntentBuilder class and set an action:

Next, every mandatory or optional parameter should be set to the instance:

enableDialogTip is pending confirmation for this channel

BPIntentBuilder does not have a documented setter for enableDialogTip today. It is confirmed as a Boolean field for the Mobile web (Links) channel and for Cloud Terminal API's extras.enableDialogTip.

Before publishing it as supported here, confirm with BP engineering whether a setter exists (or is planned) for Android intents.

Calling the POS app

The POS app must be called implicitly from your application, through the following action string.

Request data model

To send a request to the terminal, you must send an object that contains all the required properties. Below is the list of all the properties available in the request by operation type.

Property	Type	Sale	Refund	Description
`transaction`	String	Required	Required	Transaction type: `venta` (sale) or `devolucion` (refund).
`userToken`	String	Required	Required	Your user token. Set via `.setUserToken(...)`. Unlike Mobile web (Links), the property/method name is camelCase — there is no raw query string key involved.
`identifier`	String	Required	Required	An identifier generated on your side for transaction traceability. It is returned in the response. 256 characters maximum.
`amount`	Decimal	Required	N/A	Transaction amount. Does not include tip. Two decimals.
`urlScheme`	String	Required	Required	App, webhook or URL scheme to be called at the end of any transaction. This app should be ready to handle the POS app call. 50 characters maximum.
`transactionId`	String	N/A	Required	Original transaction ID generated by us, to be refunded.
`tip`	Decimal	Optional	N/A	Tip included in the transaction. Two decimals.
`msi`	Integer	Optional	N/A	Defer a payment. Number of monthly installments: `0` (one-time payment), `3`, `6`, `9` or `12`.
`reference`	String	Optional	N/A	Text reference to identify the transaction. 256 characters maximum.
`email`	String	Optional	N/A	Customer's email (when provided). 150 characters maximum.
`phone`	String	Optional	N/A	Customer's phone number (when provided). 14 characters maximum.
`showPhotoButton`	Boolean	Optional	N/A	Allows attaching a photo during the transaction. Default `false`.
`mandatoryPhoto`	Boolean	Optional	N/A	Makes the photo mandatory during the transaction. Requires `showPhotoButton` set to `true`.
`deviceToken`	String	Optional	N/A	String identifier for the device. Set via `.setDeviceToken(...)` — camelCase, same note as `userToken` above.
`3pID`	String	Optional	N/A	Identifier for the third party requesting the transaction.
`hidePrinter`	Boolean	Optional	N/A	Specifies whether the printer option is displayed after a successful transaction. Set via `.setHidePrinterOption(...)`.
`skipMailPrint`	Boolean	Optional	N/A	Specifies whether the ticket is automatically sent after a successful transaction. Requires an email or phone number set, and skips the send-ticket activity.
`xpLandscape`	Boolean	Optional	N/A	Specifies whether the POS app launches in landscape mode. Only applies to large screens.
`deviceName`	String	Optional	N/A	Name to identify the device.
`setTimerFinishTRX`	Integer	Optional	N/A	Timer (in seconds) to continue to the next screen if there is no user interaction on the confirmation screen. Requires POS app version 4.3.36 or higher and billpocket-integration dependency 2.30.0 or higher. Note: the underlying field is called `timerFinishTRX` (without `set`) in Cloud Terminal API's `extras.timerFinishTRX` and in the Links typed extra of the same functionality — the `set` prefix here is specific to this table's naming, not a different field.
`autoPaymentEnabled`	Boolean	Optional	N/A	Set to `true` to activate the collection process automatically, without pressing the Cobrar button. Same type as `extras.autoPaymentEnabled` in Cloud Terminal API and as the typed extra used in Mobile web (Links).
`enableDialogTip`	Boolean	Optional	N/A	If sent as `true` and no tip was sent (omitted or $0), the tip dialog is displayed during checkout. Pending confirmation — see the note above; not yet confirmed as a supported `BPIntentBuilder` setter.

Sale

Call the POS app through the following action string:

com.billpocket.payments.START

Start the POS app through the builder function by sending an Intent with all required parameters.

Refund

To use the refund functionality, make sure to include the following import in your project:

Refund a previously authorized transaction through an Intent by sending the transaction ID. The refund of the transaction must be made the same day of the sale, before 23:00 (22:59:59) CDMX time. View all the required parameters to refund a transaction.

Note

The transaction must be authorized within 1 minute or more at the time of a refund.

There are two ways to perform the intents.

Option 1 — With transaction ID validation

Use the transaction ID existence authentication service:

This is the validation of the service in the listener:

Option 2 — Direct intent

Send the intent directly, without validating the transaction ID existence service:

Response

The response is received by the calling Activity's onActivityResult method as an Intent, which contains the result of the transaction request. You can parse it to a BPPaymentResponse object.

Response data model

Depending on the result of the operation, you may receive additional information through the following properties:

Property	Type	Description
`result`	String	The result of the operation: `aprobada` (approved), `rechazada` (declined) or `error`.
`statusinfo`	String	In case of error, additional information is returned.
`amount`	Decimal	Transaction amount. Does not include tip.
`tip`	Decimal	Tip included in the transaction.
`reference`	String	Text reference to identify the transaction.
`transactionid`	String	Transaction ID generated by us.
`msi`	Integer	Number of monthly installments the payment was deferred to: `0` (one-time payment), `3`, `6`, `9` or `12`.
`authorization`	String	Authorization given by the issuer bank.
`creditcard`	String	Last 4 digits of the card.
`cardtype`	String	Card type.
`email`	String	Customer's email (when provided).
`phone`	String	Customer's phone number (when provided).
`arqc`	String	Card's chip validated cryptogram (when available).
`aid`	String	Card's chip application identifier (when available).
`applabel`	String	Card's chip application label (when available).
`url`	String	Identifier to obtain a digital voucher.
`identifier`	String	Identifier sent during the sale for traceability.
`bank`	String	Card issuer.
`accountType`	String	Account type: `credit` (credit card) or `debit` (debit card).
`name`	String	Cardholder name.
`bp_version`	String	POS app version.

POS app settings

Enable or disable features within the settings in the POS app.

Tips

To use tips through Intents, it is necessary to activate the option in the settings menu.

Billpocket POS app settings menu on Android

Activate the Propina option.

Propina option enabled in the POS app settings

Now, if a transaction is submitted with a tip amount greater than 0, a new label is displayed below the transaction amount.

Tip label shown below the transaction amount on the payment screen

If no tip amount is sent in the request, or if it is equal to 0 and the tip option is activated in the app settings, the tip dialog is displayed.

Do you need access to the terminal printer?

Check the manufacturer's documentation.

Resources

Check out the following demos and dependencies:

Android intents demo

GMS dependency

Printer documentation

Got a suggestion on this documentation? Contact us.

Requirements#

Adding the SDK to your project#

Building the Intent#

Calling the POS app#

Request data model#

Sale#

Refund#

Option 1 — With transaction ID validation#

Option 2 — Direct intent#

Response#

Response data model#

POS app settings#

Tips#

Resources#

Requirements

Adding the SDK to your project

Building the Intent

Calling the POS app

Request data model

Sale

Refund

Option 1 — With transaction ID validation

Option 2 — Direct intent

Response

Response data model

POS app settings

Tips

Resources