iOS Integration

This document describes the integration methods available for you as a 3rd-Party Developer to communicate and use Billpocket's payment app from within your app.

Billpocket allows any app to process payments through itself, the following pages will detail the format, parameters, and semantics of the requests handled by Billpocket's app, as well as the response parameters and values.

Overview

Introduction to URL schemes and communication

URL Schemes

URL schemes implementation was introduced in iOS 6. The main purpose of this communication protocol is to allow interaction between native and web apps. URL communication can happen between native apps or web and native apps.

The most similar comparison to URL schemes communication is the HTTP GET protocol. The parameters are sent using concatenated strings of subsequent ‘var=value’ sentences separated by any special character (the convention is to use the & ampersand symbol).

The URL scheme for each app should be declared in the source code to set up the app to listen to these calls. An example of a valid URL scheme could be myapp:// where you can observe that the traditional protocol scheme (HTTP, HTTPS, FTP, mailto, etc) has been replaced by a custom one.

How to call an app through a URL scheme

URL scheme communication is based on the simplicity of using a formatted string to call a service with specific parameters. In iOS applications, URLs are opened through the openURL method from the NSApplication class.

An example of how to open URLs in Xcode is included in the Sender App Explained section.

How does URL scheme communication works

The app that is being called through URL’s has the most work when handling incoming requests since it has to specify the way the calls are going to be received, handled, and processed in order to create a valid response for the requesting app or method. So, to any native app willing to accept URL scheme calls 4 different components should be developed and deployed:

Registering the custom URL scheme
Handling URL scheme calls
Processing URL scheme calls
Creating and/or communicating the response to the previous call

Registering a custom URL scheme receiver app

URL scheme registration specifies which URLs to redirect to your app. Register your scheme in Xcode from the Info tab of your project settings. Update the URL Types section to declare all of the URL schemes your app supports, as in Figure 1:

Specify the prefix you use for your URLs in the URL Schemes box.
Choose a role for your app:
- Specify an editor role for URL schemes that you define.
- Specify a viewer role for schemes that your app adopts, but does not define.
Specify an identifier for your app.

Figure 1. URL Types section

The identifier you supply with your scheme distinguishes your app from others that declare support for the same scheme. To ensure uniqueness, specify a reverse DNS string that incorporates your company’s domain and app name. Although using a reverse DNS string is a best practice, it does not prevent other apps from registering the same scheme and handling the associated links. Use universal links instead of custom URL schemes to define links that are uniquely associated with your website.

You can't claim support for some well known URL schemes, including HTTP, HTTPS, mailto, tel, SMS, Facetime, and Facetime-audio. The system directs well-known types of URLs to the corresponding system apps, and well-known HTTP–based URLs to specific apps such as Maps, YouTube, and Music. For information about the schemes supported by Apple, see Apple URL Scheme Reference.

Handle Incoming URLs

When another app opens a URL containing your custom scheme, the system launches your app, if necessary, and brings it to the foreground. The system delivers the URL to your app by calling your app delegate’s application:openURL:options: method. Add code to the method to parse the contents of the URL and take appropriate actions. To ensure the URL is parsed correctly, use NSURLComponents APIs to extract the components. Obtain additional information about the URL, such as which app opened it, from the system-provided options dictionary.

Displaying a Custom Launch Image When a URL is Opened

Billpocket can display a custom Splash/Launch image when it is opened by your app. To do this, you must provide the assets you want to be included as splash screens, at the sizes needed for all the devices you wish to support, including variants for retina displays. You can find more about the correct image sizes at Apple Layout documentation.

We will create and provide you with a custom urlScheme for you to call our app and use the provided assets, the standard urlScheme (billpocket) will not showcase the custom assets.

Handling URL calls

