Transcription

First Data / Payeezy: User ManualVersion 2.3 – For Magento 2.2 – Updated 2021-03-29Table of ContentsInstallation .3If you purchased from Magento Marketplace .3If you purchased from store.paradoxlabs.com .4Updating First Data: Payeezy .5If you purchased from Magento Marketplace .5If you purchased from store.paradoxlabs.com .5Configuration .6General.6Payment Settings .9Advanced Settings.10Usage .11Checkout Payment Form.11Order status page .12Customer ‘My Payment Data’ account area .12Admin order form .13Admin order status page.13Admin customer ‘Payment Data’ account area .14Admin transaction info .15Frequently Asked Questions & Troubleshooting .16How do I do an online refund from Magento? .16How does this payment method handle currency? .16Error on checkout: “An error occurred on the server. Please try to place the order again.” .16Error: “First Data Gateway: Invalid ta token provided (invalid.tatoken)” .16Technical / Integration Details .17Architecture .17Custom database schema .17Events.17Magento API: REST and SOAP .17ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33301

Magento API: GraphQL .27Split Database .35Support .35ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33302

InstallationThe installation process differs based on where you purchased our extension.If you purchased from Magento MarketplaceNOTE: You will not be able to install by downloading the extension files from Marketplace.The Marketplace download does not include all of the necessary files. You must install using either the Web SetupWizard or Composer, with the following directions.Step 1: InstallWe strongly recommend installing, configuring, and testing all extensions on a development website beforeinstalling and using them in production.If you encounter any problems during this process, please contact Magento Marketplace Support.Note, installing this extension requires familiarity with your server’s command line. Ensure your server hascomposer set up and linked to your Magento Marketplace account (including repositoryhttps://repo.magento.com). Then in SSH, from your site root, run the following commands:composer require paradoxlabs/firstdataphp bin/magento module:enable -c ParadoxLabs TokenBase ParadoxLabs FirstDataphp bin/magento setup:upgradeIf your site is in production mode, you will also need to run these commands to recompile sources:php bin/magento setup:di:compilephp bin/magento setup:static-content:deployThese commands should load and install the extension packages from the Marketplace repository.Composer installation is only available for Marketplace purchases.Step 2: ConfigureSee the configuration section below.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33303

If you purchased from store.paradoxlabs.comNOTE: This file upload installation applies only to purchases from the ParadoxLabs Store. Marketplace purchasesmust follow the Marketplace installation directions above.Step 1: Upload filesUpload all files within the upload folder into the root directory of Magento.Folder in Download/upload/app/ Folder on Server/app/Step 2: Run InstallationIn SSH, from your site root, run the following commands:php bin/magento module:enable -c ParadoxLabs TokenBase ParadoxLabs FirstDataphp bin/magento setup:upgradeThese will enable the module, flush the cache, and trigger the installation process to run.If your site is not in developer mode, you will also need to run these commands to recompile sources:php bin/magento setup:di:compilephp bin/magento setup:static-content:deployStep 3: ConfigureSee the configuration section below.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33304

Updating First Data: PayeezyAll extension updates are free. Just follow these directions to update to the latest version.If you purchased from Magento MarketplaceNote, installing/upgrading this extension requires familiarity with your server’s command line.If you installed with composer, you can update using the following commands, in SSH at your site root:composer update paradoxlabs/*php bin/magento setup:upgradeThis will download and update to the latest extension version compatible with your system.If your site is in production mode, you will also need to run these commands to recompile sources:php bin/magento setup:di:compilephp bin/magento setup:static-content:deployIf you purchased from store.paradoxlabs.comStep 1: Upload filesLog into your account at store.paradoxlabs.com and download the latest version.Open the extension archive and extract it onto your composer.Upload all files within the upload folder into the root directory of Magento.Folder in Download/upload/app/ Folder on Server/app/Step 2: Run UpdateIn SSH, from your site root, run the following commands:php bin/magento setup:upgradeIf your site is in production mode, you will also need to run these commands to recompile sources:php bin/magento setup:di:compilephp bin/magento setup:static-content:deployParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33305

ConfigurationBefore proceeding: Sign up for a Payeezy developer account and First Data merchant account if you don’t havethem already. Be sure to request that TransArmor be enabled for your account—this extension won’t workwithout it.Open your Admin Panel and go to Admin Stores Settings Configuration Sales Payment Methods. Towardthe bottom of the page, you’ll find an ‘First Data’ settings section like the below.General Version Installed: This tells you the version of our extension currently installed on your website. Pleaseinclude this in any support requests.API Test Results: If you’ve entered a Merchant Token, API Key, API Secret, and Transarmor Token, we willautomatically connect to First Data to verify that the API works successfully. If we cannot connect to FirstData or your credentials incorrect, this will tell you with a red message. Correct the error, then reload thepage and it should show ‘First Data connected successfully.’o NOTE: The API Test currently does not validate the Merchant Token and API Secret. That couldprevent checkout even if the API test succeeds.Enabled: Yes to enable the payment method. If disabled, you will still be able to invoice/refund existingorders, but it will not show up as a payment option during checkout.Is Sandbox Account: Choose ‘Yes’ if the credentials you entered are for a sandbox account. If this value isnot correct, the API Test Results will report ‘Your API credentials are invalid.’ To sign up for a sandboxmerchant account, navigate to a.com/signup.Title: This controls the payment option label on checkout and order status pages.Merchant Token: This is a secret value from your Payeezy developer account. If you don’t know it, log intoyour First Data developer account, then go to Merchants in the navigation. Your Merchant Token will bein the middle of the page. (See Merchants screenshot below for reference.)ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33306

https://developer.payeezy.com/user/me/merchants API Key: This is a secret value from your Payeezy developer account. If you don’t know it, log into yourPayeezy developer account, then go to APIs in the navigation. If you do not have an API created, createone to get the API Key (Make sure you select the appropriate environment). If you already have an API,click on it and look under Keys to get the API Key. (See My APIs screenshot below for reference)API Secret: This is a secret value from your Payeezy developer account and is found below the API Key asnoted above. (See My APIs screenshot below for psParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33307

Transarmor Token: This is a secret value from your First Data account. If you don’t know it, log into yourFirst Data merchants account, then go to Administration Terminals Select the appropriate terminal Details. WARNING: Your account needs to have TransArmor service enabled. Contact your merchantaccount representative or contact First Data for TransArmor erminal Payment Action: Set to ‘Authorize and Capture’ to capture all funds immediately when an order is placed,or ‘Authorize Only’ to authorize upon checkout, then manually invoice and capture later. Paymentprocessors strongly recommend not capturing funds unless/until you are within three days of fulfilling(shipping) the purchase.New Order Status: Set this to your desired initial status for orders paid via First Data. Default Magentobehavior is ‘Pending’ for Authorize Only, and ‘Processing’ for Authorize and Capture.Show First Data Logo: If yes, checkout will display an ‘First Data’ logo next to the payment form.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33308

Payment Settings Allow Credit Card Types: Choose the CC types you want to allow on checkout.Allow card to not be stored: If Yes, customers will have a ‘Save for next time’ checkbox on checkout. IfNo, logged in customers will see a message instead: “For your convenience, this data will be storedsecurely by our payment processor.” Guests will never be given the option to store a credit card.Note that all cards are always stored in First Data, regardless of this setting or the customer’s choice. Thisis necessary for payment processing. If the order is placed as a guest, or the customer chooses to not savetheir card, it will be automatically purged from all systems 120 days (the maximum refund period) after itslast use. This ensures the info is available for edits, captures, and refunds, but respects the customer’wishes.If a card is ‘not saved’, it will not display under the customer’s saved credit cards (Account My PaymentData), nor will it be selectable during checkout. Note that as an admin, order ‘edit’ or ‘reorder’ will bypassthis, always allowing reuse of the original payment info (unless it was since purged).Payment from Applicable Countries: This setting allows you to limit which countries can select it as apayment option.Minimum Order Total: This setting allows you to set a minimum order value for the payment option. Forinstance, set to 5 to only allow credit card checkout for orders of 5 or more.Maximum Order Total: This setting allows you to set a maximum order value for the payment option. Forinstance, set to 1000 to only allow credit card checkout for orders of 1000 or less.Set Order: This setting allows you to change the order of payment options on checkout. Enter a numberfor this and all other payment methods according to the order you want them to display in.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-33309

Advanced Settings Require CCV for all transactions: If Yes, customers and admins will be required to enter the credit cardCCV for all transactions, even with previously stored cards.Reauthorize on Partial Invoice: If Yes, and you invoice part of an order, a new authorization will becreated for the outstanding order balance (if any). This helps guarantee funds but can cause multipleholds on the card until transactions settle. Any failure during reauthorization is ignored.Auto-select 'save for next time': If Yes, the ‘save this card for next time’ checkbox will be checked bydefault. If no, customers will have to explicitly select it to store and reuse their card.Verify SSL: If Yes, the First Data API connection will be verified against known SSL information for the API.Do not disable unless you encounter SSL errors from the API test results and your host is unable to fix theunderlying problem. Disabling this will make your store vulnerable to MITM (man-in-the-middle) attacks.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333010

UsageThere isn’t much to using First Data in practice: It’s a standard Magento payment method, and all interfaces shouldbe pretty self-explanatory. That being said, here’s what you get:Checkout Payment FormThe frontend payment form lets you choose/enter billing address and credit card. You can choose an existing card(if any) from the dropdown, or to add a new one. Credit card type is detected automatically.If a customer re-enters a card they’ve used before, the existing card will be detected, and the new information(expiration date, billing address, etc.) will be saved on top of it. This happens seamlessly behind the scenes.If the customer has stored cards, their most recent one will be selected by default:ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333011

Order status pageCustomer ‘My Payment Data’ account areaThe My Payment Data section allows customers to see their stored cards, add, edit, and delete.Note that cards associated with an open (uncaptured) order cannot be edited or deleted. They will display a ‘Cardin Use’ message in place of the buttons. As soon as all orders paid by the card are completed, the ‘Edit’ and‘Delete’ buttons will appear.To prevent abuse, this section will only be available to customers after they have placed a successful order. If acustomer attempts to access the page before then, they’ll be redirected to the Account Dashboard with themessage, “My Payment Data will be available after you've placed an order.” Also, to prevent abuse, if a customerreceives errors trying to save a card five times, they will be blocked from access for 24 hours with the message,“My Payment Data is currently unavailable. Please try again later.” Both of these behaviors can be adjusted ordisabled if necessary; please contact us if you have a problem.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333012

Admin order formThe admin form displays the same options as frontend checkout, in slightly different format.Admin order status pageThe admin panel shows extended payment info after placing an order, including transaction ID and validationresults. These details are not visible to the customer at any time.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333013

Admin customer ‘Payment Data’ account areaViewing a customer, you will see an added ‘Payment Data’ tab. This shows all the same information with all of thesame functionality as the equivalent frontend section.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333014

Admin transaction infoViewing an order, you can also see full transaction info from the ‘Transactions’ tab.Click into a transaction, and you’ll see all the raw transaction data from First Data.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333015

Frequently Asked Questions & TroubleshootingPlease search our solution directory for the latest answers to common questions and olutionsIf your question is not answered there, open a support ticket and we’ll help you out.How do I do an online refund from Magento?In order to process an 'online' refund through First Data, you have to go to the invoice you want to refund and clickthe 'Credit Memo' button from there.If you’ve done that correctly, at the bottom of the page you should see a button that says 'Refund'.If you only have one button that says, ‘Refund Offline’, it’s because you clicked ‘Credit Memo’ from the orderinstead of from the invoice.The reason for this is that the refund needs to be associated with a particular capture transaction. An order cancontain any number of capture transactions, but every capture has an invoice that’s directly related. You refund aninvoice, not an order.How does this payment method handle currency?Transactions are automatically processed in the base currency for the website customers are purchasing from. Anyalternate currencies selected on the frontend are converted to the website’s base currency by Magento’s built-incurrency handling, based on conversion rates provided by a web service configured in your Magento Admin Panel.Magento allows for a separate base currency per website, if configured to do so. In order to define explicit prices inmultiple currencies, each currency must have its own website where it is set as the base currency. All currencysetup is configured outside of our payment extension settings.Error on checkout: “An error occurred on the server. Please try to place the order again.”On Magento 2.1.13 / 2.2.4 / 2.3.0 :A change to Magento’s guest checkout processing made in these versions breaks error handling around datasaving during the order process. The net result is that any failure of that type (such as a new credit card failing tovalidate) will cause a second error “Rolled back transaction has not been completed correctly”. That second errorcauses the generic error response “an error occurred” to be sent to the user instead of information about theactual payment failure.This issue is being tracked as a Magento bug. We believe the issue is resolved in Magento 2.3.5 and 2.4.0. If you’renot able to update to 2.3.5 yet, one workaround is to remove the salesConnection and checkoutConnection codethat is causing the problem from core Magento file formationManagement.php, as described in a response comment.Error: “First Data Gateway: Invalid ta token provided (invalid.tatoken)”If you encounter this error, it is likely you are encountering one of two issues. Firstly, be sure that you havecontacted First Data to enable TransArmor on your account and that the token entered in Magento matches thetoken displayed in First Data.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333016

Secondly, if you have confirmed the above you may need to request that your Payeezy and First Data accounts beresynced. This can be done by sending an email with your Merchant ID, DBA 'doing business as', and registereddeveloper email to [email protected] / Integration DetailsArchitectureThe payment method code for CIM is paradoxlabs firstdata.is the payment method module, built heavily on the ParadoxLabs TokenBase module.TokenBase defines a variety of interfaces and architecture for handling tokenization and stored cards cleanly.ParadoxLabs FirstDataThe payment method class is \ParadoxLabs\FirstData\Model\Method. This talks to First Data through\ParadoxLabs\FirstData\Model\Gateway, and stores card information in instances of\ParadoxLabs\FirstData\Model\Card. Each of these extends an equivalent abstract class in TokenBase andimplements only the details specific to the First Data API.Card instances are stored in table paradoxlabs stored card and referenced by quotes and orders via a tokenbase idcolumn on payment tables.In all cases, we strongly discourage any customization by editing our code directly. We cannot supportcustomizations. Use Magento’s preferences or plugins to modify behavior if necessary. If your use case isn’tcovered, let us know.Custom database schema Added table: paradoxlabs stored cardAdded column: quote payment.tokenbase idAdded column: sales order payment.tokenbase idEvents tokenbase before load payment info (method, customer, transport, info):Fires before preparing methodspecific information for the order payment info blocks (frontend, admin, and emails). Use this to addadditional information to the payment info block.tokenbase after load payment info (method, customer, transport, info): Fires before preparing methodspecific information for the order payment info blocks (frontend, admin, and emails). Use this to addadditional information to the payment info block or modify what’s there by default.tokenbase before load active cards (method, customer): Fires before loading a customer’s available storedcards.tokenbase after load active cards (method, customer, cards): Fires after loading a customer’s availablestored cards. Use this to modify cards available to the customer or admin.Magento API: REST and SOAPThis module supports the Magento API via standard interfaces. You can use it to create, read, update, and deletestored cards.If you have a specific use case in mind that is not covered, please let us know.ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333017

You can generate new cards by creating an order with our payment method (code paradoxlabs firstdata), andinformation for a new credit card. To place an order with a stored card, pass that card’s hash in as additional data card id.Available REST API requests below. Some response data has been omitted for brevity.Create and update (POST, PUT) requests take three objects: card with primary card data, address with addressinformation, and additional for card metadata. In responses, address and additional will be nested within card asaddress object and additional object. This is done for technical reasons. The data formats differ, and not all fieldsthat are returned can be set via API (EG in use, label). This means you cannot take a card record and directly postit back to the API to update.Integration / Admin-Authenticated API EndpointsThese API requests allow solutions acting with an admin user login, OAUTH authentication, or token-basedauthentication to take action on any card in the system. Data and behavior are not limited.GET /V1/tokenbase/:cardId (get one card by ID)Example request:GET /rest/V1/tokenbase/1 HTTP/1.1Host: {host}Authorization: Bearer {api key}Example response:{"id": 1,"in use": true,"additional object": {"cc type": "DI","cc last4": "0012","cc exp year": "2019","cc exp month": "6"},"address object": {"region": {"region code": "PA","region": "Pennsylvania","region id": 51},"region id": 51,"country id": "US","street": ["123 Test Ln."],"company": "","telephone": "111-111-1111","postcode": "17603","city": "Lancaster","firstname": "John","lastname": "Doe"},"customer email": "[email protected]","customer id": 1,"customer ip": "127.0.0.1","profile id": "1234567890","payment id": "0987654321","method": "paradoxlabs firstdata","hash": "f7d085165acdfa0ea6a0b.770111","active": "1","created at": "2017-08-03 16:31:54","updated at": "2017-09-20 14:24:14","last use": "2017-08-03 16:31:54","expires": "2019-06-30 23:59:59","label": "Discover XXXX-0012"}ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333018

GET /V1/tokenbase/search (get multiple cards, with searchCriteria)Example request:GET /rest/V1/tokenbase/search?searchCriteria[pageSize] 1 HTTP/1.1Host: {host}Authorization: Bearer {api key}Example response:{"items": [{"id": 1,// . other card info}],"search criteria": {"filter groups": [],"page size": 1},"total count": 51}See also: Search using REST APIs (Magento DevDocs)POST /V1/tokenbase (create card)Example request:POST /rest/V1/tokenbase HTTP/1.1Host: {host}Authorization: Bearer {api key}Content-Type: application/json{"card": {"customer email": "[email protected]","customer id": 1,"customer ip": "","profile id": "1234567890","payment id": "0987654321","method": "paradoxlabs firstdata","active": "1","created at": "2017-08-03 16:31:54","last use": "2017-08-03 16:31:54","expires": "2019-06-30 23:59:59"},"address": {"region": {"region code": "PA","region": "Pennsylvania","region id": 51},"region id": 51,"country id": "US","street": ["123 Test Ln."],"company": "","telephone": "111-111-1111","postcode": "17603","city": "Lancaster","firstname": "John","lastname": "Doe","vat id": ""},"additional": {"cc exp month": "06","cc exp year": "2019","cc last4": "0012","cc type": "DI"}}ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333019

Example response:{"id": 95,"in use": false,"additional object": {"cc type": "DI","cc last4": "0012","cc exp year": "2019","cc exp month": "06"},"address object": {"region": {"region code": "PA","region": "Pennsylvania","region id": 51},"region id": 51,"country id": "US","street": ["123 Test Ln."],"company": "","telephone": "111-111-1111","postcode": "17603","city": "Lancaster","firstname": "John","lastname": "Doe",},"customer email": "[email protected]","customer id": 1,"customer ip": "127.0.0.1","profile id": "1234567890","payment id": "0987654321","method": "paradoxlabs firstdata","hash": "9b83d4683f3d3.2309ccd65b","active": "1","created at": "2017-09-25 17:41:21","updated at": "2017-09-25 17:41:21","last use": "2017-08-03 16:31:54","expires": "2019-06-30 23:59:59","label": "Discover XXXX-0012"}PUT /V1/tokenbase/:cardId (update card)Example request:PUT /rest/V1/tokenbase/1 HTTP/1.1Host: {host}Authorization: Bearer {api key}Content-Type: application/json{"card": {"id": 1,"customer email": "[email protected]","customer id": 1,"customer ip": "127.0.0.1","profile id": "1234567890","payment id": "0987654321","method": "paradoxlabs firstdata","hash": "f7d085165acdfa0ea6a0b.770111","active": "1","created at": "2017-08-03 16:31:54","last use": "2017-08-03 16:31:54","expires": "2019-06-30 23:59:59"},"address": {"region": {"region code": "PA","region": "Pennsylvania","region id": 51},"region id": 51,"country id": "US","street": ["123 Test Ln."ParadoxLabs 8 N Queen St 9th Floor Lancaster, PA 17603 717-431-333020

],"company": "","telephone": "111-111-1111","postcode": "17603","city": "Lancaster","firstname": "John","lastname": "Doe","vat id": ""},"additional": {"cc exp month": "06","cc exp year": "2019","cc last4": "0012","cc type": "DI"}}Example response:{"id": 1,"in use": false,"additional object": {"cc type": "DI","cc last4": "0012","cc exp year": "2019","cc exp month": "06"},"address object": {"region": {"region code": "PA","region": "Pennsylvania","region id": 51},"region id": 51,"country id": "US","street": ["123 Test Ln."],"company": "","telephone": "111-111-1111","postcode": "17603","city": "Lancaster","firstname": "John","lastname": "Doe",},"customer email": "[email protected]","customer id": 1,"customer ip": "127.0.0.1","profile id": "1234567890","payment id": "0987654321","method": "paradoxlabs firstdata","hash": "

Upload all files within the upload folder into the root directory of Magento. Folder in Download Folder on Server /upload/app/ /app/ Step 2: Run Installation In SSH, from your site root, run the following commands: php bin/magento module:enable -c ParadoxLabs_TokenBase ParadoxLabs_FirstData php bin/magento setup:upgrade