Take payments

Android
iOS

Accept payments with a terminal from your mobile point of sale through our POS app. You can integrate your app on Android using Intents and Links.

Intents

Execute an action in our POS application through an Intent on Android from your application. Install the SDK and send the required parameters when executing an action.

Adding the SDK to your proyect

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

repositories {
maven {
...
url 'https://billpocket.jfrog.io/artifactory/billpocket-public-mobile'
...
}
}

Add the following necessary dependencies:

dependencies {
...
implementation 'com.billpocket:billpocket-integration:2.30.0@aar'
...
}

Building the Intent

Create an instance of BPIntentBuilder class and set an action:

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

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

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

Request data model

These are all the parameters you can configure when making a request.

PropertyTypeRequiredDescription
transactionStringYesTransaction type: venta: Sale operation. devolucion: Refund operation.
userTokenStringYesUser token
identifierStringYesSend an identifier generated on your side for transaction traceability. It will be returned in the response. 256 characters maximum.
amountNumberYesTransaction amount. Do not include tip. Two decimals.
urlSchemeStringYesApp, 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.
tipNumberNoTip included in the transaction. Two decimals.
msiIntegerNoDefer a payment. Choose the number of monthly installments to defer payment:
  • 0 : One-time payment.
  • 3: 3 installments.
  • 6: 6 installments.
  • 9: 9 installments.
  • 12: 12 installments.
referenceStringNoText reference to identify the transaction. 256 characters maximum.
emailStringNoCustomer’s email (when provided). 150 characters maximum.
phoneStringNoCustomer’s phone number (when provided). 14 characters maximum.
showPhotoButtonBooleanNoIt allows you to attach a photo during the transaction. The default value is false.
mandatoryPhotoBooleanNoMake photography mandatory during the transaction. You will need to set the showPhotoButton property to true.
deviceTokenStringNoString identifier for the device.
3pIDStringNoSpecify an identifier for the third party requesting the transaction.
hidePrinterBooleanNoSpecify if the printer option should be displayed after a successful transaction or not.
skipMailPrintBooleanNoSpecify 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.
xpLandscapeBooleanNoSpecify whether the POS application will launch in landscape mode. Only applies to large screens.
deviceNameStringNoName to identify the device.
setTimerFinishTRXIntegerNoSet the timer (in seconds) to continue to the next screen in case there is no user interaction on the confirmation screen.

Operations

Discover all the operations available through App to App integrations.

Sale

Send a request with the required payment settings from your system to a terminal to perform the desired transaction.

Start the POS application via the builder function by sending an Intent with all the required parameters.

Intent intent = builder.build();
onActivityResult(intent);

If the information submitted is correct, the POS app will open to the payment screen with the transaction settings configured. Follow the steps on the screen to complete the payment process with the terminal.

Please review the documentation to perform a cancellation.

Tipping

You must enable the option in the settings menu to use tipping via Intents. Follow the steps below to enable tipping.

Click on the top left icon and select the Settings option.

Ajustes pos app

Activate the Propina option.

Habilita propina aplicación POS

If a transaction is set to a tip greater than 0, the tip amount will be displayed in a new label below the transaction amount.

Pantalla de pago aplicación POS

If no tip amount is submitted in the request or if it is equal to 0 and the tip option is enabled, the tip selection dialog will be displayed.

Diálogo de propina aplicación POS

Response

The response will be received as an Intent by the onActivityResult method of the calling activity.

private fun setupResultLauncher() {
resultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
if (result.resultCode == Activity.RESULT_OK) {
val data: Intent? = result.data
binding.btnResponse.performClick()
val response = BPPaymentResponse.parseResult(data)
binding.responseLayout.responseText.text = response.toString() }
}
}

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

PropertyTypeDescription
resultStringThe result of the operation. It can be:
  • aprobada: approved.
  • rechazada: declined.
  • error: error.
statusinfoStringIn case of error, additional information will be returned.
amountNumberMonto de la transacción (sin propina incluida). Dos decimales.
tipNumberTip included in the transaction.
referenceStringText reference to identify the transaction.
transactionIdStringTransaction id.
msiIntegerIf it is a deferred payment, the number of installments will be returned.
  • 0 : One-time payment.
  • 3: 3 installments.
  • 6: 6 installments.
  • 9: 9 installments.
  • 12: 12 installments.
authorizationStringAuthorization given by the issuer bank
creditcardStringLas 4 digits of the card.
emailStringCustomer’s email (when provided).
phoneStringCustomer’s phone number (when provided).
cardtypeStringCard type.
arqcStringCard’s chip validated cryptogram (when available).
aidStringCard’s chip application identifier (when available).
applabelStringCard’s chip application label (when available).
urlStringIdentifier to obtain a digital voucher.
identifierStringTransaction amount. Do not include tip.
bankStringCard issuer.
accountTypeStringAccount type:
  • credit: credit card.
  • debit: debit card.