When another app opens a URL containing your custom scheme, the system launches your app, if necessary, and brings it to the foreground. The system delivers the URL to your app by calling your app delegate’s application:openURL:options: method. Add code to the method to parse the contents of the URL and take appropriate actions. To ensure the URL is parsed correctly, use NSURLComponents APIs to extract the components. Obtain additional information about the URL, such as which app opened it, from the system-provided options dictionary.

The URL calls must be handled with help of a Singleton a detailed example can be found in the Receiver App Explained section of this document.

Processing URL calls

Data received in the previously handled URL can be used to process a specific command, method, or class in the application. All data should be handled as an NSString object. The data need to be manipulated according to the parameters declared in the function of the singleton “urlSchemeParams”.

- (void)urlSchemeSaleParams:(NSString*)schemeURL 
                userToken:(NSString*)token 
                identifier:(NSString*)trx_id 
                amount:(NSString*)amount_trx
                transactionType:(NSString*)trx_type 
                payments:(NSString*)trx_payments 
                urlApp:(NSString*)app 
                showPhoto:(BOOL)photo;

You should store the values received in the URL in your app variables to work with them.

URL call responses

URL requests between Billpocket and other apps use the '&' (ampersand) symbol to separate pairs of variable names and values. To ensure the URL with the response being transmitted can be handled correctly by the third party application you should follow 3 simple steps:

Encode variable values to avoid calling errors
1. You can clean your variable names and values with the use of this method:
  URLScheme = [URLScheme stringByReplacingOccurrencesOfString:@"trx_urlScheme" withString:app];
2. in that specific order.
Concatenate the URL
1. You must create a URL with the variables values from the last step
Open the URL after verification
1. Call the URL using the openURL function after validating that it can be opened with canOpenURL

Request parameters

Variable	Description	Value type	Sale	Refund
transaction	The transaction type: Sale (venta).	enum(`venta`)	Mandatory	Mandatory
userToken	The Billpocket’s token identifier	varchar(64)	Mandatory	Mandatory
amount	The amount without tip of the charge.	NSNumber (2 decimals)	Mandatory	N/A
tip	The tip amount of the charge.	NSNumber (2 decimals)	Optional	N/A
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	N/A
reference	Text reference to identify the payment for the customer.	String (256 chars max)	Optional	N/A
email	The customer’s email when provided.	String (256 chars max)	Optional	N/A
phone	The customer’s mobile number when provided.	String (14 chars max)	Optional	N/A
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	Mandatory
urlScheme	App or web hook prefix 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	N/A
showPhotoButton	Whether to show the photo button to attach an image or a photo in the transaction. If the value is `true`, the photo isn’t mandatory to process the transaction, but you can attach it. The default value is `false`.	boolean	Optional	N/A
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	N/A
comesFromQR	This value is mandatory if the created url transaction is embedded in a QR image. For regular transactions that comes from an app-to-app integration, isn’t mandatory to send this value.	boolean	Optional	N/A
transactionId	Billpocket’s sale transaction identifier.	varchar(64)	N/A	Mandatory

urlScheme specifications

The URL Scheme sent in the urlScheme variable can be used to call either a native app or a webhook trigger. You can use one of both with just a bit of customization of the value and its format.

Native app. To call back a native app you just need to include the value of the URL Scheme detailed during the app building process (refer to Registering custom URL scheme receiver app).
1. urlScheme value
  1. myapp
2. Webhook
  1. myapp://result=aprobada&statusinfo=&amount=100.00&tip=15.00&reference=Pago%20%26%20%25%20%23%20(%20)%20/%20@%20con%20propina%20a%203%20meses%20sin%20intereses&transactionid=72037…

Response Parameters

