API
Log In Support
  • Clear

    • Get Started

      • Overview

      • Platform Sign Up

      • API Basics

    • Integration

      • Setup Platform

      • Onboard Merchants

      • Enable Merchants

      • Process Payments

      • Payout Merchants

      • Manage Payment Operations

      • Test and Launch

  • Link

    • Get Started

      • Overview

      • Platform Sign Up

      • API Basics

    • Integration

      • Setup Platform

      • Onboard Merchants

      • Process Payments

      • Manage Payment Operations

      • Test and Launch

    • CARD PRESENT SOLUTIONS

      • Get Started

        • Overview

      • Terminals

        • Acquire Terminals

        • Onboard Terminals

        • Authorize Cards

        • Process Payments

        • Test and Launch

      • Mobile Card Readers

        • Build Mobile App Prerequisites

        • Acquire Mobile Card Readers

        • Pair A Device

        • Authorize Cards

        • Process Payments

        • Test and Launch

      • Card Present Resources

        • Provide Receipts

    • API Reference

    • Resources

      • Payment Life Cycles

      • Server to Server Integration

      • Platform Legal Certification

      • Security Certification

      • Risk Certification

      • CIP and KYC Certification

      • Card Network Rules

      • Disputes Deep Dive

    • Cookbooks

      • Build Payment Support Tools

      • Reporting

      • Implement Merchant IC+ Pricing Model

      • Recurring Billing

      • Level 2 & Level 3 Processing

      • Style Credit Card iFrames

      • Support Merchants Outside the United States

      • Design A Retry Strategy

    • Release Notes

Home / Card Present / Terminals / Authorize Cards

 

Authorize Cards

 

In This Section
  • Verify a Card
  • Authorize a Card
    • Rules for Chip Cards
    • Store and Forward
    • Physical Authorization
    • Manual Authorization
  • Authorization Response

Now that the Card Present SDK is set up and a terminal is onboarded, you’re ready to authorize cards.

Auth Flow

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. 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"

 

Spanning both physical and manual methods of authorizing a card is the store and forward method. This method is used when the Terminal is offline, and the deferred_authorization Terminal config is enabled.

Note

Learn how to run authorizations in the stage environment here.

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

To properly implement store and forward, there are a couple risks which should be understood and mitigated:

  • Lost authorizations
  • Expired authorizations
  • Declined authorizations

With store and forward, authorizations can very easily be lost, as offline authorizations are only stored on the Terminal until it goes online again. To protect against lost authorizations, implement the following:

  • Encourage merchants to bring Terminals back online as soon as possible
  • Limit the number and amount of authorizations which are allowed offline
  • Implement robust offline authorization logging

Another risk with store and forward is the inability to obtain a valid authorization once the Terminal comes back online. Authorizations are generally valid for 7 days, and a buffer should be communicated to merchants. Implement the following to protect against expired offline authorizations:

  • Encourage merchants to bring Terminals back online as soon as possible
  • Communicate that if a Terminal remains offline for more than 5 days, any offline authorizations run the risk of expiring
  • Implement a capture strategy for offline authorizations
    • This strategy should consider the time of authorization and encourage/enforce capture well before the 7-day timeframe ends

Additionally, it is possible for a card issuer to decline an offline authorization when a Terminal goes back online. Issuers can also elect to only partially approve offline authorizations once they are forwarded.

Note

If the merchant elects to leverage the store and forward feature, they are liable for any offline authorizations which, for any reason, cannot be forwarded and successfully captured.

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 if tip.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
  • Encoded payment method
  • Input source (i.e. dip, tap, swipe, keyed)
  • Payer name
  • Masked PAN
  • Expiration month
  • Expiration year
  • Card brand
Payer email
Payment date
Merchant receipt info
Payer receipt info
Authorization Info
Detail Sub-Object Details
Authorization Result
  • Approved
  • Declined
  • Referred
  • Error
  • Partially Approved
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.

Important

If the authorization was offline, store the encoded payment method along with the authorization amount and the merchant’s Account ID. Queue these to be processed via a 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 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.

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.


Next Up: Process Payments

Begin processing payments with a encoded payment methods.

  • Use encoded payment methods
  • Capture Payments
  • Manage payment operations

 

Process Payments

 


Questions? Need help? Visit our support page!

Company

  • About
  • Careers
  • Blog
  • News & Events

Resources

  • Knowledge Center
  • Terms of Service
  • Privacy Policy
  • Security
  • Support

Developers

  • Documentation
  • Engineering Blog

Customers

  • Case Studies

Product

  • Link
  • Clear
  • Core
  • Contact Sales
© 2020 WePay Inc.