App to App — iOS - Kushki Developer Portal

Open the point of sale (POS) app from your iOS mobile app to process payments through a terminal. The POS application is called through a custom URL scheme.

INFO

Service available in Mexico 🇲🇽 only.

Requirements

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

A valid account

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

Be logged in within the POS app

A supported Billpocket reader

Calling the POS app

The POS app uses the custom URL scheme billpocket:// to receive requests from other apps. You can send parameters in the request to configure the operation to be performed. When a request is received, the application opens on the corresponding screen according to the request settings.

You can perform the following operations:

Sale

Refund

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. 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 custom URL schemes.
`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`.
`comesFromQR`	Boolean	Optional	N/A	Set to `true` if the transaction URL comes from a QR image.

Sale

Send a sale request from your app to the POS to process a payment with a terminal.

To make a sale request you must:

Set the transaction property to the value of venta.

Send your user token.

Send an identifier generated on your end for traceability. It is returned in the response.

Send a valid amount.

Send a urlScheme where the response will be returned.

You can also set a tip, defer a payment and other operations. Check the request data model to see all the parameters available in the request.

The parameters must be concatenated using a query string along with the custom URL scheme billpocket://.

Important

You must make sure you encode the parameters correctly before making a request.

Sale request example

In this example, the values necessary for the request are obtained through text fields to be concatenated to the URL.

The values of NSString are concatenated and converted to NSURL to form a valid URL.

To concatenate NSString use stringWithFormat as shown below.

Open the URL through the open() method.

If the request has been successful, the POS application is displayed on the payment screen with the configuration sent.

Refund

Send a request to process a refund from your app.

To make a refund, you must:

Set the transaction property to the value of devolucion.

Send your user token.

Send an identifier generated on your end for traceability. It is returned in the response.

Send a valid amount.

Send a urlScheme where the response will be returned.

Send the ID of the transaction to be refunded.

Review the request data model.

The parameters must be concatenated using a query string along with the custom URL scheme billpocket://. You must make sure you encode your parameters correctly before requesting a refund.

Refund conditions

To be refunded, a transaction must meet the following conditions:

The original transaction must have been approved at least 1 minute ago.

The request must be made before 11 p.m. (CDMX time) on the same day the original transaction was made.

The refund must be for an amount equal to or less than the original transaction.

Note

To process a refund on iOS, you need POS app version 4.3.24 or higher.

Refund request example

To concatenate NSString use stringWithFormat as shown below.

URLWithString is used to cast the NSURL response.

Open the URL through the open() method.

If the request has been successful, the POS application is displayed on the payment screen with the configuration sent.

Response

Find out if the request was successful (aprobada), rejected (rechazada), or if there was an error (error) through the result property returned in the response.

The response is sent along with the operation parameters to the URL established in the urlScheme property. The structure of the payload is encoded using a query string, so it has a similar structure to the request. You must process the response correctly to continue with the payment flow.

Among the important parameters returned in the response is the transactionId property, which contains the ID of the approved transaction and allows you to perform other operations, such as a refund.

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.

Example of a response

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…

You can implement a Custom URL Scheme or a Universal Link to handle the response in your application. See Apple's documentation on how to allow apps and websites to link to your content.

App to App — iOS

Requirements#

Calling the POS app#

Request data model#

Sale#

Sale request example#

Refund#

Refund conditions#

Refund request example#

Response#

Response data model#

Example of a response#

See also#

Requirements

Calling the POS app

Request data model

Sale

Sale request example

Refund

Refund conditions

Refund request example

Response

Response data model

Example of a response

See also