Variable	Description	Value type	Approved	Declined	Error
result	The result of the operation. It can be: aprobada (approved), rechazada (declined) or error (error).	enum(`aprobada`, `rechazada`, `error`)	Mandatory	Mandatory	Mandatory
statusinfo	Any special message when something goes wrong. It includes the issuer bank message when declined.	varchar(40)		Mandatory	Mandatory
amount	Amount of the successful payment.	NSNumber (2 decimals)	Mandatory
tip	The tip of the successful payment.	NSNumber (2 decimals)	Optional
reference	Customer’s provided reference/description	varchar(256)	Optional
transactionid	Billpocket’s internal transaction ID	varchar(16)	Mandatory
msi	The length of the paying period for some promotions.	enum(3, 6, 9, 12)	Optional
authorization	Authorization given by the issuer bank	varchar(6)	Mandatory
creditcard	The last 4 digits of the card used to successfully process the payment.	varchar(4)	Mandatory
cardtype	The type of card used.	varchar(16)	Mandatory
email	The customer’s email (when available).	varchar(150)	Optional
phone	The customer’s mobile phone (when available).	varchar(14)	Optional
arqc	The card’s chip validated cryptogram (when available).	varchar(16)	Optional
aid	The card’s chip application identifier (when available).	varchar(14)	Optional
applabel	The card’s chip application label (when available).	varchar(28)	Optional
url	Identifier to obtain a digital voucher.	varchar(64)	Mandatory
identifier	The origin app’s database identifier.	varchar(256)	Mandatory	Mandatory	Mandatory
bank	The card's holder bank	varchar(64)	Mandatory
accountType	Wether the account is debit or credit	enum(`credit`, `debit`)	Mandatory

Sender App explained

Objective

Perform a valid URL call to the Receiver app and handle a valid URL call from the same app containing the response to the transaction request.

Valid URL call

In this example we use a group of textfields 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 like the textfields.

As stated at Introduction to URL schemes and Communication section we have to perform 3 activities to create a valid URL call:

Get variable values
1. Getting the correct values from your textfields and pass the values to the correct key of the URL ie.
  The relation of “trx_token" with “token” and in that way for all the parameters in the textfields
  
  URLScheme = [URLScheme stringByReplacingOccurrencesOfString:@"@"trx_token"" withString:token];

Concatenate URL path

a. This is the easiest step of the process and few instructions are needed: (1) concatenate the NSString and (2) cast the NSString to NSURL.

Example for sale

The mandatory parameters to request a sale are transaction with the value venta, amount in decimal format with a maximum of 2 decimal places, identifier an identifier of the transaction generated by the merchant and userToken.

To concatenate the NSString we use the stringWithFormat instruction as shown below.

Example for refund

The mandatory parameters to request a refund are transaction with the devolucion value, identifier a transaction identifier generated by the business, transactionId a sales transaction identifier and userToken.

Keep in mind that:

You must have the iOS 4.3.24 version or higher of the Billpocket app downloaded to process a refund. Otherwise, you will not be able to process this service.
In order to make a refund, 1 minute must have passed after the sale was authorized.
The refund of the transaction must be made the same day of the sale before 23hrs (22:59:59) CDMX time.

To concatenate the NSString we use the stringWithFormat instruction as shown below.

To cast the NSURL the URLWithString is enough and is shown below these lines.

NSURL *ourURL = [NSURL URLWithString:ourPath];

Open the URL after verification

a. The last step is to open the URL created, however the URL should be validated previously. The validation is made with the openURL method and, after it, you can open the URL with the openURL instruction.

An example is shown on how to handle an error in case it exists when calling the URL with help of a completion Handler.

Handle Receiver response

For didactic purposes, we use a UIAlertView to show the result of the transaction performed by the Receiver app. However, when developing your application you can handle the result with your preferred method. To handle the response and according to the Introduction to URL schemes and Communication section you need to perform 4 steps which are detailed in the following paragraphs. All these steps are performed in the AppDelegate.m file.

Eliminate the URL

The first step is to clean the received URL from anything useless for information processing purposes. The protocol created to receive URL calls is part of the string received so we must clean it out now that the information was received correctly. To perform this step we will use the stringByReplacingOcurrenceOfString method as shown below.

Separate elements in an array