nameStringCardholder name.
bp_versionStringPOS app version.

Simulate different scenarios with test data.

Perform an action in our POS app using custom URL schemes on Android from your native or web app. Set the URL with all the parameters required to open the POS app and perform the operation. The POS app will open when a link with the custom URL scheme Billpocket:// is clicked.

You need to have our POS app installed and configured on the same device as the point of sale app.

Request data model

These are all the parameters you can configure when making a request.

PropertyTypeRequiredDescription
transactionStringYesTransaction type: venta: Sale operation. devolucion: Refund operation.
userTokenStringYesUser token.
identifierStringYesSend an identifier generated on your side for transaction traceability. It will be returned in the response. 256 characters maximum.
amountNumberYesTransaction amount. Do not include tip. Two decimals.
urlSchemeStringYesApp, 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.
tipNumberNoTip included in the transaction. Two decimals.
msiIntegerNoDefer a payment. Choose the number of monthly installments to defer payment:
  • 0 : One-time payment.
  • 3: 3 installments.
  • 6: 6 installments.
  • 9: 9 installments.
  • 12: 12 installments.
referenceStringNoText reference to identify the transaction. 256 characters maximum.
emailStringNoCustomer’s email (when provided). 150 characters maximum.
phoneStringNoCustomer’s phone number (when provided). 14 characters maximum.
showPhotoButtonBooleanNoIt allows you to attach a photo during the transaction. The default value is false.
mandatoryPhotoBooleanNoMake photography mandatory during the transaction. You will need to set the showPhotoButton property to true.
deviceTokenStringNoString identifier for the device.
3pIDStringNoSpecify an identifier for the third party requesting the transaction.
hidePrinterBooleanNoSpecify if the printer option should be displayed after a successful transaction or not.
skipMailPrintBooleanNoSpecify 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.
xpLandscapeBooleanNoSpecifies whether the POS application will launch in landscape mode. Only applies to large screens.
deviceNameStringNoName to identify the device.
enableDialogTipBooleanNoSet the property to true to display the tip dialog during checkout. For the dialog to be displayed, the tip must be omitted or sent with the value of $0.

Operations

Discover all the operations available through App to App integrations.

Sale

Send a request with the required payment settings from your system to a terminal to perform the desired transaction.

Below is an example of how to call the POS application.

<script language=javascript>
function redirectBP(){
// Create the URL using JS
window.location.replace(“billpocket://?transaction=venta&amount=1.00&tip=.10&reference=mic00f&identifier=1001&usertoken=4db75ae65ab1fc0e067a68c3e6e0a53f25e0bb68384186b5be714ff1c0980d1a&urlScheme=https://www.mywebhook.com”)
}
</script>
<button onClick="redirectBP()">
Pagar con Billpocket
</button>

If the information submitted is correct, the POS app will open to the payment screen with the settings configured for the transaction. Follow the steps on the screen to complete the payment process with the terminal.

Please review the documentation to perform a cancellation.

Chrome Intents

You can also create an Intent from an app running in Chrome to perform an operation with the POS app.

Please review the documentation on Android Intents with Chrome.

Response

Receive the response of a request via a URL callback. The response is returned to a custom URL scheme that you define. You must register the custom URL scheme within your application so that it can handle incoming requests. Please review the documentation on how to register a custom URL scheme in Android.

Example response to a custom URL scheme:

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

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

PropertyTypeDescription
resultStringThe result of the operation:
  • aprobada: approved.
  • rechazada: declined.
  • error: error.
statusinfoStringIn case of error, additional information will be returned.
identifierStringIdentifier sent during the sale for traceability.
amountNumberTransaction amount. Do not include tip.
authorizationStringAuthorization given by the issuer bank
transactionIdStringTransaction id.
tipNumberTip included in the transaction.
msiIntegerIf it is a deferred payment, the number of installments will be returned.
  • 0 : One-time payment.
  • 3: 3 installments.
  • 6: 6 installments.
  • 9: 9 installments.
  • 12: 12 installments.
referenceStringText reference to identify the transaction.
emailStringCustomer’s email (when provided).
phoneStringCustomer’s phone number (when provided).
creditcardStringLas 4 digits of the card.
cardtypeStringCard type.
arqcStringCard’s chip validated cryptogram (when available).
aidStringCard’s chip application identifier (when available).
applabelStringCard’s chip application label (when available).
urlStringIdentifier to obtain a digital voucher.
bankStringCard issuer.
accountTypeStringAccount type:
  • credit: credit card.
  • debit: debit card.
nameStringCardholder name.
bp_versionStringPOS app version.

Simulate different scenarios with the test data.

Please review the Android reference for Intents or Links for more detailed information.


Test data
Make any necessary adjustments to your system using the test data.
Transactions
Get the list of transactions with information relevant to your operations.