Get Started

 

Implement telemetry

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

Create A Session Token

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.

Send a POST /session_tokens API request with the merchant's Account ID. Your request will look like this:

Copy
Copied
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}"
  }
}'

The response will provide a session_token value. Here is an example response:

Copy
Copied
{
	"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

Once you've received a successful response from POST /session_tokens, you'll be able to configure and 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 WePay. If the device goes offline, the SDK will still collect data and then send it to WePay once the device is online again.


Build A Mobile App for Mobile Card Readers

This section is specific to integrating mobile card readers with your mobile application, and describes how to configure your mobile app to work with card reader hardware. Use the Card Present SDK in your integration, see integration prerequisites and steps on how to get started. Your mobile app will need to configure the following:

applicable
not applicable

Item to ConfigureRP457c AudioJackMoby 5500
Firmware Updatesrequired
Receiptsrequired
Funding Sourcesrequired
End User Interactions
Microphone Permissions
Location Permissions
Notification Permissions
Battery Level
Volume
Unsupported Devices
Orientation

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.

Use the firmware update version and category parameters on the card reader info method in the SDK to know when a firmware update is required. The category parameter will contain one of none, recommended, or required. When a new version is required, begin your own testing and development on the new version, release any changes needed, and then make the update available to your merchants.

Firmware updates are almost always optional (recommended category), and upgrading in those cases is up to you. WePay does, however, highly recommend being on latest version as much as possible to take advantage of enhancements and fixes.


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.

For further receipt requirements, see the Card Present receipt guide.

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.

For iOS, this information will be returned on WPAuthorizationDelegate or WPCardVerificationDelegate, and for Android it will be returned on onEMVApplicationSelectionRequested().

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 which processing a transaction may involve. For instance:

  • Signature collection
  • Adding tip
  • Attempt a new authorization

All the interactions which 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 somewhat 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 explaining why microphone access is needed.

Location

Location permission is optional, as you may turn it off at any time. That said, WePay relies 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 WePay's 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.

Warning

When a transaction is started, a (normally inaudible) signal is sent to the headphone jack of the phone, where the reader is expected to be connected. If headphones are connected instead of the reader, they may emit a very loud audible tone on receiving this signal.


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. WePay has tested the iPhone 7 adapter supplied with the phone and it works. WePay is 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.

WePay cannot guarantee support with devices not on ROAM's support list, but WePay does work closely with ROAM to get the latest devices profiled and added to the WePay Card Present SDK.


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.

WePay suggests 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.