Connect Mobile Card Readers

Before a card reader can be used, it must be paired with the merchant's mobile device.

Pair a Moby 5500 Reader

Moby 5500 button and LED configuration

Connect the mobile device to WiFi.
Turn on the mobile device's Bluetooth.
Push the card reader's power button until the reader beeps (2-3 seconds). If the reader is sufficiently charged the Bluetooth readiness LED should be flashing, indicating that it is ready to pair.
If the battery status LED is solid red, then the reader needs to be charged. If so, plug the reader into its charging cable and continue. The battery status LED will begin flashing red to indicate that it is charging.
Configure the SDK and initialize it (outlined below).
For initial setup of a reader, it must go through configuration outlined below.
A request to pair the reader will be initiated from the SDK (more on this below).
Show the request from the SDK to the merchant on your mobile app, with UI for the merchant to verify that the LED sequence matches. Upon successful confirmation, pairing is complete.
To turn off the reader hold the power button until the Bluetooth readiness LED is solid blue, then release the power button.

Pair an RP457c AudioJack

Connect the mobile device to WiFi.
Turn on the mobile device's Bluetooth.
Plug the reader into the mobile device's audio jack port.
Push the power button on the side opposite the audio jack until the reader beeps. The light next to the power button should be flashing blue at this point, indicating that it is ready to pair.
Ensure the reader is sufficiently charged. If the light on the same side of the audio jack is solid red, then the reader needs to be charged. If so, plug the reader into its charging cable and continue. The light next to the charging port will begin flashing red to indicate that it is charging.
Configure the SDK and initialize it (outlined below).
For initial setup of a reader, it must go through configuration outlined below.
A request to pair the reader will be initiated from the SDK (more on this below).
Complete pairing in the devices Bluetooth settings.

Create a Session

Before the pairing process can complete, the SDK must be configured with the merchant's Account ID and session token.

To create a session token for the merchant, 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}"
	}
}

Note

The time-to-live (TTL) for a session token is 5 minutes. Once the session token is used in a Card Present SDK function, it will remain active for 12 hours.

Next, configure the Card Present SDK with the session token, the merchant's Account ID, and your App ID, and initialize the SDK (this is one of the steps in pairing a device outlined above). Use the get card reader info function to initialize the SDK.

Handle Session Initialization Errors

The first time a session token is required (e.g. if this is the first method call into the SDK or the SDK has never had a valid session) the delegate method didRequestSessionTokenWithCallback will be called. If the session is valid, the method sessionDidSucceed will executed next, and the remaining requests will continue to execute. In the event the session fails, the failure will be reported in the sessionDidFailWithError delegate method.

If a valid session token is not provided, every subsequent call to the SDK will return the didRequestSessionTokenWithCallback method. This method will be called during every request until a valid session token is provided. The explanation above pertains to an IOS integration, see fxn mapping below for android integrations.

WePay iOS Function	WePay Android Function
`sessionDidSucceed`	`onSessionSuccess`
`sessionDidFailWithError`	`onSessionFailure`
`didRequestSessionTokenWithCallback`	`onSessionTokenRequested`
`refreshSessionWithToken`	`refreshSession`

See the SDK integration guide for further instruction on how to retrieve a new session token using the POST /session_tokens endpoint.

Session Initialization Failures

A failed session will be reported in the sessionDidFailWithError delegate method and should be followed by a request to make a new session token through POST /session_tokens.

Some of the most common errors that can lead to a failed session include:

WePay iOS Error	WePay Android Error	Description
`WPErrorUnknown`	`UNKNOWN_ERROR`	An unknown error occurred during session authentication.
`WPErrorNoDataReturned`	`NO_DATA_RETURNED_ERROR`	No data was returned during the session authentication.
`WPErrorSecureSessionNotActive`	`SECURE_SESSION_NOT_ACTIVE`	A session could not be initialized.

Invalid Session

A number of errors can manifest due to an invalid session. These will be returned within the error delegate method for the action you tried to perform. When encountering one of the session error codes below, manually refresh the session token by calling the refreshSessionWithToken method with your WePay instance. This is where you will provide a new session token that will be used to authenticate the user.

These error codes include:

WePay Error	Description
`WPErrorSecureSessionNotActive`	A session could not be initialized.

Set Up a Reader

The first time a card reader is paired with a mobile device (and after firmware updates), the card reader is configured by the Card Present SDK. Upon initialization, the SDK will return a “configuring” status until the Ingenico profile is uploaded to the device. Your app should notify the user to wait for this to complete.

If the user uninstalls and re-installs your app, then the device will be configured again on the next use.

Select a Reader

Once you have a session token and you've used it to initialize the Card Present SDK, you can use a mobile card reader to interact with the SDK.

The first time a merchant's mobile device wants to interact with a card reader after the Card Present SDK has been initialized, the SDK helps your app detect and choose which mobile card reader to use. The steps are:

Power on the reader. For the Moby 5500 make sure that Bluetooth is enabled on the mobile device. In the case of the RP457c AudioJack, connect it to the audio jack.
Initialize the Card Present SDK

Remember that if this is the first time a card reader is being used with the Card Present SDK, it will automatically be configured when the first interaction is attempted.

Begin a transaction with the start transaction function
The Card Present SDK will look for devices available via Bluetooth (Moby 5500) or audio jack (RP457c AudioJack) and return a complete list of all devices found. Note: if there are headphones plugged in to the audio jack, this will show up as an available device.
The Card Present SDK will return this list to your mobile app. Your app can decide to either ask the user which device they want to pair, or choose the device for them. For example, if you know the merchant doesn't have an RP457c AudioJack, then your app can eliminate this choice and thus avoid any confusion with headphones.
The Card Present SDK will attempt to connect to the selected device.
The SDK will store card reader information about the last successfully connected device. This information can be queried using the get remembered card reader info call, or purged using the forget remembered card reader info call. That said, the Card Present SDK will not automatically connect to a remembered device, so we recommend building this logic into your mobile app (as implemented in the WePay example app).

Questions? Need help? Visit our support page!