Android: Integration for the sale service

Owned by Julieth Sandoval (Unlicensed)
Last updated: May 03, 2024 by Bryan Diaz

App to App Integration

 

You can integrate your application using Intents or Android App Links with Billpocket services on Android.

 

 

Intents integration

 

An Intent is a messaging object that can be used to request an action from another component in an application. You can start a new Billpocket instance by passing an Intent with the required parameters when starting the activity.

 

Calling Billpocket from your app

 

Android supports 2 kinds of Intents, explicit and implicit:

  • Explicit Intents are the ones you usually use to call Activities that are part of your app.

  • Implicit Intents are only supplied a general action to perform and, optionally, data to communicate to the app responding to the request. The Android system will look up for any app capable of handling your request and let the user choose if there is more than 1 option to choose from.

 

Billpocket app should be implicitly called from your app, by supplying the following action String:

com.billpocket.payments.START

 

As long as you provide the mandatory parameters to request a transaction, Billpocket will be launched when the Intent is passed to your Activity’s onActivityResult() method.

You can build the intent by using the BPIntentBuilder supplied by the library:

 

Intent intent = new BPIntentBuilder() .setAction(BPIntentBuilder.INTEGRATION_ACTION_BILLPOCKET) .setTransactionType(...) //set parameters .build()

 

Building the Intent

 

In this example we use a group of text fields to capture the value of each variable. When developing your app you can use any kind of object to capture each value. For didactic purposes, we will use visible elements, such as text fields.

As stated before, we will build the intent using the BPIntentBuilder and set INTEGRATION_ACTION_BILLPOCKET as the action:

 

BPIntentBuilder builder = new BPIntentBuilder() .setAction(BPIntentBuilder.INTEGRATION_ACTION_BILLPOCKET);

 

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

 

builder.setTransactionType(BPIntentBuilder.TRANSACTION_TYPE_SALE) .setIdentifier(...) .setDescription(...) .setMailRecipient(...) .setSmsRecipient(...) .setUserToken(...) .setShowPhotoButton(...) .setMandatoryPhoto(...) .setHidePrinterOption(...);

 

Once you have added all the parameters you need, you are ready to build the intent and request Billpocket to process your transaction:

 

Parameters

Parameters

intent

Intent: The intent to start.

 

Tips

 

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

 

app-settings.png

 

Activate the Propina option.

 

enable-tip.png

 

Now, if a transaction is submitted with a tip amount greater than 0, a new label will be 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 application settings, the tip dialog will be displayed.

 

 

Handling Billpocket's response

 

Billpocket's response will be received by the calling Activity's onActivityResult method as an Intent, which contains in its extras the result of the transaction request but you can parse it to a BPPaymentResponse object.

 

 

 

Request Parameters

 

Name

Description

Value type

Sale

Name

Description

Value type

Sale

transaction

The transaction type: Sale (venta).

enum(‘venta’)

Mandatory

amount

The amount without the tip of the charge

String (Decimal format, 2 decimals)

Mandatory

tip

The tip amount of the charge. If the tip field is sent, a label with the amount of the tip is displayed on the payment screen; if it is not sent, this new label is not displayed.

String (Decimal format, 2 decimals)

Optional

reference

Text reference to identify the payment for the customer.

String (256 chars max)

Optional

msi

Requested deferred-payments plan for this transaction. A value of 0 enforces a 1-installment payment, sending 3, 6, 9, or 12 will cause the transaction to be sent for authorization with the given deferral program. You can check your available payment plans and minimum amounts with us during the integration process

enum(0, 3, 6, 9, 12) May vary between users

Optional

email

The customer’s email when provided.

String (150 chars max)

Optional

phone

The customer’s mobile number when provided.

String (14 chars max)

Optional

identifier

An identifier your app can relate the payments with its database, we will echo this field in the response.

String (256 chars max)

Mandatory

urlScheme

App, webhook or url-schema to be called at the end of any transaction. This app should be ready to handle Billpocket’s call (see Sender App Explained section for more information).

String (50 chars max)

Optional

userToken

A string identifier for the user

String

Mandatory

deviceToken

A string identifier for the device

String (8-12 chars)

Optional

showPhotoButton

Whether to show the photo button to attach an image or a photo in the transaction. If the value is true, you can attach it. The default value is false. The photo isn’t mandatory to process the transaction.

Boolean

Optional

mandatoryPhoto

Sending a photo is mandatory or not to process the transaction. To take into account this parameter, it is necessary to send a true value in showPhotoButton.

Boolean

Optional

 

3pID

Specify an identifier for the third party requesting the transaction

String

Optional

hidePrinter

Specify if the printer option should be displayed after a successful transaction or not

Boolean

Optional

skipMailPrint

Specify if the ticket should be automatically sent after a successful transaction or not, this requires a mail or phone number set and will skip the send ticket activity

Boolean

Optional

xpLandscape

Specify if the orientation of the launched activity should be landscape, only for big screens

Boolean

Optional

deviceName

A string identifier to name an integration device so that your app can relate which device is making the sale.

String

Optional

 

 

Response Parameters

 

Name

Description

Value type

For approved transaction

For error transaction

result

The result of the operation. It can be only: aprobada or error

aprobada: Transaction completed successfully (issuer approved)

error: Transaction manually canceled by the user

 

enum(“aprobada”, “error”)

 

Mandatory

 

Mandatory

statusinfo

Any special message when something goes wrong. It includes the issuer bank message when declined.

String (40 chars max)

Mandatory

Mandatory

amount

Amount of the successful payment.

String (Decimal format, 2 decimals)

Mandatory

Mandatory

tip

The tip of the successful payment.

String (Decimal format, 2 decimals)

Optional

Optional

reference

Customer’s provided reference/description

String (256 chars max)

Optional

Optional

