INTEGRATION DOCUMENTATION V2.0 - MaxiPago

INTEGRATION DOCUMENTATIONV2.0.2

Revision HistoryVersionDate1.001/30/2012Initial version of the document.1.102/13/2012Added observation on line breaks in the boleto instructions.1.202/27/2012Added new fields to the Post in the smartPage! criptionAdded field transactionState to the report response.Added comments on other fields in the reportresponse.Modified fields in the add-consumer command.Removed field hp cmd (obsolete) from the smartPage!section. Added save card section to smartPage!.Added Annex “A” with the payment flows.Added reference to processorID 1 (Simulator for credit card tests).Added command currencyCode and hp currency to define thecurrency used in the transaction.Added command to cancel recurringpayments Added acquirer ChasePaymentech.Added hp lang to change the language on the smartPage! Addedfields hp cf 1 to hp cf 5 to the smartPage!Fixed the nomenclature in the field hp savepayment in thesmartPage Added hp customer token to the smartPage!Removed field eCommInd (obsolete).1.608/02/20121.712/10/2012Added new fraudControl! functionality1.801/04/2013Fixed XML example for command delete-card-onfile1.902/25/2013Added new Online Debit paymentmethods Added list with common 3Added Billing fields to Online DebitAdded Discover card to Cielo1.9.408/19/2013Added boleto bar code reply (processorCodefield) Removed restriction for unique BoletoNumbers Updated test scenariosUpdated hp signature response validation method1.9.501/03/2014Consider changes done in Release 6:Added Magento integrationAdded payment method listAdded TEF paymentmethodAdded Certification processmaxiPago! Smart Payments 20152

