In this section:
In this section:

WePay’s mobile point of sale (mPOS) solution lets your users accept in-person EMV and swiped credit card payments from their customers, using WePay’s card reader (optionally branded with your logo) paired with an iOS or Android device. Your users benefit from a single, consolidated platform to manage all of their payments, powered behind the scenes by WePay’s API.

Your users will accept in-person payments through your own merchant-facing app. WePay provides an SDK for you to integrate into your iOS and Android apps, along with the physical Bluetooth reader to pair with an iOS or Android device.

Who Can Participate

WePay’s mPOS program requires consultation and approval. Please contact your account manager or sales@wepay.com before beginning any implementation. Although platforms can be in any area that WePay supports, mPOS can only be used by merchants registered in the US.

Guide To mPOS Documentation

This doc explains the mPOS program. Developers looking to start integrating WePay’s SDK should start here. This document assumes you are familiar with WePay’s online (card not present) payment integration, and focuses on the additional steps needed to integrate mPOS.

Complete document includes:

  • This doc - the mPOS program overview
  • mPOS integration overview
  • The rest of WePay’s API docs for all server-to-server API calls
  • Mobile SDK including its documentation (linked from the mPOS integration overview)

Key Pieces Of The mPOS Program

The key pieces of the program are:

  • Brandable card reader hardware
  • Support for EMV (chip & signature), mag stripe (swipe), and manually keyed (virtual terminal) transactions.
  • The option to price card present, card not present, and virtual terminal transactions within a given fee schedule.
  • iOS and Android SDKs ready to integrate into a partner’s app, along with sample applications
  • Reporting updates to reflect transactions that are taken via mobile devices
  • Risk management policies tailored to card present transactions.

Integration Overview

A detailed technical guide is here. This section provides an overview of the technical and non-technical aspects of integrating mPOS into your platform.

On a technical level, the card reader essentially takes the place of tokenizing a credit card in a web browser using WePay’s custom checkout. All other aspects of an integration are the same for mPOS and the web, using the same server to server API calls.

Risk Management For mPOS

Consumers who buy products online know they can’t get their product shipped in seconds, which creates a natural window for offline risk review of transactions. WePay reviews a small percentage of online transactions today that can leave a transaction in the authorized state for up to 24 hours before it is captured. However, for mobile payments (especially when selling a physical good), merchants expect a transaction to be final on the spot.

To meet this need, WePay has special risk management procedures for mPOS:

  • Your platform needs to guide merchants thru KYC (Know Your Customer) before ordering a reader or making any mPOS transactions.
  • Your platform requests early review of the merchant using /account/request_review.
  • When the review is completed, the review status will be updated in /account and an IPN will be sent. WePay’s SLA for reviewing KYC information is 1 business day.

In return for the early KYC review, WePay modifies its transaction review policies:

  • For transactions processed via the card reader, WePay will not cancel an authorized transaction.
  • For transactions processed via virtual terminal (card keyed on the merchant’s device), WePay reserves the right to cancel suspicious transactions, but will generally not do so.

Developers should note that transactions will still go thru WePay’s normal risk review, and on occasion may remain in an authorized state for up to a day before being captured. The difference is that card present transactions will not be cancelled. Your platform should guide merchants to accept a card present transaction as final once it is in state authorized.

mPOS Implications For Your Mobile App

Integrating mPOS will place some requirements on your mobile app.

Application Permissions

Your mobile app will need to obtain certain permissions from the user in order to run. The details of this are somewhat specific to iOS and Android.

Microphone

This is recommended if using the Moby 3000, and is required to support the RP350x.

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 RP350x to some merchants, it will have 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.

If users decline, the card reader won’t work.

Location

This permission is needed so WePay can activate part of its 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.

Initial reader setup

The first time a card reader is used on a given phone/tablet, the card reader is configured by the SDK. This may take 30 seconds. Your app should message to the user they should wait for this to complete.

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

Device selection

The first time a merchant’s phone wants to use a card reader, the SDK helps your app detect and choose which device to use. The steps are:

  • Have the merchant power on the reader. For the Moby 3000 make sure that Bluetooth is enabled on the phone. In the case of the RP350x, connect it to the audio jack.
  • Begin a transaction
  • The SDK will look for devices available via Bluetooth (Moby 3000) or audio jack (RP350x) 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 WePay 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 can’t have an RP350x, then your app can eliminate this choice and thus avoid any confusion with headphones.
  • The WePay SDK will attempt to connect to the selected device. If the connection is successful, the device is remembered.

In future transactions, if the remembered device is found, the WePay mobile SDK will just use it without checking. Your app can always force the WePay mobile SDK to forget any previously remembered device and thus re-scan for available devices.

Battery Level

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

Volume

Note

This section is relevant to the RP350x device only.

