App to App — Mobile Web - Kushki Developer Portal

Open the point of sale (POS) app from a native or mobile web app on Android using custom URL schemas to process payments through a terminal.

INFO

Service available in Mexico 🇲🇽 only.

Requirements

In order to call the POS app from a mobile web application within an Android device, you must meet the following requirements:

A valid account

The latest available version of the Billpocket POS app installed on Android

A supported Billpocket reader

Calling the POS app

Collect and send all the required string and decimal parameters in the URL as a query string when calling the POS app to perform an operation with a terminal. The POS app is displayed when you open a link with the custom URL scheme Billpocket://. The transaction is configured according to the parameters received in the call.

Boolean and Integer parameters are not read from the query string

The POS app parses Boolean and Integer values as native types. A URL query string can only carry text, so those parameters are not read reliably if they only travel in the URL.

To use any of the parameters listed in Typed Intent extras, attach them as typed Android Intent extras (Intent.putExtra(...)) on the same ACTION_VIEW intent that opens the billpocket:// URI — see the native Android example below.

Supported operations

Sale

Refund

Request data model

To send a request to the terminal, you must send an object that contains all the required properties. The properties are split into two groups, because they travel through two different mechanisms on the same call.

Query string parameters

String and Decimal parameters. Send these as the query string of the billpocket:// URL, using the exact key shown in the Property column below.

Property	Type	Sale	Refund	Description
`transaction`	String	Required	Required	Transaction type: `venta` (sale) or `devolucion` (refund).
`usertoken`	String	Required	Required	Your user token. The query string key is lowercase. This same value is called `userToken` (camelCase) in Android intents and in the SDK — the POS app does not recognize the camelCase key in links.
`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.
`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.
`devicetoken`	String	Optional	N/A	String identifier for the device. The query string key is lowercase. This same value is called `deviceToken` (camelCase) in Android intents and in the SDK.
`3pID`	String	Optional	N/A	Identifier for the third party requesting the transaction.
`deviceName`	String	Optional	N/A	Name to identify the device.

Typed Intent extras

Boolean and Integer parameters. Send these as typed extras on the Intent that opens the billpocket:// URL — not as query string text. See Sale from a native Android app.

Property	Type	Sale	Refund	Description
`msi`	Integer	Optional	N/A	Defer a payment. Number of monthly installments: `0` (one-time payment), `3`, `6`, `9` or `12`.
`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`.
`hidePrinter`	Boolean	Optional	N/A	Specifies whether the printer option is displayed after a successful transaction.
`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.
`enableDialogTip`	Boolean	Optional	N/A	Set to `true` to display the tip dialog during checkout. For the dialog to be displayed, `tip` must be omitted or sent with the value `0`.
`autoPaymentEnabled`	Boolean	Optional	N/A	Set to `true` to activate the collection process automatically, without pressing the Cobrar button. Same type used in Android intents and in Cloud Terminal API's `extras.autoPaymentEnabled`.
`setTimerFinishTRX`	Integer	Optional	N/A	Timer (in seconds) to continue to the next screen if there is no user interaction on the confirmation screen. The typed extra key is `timerFinishTRX` (without `set`) — it matches `extras.timerFinishTRX` in Cloud Terminal API and the reference Android implementation.

Important

Booleans must be sent as true / false, never as 1 / 0.

Sale

Here is an example of how to call the POS app via custom URL schema on Android to make a sale. This covers String / Decimal parameters only — use it from a mobile web page or WebView.

Sale from a native Android app

A pure browser window.location.replace(...) call cannot attach typed Intent extras — that requires a native Android caller building the Intent directly. Use this pattern whenever the sale needs any Boolean / Integer parameter from Typed Intent extras:

If the information sent is correct, the POS app opens on the payment screen with the configuration set for the transaction. Follow the on-screen steps to complete the collection process with the terminal.

Refund

Here is an example of how to call the POS app via custom URL schema on Android to make a refund:

Chrome intents

You can also create an Intent from a web application running on Chrome to start the integration process with an installed instance of the POS app.

Note

Integrations via Chrome intents do not return a response via a URL callback. To get the response, you can implement a webhook to receive the events in your application.

Check out the Android Intents with Chrome reference for more information.

POS app settings on Android

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.

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. This is the same behavior triggered by enableDialogTip.

Response

Receive the response of a request through a URL callback. The response is returned via custom URL schemas. The URL callback must correctly process the requests with the operation response.

You can place a custom URL scheme in the callback URL. You will need to register your custom URL scheme within your application so that it can handle incoming requests. Review the Android documentation on how to register custom URL schemes.

Below is an example of a response to a custom URL schema:

myApp://identifier=bpTRX&amount=10.00&authorization=BP6602&result=aprobada&reference=Venta%2520-%2520B99773E6BA6&creditcard=3292&cardtype=MASTERCARD&aid=A0000000041010&tip=1.01&url=68a30855f20923fc0d20eeaeee11061a62ab0eec&arqc=3C2A4D155F23AA81&bank=Bancomer%2520%252F%2520Banamex&name=%2520PERFIL%2520EJECUTIVO%252FPRG%2520%2520%2520%2520%2520&bp_version=4.3.0&transactionid=111029&accountType=DEBIT&applabel=Debit%2520Mastercard

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.

Got a suggestion on this documentation? Contact us.

App to App — Mobile Web

Requirements#

Calling the POS app#

Supported operations#

Request data model#

Query string parameters#

Typed Intent extras#

Sale#

Sale from a native Android app#

Refund#

Chrome intents#

POS app settings on Android#

Tips#

Response#

Response data model#

Requirements

Calling the POS app

Supported operations

Request data model

Query string parameters

Typed Intent extras

Sale

Sale from a native Android app

Refund

Chrome intents

POS app settings on Android

Tips

Response

Response data model