Now we have a clean list of variable names and values separated by the standardized symbol “&”, so we can separate each pair of elements with a very simple instruction including the componentsSeparatedByString method as shown below.

NSArray *content = [urlHost componentsSeparatedByString:@“&”];

Separate array elements in name and value pairs

Now, to handle variables regardless of the order in the URL call, we will separate the variable names and values in 2 different arrays so the pairs are stored in the same array index. To perform this we will use a combination of componentsSeparatedByString and a for loop to catch the whole array:

Store result in local variables

The next step is to store the values received in local variables. This is a very delicate step because the app should consider each of the needed or implemented variables from the Receiver app to take the most gain of the received information. Therefore, when any update to Billpocket is made, the developer of your app should consider updating this parsing information by simply adding a new variable to catch new values. This complex process is URL alteration or incompletion proof. You will find the snippet of code included in the project. Only 3 variables are mandatory for this message (result, statusinfo, identifier), so you should consider evaluating if the other variables are found or not.

Receiver app explained

Objective

The receiver app’s purpose is to emulate the behavior of the Billpocket app. It works as a sandbox to perform testing and to help developers on their way to integrate with Billpocket.

It offers 3 different emulated responses which are the possible responses from the Billpocket app.

Transaction Approved

This is the desired output for every transaction. The message should include the mandatory variables at least and can include the optional variables when available. The transactionid is very important to identify the transaction when trying to perform a refund. The rest of the variables inform the details of the transaction. The url can be concatenated in order to visualize Billpocket’s transaction receipt as shown below.

Transaction Declined

When a transaction is declined by the issuer bank you will receive a “rechazada” value in the result variable. You can show the cardholder the value of the statusinfo variable because it contains the issuer bank response and can include indications for the cardholder.

You will also get the identifier property to identify which transaction went wrong and decide whether to try again or not.

Transaction Error

Billpocket’s team works every day to develop the best mobile payments app available, however we are humans and errors can occur. When something like this happens, please don’t worry. Our system includes an active error and crashes reporting module which tells everyone at the Billpocket’s bunker that something went wrong and we have to start working. We beg you to try again the transaction if this happens. Thank you!

User Tokens

How do they work?

User tokens are used to identify a user in the Billpocket platform. When provided as a parameter in your app’s request to Billpocket, our app will configure itself to behave as a new terminal for the given user. Successive calls with the same token will bear the same result.

If another User token is sent to Billpocket, it will configure itself to behave as if it was a terminal for this new user. This behavior enables your app to configure the current Billpocket installation for as many users as User tokens you manage.

User Tokens

User tokens are cryptographically-secure generated ID’s with a 1-to-1 relationship to our user base, and they’re used to know who is making a setup request when Billpocket’s app is called from the outside.

In this use-case, user tokens are the first configuration parameter required to setup a device and start the payments process. The second parameter is:

Device Tokens

Device tokens are short random-generated ID’s for each device registered in your account. These represent a device with a name or “Alias" and possibly some transactions related to them. Device tokens can be in 1 of 2 states: Dead or Alive.

Alive Tokens

These tokens are available for use. You can only configure new devices if the given token is alive. When you create a new device or request an existing device’s token in your web interface, the generated token is alive and ready to be used.

Dead Tokens

Dead tokens are not available for use. An alive token becomes dead when it is used to configure a device through App-2-App integration or regular usage in the Billpocket's app.

These are logically paired to a physical device and will continue working for that device only.

Building the Request

The User token must be included as described below

Variable	Description	Value type
usertoken	User token for 3rd Party use	String
devicetoken	Device token	String (8-12 chars)

Using URL’s

With Great Power Comes Great Responsibility

Remember that user tokens are sensitive data and should not be sent in a non-secure channel. Please transmit these using (at least) an SSL channel.

If you suspect a user token has been compromised, please notify our team to invalidate or rotate the token. Future calls with this invalidated token will be taken as errors.

Billpocket app download

Tap or click here to download the latest version of Billpocket app for iOS.