transactionId

Billpocket’s internal transaction ID

String (16 chars max)

Mandatory

N/A

msi

The length of the paying period for some promotions.

enum(3, 6, 9, 12)

Optional

N/A

authorization

Authorization given by the issuer bank

String (6 chars)

Mandatory

N/A

creditcard

The last 4 digits of the card used to successfully process the payment.

String (4 chars)

Mandatory

N/A

cardtype

The type of card used.

String (16 chars max)

Mandatory

N/A

email

The customer’s email (when available).

String (150 chars max)

Optional

N/A

phone

The customer’s mobile phone (when available).

String (14 chars max)

Optional

N/A

arqc

The card’s chip validated cryptogram (when available).

String (16 chars max)

Optional

N/A

aid

The card’s chip application identifier (when available).

String (14 chars max)

Optional

N/A

applabel

The card’s chip application label (when available).

String (28 chars max)

Optional

N/A

url

Identifier to obtain a digital voucher.

String (64 chars max)

Mandatory

N/A

identifier

The origin app’s database identifier.

String (256 chars max)

Mandatory

Mandatory

bank

The card's holder bank

String (64 chars max)

Mandatory

N/A

accountType

Whether the account is debit or credit

enum(“credit”, “debit”)

Mandatory

N/A

 

 

 

Integration through Android App Links allows you to interact with the Billpocket application through links, which are associated with the app.

 

Building the URL Query 

 

Billpocket is also enabled to handle URL HTTP-like requests from native, hybrid, and web apps.ﾠThe calling URL must specify billpocket as its protocol (billpocket://), followed by a string containingﾠthe transaction request parameters in a name=value format, using as separator the & symbol.ﾠ

 

Parameters names and values should be encoded according to RFC 3986.ﾠGiven this URL, your Web code must perform an HTTP redirection for the Intent to be caught andﾠdispatched successfully to Billpocket:

 

 

Request Parameters

 

Name

Description

Value type

Sale

Name

Description

Value type

Sale

transaction

The transaction type: Sale (venta).

enum(‘venta’)

Mandatory

amount

The amount without the tip of the charge

String (Decimal format, 2 decimals)

Mandatory

tip

The tip amount of the charge. If the tip field is sent, a label with the amount of the tip is displayed on the payment screen; if it is not sent, this new label is not displayed.

String (Decimal format, 2 decimals)

Optional

reference

Text reference to identify the payment for the customer.

String (256 chars max)

Optional

msi

Requested deferred-payments plan for this transaction. A value of 0 enforces a 1-installment payment, sending 3, 6, 9, or 12 will cause the transaction to be sent for authorization with the given deferral program. You can check your available payment plans and minimum amounts with us during the integration process

enum(0, 3, 6, 9, 12) May vary between users

Optional

email

The customer’s email when provided.

String (150 chars max)

Optional

phone

The customer’s mobile number when provided.

String (14 chars max)

Optional

identifier

An identifier your app can relate the payments with its database, we will echo this field in the response.

String (256 chars max)

Mandatory

urlScheme

App, web hook or url-schema to be called at the end of any transaction. This app should be ready to handle Billpocket’s call (see Sender App Explained section for more information).

String (50 chars max)

Mandatory

userToken

A string identifier for the user

String

Mandatory

deviceToken

A string identifier for the device

String (8-12 chars)

Optional

showPhotoButton

Whether to show the photo button to attach an image or a photo in the transaction. If the value is true, you can attach it. The default value is false. The photo isn’t mandatory to process the transaction.

Boolean

Optional

mandatoryPhoto

Sending a photo is mandatory or not to process the transaction. To take into account this parameter, it is necessary to send a true value in showPhotoButton.

Boolean

Optional

 

3pID

Specify an identifier for the third party requesting the transaction

String

Optional

hidePrinter

Specify if the printer option should be displayed after a successful transaction or not

Boolean

Optional

skipMailPrint

Specify if the ticket should be automatically sent after a successful transaction or not, this requires a mail or phone number set and will skip the send ticket activity

Boolean

Optional

xpLandscape

Specify if the orientation of the launched activity should be landscape, only for big screens

Boolean

Optional

deviceName

A string identifier to name an integration device so that your app can relate which device is making the sale.

String

Optional

enableDialogTip

If the field is sent as true and the tip field is not sent or is equal to 0, the tip dialog is displayed on the payment screen.

Boolean

Optional

 

 

This will trigger Billpocket app which will validate your data before letting you perform any operation. Calling Billpocket from its URL scheme introduces a new mandatory parameter: urlScheme, which is the callback URL which will be called to report the results of the operation.

 

Given urlScheme=“http://www.mywebhook.com/“, the URL to be called at the end of any operation

within the app would be: 

 

https://www.mywebhook.com?identifier=bpTRX&amount=10.00&authorization=BP6602&result=aprobada&reference=Venta%2520-%2520B99773E6BAD6&creditcard=3292&cardtype=MASTERCARD&aid=A0000000041010&tip=1.01&url=68a30855f20923fc0d20eefeee1cb61a62ab0eec&arqc=3C2A4D155F28AA85&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

 

The phone will open its default browser or show the available apps to open the URL. You should always choose a Web Browser (Chrome, Safari, Firefox) to ensure that the transaction results are sent to the correct address for you to process them. 

 

Tips

 

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

 

 

If you want the tip dialog to be displayed during the transaction, you need to set the enableDialogTip parameter to true. For this dialog to be displayed, the tip field must not be sent or must be equal to 0.

 

 

 

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 Billpocket.

 

As a caveat, integrations through Chrome Intents do not return a response to your web application. In order to get the transaction result, you can resort to our authorization webhook.

 

For more information, please follow https://developer.chrome.com/docs/multidevice/android/intents/

© Billpocket, 2018