Get Started

Implement telemetry

Allow us to monitor your Card Present SDK event data for diagnostics and general insights with telemetry.

Create A Session Token

The first step in implementing telemetry is integrating with session tokens.

If you've integrated Mobile Card Readers, you'll already be familiar with this process. In fact, Mobile Card Reader integrations will use the same session token for pairing the device and telemetry.

For Terminal integrations, you'll need to add this step.

curl -L -X POST 'https://stage-api.wepay.com/session_tokens' \
-H 'Content-Type: application/json' \
-H 'App-Token: {your-app-token}' \
-H 'Api-Version: 3.0' \
-H 'App-Id: {your-app-id}' \
--data-raw '{
  "type": "mobile_session",
  "mobile_session": {
    "account_id": "{merchant-account-id}"
  }
}'

{
	"id": "{session-token-ID}",
	"session_token": "stage_{token-hash}",
	"expire_time": 1560544108,
	"path": "/session_tokens/{session-token-ID}",
	"resource": "session_tokens",
	"owner": {
		"id": "{merchant-account-ID}",
		"path": "/accounts/{merchant-account-ID}",
		"resource": "accounts"
	},
	"create_time": 1560543108,
	"api_version": "3.0",
	"state": "active",
	"type": "mobile_session",
	"mobile_session": {
		"time_to_live": 86400,
		"account_id": "{merchant-account-ID}"
	}
}

Initialize The SDK

Configure the SDK initializer with this session token, the merchant's Account ID, and your app ID.

Once the SDK is up and running, event data will be collected and sent to us. If the device goes offline, the SDK will still collect data and then send it to us once the device is online again.

Build A Mobile App for Mobile Card Readers

Firmware Updates

Occasionally (0-1x per year), Ingenico will release a required firmware update in response to security patches, updated card network rules, etc., which cannot be resolved via the SDK. Your mobile application must provide merchants with a UI to download and install firmware updates.

Receipts

Receipts are required for Card Present payment processing.

• Electronic receipts can be delivered via email or phone, which your platform must build into your mobile app UI.
• Paper receipts require the use of a receipt printer, and there are bluetooth options available on the market.

Signature must be collected on electronic and paper receipts for NFC/contactless transactions. In addition, merchants who accept tips and/or wish to validate the terms of sale (such as "all sales final") are encouraged to collect signatures on receipts.

Funding Sources

Cards with chips can, and often do, have multiple “payment applications” on them. For example, there can be both a credit and a debit application. For cards that have multiple EMV applications or funding sources on them, the WePay Card Present SDK will return a list of available options, which your mobile app must display to the card holder so that they can select the desired funding source.

Card authorization cannot be completed until your mobile app completes a callback with the index of the card holder's funding source selection.

End User Interactions

When building your mobile app, consider any and all end user interactions that processing a transaction may involve. For instance:

• Collecting signatures
• Adding tips
• Attempting new authorizations

All the interactions that you plan for end users to engage in must be built into your app's UI.

Permissions

Your mobile app will need to obtain certain permissions from the user's mobile device in order to work with mobile card readers. The details of this are partly specific to iOS and Android.

Microphone

Microphone permission is required to access the audio jack. If your app does not request audio jack permissions up front, and then at some point decides it does want to offer the RP457c AudioJack, your app will need to be re-released.

The way permissions are presented to an app user are specific to iOS and Android:

• iOS: User will be prompted for permission the first time your app starts the card reader.
• Android: Before Android M, users will not be prompted. Starting from Android M, you will have to include code to prompt the user for permission before starting the card reader.

The card reader won't work if users decline microphone permission, so your mobile app should implement blocking UI to prevent mobile app use without microphone access and explain why microphone access is needed.

Location

Location permission is optional, as you may turn it off at any time. That said, we rely on location as part of our fraud detection tools, which include noting a device's location when transactions are made.

Although technically optional, not getting this significantly hinders our risk management ability. Please discuss with your account manager if you are not able to provide this permission.

Notifications

As outlined in the Card Present SDK package, collect notification permissions in order to perform bluetooth pairing on this device.

Battery Level

The Card Present SDK provides battery level information. You should provide some way in your app to show users what the current battery level is.

Volume

If your app programmatically enables speakerphone mode, then you must ensure that the speakerphone is turned off before starting a transaction. Otherwise, the Card Present SDK manages volume on the device so that the audio jack connection functions. It automatically increases volume levels for best performance.

Unsupported Devices

Because the RP457c AudioJack connects via audio jack, there may be two issues to consider, depending on the mobile device (phone or tablet) your merchant is using:

• No audio jack: generally an adapter will work. We have tested the iPhone 7 adapter supplied with the phone and it works. We are continuing testing on other models and will update documentation accordingly.
• Volume: Each device has different volume levels. The WePay Card Present SDK includes profiles for many devices. However, there is always a chance that a new phone model is not supported yet by the Card Present SDK. In the case of Android, there are many more devices than ROAM can reasonably test and profile. For this reason, there is a calibration ability within the WePay Android Card Present SDK that allows users to profile their own device. This almost always leads to supporting a device.

Orientation

The audio plug is near the side of the device, and mobile devices vary where the headphone jack is located. As a result, the device may naturally face “forward” or “backward”. This can lead to inserting the card for swipe or dip backwards.

We suggest that partners take note of the orientation on the most common mobile devices and visually indicate to users the right way to swipe/dip, perhaps as part of a first time use experience.