Once a reader has been paired with a mobile device, you can begin authorizing cards.
Create a trigger in your mobile app to begin an authorization by calling the start transaction function. For instance, your trigger could be a “Pay Now” button for a server to ring up a table, which will run the auth function. Be sure to provide the required parameters for the start transaction function, listed in the Card Present SDK documentation.
On a successful response, the mobile card reader is ready to collect card information. Note that the call will timeout if a card is not provided after 60 seconds. It is recommended to display this pending status and the time window in your mobile app.
Mobile card readers can collect payment info from a card in the following ways:
- Using the chip (“dip”)
- Using the mag stripe (“swipe”)
- Using NFC (“tap”)
Most cards today have EMV chips. If an attempt is made to swipe an EMV chip card, the reader will reject the swipe and the Card Present SDK will prompt your app to ask the payer to dip the card instead. In case the chip is damaged, the reader will fallback to swipe mode after 3 consecutive failed dip attempts. Those 3 attempts and the subsequent dip must occur within the same Card Present SDK transaction (a single call to start the card reader).
Use Case: Complete 1 Transaction With 2 Cards
Oftentimes, customers will begin a payment with a gift card (or any other card with a balance limit) which does not have sufficient funds for the requested authorization amount. In these cases, a partial authorization will return, allowing the available balance on the card to be charged, but a remaining balance due.
Your platform should build out logic in your mobile app to handle splitting a single transaction into multiple payments to cover this use case.
To complete these kinds of transactions, prompt the merchant to run a second authorization for the remaining amount due.
You’ll now have 2 encoded payment methods, each to be used in seperate POST /payments requests for the authorized amounts. Take care to note the encoded payment method which returned with a partial authorization, and only capture the authorized amount via the API.
Note that the flat fee will be applied to each leg of the transaction, so these use cases are more expensive than completing a single transaction with a single card.
Chip cards are able to be coded differently by the issuing bank. Unlike mag stripes, the card reader can interrogate the chip and potentially reject a card for various reasons. These are the key business rules enforced by WePay and the Card Present 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 Card Present SDK both accept cards from anywhere in the world, not all cards are set to allow USD.
- Very rarely, a card network issues new cryptographic keys. When this happens, an update to the Card Present SDK is required. Authorizations attempted when an update is required will fail, and WePay will return an error in the Card Present SDK with the failed authorization delegate block. Call the firmware upgrade function in order to unblock the card reader from authorizing.
- 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 chips can, and often do, have multiple “payment applications” on them. For example, there can be both a credit and a debit application. In most cases, the Card Present SDK is allowed to choose the credit application automatically. It is possible that the Card Present SDK won’t be able to choose, and when this happens the SDK makes a select EMV application callback to your mobile app to present the choice to the payer.
Your mobile app will need to collect certain details from the payer, depending on how the transaction is accomplished. For dip, swipe, and tap transactions you must collect the following in your mobile app:
- Signature (when applicable)
- Email address (optional)
The payer’s email address will not be passed to the Card Present SDK, but can be used in the POST /payments request, which we outline next.
Collecting signatures when…
- Card information is collected via swipe or tap method
- A merchant collects tips
Next Up: Process Payments
Use encoded payment methods to process payments.
- Handle payment responses
- Leverage different capture flows
- Manage payment operations
Questions? Need help? Visit our support page!