Private Eye Case: Different Responses Based on Card and Entry Method
Private Eye: “Ok card transaction, tell me your brand name”.
Client: “Well…My name is Joe Doe and I am from Visa…Visa Credit”
Private Eye: “How did you enter the Clover, what was your payment method, and what happened?”
Client: “I…I was at a clothing store and I ‘Mag Striped’ in for a sale but I was declined…they said I was over the limit!”
Private Eye: “Thank you for your time.”
On Clover, a semi-integration connects your software (and often hardware) with Clover, making your point-of-sale EMV compliant quickly and easily.
As a Point of Sale developer, you’re going to see various transaction responses based on the card and entry method. Having this knowledge is key to understanding how transactions are processed and what responses your semi-integration app or the Clover Server may throw.
Branding and Entering: Card Brands and Responses
The Clover platform is capable of accepting major card brands and their umbrella branches. However, there are some restrictions based on the merchant’s account. Depending on what they have agreed to allow, each merchant will have different entitlements. For example, Clover can accept American Express but an individual merchant may not agree to process American Express cards on their account. Therefore, they are unable to accept Amex transactions.
Clover can also accept contactless payments, e-wallets, and P2P(peer-to-peer) payments like Venmo. Below is a brief list of some of these payment types:
- Venmo
- PayPal
- Apple Pay
- Samsung Pay
- Google Pay
- AliPay
- WePay
Depending on the goals of your Semi-Int app, you will also see various types of entry methods to process a card. Each method can also be represented by a numeric value. For more information, please visit Payment Responses Reference.
In addition to entry methods, Clover has provided clearance for your app to manipulate the entry methods you can accept. These settings can be changed in the BaseTransactionRequest. For example, if you only want your app to only accept EMV chip sales due to security protocols (made by dipping the card in the device), you can simply specify the entry method:
Clover Docs explains in more depth how per-transaction settings that can be edited.
*If you want to fetch the payment information from an API call for reporting or validation after the transaction occurred, the Payment- R permission will be required for your app.
Transaction Types
Semi-integrating with Clover is all about what type of transactions are coming through. Many of them have the same available payment response properties, such as payment.id, payment.tender, payment.employee, payment.result, and so forth. Clover categorizes these transaction types into 3 categories:
- Sale
- Auth
- Pre-Auth
These transaction types are the same no matter the card brand.
Sale: A transaction in which the amount is final and cannot be adjusted after payment(no tips after the payment). If your total is $20.86, that will be the final amount you will pay.
Auth: A transaction where the final amount is unknown but the cardholder’s account must be checked to determine if they have sufficient credit or funds. The card is authorized and the amount can be adjusted later. For example, adding a tip on paper means updating the total charged post-payment. Auths are typically payments that are held until a completion request is sent (the merchant closes/batches/settles out for the day).
Pre-Auth: A transaction that lets the merchant know whether the cardholder has sufficient funds, without charging the card. This type of transaction is just peeking in. This transaction will place a hold on the account without transferring money to the merchant. When the merchant is ready to complete the transaction, they will capture the pre-auth to complete the payment. Pre-auths are typically larger than the expected bill.
*Pre-auths in Semi-Int are currently available for US only.
Below is a table of examples for each transaction type and what is required when calling them in the SDK
Cold Cases: Refunds/Voids
Refunds and voids can be bittersweet. A customer did not like the product or services and wanted to refund it or the size didn’t fit.
Refund: This can be a partial or full repayment given to a customer for a specific order. Refunds can be credited back to a card or given in cash. If a refund is not associated with a particular order, it will be named as a Manual/Naked Refund. Here you can do a partial refund of an amount (i.e refunding $3.27 of a $10 charge). There may be a variety of reasons why a partial refund is necessary. Clover provides detailed refund responses like the amount, created time, who did the refund, and ids(payment, refund, device).
Please keep in mind that partial refunds on orders can be done on the line item or payment level. Otherwise, the merchant will need to issue a manual/naked refund.
Voids: A request to cancel a previous transaction before it enters the clearing process. They can be used to “whoopsies” sales and pre-authorizations. Maybe the merchant meant to run the transaction for $3.99 but put $39.99? Or maybe the customer had a change of heart and no longer wants what they just purchased.
Void can only be made within 25 minutes of the original transaction; anything after that mark will have to be a refund. When you void a pre-authorization, it will release the holds on the customer’s account. A void can also happen when the payment is not finished and the payment times out.
Card Responses
Every processed transaction has something to say, whether they’re good responses like approvals, bad responses like declines, or unsure responses like voids.
SUCCESS (Approvals): Responses when a payment ran successfully with no issues. The expiration, CVV, ZIP (or postal) code, card number, and funds were all valid and the bank approved the authorization to be successful. Everyone is happy with approvals. Clover will confirm the transaction was approved on the device screen and the backend will show it in the JSON output.
Sale, pre-auth, auth, and refund can all have an approved message. Approvals can also be broken up into PENDING and CLOSED as the “state” of the payment.
- Pre-auths that are awaiting further instructions and offline payments will be successful and set to PENDING.
- Payments that have successfully been processed will be set to CLOSED, which means that the funds have already been taken out of the card holder’s banks (popular in debit transactions). CLOSED will also show when the merchant has batch/settled/closed out for the day to send the payments for funding.
Decline: We all hear the saying “A decline is a decline”. But what exactly does that mean? Declines occur when the cardholder’s bank rejects the authorization of the card for a number of reasons, including:
- Expired card
- Amount over the credit limit
- Fraud
- Insufficient funds
- Etc.
Declines can also happen from the merchant end:
- Card type not supported
- Account doesn’t process transactions offline
- Account issues
- Etc.
The Clover platform has the ability to output more details on the decline message than the standard UI. You can check the logs or JSON response for more details.
Voids: Hypothetically, there could also be more to a void. There is always a reason why.
- User Canceled: Either the merchant or the customer canceled the transaction. This can happen mid-processing and the card gets taken out too early, or someone simply cancels the transaction.
- Timed out: In some cases, the authorization was left waiting for the done button to be pressed and then it timed out to avoid freezing/halting other interactions.
- Rejected signature: If the merchant rejects the signature, this causes a void.
Case Studies
Transaction data can have a combination of states, responses, brands, entries, and other details. Here are some examples of the variations:
Messages Most Wanted
The most popular declined/error responses are quickly noticed on the Clover UIs. Below is the JSON message output from the onDeviceActivityStart of the CloverConnector. These messages can appear in your console log or as a response to an API request for the data.
The Archives: Retrieving Payment Information
Resources are always important when working with data. Below is an example API call to retrieve all payments and expand the card transactions details to view the card type and entry methods. Further down the JSON output, you will see the expanded card transaction details:
{{baseUrl}}/v3/merchants/{{merchantId}}/payments?expand=cardTransaction
You can also get this same information from using the order API and expanding the cardTransaction:
{{baseUrl}}/v3/merchants/{{merchantId}}/orders?expand=payment.cardTransaction*You will need the Payments Read permission to access payment data and the Orders Read permission to access order data.
If working with Clover Android SDK, you can access the payment data by calling the saleRequest. You can do the same with the refunds, manual refunds, and pre-auths. The following example illustrates how to print the saleRequest data to your console.
Clover Docs are a great resource on seeing how the PaymentConnector and CloverConnector are implemented — and offer more some examples for you to explore.
Wrapping up
Knowing the elements of payments is key in Semi-Integration apps. It’s part of a developer’s debugging, reporting, and reconciliation. Being your own P.I. and digging deeper into a transaction can give you great evidence in finding exactly just what happened in every transaction. With Clover’s ability to expand more on transaction data, your app can utilize this information for innovation.
Case Closed.
No hesitation here, you can always reach out and ask questions at developer-relations@devrel.clover.com.
We look forward to seeing what you build!
