Clear
Core
LinkAuthorize Cards
Mobile
Once a reader has been paired with a mobile device, you can begin authorizing cards.
Once an authorization response is received with the encoded payment method, indicate to the merchant that the transaction is complete.
Verify A Card
Outside the standard authorization flow, terminals can also verify that a card is valid. Note that this will not pre-authorize a card for any amount, it will simply verify that a card will not be declined due to being invalid, lost, or stolen via $0 auth. This function can only be used via the physical authorization flow.
Authorize A Card
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).
Note
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 separatePOST /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.
Rules For Chip Cards
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:
- Authorizations are always completed online, so internet access is always required to collect an authorization and then 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.
- An exception to the above exists with the Moby 5500: PIN preferring cards will largely be accepted by the Moby 5500 unless the card only accepts "chip & PIN" without the "chip & signature" fallback. Those cards will be declined, and the card holder should expect this. These cards are infrequent but are sometimes still issued by foreign banks or for cards with niche uses, such as health savings accounts.
- 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 Multiple Payment Applications
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.
Find more information here.Required Information
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)
- NFC/contactless payments require signatures
- Merchants who accept tips are encouraged to collect signatures
- Merchants who wish to validate the terms of sale (such as "all sales final") are encouraged to collect signatures
- Email address (optional)
POST /payments request, which we outline next.Authorization Response
After the manual or physical authorization flow has been initiated, the Card Present SDK then attempts to authorize the provided card information. The Card Present SDK will respond a Payment Info and an Authorization Info object, which both get passed back to the delegate method. There, you can identify whether the authorization succeeded or failed, and retrieve the encoded payment blob on a success:
| Payment Info | |
|---|---|
| Detail | Sub-Object Details |
| Payment method |
|
| Payer email | |
| Payment date | |
| Merchant receipt info | |
| Payer receipt info | |
| Authorization Info | |
| Detail | Sub-Object Details |
| Authorization Result |
|
| Amount | |
| Tip Amount | |
| Currency | |
| Authorization Code | |
| Offline? (boolean value) | |
| EMV information (for receipts) | |
Find the definitions of these results in the constants file of the Card Present SDK, and in the Classes section of the SDK documentation (found in the Card Present SDK package).
When the Card Present SDK responds with either approved or partially approved values for the authorization result, the transaction can be considered complete from the user perspective. Get the encoded payment method value from the payment info delegate and continue to the next article: Process Payments.Terminals And SmartPOS
Now that the Card Present SDK is set up and a terminal is onboarded, you're ready to authorize cards.
POST /payments API request to finish processing the transaction while the merchant carries on with their next customer.Once a card has been authorized, it is exceptionally rare for the resulting transaction to be declined. In those rare cases where the transaction might be declined, we will complete the capture on your behalf.
Additionally, this design allows for unexpected 500's and retryable errors without hindering the merchant. Be sure to Design a Retry Strategy.Verify a Card
Outside the standard authorization flow, terminals can also verify that a card is valid. Note that this will not pre-authorize a card for any amount, it will simply verify that a card will not be declined due to being invalid, lost, or stolen. This function can only be used via the physical authorization flow.
Authorize a Card
There are two types of authorization supported by terminals: manual and physical. Manual authorization involves typing in the card data while physical authorization involves the terminal collecting the card data from a card interaction (chip, swipe, or tap).
| Event | Physical auth | Manual auth |
|---|---|---|
| Begin a transaction | Default “Pay Now” button in UI | Alternative key-in card button in UI |
| Prompt for tip | Depends on terminal's tip config | |
| Prompt for card | Dip/swipe/tap card | Key the card info into the terminal |
| Process authorization | Terminal status of "Terminal is authorizing" | |
deferred_authorization Terminal config is enabled.Note
Rules For Chip Cards
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:
- Authorizations are always completed online, even if the terminal is configured to accept offline authorizations (offline auths must later be completed online; find more below). This means that internet access is always required to successfully authorize a card and then 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.
- 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.
- In addition, cards can fail to process via the chip for the same reasons a magnetic stripe can fail, e.g. expired card.
Store and Forward
Find a detailed discussion of Store and Forward here.Physical Authorization
Create a trigger in your merchant-facing UI in order to begin an authorization. Note that simply initiating authorization does not require card info. For instance, your trigger could be a “Pay Now” button for a server to ring up a table, which will run the physical auth function.
The terminal will prompt the payer for tip information iftip.mode was set to prompt_on_terminal. If tip.mode was set to prompt_on_receipt or disabled, then this step will be skipped.Next, the terminal will prompt the payer for a card, and once provided the Card Present SDK will provide a new Terminal status with Terminal is authorizing. If the authorization is successful, then the Card Present SDK will return a successful auth.
Manual Authorization
This authorization flow is the same as the physical authorization flow, except for the following:
- Your merchant-facing UI should have a separate trigger indicative of keying-in card information. For instance, a “Key in card to pay now” button.
- That trigger will initiate the Manual auth function.
Authorization Response
After the manual or physical authorization flow has been initiated, the Card Present SDK then attempts to authorize the provided card information. The Card Present SDK will respond a Payment Info and an Authorization Info object, which both get passed back to the delegate method. There, you can identify whether the authorization succeeded or failed, and retrieve the encoded payment blob on a success:
| Payment Info | |
|---|---|
| Detail | Sub-Object Details |
| Payment method |
|
| Payer email | |
| Payment date | |
| Merchant receipt info | |
| Payer receipt info | |
| Authorization Info | |
| Detail | Sub-Object Details |
| Authorization Result |
|
| Amount | |
| Tip Amount | |
| Currency | |
| Authorization Code | |
| Offline? (boolean value) | |
| EMV information (for receipts) | |
Find the definitions of these results in the constants file of the Card Present SDK, and in the Classes section of the SDK documentation (found in the Card Present SDK package).
When the Card Present SDK responds with either approved or partially approved values for the authorization result, the transaction can be considered complete from the user perspective. Get the encoded payment method value from the payment info delegate and continue to the next article: Process Payments.Note
POST /payments API request once the terminal is online again. Find more information in the deffered_authorization portion of the Configure a Terminal section.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 separatePOST /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.
At this point, a Payment does not exist. You'll need to use the encoded payment method in the Payments API in order to charge the authorized card.