If your app programmatically enables speakerphone mode, then you must ensure that the speakerphone is turned off before starting a transaction. Otherwise, the WePay SDK manages volume on the device so that the audio jack connection works fine. 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.

Taking Payments With A Card Reader

This is the typical payment flow that partners create by integrating the WePay SDK into the partner’s app:

  • Ensure the card reader is connected and get it ready to read a card (one SDK call)
  • Merchant “dips” a card (or swipes a card that does not have a chip)
  • SDK automatically attempts to read the card, tokenize it, and if successful, returns a token to the app.
  • Send the token to your app server, along with other payment info such as amount
  • Your server charges the card using /checkout/create and referencing the token, just like a web-based checkout
  • Optionally, power down the swiper
  • Collect a signature. Use your own UI and upload to WePay via the mobile SDK. The signature will be available in receipts and reports.

WePay also supports manual entry (virtual terminal) of card info in the event a swipe/dip is not possible.

The mPOS technical overview provides full details on using the mobile SDK.

Chip vs Mag Stripe vs Virtual Terminal

Merchants can collect payment info from a card in 3 ways:

  • Using the chip (“dip” the card)
  • Using the mag stripe (“swipe”)
  • Manually entering the card info (virtual terminal)

Most cards today have chip. Your app needs to strongly encourage merchants to use the chip reader whenever a card has a chip. The reader can tell when a swipe is attempted but the card has a chip, and will reject the swipe. To allow card present processing in the rare case of a bad chip, the SDK will allow a swipe after 3 failed attempts to dip. Those 3 attempts and the subsequent dip must occur within the same SDK transaction (a single call to startcardreader).

If neither chip nor swipe is accepted by the reader, you and your merchants have the option of manually entering card info. This is considered a higher-risk transaction and will be processed using the virtual terminal rates, which are generally higher than both card present and card not present rates. Your app should position virtual terminal as a last resort.

Technical Rules For Chip Cards

Chip cards are able to be coded for a wide variety of rules by the issuing bank. Unlike mag stripes, the card reader can interogate the chip and potentially reject a card for various reasons. These are the key business rules enforced by WePay and the WePay mobile SDK:

  • Cards are always processed online, even if the card allows offline authorizations. Thus, internet access is always required to process a payment (Internet access is also required for mag stripe transactions).
  • Cards that are set to require a PIN cannot be accepted. Cards issued outside the US may be “PIN Preferring”, meaning that they have a PIN and require it if the reader supports it. However, the vast majority of these also allow “chip & signature” transactions, which is what is used in the US. ** 3 try rule doesn’t apply here (but could insert backwards)
  • Cards must accept USD as a currency - this does not mean it has to be issued by a US bank. While WePay and the mobile SDK accept cards from anywhere in the world, not all cards are set to allow USD. ** Try to find a few UK / overseas cards and vet
  • Very rarely, a card network issues new cryptographic keys. When this happens, an update to the WePay SDK is required.

In addition, cards can fail to process via the chip for the same reasons a magnetic stripe can fail, e.g. expired card.

Cards With Multiple Payment Applications

Cards with chips can, and often do, have mutliple “applications” on them. For example, there can be both a credit and a debit application. In most cases, the WePay SDK is allowed to choose the credit application automatically. It is possible that the SDK won’t be able to choose, and when this happens, the SDK makes a callback to your mobile app to present the choice to the payer.

Required Information

Your mobile app will need to collect info from the payer, depending on how the transaction is accomplished. For dip and swipe transactions:

  • Signature
  • Email address (not required but strongly recommended)

For virtual terminal transactions:

  • Card number
  • Expiration date
  • CVV2
  • Billing zip code (or full address for non-US payers)
  • Signature
  • Email address (strongly recommended)
  • Payer’s full name (strongly recommended)

Note that where your platform already has this info, it is acceptable to send it to WePay without re-obtaining it directly from the user.

Generating Receipts

Card networks have specific requirements for card present transaction receipts. If your integration will rely on WePay to generate receipts, your platform has nothing to do here.

If your platform will generate its own receipts, then please note these receipt requirements. All of this detail is available in /checkout - see specifically the EMV receipt structure :

  • Source: indicate whether it was swiped, from a chip card, or keyed in
  • AID (the Application ID): a hex string that identifies the specific application on the chip that was used in the transaction
  • Application name: the human readable name of the specific application on the chip that was used in the transaction
  • TC (Transaction Cryptogram): similar to (but longer than) the traditional approval code, this will be included in chip transactions

Restrictions On mPOS Transactions

There are some restrictions on mPOS transactions to be aware of:

Authorization Happens During Tokenization

For regular online card processing, /credit_card/create tokenizes cards without needing to know the amount. The amount is given later as part of /checkout_card/create. The card is authorized as part of the checkout/create call.