Add Soft Descriptorfield Add AVSfunctionality AddIATA Fee fieldCielo onlinerefund Queryby orderIDRecurring Flag (CVV2 exemption)1.9.604/02/2014Greater detail in the implantation of the iFrame1.9.705/26/2014Inclusion of the means of payment KOIN1.9.811/05/2014Inclusion of the FraudId KoinInclusion of the ProcessorIDElavonRemoved obsolete fields in the SmartPagePost! Removed ProcessorId AmexAmended the descriptive of ResponseCode 21.9.906/11/2015Included new ProcessorID GetNet (pages. e 19)Updated Source Code Sample of fraudControl! – (page clusion of TLS 1.2ProcessorID - GetNet 3SmartPage - observation only transact credit cardManual Objective namingRemove American Express flagInclusion of other flagsInclusion of PayPal methodInclusion of CVV for transaction with tokenInclusion of a new method to change a recurring paymentmaxiPago! Smart Payments 20153

Table of ContentsAbout this document. 7Glossary . 7Choosing your integration . 8API Integration .8smartPage! Integration .8Magento Integration . 8Test Environment . 9Integration Certification . 10Merchant Credentials . 11Payment methods available . 11Request Types . 12Transaction Request - Credit Cards . 13Authorization . 14Capture . 17Sale . 19Void . 21Return . 23Recurring Payments . 26Customer Information . 31AVS (Address Verification Service) . 33Soft Descriptor . 33fraudControl! – Fraud Verification . 33iFrame for browser analysis . 32Fraud Requests . 36Transaction Request - Boleto . 39Creating a boleto . 39Conciliating a boleto payment . 41Requests for Transaction - Koin Postpaid. 41maxiPago! Smart Payments 20154

Transaction Request – Bank Transfer . 50Bank transfer request . 50Transaction Request – PayPal . 53Transaction Response . 54Approved Transaction . 57Invalid Parameters . 57Other errors . 58Consumer Request. 59Adding a Customer . 60Removing a Customer . 62Updating a Customer . 61Storing a credit card . 63Removing a stored card . 66Consumer Response . 67Token transactions . 68Recurring transactions with Token . 68Saving a card during a transaction . 70Report Request . 72Querying a single transaction . 73Querying a single order . 74Reports Response . 77Using the paging system . 82Pulling large reports . 84Checking the status of a large report . 85smartPage! - HTTPS Post Integration . 87Submitting a transaction . 88Saving a card automatically . 91smartPage Response . 92Integration support. 95Annex “A” – Transaction Flows . 96maxiPago! Smart Payments 20155

Authorization and Capture – 2-step order . 96Sale – Immediate response to buyer . 97Sale – Delayed response to buyer . 97Boleto creation and payment . 98Refund – Acquirer with online response . 98Refund – Acquirer with offline response . 99Save card automatically . 100smartPage! – HTTPS Post integration . 101Online Debit Transaction . 102Annex “B” – Currency list. 103maxiPago! Smart Payments 20156

About this documentThis document covers the basic concepts of the payment transaction types and the technical details of themaxiPago! payment platform. It contains functional examples of the requests, which can be copied andused in the first tests, and important observations that should be taken into account during integration.The latest version of this document is available at http://www.maxipago.com/docs/maxiPago API Ultima.pdfGlossaryAcquirerFinancial institution responsible for processing the credit card transaction and for funding theMerchant (i.e. Cielo, Rede)Card brandCompany that licenses the use of its name for credit card issuers. This is basically the "cardbrand" (i.e. Visa, Mastercard, Diners)CredentialsCombination of Merchant ID and Merchant Key, both supplied by maxiPago!CVV orCVNCard Verification Value or Card Verification NumberIssuerBank responsible for issuing the cards to consumers. It verifies if the card holder hassufficient funds for the purchase (ie. Itaú, Bradesco, HSBC)MerchantMIDCard holderBusiness that sells its products or services onlineUnique ID within maxiPago! and part of the CredentialsFinal customer, buyer.maxiPago! Smart Payments 20157

Choosing your integrationAPI IntegrationThe main feature of integration via API is that credit card data is typed in the merchant’s site and then sent tothe maxiPago!. There is no pop-up or redirects. The responsibility to collect the buyer's card data belongs tothe merchant, so there must be a concern about the safety of the data. It is necessary to purchase an SSLsecurity certificate.maxiPago! has integration libraries in Java, .NET, PHP, Python and Ruby available to help develop yourapplication. The SDKs are available online at http://www.maxipago.com/api.smartPage! IntegrationThe smartPage! is a quick integration method in our platform. After ending the order, the buyer is redirectedto our secure page to type their credit card information and complete the purchase. With this the merchant isnot responsible for managing or protecting the customer’s sensitive information, maxiPago! handles that.Magento IntegrationmaxiPago! has a Magento module, which allows a fast integration between your e-commerce store andour payment platform. Please get in touch with our support and Integration department to get theinstructions to download, configuring and access to our Magento’s documentation.Note: For Magento Integration and API: PCI request a mandatory security feature that is the use of TLS1.2 security certificate (Transport Layer Security) or higher. The maxiPago! as PCI compliant asks itscustomers to check the technical requirements needed to implement this safety certificate.maxiPago! Smart Payments 20158

Test EnvironmentThe test environment can simulate most of the requests and transaction types available in the platform.Please note that in the test environment no transactions will actually be processed.Below we have a list of scenarios that will generate programmed responses from our payment platform:ScenarioTransaction ResultTransaction is sale (“Sale”), with a pair amount, lower than 300.00 orhigher than 500.00Example: 1,00 or 299,92 or 610,06ApprovedTransaction is sale (“Sale”), it is an odd amount, lower than 300.00 orhigher than 500.00Example: 1,01 or 20,09 or 700,55DeclinedTransaction is sale (“Sale”) with amount between 300.00 and 500.00Example: 310,00 or 499,99Partially Approved(available in the US only)Authorization (“auth”), it is a pair value, lower than 300.00 or higher than 500.00 and the credit card number is 4901720380077300Fraud DeclineAuthorization (“auth”), it is an odd value, lower than 300.00 or higher than 500.00 and the credit card number is 4901720366459100Fraud ReviewBelow there is a list of test cards available. The CVV field can be any value with 3 or 4 digits and theexpiration date just needs to be valid, it means in the future.TypeTest NumberAmerican Express378282246310005American 000maxiPago! Smart Payments 20159

Integration CertificationTo ensure the quality of the technical integration between merchant and payment gateway and avoid problemswhen switching to Production, maxiPago! performs a Certification process. And maxiPago!’s team willvisit the merchant’s website and do a few purchases in order to validate the checkout process and the paymentIn this step.This process is usually fas

Added Magento integration Added payment method list Added TEF payment method 1.9.2 04/01/2013 Added Certification process 1.9.3 04/19/2013 Added Billing fields to Online Debit Added Discover card to Cielo 1.9.4 08/19/2013 Added boleto bar code reply (processorCode field) Removed restriction for unique Boleto Numbers Updated test scenarios