For EMV transactions, authorization takes place as part of tokenization, and so the amount must be known up front and cannot be changed. The implications for your platform and mobile app:

  • Your app must call /checkout/create with the exact same amount as was given to the mobile SDK.
  • Your app must call /checkout/create within 30 minutes after tokenizing via the mobile SDK. Otherwise WePay will cancel the transaction to avoid any authorizations being held against the payer’s credit limit.
  • The fee_payer parameter to the fee structure in /checkout/create can only be “payee” or “payee_from”app”. Using the “payer” or “payer_from_app” is not allowed as this would increase the amount the payer was charged after the authorization.

Recurring Transactions

Normally, cards that are dipped or swipped are meant to be used once, and any subsequent purchases would be made with a new dip/swipe. WePay reflects this by making a dip/swipe token only usable for one checkout.

However, WePay does allow platforms to explicitly convert a dip/swipe token to recurring use. See the call /credit_card/enable_recurring for details.

Card Reader Details

Read below for detailed device information about the Moby 3000 and RP350x.

Battery

Merchants used to swipe-only solutions may not realize that EMV readers have a battery, and they will occasionally need to charge it. Both the Moby 3000 and RP350x can be used 200 to 400 times before needing to be recharged. The battery status is available via the SDK, and also on the device via an LED:

Moby 3000

  • Red solid: device is on and has sufficient charge
  • Red flashing: device is on, but has low battery; also indicates charging battery
  • Blue solid: device connected via Bluetooth
  • Blue flashing: device ready to connect, but not yet connected

RP350x

  • Red solid: full battery
  • Red flashing: low battery
  • Red slow flashing: very low battery
  • Off: battery empty
  • Red rapid flashing: charging battery

WePay suggests your mobile app take advantage of the SDK to alert users to readers that need charging.

Resetting A Device

When starting each transaction, the SDK asks your app if you want to reset the reader. Normally the answer to the question should be NO/false, but you can respond with a YES/true for one transaction if you want to reconfigure the reader.

Ideally your app should provide a mechanism for your merchants to reset the reader using this method, and also advise them not to press the physical reset button.

For a RP350x reader specifically, if the device ever gets into bad state, or a merchant hard-resets it by pressing the physical button on it, then it must be reconfigured via the WePay SDK.

Troubleshooting Tips

WePay encourages platforms to incorporate these steps into your own app. Remember that WePay cannot offer direct tech support to merchants for card readers, as WePay does not create the mobile app.

  • Is your mobile app properly running on the device?
  • Is the reader charged?
  • Is the card inserted/swiped the correct way?
  • Is the reader fully inserted into the audio jack? (RP350x only)

As a last resort, you can guide users to resetting the device. However, we recommend this only be done during a live tech support conversation with your support team. Your app will need to manually initiate device configuration via the resetRequested() callback. We suggest making reset functionality available in your app but hidden so that it will only be invoked during a support call after your support rep eliminates all other possibilities.

Unsupported Phones & Tablets

Note

This section is relevant to the RP350x device only.

Because the RP350x connects via audio jack, there are two possible issues:

  • No audio jack: generally an adapter will work. WePay has tested the iPhone 7 adapter supplied with the phone and it works.
  • Volume: Each device has different volume levels. The WePay SDK includes profiles for many devices. However, there is always a chance that a new phone model is not supported yet by the 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 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 SDK.

Orientation

Note

This section is relevant to the RP350x device only.

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

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

Status

Note

This section is relevant to the RP350x device only.

The RP350x also has a green LED on each side of the reader to display status. The SDK provides equivalent status information:

  • Green rapid flashing: booting up
  • Green steady: ready to read a card
  • Green steady and beep: waiting to read a card
  • Green slow flashing: reading a card
  • Green medium fashing: unexpected error but reader is still active

Note: the beep when the device is actively waiting for a card cannot be disabled.

Testing Your Integration

As with web-based integrations, you will do your development and integration testing using WePay’s stage environment, and then do a few tests in production. The SDK allows your mobile app to be configured for either WePay’s production or stage environment.

Using Test Cards

While working with WePay’s stage environment, you must use test EMV cards. Your WePay account manager can obtain these for you, or you an acquire them yourself. Unlike web integration testing on stage, where you can type in test card numbers, you need a physical card to test dip and swipe. Please do not use your personal, real cards on stage as this environment is not secure.

Note: the SDK has a config option that has to be explicitly set before using test cards.

Special test procedures

For testing dip/EMV transactions with WePay’s stage environment, certain “magic” amounts must be used for the transactions. These are documented in the SDK reference.

When calling /checkout/create to complete these magic transactions, the server will return mock success/failure responses. These transactions will not be processed by the stage environment, and thus cannot be used for future lookups or for triggering IPNs.