Vantiv CnpAPI Reference Guide Cnp API API9.14 V1.32
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 882
| Download | |
| Open PDF In Browser | View PDF |
cnpAPI Reference Guide January 2018 XML Release: 9.14 Document Version: 1.32 Vantiv cnpAPI Reference Guide Document Version: 1.32 All information whether text or graphics, contained in this manual is confidential and proprietary information of Vantiv, LLC and is provided to you solely for the purpose of assisting you in using a Vantiv, LLC product. All such information is protected by copyright laws and international treaties. No part of this manual may be reproduced or transmitted in any form or by any means, electronic, mechanical or otherwise for any purpose without the express written permission of Vantiv, LLC. The possession, viewing, or use of the information contained in this manual does not transfer any intellectual property rights or grant a license to use this information or any software application referred to herein for any purpose other than that for which it was provided. Information in this manual is presented "as is" and neither Vantiv, LLC or any other party assumes responsibility for typographical errors, technical errors, or other inaccuracies contained in this document. This manual is subject to change without notice and does not represent a commitment on the part Vantiv, LLC or any other party. Vantiv, LLC does not warrant that the information contained herein is accurate or complete. All trademarks are the property of their respective owners and all parties herein have consented to their trademarks appearing in this manual. Any use by you of the trademarks included herein must have express written permission of the respective owner. Copyright © 2003-2018, Vantiv, LLC - ALL RIGHTS RESERVED. CONTENTS About This Guide Intended Audience ........................................................................................................ xxiii Revision History ............................................................................................................ xxiii Document Structure ..................................................................................................... xxvii Documentation Set xxix Typographical Conventions ........................................................................................... xxx Contact Information....................................................................................................... xxxi Chapter 1 Introduction The cnpAPI Data Format .................................................................................................. 2 Communications Protocols ......................................................................................... 2 General XML Coding Requirements ........................................................................... 4 Other XML Resources................................................................................................. 4 Batch Transaction Processing .......................................................................................... 5 Recommended Session File Size ............................................................................... 5 Payment Integration Platform (cnpAPI SDKs) .................................................................. 6 Duplicate Transaction Detection ....................................................................................... 7 Batch Duplicate Checking ........................................................................................... 7 Online Duplicate Checking.......................................................................................... 8 Coding for Report Groups............................................................................................... 10 Additional/Alternate Methods of Tagging Transactions ............................................ 11 Recovery......................................................................................................................... 12 Authorization/Sale Recycling .................................................................................... 12 Recycling Engine ................................................................................................ 12 Account Updater Service ......................................................................................... 14 Match Back ......................................................................................................... 15 Merchant Requirements ...................................................................................... 17 Account Updater Features .................................................................................. 17 Recurring Engine ............................................................................................................ 18 Payment Plans .......................................................................................................... 18 Subscriptions............................................................................................................. 19 Add Ons and Discounts ...................................................................................... 21 Recurring Reports ..................................................................................................... 21 Transaction Types and Uses .................................................................................... 22 Issuer Insights................................................................................................................. 24 Issuer Insights Secure Scheduled Report................................................................. 24 Real Time Indicators ................................................................................................. 24 Prepaid Indicator ................................................................................................. 24 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. iii cnpAPI Reference Guide Contents Affluence Indicator .............................................................................................. 25 Issuer Country Indicator ...................................................................................... 26 Cardholder Type Indicator................................................................................... 26 Extended Network Data ............................................................................................ 26 Insights Analytics Dashboard.................................................................................... 28 Fraud Toolkit .................................................................................................................. 29 Essential Tier ............................................................................................................ 30 Prepaid Card Filtering ........................................................................................ 30 International BIN Filtering ................................................................................... 31 Prior Chargeback Filtering ................................................................................. 31 Security Code No-Match Filter ........................................................................... 31 Card Velocity Filtering ........................................................................................ 32 Prior Fraud Advice Filtering ................................................................................ 32 AVS Filter ........................................................................................................... 32 Email Velocity Filter............................................................................................. 33 Phone Velocity Filter ........................................................................................... 33 IP Velocity Filter .................................................................................................. 33 Device Velocity Filter........................................................................................... 34 Application of Filters - Filtering Rules ................................................................. 34 Extended Tier............................................................................................................ 35 Premium Tier............................................................................................................. 36 Modifications to Your Web Page............................................................................... 36 cnpAPI Transactions ........................................................................................... 37 Information Only Option ...................................................................................... 39 Fraud Check Transactions ................................................................................. 39 Tokenization Feature ...................................................................................................... 41 How Tokenization Works .......................................................................................... 42 Token Formats .......................................................................................................... 43 Obtaining Tokens ...................................................................................................... 44 Bulk Token Registration ...................................................................................... 44 Supported Token Transactions ................................................................................. 45 Compliance with Visa Best Practices for Tokenization ............................................. 46 eCheck Processing ......................................................................................................... 47 Validation Feature ..................................................................................................... 47 Verification Feature ................................................................................................... 47 Required Contents of Decline Notice .................................................................. 48 Automatic Notice of Change (NoC) Updates ............................................................ 49 Auto Redeposit Feature ............................................................................................ 49 eCheck Prenotification .............................................................................................. 50 SEPA Direct Debit........................................................................................................... 52 SEPA Direct Debit - Vantiv Supplied Mandate.......................................................... 52 iv Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents SEPA Direct Debit - Merchant Supplied Mandate..................................................... 55 iDEAL, SOFORT, and Giropay ...................................................................................... 58 eCommerce Solution for Apple Pay™ ............................................................................ 61 Overview of Apple Pay Operation ............................................................................. 61 Vantiv Decryption of Apple Pay PKPaymentToken................................................... 62 Using the Browser JavaScript API for Apple Pay on the Web ............................ 62 Using the Vantiv Mobile API for Apple Pay ............................................................... 64 Alternate Flow using a Register Token Request ................................................. 66 Submitting the Apple Pay PKPaymentToken in cnpAPI ..................................... 66 Merchant Decryption of Apple Pay PKPaymentToken.............................................. 67 Recurring Payments with Apple Pay......................................................................... 68 eCommerce Solution for Android Pay™ ......................................................................... 69 Android Pay using eProtect....................................................................................... 69 Merchant Decryption Method .................................................................................... 72 Recurring Payments with Android Pay...................................................................... 75 Supported Transaction Types ......................................................................................... 76 Authorization Transaction ......................................................................................... 76 AVS Only Transaction ......................................................................................... 77 Authorization Reversal Transactions ........................................................................ 77 Notes on the Use of Authorization Reversal Transactions.................................. 78 Using Authorization Reversal to Halt Recycling Engine...................................... 79 Activate Transaction.................................................................................................. 79 Activate Reversal Transaction (Online Only) ............................................................ 79 Balance Inquiry Transaction...................................................................................... 79 Cancel Subscription Transaction .............................................................................. 79 Capture Transaction.................................................................................................. 80 Capture Given Auth Transaction............................................................................... 80 Create Plan Transaction ........................................................................................... 81 Credit Transaction..................................................................................................... 81 Deactivate Transaction ............................................................................................. 81 Deactivate Reversal Transaction (Online Only) ........................................................ 81 Deposit Reversal Transaction (Online Only)............................................................. 81 eCheck Credit Transaction........................................................................................ 82 eCheck Prenotification Credit Transaction................................................................ 82 eCheck Prenotification Sale Transaction .................................................................. 82 eCheck Redeposit Transaction ................................................................................. 82 eCheck Sales Transaction ........................................................................................ 82 eCheck Verification Transaction ............................................................................... 82 eCheck Void Transaction (Online Only).................................................................... 83 Force Capture Transaction ....................................................................................... 83 Load Transaction ...................................................................................................... 83 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. v cnpAPI Reference Guide Contents Load Reversal Transaction (Online Only) ................................................................. 83 Refund Reversal Transaction (Online Only) ............................................................. 83 Sale Transaction ....................................................................................................... 84 Unload Transaction ................................................................................................... 84 Unload Reversal Transaction (Online Only).............................................................. 84 Update Plan Transaction........................................................................................... 84 Update Subscription Transaction .............................................................................. 84 Void Transaction (Online Only) ................................................................................. 85 Using Void to Halt Recycling Engine................................................................... 85 Instruction-Based Dynamic Payout Transactions .................................................... 85 Chapter 2 Testing Your cnpAPI Transactions Certification and Testing Environments .......................................................................... 88 Sandbox Environment............................................................................................... 88 Pre-Live Environment................................................................................................ 88 Pre-Live Environment Limitations and Maintenance Schedules ......................... 89 Post-Live Environment .............................................................................................. 89 Post-Live Environment Limitations and Maintenance Schedules ....................... 89 Overview of Testing ........................................................................................................ 91 Planning for Certification Testing .............................................................................. 91 Required Certification Testing................................................................................... 92 Optional Testing ........................................................................................................ 92 System Doctor........................................................................................................... 92 Transferring Files ............................................................................................................ 95 Transferring Session Files ........................................................................................ 95 Submitting a Session File for Processing............................................................ 95 Retrieving Processed Session Files.................................................................... 96 Transferring Online Files........................................................................................... 96 ASP Programming Example ............................................................................... 97 Java Programming Example ............................................................................... 98 Notes on Timeout Settings .................................................................................. 99 Notes on Persistent Connections ........................................................................ 99 Helpful Web Sites.............................................................................................. 100 Performing the Required Certification Tests ................................................................. 101 Testing Authorization (including Indicators), AVS Only, Capture, Credit, Sale, and Void Transactions............................................................................................................ 101 Testing Recycling Advice .................................................................................. 116 Testing Authorization Reversal Transactions.......................................................... 117 Testing eCheck Transactions.................................................................................. 121 Testing Token Transactions.................................................................................... 128 Performing the Optional Tests ...................................................................................... 133 vi Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents Testing AVS and Card Validation............................................................................ 134 Testing Address Responses ................................................................................... 135 Testing Advanced AVS Response Codes............................................................... 137 Testing Response Reason Codes and Messages .................................................. 138 Testing 3DS Responses ......................................................................................... 141 Testing the Prepaid Filtering Feature...................................................................... 142 Testing the International Card Filter Feature .......................................................... 144 Testing Security Code No-Match Filtering .............................................................. 145 Testing Advanced Fraud Tools ............................................................................... 147 Testing Account Updater......................................................................................... 149 Testing Account Updater Extended Response Codes ...................................... 150 Testing Account Updater for Tokenized Merchants .......................................... 151 Testing Tax Billing................................................................................................... 151 Testing Convenience Fees ..................................................................................... 152 Testing the Recycling Engine.................................................................................. 155 Testing Recycling Engine Cancellation ............................................................. 163 Testing Recurring Engine Transactions .................................................................. 165 Testing Gift Card Transactions ............................................................................... 178 Testing MasterPass Transactions........................................................................... 186 Testing Apple Pay Transaction Processing ............................................................ 187 Testing the Submission of the Decrypted PKPaymentToken in cnpAPI ........... 187 Testing the Submission of PKPaymentToken in cnpAPI .................................. 187 Testing Android Pay Transaction Processing ......................................................... 189 Testing Android Pay using eProtect .................................................................. 189 Testing SEPA Direct Debit Transactions ................................................................ 190 Testing iDEAL Transactions.................................................................................... 192 Testing Giropay Transactions ................................................................................. 193 Testing SOFORT Transactions............................................................................... 194 Testing Online Duplicate Transaction Processing .................................................. 196 Testing Transaction Volume Capacity .................................................................... 197 Chapter 3 cnpAPI Transaction Examples Overview of Online and Batch Processing Formats ..................................................... 200 Batch Process Format............................................................................................. 200 Supported Communication Protocols................................................................ 201 Batch Processing Request Format ................................................................... 201 Batch Processing Response Format................................................................. 201 Online Processing Format ............................................................................................ 202 Supported Communication Protocols...................................................................... 203 Online Processing Request Format ........................................................................ 203 Online Processing Response Format ..................................................................... 203 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. vii cnpAPI Reference Guide Contents Transaction Types and Examples................................................................................. 204 Authorization Transactions...................................................................................... 206 Authorization Request Structure ....................................................................... 206 Authorization Response Structure .................................................................... 213 Authorization Reversal Transactions ...................................................................... 218 Authorization Reversal Requests ...................................................................... 218 Authorization Reversal Responses ................................................................... 219 Activate Transactions.............................................................................................. 221 Activate Request ............................................................................................... 221 Activate Response ............................................................................................ 222 Activate Reversal Transactions (Online Only) ........................................................ 224 Activate Reversal Request ................................................................................ 224 Activate Reversal Response ............................................................................. 224 Balance Inquiry Transactions.................................................................................. 225 Balance Inquiry Request ................................................................................... 225 Balance Inquiry Response ................................................................................ 226 Cancel Subscription Transactions........................................................................... 227 Cancel Subscription Request............................................................................ 227 Cancel Subscription Response ......................................................................... 228 Capture Transactions.............................................................................................. 229 Capture Request ............................................................................................... 229 Capture Response ............................................................................................ 236 Capture Given Auth Transactions ........................................................................... 237 Capture Given Auth Request ............................................................................ 237 Capture Given Auth Response ......................................................................... 242 Create Plan Transactions........................................................................................ 243 Create Plan Request......................................................................................... 243 Create Plan Response ...................................................................................... 244 Credit Transactions ................................................................................................. 245 Credit Request for a Vantiv Processed Transaction ......................................... 245 Credit Request for a Non-Vantiv Processed Transaction ................................. 249 Credit Response ............................................................................................... 254 Deactivate Transactions.......................................................................................... 255 Deactivate Request........................................................................................... 255 Deactivate Response ........................................................................................ 256 Deactivate Reversal Transactions (Online Only) .................................................... 257 Deactivate Reversal Request............................................................................ 257 Deactivate Reversal Response......................................................................... 258 Deposit Reversal Transactions (Online Only) ......................................................... 259 Deposit Reversal Request ................................................................................ 259 Deposit Reversal Response.............................................................................. 259 viii Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents eCheck Credit Transactions.................................................................................... 260 eCheck Credit Request Against a Vantiv Transaction ...................................... 261 eCheck Credit Request for a Non-Vantiv Processed Sale ................................ 262 eCheck Credit Response .................................................................................. 263 eCheck Prenotification Credit Transactions (Batch Only) ....................................... 264 eCheck Prenotification Credit Request ............................................................. 264 eCheck Prenotification Credit Response .......................................................... 265 eCheck Prenotification Sale Transactions (Batch Only) ......................................... 266 eCheck Prenotification Sale Request................................................................ 266 eCheck Prenotification Sale Response ............................................................. 267 eCheck Redeposit Transactions ............................................................................. 268 eCheck Redeposit Request .............................................................................. 268 eCheck Redeposit Response............................................................................ 270 eCheck Sale Transactions ...................................................................................... 271 eCheck Sale Request ....................................................................................... 272 eCheck Sale Response..................................................................................... 273 eCheck Verification Transactions............................................................................ 275 eCheck Verification Request ............................................................................. 275 eCheck Verification Response .......................................................................... 278 eCheck Void Transactions (Online Only) ................................................................ 279 eCheck Void Request ....................................................................................... 279 eCheck Void Response..................................................................................... 280 Force Capture Transactions.................................................................................... 280 Force Capture Request..................................................................................... 280 Force Capture Response .................................................................................. 284 Load Transactions................................................................................................... 286 Load Request.................................................................................................... 286 Load Response ................................................................................................. 287 Load Reversal Transactions (Online Only) ............................................................. 288 Load Reversal Request..................................................................................... 288 Load Reversal Response.................................................................................. 288 Refund Reversal Transactions (Online Only).......................................................... 289 Refund Reversal Request ................................................................................. 290 Refund Reversal Response .............................................................................. 290 Register Token Transactions .................................................................................. 291 Register Token Request ................................................................................... 291 Register Token Response................................................................................. 294 RFR Transactions (Batch Only) .............................................................................. 297 RFR Request .................................................................................................... 297 RFR Response.................................................................................................. 298 Sale Transactions ................................................................................................... 299 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. ix cnpAPI Reference Guide Contents Sale Request..................................................................................................... 299 Sale Response.................................................................................................. 304 Unload Transactions ............................................................................................... 310 Unload Request ................................................................................................ 310 Unload Response.............................................................................................. 311 Unload Reversal Transactions (Online Only).......................................................... 312 Unload Reversal Request ................................................................................. 312 Unload Reversal Response .............................................................................. 313 Update Plan Transactions....................................................................................... 314 Update Plan Request ........................................................................................ 314 Update Plan Response ..................................................................................... 315 Update Subscription Transactions .......................................................................... 315 Update Subscription Request ........................................................................... 315 Update Subscription Response......................................................................... 317 Update Card Validation Number Transactions........................................................ 318 Update Card Validation Number Request ......................................................... 318 Update Card Validation Number Response ...................................................... 318 Void Transactions (Online Only) ............................................................................. 319 Void Request..................................................................................................... 320 Void Response.................................................................................................. 320 Chapter 4 cnpAPI Elements accNum......................................................................................................................... 324 accountInfo ................................................................................................................... 325 accountInformation ....................................................................................................... 326 accountNumber............................................................................................................. 327 accountNumberLength ................................................................................................. 328 accountUpdate.............................................................................................................. 329 accountUpdateFileRequestData ................................................................................... 330 accountUpdater............................................................................................................. 331 accountUpdateResponse.............................................................................................. 335 accType ........................................................................................................................ 336 actionReason ................................................................................................................ 337 activate ......................................................................................................................... 338 activateResponse ........................................................................................................ 339 activateReversal .......................................................................................................... 340 activateReversalResponse .......................................................................................... 341 active ............................................................................................................................ 342 addOnCode .................................................................................................................. 343 addressIndicator ........................................................................................................... 344 addressLine1, addressLine2, addressLine3 ................................................................. 345 x Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents advancedAVSResult ..................................................................................................... 346 advancedFraudChecks ................................................................................................ 347 advancedFraudResults ................................................................................................ 348 affiliate........................................................................................................................... 349 affluence ....................................................................................................................... 350 allowPartialAuth ............................................................................................................ 351 amexAggregatorData.................................................................................................... 352 amount .......................................................................................................................... 353 androidpayResponse ................................................................................................... 354 applepay ....................................................................................................................... 355 applepayResponse ....................................................................................................... 356 applicationData ............................................................................................................. 357 applicationExpirationDate ............................................................................................. 358 applicationPrimaryAccountNumber............................................................................... 359 approvedAmount........................................................................................................... 360 authAmount................................................................................................................... 361 authCode ...................................................................................................................... 362 authDate ....................................................................................................................... 363 authenticatedByMerchant ............................................................................................. 364 authentication................................................................................................................ 365 authenticationResult ..................................................................................................... 366 authenticationTransactionId.......................................................................................... 367 authenticationValue ...................................................................................................... 368 authInformation ............................................................................................................. 369 authorization ................................................................................................................. 370 authorizationResponse ................................................................................................. 371 authorizationSourcePlatform......................................................................................... 372 authReversal................................................................................................................. 373 authReversalResponse................................................................................................. 374 availableBalance........................................................................................................... 375 avsResult ...................................................................................................................... 376 balanceInquiry .............................................................................................................. 377 balanceInquiryResponse ............................................................................................. 378 batchRequest................................................................................................................ 379 batchResponse ............................................................................................................. 386 beginningBalance ........................................................................................................ 387 billingDate .................................................................................................................... 388 billMeLaterRequest ....................................................................................................... 389 billMeLaterResponseData............................................................................................. 391 billToAddress ................................................................................................................ 392 bin ................................................................................................................................. 394 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xi cnpAPI Reference Guide Contents bmlMerchantId .............................................................................................................. 395 bmlProductType............................................................................................................ 396 bypassVelocityCheck .................................................................................................... 397 campaign ...................................................................................................................... 398 cancelSubscription ....................................................................................................... 399 cancelSubscriptionResponse ....................................................................................... 400 capability ....................................................................................................................... 401 capture .......................................................................................................................... 402 captureGivenAuth ......................................................................................................... 403 captureGivenAuthResponse ......................................................................................... 405 captureResponse.......................................................................................................... 406 card ............................................................................................................................... 407 cardAcceptorTaxId........................................................................................................ 409 cardholderAuthentication .............................................................................................. 410 cardholderId .................................................................................................................. 411 cardholderName ........................................................................................................... 412 cardOrToken ................................................................................................................. 413 cardProductType........................................................................................................... 414 cardSuffix ...................................................................................................................... 415 cardValidationNum........................................................................................................ 416 cardValidationResult ..................................................................................................... 417 cashBackAmount ......................................................................................................... 418 catLevel ........................................................................................................................ 419 ccdPaymentInformation ................................................................................................ 420 chargeback ................................................................................................................... 421 checkNum ..................................................................................................................... 422 city................................................................................................................................. 423 clinicOtherAmount......................................................................................................... 424 code .............................................................................................................................. 425 commodityCode ............................................................................................................ 426 companyName.............................................................................................................. 427 country .......................................................................................................................... 428 createAddOn ................................................................................................................ 429 createDiscount ............................................................................................................. 430 createPlan .................................................................................................................... 431 createPlanResponse .................................................................................................... 432 credit ............................................................................................................................. 433 creditLine ...................................................................................................................... 435 creditLitleTxnId ............................................................................................................. 436 creditResponse ............................................................................................................. 437 cryptogram ................................................................................................................... 438 xii Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents currencyCode................................................................................................................ 439 customAttribute1 ........................................................................................................... 440 customBilling................................................................................................................. 441 customerInfo ................................................................................................................. 443 customerIpAddress ....................................................................................................... 445 customerReference....................................................................................................... 446 customerRegistrationDate ............................................................................................ 447 customerType ............................................................................................................... 448 customerWorkTelephone.............................................................................................. 449 data ............................................................................................................................... 450 deactivate ..................................................................................................................... 451 deactivateResponse .................................................................................................... 452 deactivateReversal ...................................................................................................... 453 deactivateReversalResponse ...................................................................................... 454 debtRepayment............................................................................................................. 455 deleteAddOn ................................................................................................................ 456 deleteDiscount ............................................................................................................. 457 deliveryType.................................................................................................................. 458 dentalAmount................................................................................................................ 459 depositReversal ........................................................................................................... 460 depositReversalResponse ........................................................................................... 461 description .................................................................................................................... 462 descriptor ...................................................................................................................... 463 destinationCountryCode ............................................................................................... 464 destinationPostalCode .................................................................................................. 465 detailTax ....................................................................................................................... 466 deviceManufacturerIdentifier......................................................................................... 467 deviceReputationScore ................................................................................................ 468 deviceReviewStatus...................................................................................................... 469 discountAmount ............................................................................................................ 470 discountCode ............................................................................................................... 471 dob ................................................................................................................................ 472 dutyAmount................................................................................................................... 473 echeck........................................................................................................................... 474 eCheckAccountSuffix ................................................................................................... 475 echeckCredit ................................................................................................................. 476 echeckCreditResponse................................................................................................. 478 echeckForToken ........................................................................................................... 479 echeckOrEcheckToken................................................................................................. 480 echeckPreNoteCredit ................................................................................................... 481 echeckPreNoteCreditResponse ................................................................................... 482 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xiii cnpAPI Reference Guide Contents echeckPreNoteSale ..................................................................................................... 483 echeckPreNoteSaleResponse ..................................................................................... 484 echeckRedeposit .......................................................................................................... 485 echeckRedepositResponse .......................................................................................... 486 echeckSale ................................................................................................................... 487 echeckSalesResponse ................................................................................................. 488 echeckToken................................................................................................................. 489 echeckVerification......................................................................................................... 490 echeckVerificationResponse......................................................................................... 491 echeckVoid ................................................................................................................... 492 echeckVoidResponse ................................................................................................... 493 eciIndicator.................................................................................................................... 494 email ............................................................................................................................. 495 employerName.............................................................................................................. 496 encryptedTrack ............................................................................................................ 497 endDate ....................................................................................................................... 498 endingBalance ............................................................................................................. 499 enhancedAuthResponse............................................................................................... 500 enhancedData............................................................................................................... 502 entryMode ..................................................................................................................... 506 ephemeralPublicKey ..................................................................................................... 507 expDate......................................................................................................................... 508 expMonth ..................................................................................................................... 509 expYear ........................................................................................................................ 510 extendedCardResponse .............................................................................................. 511 filtering .......................................................................................................................... 512 finalPayment ................................................................................................................ 513 firstName....................................................................................................................... 514 forceCapture ................................................................................................................. 515 forceCaptureResponse ................................................................................................. 516 formatId ........................................................................................................................ 517 fraudCheck ................................................................................................................... 518 fraudCheckResponse .................................................................................................. 519 fraudFilterOverride ....................................................................................................... 520 fraudResult ................................................................................................................... 521 fundingSource............................................................................................................... 522 fundingSubmerchantId ................................................................................................. 523 fundsTransferId............................................................................................................. 524 giftCardBin ................................................................................................................... 525 giftCardResponse ........................................................................................................ 526 giropay ......................................................................................................................... 527 xiv Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents giropayResponse ......................................................................................................... 528 header .......................................................................................................................... 529 healthcareAmounts ....................................................................................................... 530 healthcareIIAS .............................................................................................................. 531 iban .............................................................................................................................. 532 ideal .............................................................................................................................. 533 idealResponse ............................................................................................................. 534 IIASFlag ........................................................................................................................ 535 incomeAmount .............................................................................................................. 536 incomeCurrency............................................................................................................ 537 international .................................................................................................................. 539 intervalType ................................................................................................................. 540 invoiceReferenceNumber ............................................................................................. 541 issuerCountry................................................................................................................ 542 itemCategoryCode ........................................................................................................ 543 itemDescription ............................................................................................................. 544 itemDiscountAmount..................................................................................................... 545 itemSequenceNumber .................................................................................................. 546 ksn ................................................................................................................................ 547 lastName....................................................................................................................... 548 lineItemData.................................................................................................................. 549 lineItemTotal ................................................................................................................. 551 lineItemTotalWithTax .................................................................................................... 552 litleInternalRecurringRequest ....................................................................................... 553 litleOnlineRequest......................................................................................................... 554 litleOnlineResponse ...................................................................................................... 555 litleRequest ................................................................................................................... 557 litleResponse ................................................................................................................ 558 litleSessionId................................................................................................................. 560 litleToken....................................................................................................................... 561 litleTxnId........................................................................................................................ 562 load .............................................................................................................................. 563 loadResponse .............................................................................................................. 564 loadReversal ................................................................................................................ 565 loadReversalResponse ................................................................................................ 566 mandateProvider .......................................................................................................... 567 mandateReference ...................................................................................................... 568 mandateSignatureDate ................................................................................................ 569 mandateURL ................................................................................................................ 570 merchantData ............................................................................................................... 571 merchantGroupingId ..................................................................................................... 572 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xv cnpAPI Reference Guide Contents merchantId .................................................................................................................... 573 message ....................................................................................................................... 574 middleInitial ................................................................................................................... 575 mpos ............................................................................................................................. 576 name ............................................................................................................................. 577 networkTransactionId ................................................................................................... 578 newAccountInfo ............................................................................................................ 579 newCardInfo ................................................................................................................. 580 newCardTokenInfo ....................................................................................................... 581 newTokenInfo ............................................................................................................... 582 nextRecycleTime ......................................................................................................... 583 number.......................................................................................................................... 584 numberOfPayments ..................................................................................................... 585 onlinePaymentCryptogram ........................................................................................... 586 orderDate ...................................................................................................................... 587 orderId........................................................................................................................... 588 orderSource .................................................................................................................. 589 originalAccountInfo ....................................................................................................... 591 originalCard................................................................................................................... 592 originalCardInfo ............................................................................................................ 593 originalCardTokenInfo .................................................................................................. 594 originalToken ................................................................................................................ 595 originalTokenInfo .......................................................................................................... 596 originalTransactionAmount .......................................................................................... 597 originalNetworkTransactionId ...................................................................................... 598 password....................................................................................................................... 599 payerId .......................................................................................................................... 600 payFacCredit................................................................................................................. 601 payFacCreditResponse ............................................................................................... 602 payFacDebit ................................................................................................................. 603 payFacDebitResponse ................................................................................................. 604 paymentDataType ........................................................................................................ 605 paymentPurpose........................................................................................................... 606 paypage ........................................................................................................................ 607 paypageRegistrationId .................................................................................................. 608 paypal ........................................................................................................................... 609 payPalNotes.................................................................................................................. 610 payPalOrderComplete .................................................................................................. 611 phone ............................................................................................................................ 612 phone as a child of billToAddress and shipToAddress ..................................... 612 phone as a child of customBilling...................................................................... 612 xvi Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents physicalCheckCredit .................................................................................................... 613 physicalCheckCreditResponse .................................................................................... 614 physicalCheckDebit ...................................................................................................... 615 physicalCheckDebitResponse ..................................................................................... 616 pin ................................................................................................................................ 617 planCode ...................................................................................................................... 618 pos ................................................................................................................................ 619 postDate........................................................................................................................ 620 postDay ........................................................................................................................ 621 preapprovalNumber ...................................................................................................... 622 preferredLanguage ...................................................................................................... 623 prepaid .......................................................................................................................... 624 prepaidCardType .......................................................................................................... 625 processingInstructions .................................................................................................. 626 processingType............................................................................................................. 627 productCode ................................................................................................................. 628 publicKeyHash ............................................................................................................. 629 quantity ......................................................................................................................... 630 recurringRequest ......................................................................................................... 631 recurringResponse ....................................................................................................... 632 recurringTxnId .............................................................................................................. 633 recycleAdvice................................................................................................................ 634 recycleAdviceEnd ........................................................................................................ 635 recycleBy ...................................................................................................................... 636 recycleEngineActive ..................................................................................................... 637 recycleId ....................................................................................................................... 638 recycling ....................................................................................................................... 639 recycling Element as a Child of authorizationResponse or saleResponse ............. 639 recycling Element as a Child of voidResponse ....................................................... 640 recyclingRequest .......................................................................................................... 641 redirectToken ............................................................................................................... 642 redirectUrl .................................................................................................................... 643 refundReversal ............................................................................................................. 644 refundReversalResponse ............................................................................................ 645 registerTokenRequest................................................................................................... 646 registerTokenResponse................................................................................................ 647 reloadable ..................................................................................................................... 648 reserveCredit ............................................................................................................... 649 reserveCreditResponse ............................................................................................... 650 reserveDebit ................................................................................................................. 651 reserveDebitResponse ................................................................................................. 652 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xvii cnpAPI Reference Guide Contents residenceStatus ............................................................................................................ 653 response ....................................................................................................................... 654 responseCode .............................................................................................................. 655 responseMessage ........................................................................................................ 656 responseTime ............................................................................................................... 657 RFRRequest ................................................................................................................. 658 RFRResponse .............................................................................................................. 659 routingNum ................................................................................................................... 660 RxAmount ..................................................................................................................... 661 sale ............................................................................................................................... 662 saleResponse ............................................................................................................... 664 salesTax........................................................................................................................ 666 secondaryAmount ........................................................................................................ 667 sellerId .......................................................................................................................... 668 sellerMerchantCategoryCode ....................................................................................... 669 sepaDirectDebit ........................................................................................................... 670 sepaDirectDebitResponse ........................................................................................... 671 sequenceType ............................................................................................................. 672 shipFromPostalCode .................................................................................................... 673 shippingAmount ............................................................................................................ 674 shipToAddress .............................................................................................................. 675 signature ....................................................................................................................... 676 sofort ............................................................................................................................ 677 sofortResponse ............................................................................................................ 678 ssn ................................................................................................................................ 679 startDate ...................................................................................................................... 680 state .............................................................................................................................. 681 submerchantCredit ....................................................................................................... 682 submerchantCreditResponse ...................................................................................... 683 submerchantDebit ........................................................................................................ 684 submerchantDebitResponse ........................................................................................ 685 submerchantName........................................................................................................ 686 subscription .................................................................................................................. 687 subscriptionId ............................................................................................................... 689 surchargeAmount ......................................................................................................... 690 taxAmount..................................................................................................................... 691 taxExempt ..................................................................................................................... 692 taxIncludedInTotal......................................................................................................... 693 taxRate.......................................................................................................................... 694 taxType ......................................................................................................................... 695 taxTypeIdentifier ........................................................................................................... 696 xviii Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents terminalId ..................................................................................................................... 697 termsAndConditions...................................................................................................... 698 threatMetrixSessionId .................................................................................................. 699 token ............................................................................................................................. 700 token (Vantiv generated card number replacement)............................................... 700 token (PayPal generated) ....................................................................................... 700 tokenMessage............................................................................................................... 702 tokenResponse ............................................................................................................. 703 tokenResponseCode .................................................................................................... 704 totalHealthcareAmount ................................................................................................. 705 track .............................................................................................................................. 706 track1Status ................................................................................................................. 707 track2Status ................................................................................................................. 708 transactionAmount ....................................................................................................... 709 transactionId ................................................................................................................. 710 transactionId as a Child of the paypal element ....................................................... 710 transactionId as a Child of the header element....................................................... 710 trialIntervalType ........................................................................................................... 712 trialNumberOfIntervals ................................................................................................. 713 triggeredRule ............................................................................................................... 714 type ............................................................................................................................... 715 type Element as a Child of the parent elements listed below.................................. 715 type Element as a Child of fundingSource .............................................................. 716 unitCost......................................................................................................................... 717 unitOfMeasure .............................................................................................................. 718 unload .......................................................................................................................... 719 unloadResponse .......................................................................................................... 720 unloadReversal ............................................................................................................ 721 unloadReversalResponse ............................................................................................ 722 updateAddOn ............................................................................................................... 723 updatedCard ................................................................................................................. 724 updateCardValidationNumOnToken ............................................................................. 725 updateCardValidationNumOnTokenResponse............................................................. 726 updateDiscount ............................................................................................................ 727 updatePlan ................................................................................................................... 728 updatePlanResponse ................................................................................................... 729 updateSubscription ...................................................................................................... 730 updateSubscriptionResponse ...................................................................................... 734 updatedToken ............................................................................................................... 735 url .................................................................................................................................. 736 user ............................................................................................................................... 737 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xix cnpAPI Reference Guide Contents vendorCredit ................................................................................................................ 738 vendorCreditResponse ................................................................................................ 739 vendorDebit .................................................................................................................. 740 vendorDebitResponse ................................................................................................. 741 vendorName ................................................................................................................ 742 verificationCode ............................................................................................................ 743 verify ............................................................................................................................. 744 version ......................................................................................................................... 745 visionAmount ................................................................................................................ 746 virtualAccountNumber .................................................................................................. 747 virtualAuthenticationKeyData........................................................................................ 748 virtualAuthenticationKeyPresenceIndicator .................................................................. 749 virtualGiftCard .............................................................................................................. 750 virtualGiftCardResponse .............................................................................................. 751 void ............................................................................................................................... 752 voidResponse ............................................................................................................... 754 wallet ............................................................................................................................ 755 walletSourceType ........................................................................................................ 756 walletSourceTypeId ..................................................................................................... 757 yearsAtEmployer........................................................................................................... 758 yearsAtResidence......................................................................................................... 759 zip ................................................................................................................................. 760 Appendix A Payment Transaction Response Codes Payment Transaction Response Codes ....................................................................... 762 3DS Authentication Result Codes................................................................................. 784 AVS Response Codes .................................................................................................. 786 AAVS Response Codes................................................................................................ 787 Card Validation Response Codes ................................................................................. 790 Advanced Fraud Tools Triggered Rules ....................................................................... 791 XML Validation Error Messages ................................................................................... 806 Additional Response Header Error Messages .............................................................. 808 ACH Return Reason Codes .......................................................................................... 809 ACH NoC Change Codes ............................................................................................. 813 Canadian eCheck Return Codes .................................................................................. 814 xx Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents Appendix B Credit Card Number Formats Appendix C Test Card Numbers Appendix D PayFac™ Dynamic Payout Advantages of Using Dynamic Payout.......................................................................... 826 Overview of Dynamic Payout........................................................................................ 827 Timing of Transactions, Reports, and Money Movement........................................ 828 Money Movement and Accounts............................................................................. 829 Account Balance Verifications........................................................................... 830 Example of Funding Instruction Session File................................................................ 832 Funding Instruction Certification Testing....................................................................... 835 SSR Reports ................................................................................................................. 837 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xxi cnpAPI Reference Guide xxii Contents Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. ABOUT THIS GUIDE This manual serves as a reference to the cnpAPI transaction formats used for payment processing with Vantiv, LLC. It also explains how to perform unattended transaction testing and attended certification testing with Vantiv. Intended Audience This document is intended for technical personnel who will be setting up and maintaining payment processing using the cnpAPI format. Revision History This document has been revised as follows: TABLE 1 Document Revision History Doc. Version Description Location(s) 1.0 Initial release of LitleXML Reference Guide for schema V9.0. N/A Added information about PayFac Instruction-Based funding. Chapter 1 & Appendix D Added information about Mobile Point of Sale feature. Chapter 1 1.1 Added Cert test cases for MasterCard MasterPass Chapter 2 1.2 Added information about new (Batch only) transaction types for eCheck Prenotification. Note: These transaction types are not yet Generally Available. Examples will be added later. Chapter 4 Added applepay enum to the orderSource element. Also, changed MaxLength of authenticationValue element from 32 to 56. Chapter 4 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xxiii cnpAPI Reference Guide About This Guide TABLE 1 Doc. Version 1.3 1.4 1.5 1.6 1.7 1.8 xxiv Revision History Document Revision History Description Location(s) Added several new elements for Apple Pay transactions and for convenience Fees added in schema version V9.2. Chapter 4 Added info about new transaction types associated with the PayFac Instruction-Based Dynamic Payout. Chapter 4 and Appendix D Added explanations and examples of eCheck Prenotification transactions, as well as Cert test info. Chapters 1, 2, and 3 Added secondaryAmount element for Convenience Fees credit and echeckCredit transaction types. Also added certification tests for Convenience fees and Response Reason Codes (380-385). Chapters 2,and 4 Added account markers for use with Advanced Fraud Tools. Chapters 1 and 4 Augmented the description of eCheck Prenotification. Chapter 1 Added ccdPaymentInformation to the echeck element for use by PayFacs using Instruction-Based Dynamic Payout. Chapter 4 Minor corrections and change to recommended Batch size. Chapter1 Updated info about several ApplePay elements. Also added cardSuffix element. Chapter 4 Added two new Response Codes (530 and 531) for Apple Pay. Appendix A Added sections about Apple Pay options and Certification tests. Chapters 1 and 2 Added more Triggered Rule Definitions for Advanced Fraud Tools. Appendix A Added info about front-end check performed on funding instruction batches. Appendix D Added information about support for eChecks in Canada. All Changed maxLength of terminalId element from 10 to 8. Chapter 4 Changed applicationData element from required to optional. Chapter 4 Removed test for Unknown Session response from Advanced fraud Tools tests. Chapter 2 Miscellaneous minor corrections. Chapters 2, 3, & 4 Added Note about use of pipe character, "|", in orderId. Chapter 4 Added two new Advanced Fraud Triggered Rules. Appendix A Appendix A Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Revision History TABLE 1 About This Guide Document Revision History Doc. Version Description Location(s) 1.9 Miscellaneous minor corrections. All Added note about Visa Level 3 data requirements. Chapter 4 Added applepayResponse element to structural examples. Also, added notes about structure of the applepayResponse element for Register token transactions. Chapters 3 & 4 Eliminated references to self-certification. Chapter 2 Eliminated references to white-listed IP Address requirement. Chapter 2 Minor corrections. All Added list of Canadian eCheck Return Codes Appendix A Added XML example of saleResponse with recurring info. Chapter 3 General update to Appendix D. Appendix D 1.12 Clarified definition of fundingSubmerchantId element. Chapter 4 1.13 Added new Triggered Rules to Table A-6. Appendix A Added info about new processingType element (XML V9.6). Chapters 3 & 4 Corrected definitions of transactionId and applicationData elements (child of header). Chapter 4 1.14 Added VisaCheckout enum to the walletSourceType element. Chapter 4 1.15 Changed all 2016 expiration dates in tests to 2021. Chapter 2 Added information about Vantiv eComm support for Android Pay, as well as certification test and element information. Chapters 1, 2, and 4 1.16 Added information about the pin element (Gift Card) and updated various examples to include the new element. Chapters 3 and 4 1.17 Corrected definitions ofelement and its child elements. Chapter 4 Added information about Response Code 823. Appendix A 1.18 Purged info about PayPal Credit (aka BillMeLater) support and added notes to PayPal Credit elements in schema. All 1.19 Corrected in Cert tests cases 10 through 13. Chapter 2 Added 2-series MC test card numbers to list. Appendix C Added info to Apple Pay section. Chapter 1 Added information about new networkId and related elements introduced in XML V9.10. Chapters 1 and 4 1.10 1.11 1.20 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xxv cnpAPI Reference Guide About This Guide TABLE 1 Revision History Document Revision History Doc. Version Description Location(s) 1.21 Corrected minor typos in some examples and Notes. All Added eciIndicator element to anodroidpayResponse. Chapter 4 Corrected Apple Pay and Android Pay recurring sections to reflect correct element names. Chapter 1 Removed section about Health Care card support feature. Chapter 1 Added more Convenience Fee test (partial capture). Chapter 2 Added section about SEPA payments and new SEP elements. Chapters 1, 3, and 4 Added new elements for iDeal method of payment (not GA). Chapters 3 and 4 Added example of Sessionless Advanced Fraud request. Chapter 1 Add info about new Report Group creation limits. Chapter 1 Augment information about SEPA capabilities. Chapter 1 Added SEPA Cert test info. Chapter 2 Added info to Apple Pay section about using a Register Token Request prior to submitting an Auth/Sale. Chapter 1 Added code R900 to list of Canadian eCheck Return Codes Appendix A Added SEPA related Response Codes 379, 386, and 901 through 916. Appendix A Augment information about SEPA capabilities. Chapter 1 Revamped Fraud Toolkit section Chapter 1 Changed salesTax requirements for Level 2 and Level 3 data. Chapter 4 Removed R900 eCheck Return Code and added 900-x series. Appendix A 1.25 Added information about the iDEAL international payment method, which is now GA. Chapters 1, 2, and 4 1.26 Corrected times for Pre/Post-Live Maintenance Windows. Chapter 2 1.27 Replaced LitleXML with cnpAPI. All Added information about SOFORT and Giropay. Chapters 1, 2, and 4 Replaced Customer Insights section with Issuer Insights section. Chapter 1 Corrected Response Code for Test GC17 - 281 changed to 218. Chapter 2 Updated Litle to Vantiv in Response messages. All Added Note about expDate to token element definition. Chapter 4 Added/modified information in section 2.1. Chapter 2 Modified requirements for Level 2/3 data (enhancedData element). Chapter 4 1.22 1.23 1.24 1.28 1.29 xxvi Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Document Structure TABLE 1 About This Guide Document Revision History Doc. Version Description Location(s) 1.30 Removed Mobile Point of Sale material from Guide. Chapters 1 and 2 Fix Sandbox/github links to point at new domains. Chapter 2 Fixed error in definition of customerReference element. Chapter 4 Added info about support for Visa token transactions with 3-D Secure (TAVV and DTVV), as well as new 3-DS response code definitions. Chapter 4 & Appendix A Removed reference to Recurring Snapshot report. Chapter 1 Updated Android Pay Certification test results. Chapter 2 Modified the descriptions of several elements associated with the use of Network Transaction Id (processingType, networkTransactionId, originalnetworkTransactionId, and originalTransactionAmount). Chapter 4 Added info about Response Reason Code 825. Appendix A Added info about allowing 60 second gap between a transaction and submitting a Void. Chapters 1, 3, & 4 Added processingType enums for Card on File transactions. Chapter 4 1.31 1.32 Document Structure This manual contains the following sections: Chapter 1, "Introduction" This chapter provides an introduction to transaction processing using the cnpAPI. Chapter 2, "Testing Your cnpAPI Transactions" This chapter provides information concerning the testing and certification process, which you must complete prior to submitting transactions to the Vantiv production environment. Chapter 3, "cnpAPI Transaction Examples" This chapter provides information concerning the cnpAPI structure for transaction submission, as well as examples. Chapter 4, "cnpAPI Elements" This chapter provides definitions and other information concerning each cnpAPI element. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xxvii cnpAPI Reference Guide About This Guide Document Structure Appendix A, "Payment Transaction Response Codes" This appendix lists all of the possible response codes and messages. Appendix B, "Credit Card Number Formats" This appendix provides information about credit card number formats and Mod-10 validation. Appendix C, "Test Card Numbers" This appendix provides credit card number that can be used for testing. Appendix D, "PayFac™ Dynamic Payout" This appendix provides information about PayFac Dynamic Payout transactions. xxviii Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Document Structure About This Guide Documentation Set For additional information concerning the Vantiv application, see any of the following guides in the documentation set: • iQ Reporting and Analytics User Guide • Vantiv Chargeback API Reference Guide • Vantiv Chargeback Process Guide • Vantiv eCommerce Partner Integration Overview Guide • Vantiv PayPal™ Integration Guide • Vantiv PayFac™ API Reference Guide • Vantiv PayFac™ Portal User Guide • Vantiv PayFac™ Integration Overview Guide • Vantiv eProtect™ Integration Guide • Vantiv Enterprise eProtect™ Integration Guide • Vantiv cnpAPI Differences Guide • Vantiv Secure Scheduled Reports Reference Guide Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xxix cnpAPI Reference Guide About This Guide Typographical Conventions Typographical Conventions Table 2 describes the conventions used in this guide. TABLE 2 Typographical Conventions Convention . . . Meaning Vertical ellipsis points in an example mean that information not directly related to the example has been omitted. ... Horizontal ellipsis points in statements or commands mean that parts of the statement or command not directly related to the example have been omitted. <> Angle brackets are used in the following situations: • • xxx user-supplied values (variables) XML elements [] Brackets enclose optional clauses from which you can choose one or more option. bold text Bold text indicates emphasis. Italicized text Italic type in text indicates the name of a referenced external document. blue text Blue text indicates either a hypertext link or an element name (in xml examples). monospaced text Used in code examples and elsewhere to designate field/element names. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contact Information About This Guide Contact Information This section provides contact information for organizations within Vantiv. Implementation - For technical assistance to resolve issues encountered during the on-boarding process, including cnpAPI certification testing. Implementation Contact Information E-mail implementation@vantiv.com Hours Available Monday – Friday, 8:30 A.M.– 5:30 P.M. EST Chargebacks - For business-related issues and questions regarding financial transactions and documentation associated with chargeback cases, contact the Chargebacks Department. Chargebacks Department Contact Information Telephone 1-844-843-6111 (option 4) E-mail chargebacks@vantiv.com Hours Available Monday – Friday, 7:30 A.M.– 5:00 P.M. EST Technical Support - For technical issues such as file transmission errors, email Technical Support. A Technical Support Representative will contact you within 15 minutes to resolve the problem. Technical Support Contact Information E-mail eCommerceSupport@vantiv.com Hours Available 24/7 (seven days a week, 24 hours a day) Relationship Management/Customer Service - For non-technical issues, including questions concerning iQ Reporting and Analytics, help with passwords, modifying merchant details, and changes to user account permissions, contact the Relationship Management/Customer Service Department. If you are a Payment Facilitator (PayFac), refer to the second table. Relationship Management/Customer Service Contact Information - Merchants Telephone 1-844-843-6111 (Option 3) E-mail ecc@vantiv.com Hours Available Monday – Friday, 8:00 A.M.– 6:00 P.M. EST Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. xxxi cnpAPI Reference Guide About This Guide Contact Information Relationship Management/Customer Service Contact Information - Payment Facilitators Telephone 1-844-843-6111 (Option 5) E-mail PayFacEComm@vantiv.com Hours Available Monday – Friday, 8:00 A.M.– 5:00 P.M. EST Technical Publications - For questions or comments about this document, please address your feedback to the Technical Publications Department. All comments are welcome. Technical Publications Contact Information E-mail xxxii TechPubs@vantiv.com Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 1 INTRODUCTION The cnpAPI data format supports two types of transaction submission methods: Online and Batch. With the Online method, you submit each transaction independently and receive a response in real-time. Typically, merchants use the Online method for Authorization transactions, as well as transactions available only via Online (for example, Void). The Batch method enables you to submit multiple transactions simultaneously in a single Session file. Vantiv recommends the Batch method for all transaction submissions except Authorizations and the transaction available only via Online. This chapter provides an overview of the cnpAPI data format, including some basic XML coding requirements. Also discussed are the advantages of using batch processing, duplicate transaction detection, report groups, Value Added Services, and supported transaction types. The topics discussed in this chapter are: • The cnpAPI Data Format • Fraud Toolkit • Batch Transaction Processing • Tokenization Feature • Payment Integration Platform (cnpAPI SDKs) • eCheck Processing • Duplicate Transaction Detection • SEPA Direct Debit • Coding for Report Groups • iDEAL, SOFORT, and Giropay • Recovery • eCommerce Solution for Apple Pay™ • Recurring Engine • eCommerce Solution for Android Pay™ • Issuer Insights • Supported Transaction Types Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 1 cnpAPI Reference Guide Introduction 1.1 The cnpAPI Data Format The cnpAPI Data Format Although Vantiv supports transaction processing via many data formats, there are several advantages to using the cnpAPI format. Some of the advantages are as follows: • Easier Implementation, Operations, and Debugging - Compared to fixed length or binary formats, the XML format is considerably easier for operations staff to read and edit, using virtually any text editor. This allows Vantiv’s Implementation, First Line Support, and Customer Experience Managers to quickly communicate any issues and work with your own operations staff to make necessary corrections without worrying about line lengths, padding or encoding. • Fewer Downgrades - Since the cnpAPI format allows you to explicitly tie deposits to their associated authorizations via the element, your transactions qualify for the best interchange rates at a higher frequency than with formats that do not support this transaction cross-referencing. • Simpler Capture (Deposit) and Refund Transactions - Because the cnpAPI format associates related transactions using the element, our format does not require you to resubmit all of the authorization information on a deposit nor all of the deposit information on a refund. When you submit the unique transaction id, Vantiv automatically pulls the information from the original transaction. Most other formats require you to resubmit the related data with each transaction. • Superior Reporting - The cnpAPI format allows you to separate your transactions into different categories by specifying a Report Group on each transaction. When accessing your data on the iQ reporting and Analytics Interface, this feature allows you to filter your financial reports by Report Groups, providing more granular detail based on a reporting hierarchy the Report Groups create. Most other formats restrict reporting categories to a batch or specific merchant id. • Improved Chargeback Management - Unlike most other formats where transactional relationships can be a “best guess” proposition, the cnpAPI format explicitly ties related transactions, allowing you and Vantiv to see authorization-to-deposit and deposit-to-refund relationships with precision. This knowledge is indispensable when fighting chargebacks. • New Features - New features developed for the Vantiv eCommerce platform are first exposed via the XML API. While the SDKs and DevHub add new capabilities shortly after development, direct coding to the XML API gains access to these feature and capabilities earlier. 1.1.1 Communications Protocols There are two communication protocols supported for the submission of Batch transactions to Vantiv eCommerce platform for processing and one for Online submissions as shown in Table 1-1. For Batch submissions Vantiv recommends that you use one of the two FTP methods. Use the HTTPS Post method for Online transactions. 2 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide The cnpAPI Data Format Introduction NOTE: TABLE 1-1 Although the Vantiv eComm platform currently supports both TLS 1.1 and TLS 1.2, Vantiv strongly recommends the use of TLS 1.2 to ensure the best encryption security. Communication Protocol Support Matrix Protocol Encryption Batch Online HTTPS Post TLS 1.2 N/A Required TCP/IP Socket TLS 1.2 N/A N/A FTP PGP or GPG (open source) Recommended N/A sFTP SSH Key Recommended N/A If you use the standard FTP method, you must use either the Pretty Good Privacy (PGP) or the open source GNU Privacy Guard (GPG) encryption for your submissions. Both of these encryption methods use key cryptography and support message authentication and integrity checking. The alternate method, Secure FTP (sFTP), uses Secure Shell (SSH) to secure the transmission. The Vantiv eComm platform supports the following ciphers for the TLS 1.2 encryption protocol: TABLE 1-2 Supported TLS Ciphers Server Priority Ciphe r Id Cipher Name TLS 1.2 Support TLS 1.1 Support 1 c030 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 Yes No 2 c02f TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 Yes No 3 c028 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 Yes No 4 c014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA Yes Yes 5 c027 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 Yes No 6 c013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA Yes Yes 7 009d TLS_RSA_WITH_AES_256_GCM_SHA384 Yes No 8 009c TLS_RSA_WITH_AES_128_GCM_SHA256 Yes No 9 003d TLS_RSA_WITH_AES_256_CBC_SHA256 Yes No 10 003c TLS_RSA_WITH_AES_128_CBC_SHA256 Yes No 11 0035 TLS_RSA_WITH_AES_256_CBC_SHA Yes Yes 12 002f TLS_RSA_WITH_AES_128_CBC_SHA Yes No Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 3 cnpAPI Reference Guide Introduction 1.1.2 The cnpAPI Data Format General XML Coding Requirements As part of the on-boarding process, you receive XML schema files from your Implementation Consultant. Using those files and this document as a guide, you create the required XML documents for submission of your transactions. You should validate all XML you create using the supplied schema. Also, working with your Implementation Consultant, you are required to perform various tests of your XML (see Chapter 2, "Testing Your cnpAPI Transactions") prior to submitting transactions to the production environment. In addition to the process outlined above, there are a few XML basics of which you should be aware. • Encode all data using the UTF-8 format. • Although it is not required, Vantiv recommends that when formatting your XML, you keep each element on its own line. This will aid in debugging situations where an error message specifies an issue in a particular line of XML code (for example, line 20). • Be aware of special characters that require specific handling (see Table 1-3). For example, the less than (<) and greater than (>) symbols define element tags in the XML code. Using the entity names < and > instead of < and > prevents a browser from interpreting these characters as element brackets. Be sure to review data provided by customers for special character handling. For example, an address of "4th & Main," must be rewritten as "4th & Main" (including quotes) before being submitted via XML. Failure to quote this type of input causes rejection of XML submissions due to syntax errors. TABLE 1-3 Character 1.1.3 Coding for Special Characters Description Entity Reference (case sensitive) < less than < > greater than > “ quotation " ‘ apostrophe ' & ampersand & Other XML Resources There are several Internet sites that provide both reference and educational information that may help you when implementing your XML. A few of these sites are: 4 • http://www.w3schools.com/xml/xml_syntax.asp • http://www.w3.org/ • http://www.utf-8.com/ Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Batch Transaction Processing 1.2 Introduction Batch Transaction Processing Batch processing involves a group of transactions submitted in a single file. In the case of a cnpAPI Batch the parent or root element is the element. A single , referred to as a Session, can contain many batches and each batch can contain multiple transactions. We recommend that you use Batch processing for all transaction types except Authorizations and Voids (Online only). Some of the advantages of using Batch processing are: • Better Performance - We optimize batch processing by processing multiple transactions in the batch simultaneously. This allows you to process thousands of transactions quickly without writing complicated logic or managing complicated processes. • Easier Reconciliation - When processing a batch, all transactions within that batch post on the same day. In the case of Online transactions, you could submit two transactions at the same time and one could post today and the other tomorrow. This can cause confusion in your accounting process. • Easier Error Recovery - A batch processes as a single unit, thus if you experience any system or communication issue while processing a batch, you can easily determine if the file was processed. With Online transactions, determining which individual transactions were not processed can be more difficult. 1.2.1 Recommended Session File Size As stated above, a Session file is a group of batches. A batch is a set of transactions for a single merchant. Normally, you send in a single file which has one batch for each merchant. This works well when the overall number of transactions is small. The number of transactions you should submit in any individual Session or Batch depend on a number of factors, including whether or not you are an individual merchant or a presenter submitting transactions for multiple merchants. In general, you should keep the following recommendations and rules in mind when determining the number of transactions you submit in an Session/Batch file: • A Batch should not exceed 20,000 transactions. If the number of transaction for a single merchant exceeds 20,000, you should create multiple batches for the same merchant, each batch containing not more than 20,000 transactions. • A Batch should not contain only one transaction, unless the merchant has only one transaction for the day. • A Session file must never contain more than 9,999 Batches. • A Session file must never contain more than 1,000,000 transactions across all Batches. • Always allow sufficient time between your submission time and your cut-off time for the processing of the Session. Larger files take longer to process. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 5 cnpAPI Reference Guide Introduction 1.3 Payment Integration Platform (cnpAPI SDKs) Payment Integration Platform (cnpAPI SDKs) In order to facilitate integration to the platform, Vantiv provides several language specific SDKs (Software Development Kits). The developers page on our website (http://www.vantiv.com/developers) provides links to SDK libraries for several popular languages, including: • PHP • Ruby • Java • .NET • Python Extensions for: • Magento • Opencart In addition to the SDKs and extensions, Vantiv provides examples of each supported transaction type, as well as demonstration applications. Once you install the library appropriate to your language, the Vantiv Sandbox, which functions as an emulator of our production environment, is available to validate your transaction format. 6 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Duplicate Transaction Detection 1.4 Introduction Duplicate Transaction Detection In order to help you avoid transaction errors, Vantiv performs duplicate transaction checking for both Online and Batch transaction submissions. While we use a robust duplicate checking methodology, we cannot guarantee our system will catch all duplicates and bear no responsibility for correcting the impact of erroneously submitted transactions. This section discusses the different checking methodologies used depending upon the type of submission. NOTE: For tokenized transactions, the token is used in place of the card numbers by the Duplicate Transaction Detection process. For PayPal transactions a combination of the PayPal Id + the (consumer’s) email is used by the Duplicate Transaction Detection process. For transactions submitted using other formats (e.g., PTI, Nabanco, etc.), the logic used to detect duplicates for these supported, but foreign APIs, is less robust and may miss duplicates in certain scenarios. Vantiv recommends, for better dupe checking, convert to the cnpAPI format, as soon as possible. 1.4.1 Batch Duplicate Checking When processing a Batch, the system acts to detect duplicate transactions for the following transaction types: Authorization, Auth Reversal, Capture, Force Capture, Capture Given Auth, Credit, Sales, eCheck Credit, and eCheck Sales. For each of these transaction types, the application compares the transaction type, transaction amount, the element from the request, credit card number, and credit card expiration date against transactions in other Batch processed within the previous five days. If the characteristics of the new transaction match a previously processed transaction, the system marks it as a duplicate. The system only performs duplicate detection against valid transactions from the previous five days. For example, if an Authorization request matches a declined Authorization from the previous day, the system would not count it as a duplicate, because the declined Authorization was not a valid Authorization. Also, a Batch must be processed completely to be included in the previous five days of data. For example, if multiple submitted Batches are processing simultaneously, the system will not compare the transactions in one batch with the transactions in the other, because neither has completed processing. For this same reason the system cannot detect duplicate transactions within the same Batch. If the system detects ten consecutive duplicate transactions or if the number of duplicate transactions is greater than or equal to 25% of the total transactions in the batch, the system flags the Batch as a duplicate. When either threshold is met, Vantiv will not process the Batch. If Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 7 cnpAPI Reference Guide Introduction Duplicate Transaction Detection neither threshold is met, Vantiv continues processing the Batch, including any transactions that may have been duplicates. 1.4.2 Online Duplicate Checking When processing an Online transaction, the system acts to detect duplicate transactions for the following transaction types: Auth Reversal, Capture, Force Capture, Capture Given Auth, Credit, Sales, eCheck Credit, eCheck Sales, eCheckVoid, and Void. For most transactions, the system compares the transaction type, the id attribute from the request, and the credit card number against other Online transactions processed within the previous two days. For transactions that reference other transactions (for example, a deposit referencing an authorization or a refund referencing a deposit), the system compares the transaction type, id attribute, and the card number from the referenced transaction (i.e. the transaction identified by the element) against other Online transactions processed within the previous two days. IMPORTANT: For Online transactions, if you do not include the id attribute in the request, or if you set the id attribute to null (id=""), duplicate Checking is not performed. The system only performs duplicate detection against valid transactions. For example, if a Capture request matches a declined Capture from the previous day, the system would not count it as a duplicate, because the declined Capture was not a valid transaction. NOTE: While it is uncommon, under certain circumstances network latency may cause a duplicate Sale transaction to go undetected as a duplicate. This can occur if you submit a second, duplicate Sale transaction while the response from the network for the Authorization portion of the first transaction is sufficiently delayed such that the first Sale has not been recorded as a valid transaction in the system. If you elect to submit Online Sale transactions, Vantiv recommends a timeout setting of not less than 60 seconds to reduce the chances of undetected duplicate Sale transactions. If the system determines a transaction to be a duplicate, it returns the original response message with the duplicate attribute set to true (see example below). This attribute indicates that the response was returned on a previous transaction. 8 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Duplicate Transaction Detection NOTE: Introduction If you do not receive a response for a submitted transaction, Vantiv recommends you re-send the transaction. If Vantiv received and processed the original transaction, you will receive a duplicate response. If Vantiv did not receive the original transaction, the new submission will be processed. Example: captureResponse for a duplicate Capture Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 9 cnpAPI Reference Guide Introduction 1.5 Coding for Report Groups Coding for Report Groups You use Report Groups (reportGroup attribute) to separate your transactions into different categories, so you can view the financial reports by your specific report group names. If you are unsure what groupings to use, your Customer Experience Manager can help you determine the best practice for your business. CAUTION: Creation of an excessive number of Report Groups (in excess of 250) will impact the amount of time require to compile various reports in the iQ. Report Groups are intended to allow you to segregate transactions by logically grouping them into the different segments of your business. Report Groups are not intended to track sales or marketing programs that exist for limited times. For this type of tracking, Vantiv provides other transaction tagging methods detailed in Additional/Alternate Methods of Tagging Transactions on page 11. Example: Report Groups The merchant, Demo, wants to separate their domestic and international sales information. To do this the company submits all domestic transactions using reportGroup = "Domestic Business", and all international transactions using reportGroup = "International Business". When they access the Authorization Report in the iQ using the By Reporting Group tab, the transactions would be separated as shown in Figure 1-1. NOTE: FIGURE 1-1 The reportGroup attribute is case and space sensitive. A reportGroup = “Picture Frame” is a different report group than a reportGroup = “pictureframe”. Report Group Example - 2 Groups The plus sign next to the Domestic Business report group signifies that there are child groups present. When fully expanded (see Figure 1-2), the iQ shows a report group hierarchy with information for the Domestic Business group further separated into Service A and Service B groups and Service A containing two additional child groups. If you find it necessary to establish this type of nested hierarchy, your Implementation Consultant will assist you. 10 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Coding for Report Groups FIGURE 1-2 1.5.1 Introduction Report Group Example - Expanded to Show Child Groups Additional/Alternate Methods of Tagging Transactions If you are using schema version 7.x or above you can use the merchantData element and its children to tag transactions (Authorization, Sale, Credit, Force Capture, Capture Given Auth, eCheck Sale, and eCheck Credit) with additional information. The three children of merchantData: campaign, affiliate, and merchantGroupingId, allow you to designate transactions as members of different groups enabling a deeper analysis of sales patterns. For example, if the merchant from the previous example were trying a new sales initiative for Product 2 during the month of September. They plan to run ads in Boston and New York to test the new offering. To allow a deeper analysis of sales resulting from the new campaign, they can add the campaign element with a value of "September Ads" to the transactions originating in both test market. They can also include the merchantgroupingId with values that reflect the city where the order originates. By exporting either the Session report or the NSS by Transaction report from the iQ, the company can sort their sales data based upon these fields and gain a better understanding of the effectiveness of the sales campaign. NOTE: The transaction tagging elements described above appear in the exported Session and NSS by Transaction reports. They are also visible within the iQ in the new Transaction Detail reports. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 11 cnpAPI Reference Guide Introduction 1.6 Recovery Recovery Recovery is a bundle of services that include both Account Updater and Recycling Engine. By combining these two managed services into a single bundle, Vantiv simultaneously increases your approval rates, optimizes customer lifetime value, and improves your cash flow, while reducing the cost of implementing the individual features separately in terms of IT resources. For additional information about the capabilities included in this bundle, please refer to Recycling Engine on page 12, and (AAU) Account Updater Service on page 14. 1.6.1 Authorization/Sale Recycling Authorization recycling is the process of retrying declined authorization attempts. Every merchant, especially those with a business model that uses recurring or installment payments, should devise a strategy for dealing with declined authorizations. As part of optimizing their operations, merchants must devise plans for both the timing and number of recycling attempts before contacting the cardholder or risking interruption of service. If a merchant does not recycle enough, they risk losing customers and revenue; whereas, if the merchant recycles too often, they risk increasing their total cost of payments. Implementing an optimal recycling strategy aids customer retention and therefore yields higher revenues, while lowering the costs of payment acceptance and improving cash flow. 1.6.1.1 Recycling Engine The Recycling Engine is a managed service that automatically retries declined authorization attempts on your behalf. It requires little or no IT investment on your part. Also, implementing the Vantiv service removes the need to plan your own recycling strategy. Recycling Engine has the following benefits: • Increases approval rates • Shortens time to approval, improving cash flow • Reduces the number of authorization retries • Lowers the risk of account/service cancellation In order to determine the most effective recycle timing, Vantiv performs statistical analysis of past recycling attempts across our entire merchant portfolio. This analysis examines many factors, including method of payment, response codes, and transaction amount among others, to determine the optimum intervals between attempts to obtain a successful authorization. When you receive a declined Authorization, the system automatically queues the transaction for a retry at a designated time. Recycling of the Auth continues until it is either successful or the algorithm determines that it is no longer advantageous to retry. 12 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recovery Introduction NOTE: For Visa transactions, the Recycling Engine will retry declined Authorizations a maximum of 4 times within 16 days, per Visa regulations. For MasterCard and Discover transactions, we retry declined Authorizations a maximum of 8 times within 28 days. Vantiv provides the results of the recycling efforts to you in a Batch posted daily to your Vantiv sFTP account. This file contains transactions that either approved or exhausted the recycling pattern on the previous day. If you submit an Authorization for a transaction in the recycling queue, Vantiv returns the response from the last automatic recycling attempt. To halt recycling of a particular transaction, submit either an Authorization reversal transaction, if the original transaction was an Auth, or a Void transaction, if the original transaction was a Sale. Declined Transactions Not Recycled The system does not recycle transactions declined with one of the Response Codes listed in Table 1-4 below. The 1100030204 65347567 000 2016-08-11T14:48:48 2016-08-11 Approved element in the response files indicates if the transaction is being handled by the Recycling Engine. TABLE 1-4 Response Codes Not Recycled Response Code Message 213 Pickup Card - Lost Card 214 Pickup Card - Stolen Card 303 Pick up Card1 304 Lost/Stolen Card1 305 Expired Card1 308 Restricted Card - Chargeback 309 Restricted Card - Prepaid Card Filtering Service 312 Restricted Card - International Card Filtering Service 315 Restricted Card - Auth Fraud Velocity Filtering Service 318 Restricted Card - Auth Fraud Advice Filtering Service 323 No such Issuer1 328 Cardholder requested that recurring or installment payment be stopped 358 Restricted by Vantiv due to security code mismatch 550 Restricted Device or IP - ThreatMetrix Fraud Score Below Threshold 1. Not recycled for MasterCard, unless updated account information is available. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 13 cnpAPI Reference Guide Introduction Recovery Transaction Signature The Recycling Engine analyzes each Authorization or Sale request message to determine if it is a new request. The result of the analysis determines if the transaction should be added to the recycling pool upon decline or if the system should intercept the transaction to prevent a duplicate transaction entering the recycling pool. To perform the analysis, the system checks the transaction signature. Depending upon your configuration, the transaction signature can be: • Value of the element • Value of the element • Values of the , , and elements NOTE: If you submit a transaction with the identical signature, but containing new information (for example, a new card number), the system updates the transaction in the recycling pool with the new info and continues to recycle. Additional Configuration Options The Recycling Engine allows you the additional flexibility of excluding certain transactions from automatic recycling. You can exclude transactions manually by including the element set to None. There are also global controls that allow you to exclude transactions based upon either submission by a particular presenter, or based upon the transaction type (authorization or sale). Please consult your Customer Experience Manager about the global options, since they must be configured in your Vantiv Merchant Profile. 1.6.2 Account Updater Service Credit and debit card numbers change for a variety of reasons including card expirations, card product type upgrades, portfolio conversions, and compromised account numbers among others. For merchants who offer services that are billed on a recurring or installment basis (for example, web hosting, gym memberships, specialized social networking, career services, monthly donation plans, etc.) out-of-date payment information can result in lost revenue, involuntary churn and decreased customer satisfaction. Prior to the development of the Account Updater service, the standard method for merchants to obtain updated account information was to submit a Batch containing existing card information, requesting that Vantiv check for updates. Typically, merchants request updates for customer accounts scheduled to be billed in the next billing cycle. This legacy method is a relatively slow process, requiring several days for Vantiv to accumulate responses from the card networks/issuers and then to make the response file available to the merchant. Merchants must then update their billing systems with the new information, requiring IT processing cost. Failure to update their files can result in multiple requests (and charges) for the update information, as well as delays in or lost revenue, higher Authorization expenses, and possibly chargebacks when old account information is used. 14 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recovery Introduction The Account Updater service shifts the workload of obtaining and maintaining updated account information to Vantiv. Utilizing configurable scheduling algorithms, we initiate account update requests on your behalf and then stores the updated card information for use in future transactions. You simply submit billing transactions normally and, if necessary, Vantiv updates the transaction with the stored card information before submitting it to the networks for authorization. This fully managed service requires no code update on your systems. FIGURE 1-3 Account Updater Overview Merchant Card Networks Scheduled AU Requests Response with updates from Network Process and Store Matches Vantiv Submits Auth w/Repaired Card Info (if info on file) Submit Transaction Vantiv Adds Account Info to Next Scheduled AU Request Re-Submit Transaction Auth Auth Decline if updated info not yet on file Vantiv Repairs Card Info and Submits Auth (+ 3 days) Auth Approval 1.6.2.1 Auth Auth Approval Match Back If you decide you wish to have the updated card information returned to you, Vantiv offers the Match Back option. In this case, you can opt to receive updated information either in a Batch deposited to the merchant sFTP account, or in the XML transaction response messages. Once you update your systems, you can resubmit the failed transaction with the new card information. If, Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 15 cnpAPI Reference Guide Introduction Recovery after receiving an update, you submit a transaction with the old information, systems detect that you are using the old data and update the transaction for you prior to submitting it to the networks for authorization. Please consult your Customer Experience Manager for additional information and configuration options. FIGURE 1-4 Match Back Overview Merchant Card Networks Scheduled AU Requests Response with updates from Network Process and Store Matches Vantiv Submits Auth w/Repaired Card Info (if info on file) Submit Transaction Vantiv Adds Account Info to Next Scheduled AU Request Re-Submit Transaction Vantiv Repairs Card Info and Submits Auth (+ 3 days) Auth Approval w/New Card Info (Next Payment) Submit Transaction w/New Info 16 Auth Auth Decline if updated info not yet on file Auth Auth Approval w/New Card Info Auth Submit for Auth Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recovery Introduction 1.6.2.2 Merchant Requirements In order to use the Account Updater service, you must first apply for membership to the following: • MasterCard Automatic Billing Updater • Visa Account Updater • Discover Account Updater (not required by Discover for Vantiv acquired merchants) Your Account Updater Welcome Kit includes the required application forms. If you have any questions about these forms, contact your Customer Experience Manager, who can walk you through the application process. Approval from Visa and MasterCard typically takes between 10-15 business days. Normally, merchants are approved without issue; however, you can be declined for a variety of reasons. For example, merchants on a risk mitigation program typically are not accepted. NOTE: 1.6.2.3 Visa does not allow merchants with SIC numbers 5962, 5966, 5967, or 7995 to participate in their Account Updater service. MasterCard has no restrictions against any specific MCC numbers Account Updater Features The Account Updater service can include the following features depending upon the implementation option you select: • Vantiv initiates requests for updated account information to card networks based upon your billing cycle. • Vantiv initiates requests for updated account information following certain failed Authorization attempts. • All updated card information stored (per merchant) in our secure database. • Automatic repair/replacement of outdated information with updated information in new Authorization/Sale transaction submissions. • Return of the updated account information in the cnpAPI response message when auto-repair occurs. • Maintenance of card information history, so that the system can repair a card even if multiple updates have occurred during the card's billing lifecycle. • All linked (to an Authorization) transactions will use the updated account information from the repaired parent transaction, including Captures, Refunds, and Reversals. If a re-Auth is needed on an attempted capture due to an expired authorization, the system uses the updated account information. • Integration with Vault for merchants utilizing Vantiv’s tokenization solution. • Return of Extended Response Codes in the cnpAPI response messages. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 17 cnpAPI Reference Guide Introduction 1.7 Recurring Engine Recurring Engine The Recurring Engine is a managed service that relieves the burden of developing an in-house billing solution for merchant engaged in installment or recurring transactions. This powerful, but flexible service allows you to create virtually any payment Plan required by your business model, whether it is part of a predetermined campaign or a marketing test, and then apply the Plan to customers as part of the standard Authorization or Sale transaction. The Recurring Engine provides the following benefits: •Reduced Infrastructure Costs - since you do not need to program your own solution, you save the up-front development cost, as well as ongoing maintenance expenses. •Reduced Labor - once you create a Subscription in the Recurring Engine via a standard Authorization or Sale transaction, no further action is required for the life of the Subscription. •Integration with other Vantiv Value Added Services - if you include the Recovery Services (Account Updater and Recycling Engine) as part of your implementation, you eliminate any concerns (and reduce expenses) associated with issues such as account number changes and recycling of declined payments. •Flexible Plans - You can define the billing interval (weekly, monthly, quarterly, etc.), number of payments (including open ended schedules), amount of payments, as well as trial periods within a Plan. To add flexibility you can override several of these settings and set a specific start date at the individual Subscription level. •Flexible Creation of Discounts - if you wish to offer a discount to selected customers, simply include the information at the time of the Subscription creation, or add it anytime afterward by updating the Subscription. •Flexible Creation of Add Ons - similar to a discount, you can apply changes for additional services at the time of the Subscription, or anytime afterward. •Integrated Reporting - in addition to the normal revenue reconciliation information available in the iQ Reporting and Analytics platform, there are a number of recurring specific reports that allow you to better analyze your revenue stream associated with recurring payment plans and strategies. 1.7.1 Payment Plans The first step in setting up recurring billing on the Vantiv eCommerce platform is to establish one or more payment Plans. To establish a payment Plan you use a Create Plan transaction type, which allows you to define the payment interval, the number of payments, and the amount. For example, you could easily define any number of Plans to fulfill your business needs. For example, suppose you are a SaaS company that sells your product under 1, 2, or 3 year deals, with either monthly or quarterly payment schedules and reduced rates for longer deals. You could easily set-up six Plans as shown in the table below. 18 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recurring Engine Introduction TABLE 1-5 Example Pans Payment Interval Plan Code Amount per Payment # of Payments Total Subscription 1_Year_Monthly Monthly $50.00 12 $600.00 1_Year_Quarterly Quarterly $150.00 4 $600.00 2_Year_Monthly Monthly $46.66 24 $1119.84 2_Year_Quarterly Quarterly $140.00 8 $1120.00 3_Year_Monthly Monthly $41.66 36 $1499.76 3_Year_Quarterly Quarterly $125.00 12 $1500.00 As part of the Plan, you can also specify trial period. You want to have longer trials for longer Plans, so for either 1-year Plan, there is a 1 week trial, for either 2-year Plan there is a 2 week trial, and for the 3-year Plans, a 1 month trial. Below is a cnpAPI example transaction to create the 3_Year_Monthly Plan. Example: 3-Year Monthly Plan 1.7.2 Subscriptions Subscriptions marry a customer order to a particular payment Plan and initiate the Recurring Engine to manage your future billing. You create a Subscription using either an Authorization or a Sale transaction. In the Auth/Sale you simply include a 3_Year_Monthly 3Year_Monthly 3 Year, monthly Payments, 1 month trial MONTHLY 4166 36 1 MONTH true element to initialize the Subscription using a named Plan and set the start date for the first recurring bill. If you do not include a start date, the Recurring Engine uses the current date for the first payment. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 19 cnpAPI Reference Guide Introduction Recurring Engine If the recurring bill had an associated set-up or one-time fee use a Sale transaction. The amount of the Sale transaction would represent that fee, whereas the amount of future recurring payments are defined in the Plan. If you use an Authorization to create the Subscription, the transaction would normally be a $0 Auth (or small amount followed by a reversal) and would include the billing information for Address Verification. As part of the Subscription creation, you can also override both the number of payments and the amount, as well as include Add Ons and Discounts (discussed in the next section). The overrides give you a granular control to modify a standard payments Plan for a particular consumer without creating additional Plans. For example, if you offered a 1-year Plan with monthly payments as shown in the previous section, you could allow a consumer to complete their payments in 10 months instead of a year. In this case you would override the number of payments defined in the Plan (12) with 10 payments, while increasing the amount of each payment from $50 to $60. Example: Subscription with Overrides 20 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recurring Engine 1.7.2.1 Introduction Add Ons and Discounts Occasionally, you might wish to modify a Subscription with either a Discount or an Add On without creating a new Plan that has limited use. A Discount reduces the recurring amount for one or more payments, while an Add On increases the payments in return for an added service or item. You can apply either of these payment modifications at the time you initialize the Subscription or anytime afterward by updating the Subscription. In both cases you define the start date, end date, and amount of the Discount/Add On. For example, suppose as part of your standard offering, your customers received 2GB of cloud-based storage. You also offer additional storage in 2GB blocks for $10 each. One of your customers wants an additional 4GB of storage for the 8 months remaining on his contract and you are discounting the first month at 50%, or $10. The example below show the updateSubscription transaction with the Add On and Discount. Example: Update Subscription with Discount and Add On 65347567 0 ecommerce . . . . . . 1_Year_Monthly 10 2017-06-21 6000 1.7.3 Recurring Reports In addition to recurring transactions appearing in the normal Vantiv reports (i.e., Payment Detail, Reconciliation report, etc.), there is an additional report associated specifically with the Recurring Engine. Available via sFTP, this report is in Batch format and contains cnpAPI saleResponse messages for all recurring transactions run that day, including all approvals and declines (see the example, Batch Sales Response with Recurring Info on page 308). Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 21 cnpAPI Reference Guide Introduction 1.7.4 Recurring Engine Transaction Types and Uses The table below provides information about the various Recurring Engine transaction types and their uses. TABLE 1-6 Recurring Engine Transaction Types Use Case/Intent Create Plan Parent Element createPlan Used to create new Plans. updatePlan Used to toggle a Plan between an active and inactive state. You can not associate an inactive Plan with a Subscription. Toggling a Plan to an inactive state does not affect existing Subscriptions associated with the Plan. 1234 4GBExtraDeal Half-Off 1st Payment 4GB Extra 1000 2016-09-15 2017-09-14 4GB_Extra Four_GB_Extra 2000 2016-09-15 2017-04-15 or Used to initiate a Subscription with an associated Plan. The Subscription can include amount and numberOfPayment overrides to the Plan. Also, the Subscription can include createAddOn and createDiscount children. Update Plan Create Subscription updateSubscription Used to modify Subscription information including: changing the Plan, changing the billing name/address, and changing the method of payment. You can also use this transaction type to create/delete/update Add Ons and Discounts. cancelSubscription Used to cancel an existing Subscription. or Used to create an Add On charge associated with the Subscription. Update Subscription Cancel Subscription Description/Uses Create Add On Or Update Add On 22 Used to modify one or more of the parameters associated with the Add On. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recurring Engine TABLE 1-6 Introduction Recurring Engine Transaction Types Use Case/Intent Delete Add On Parent Element or Description/Uses Used to delete an Add On charge from the associated Subscription. Used to create a Discount charge associated with the Subscription. Create Discount Or Update Discount Delete Discount Used to modify one or more of the parameters associated with the Discount. Used to delete a Discount from the associated Subscription. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 23 cnpAPI Reference Guide Introduction 1.8 Issuer Insights Issuer Insights Issuer Insights provides you additional card/transaction, performance descriptive data, allowing you to understand the differences among Issuers and card products, and identify trends that may impact future transactions. Currently, Vantiv bundles four feature sets into Issuer Insights: the Issuer Insights Secure Scheduled Report, Real Time Indicators (i.e., Prepaid Indicator, Affluence Indicator, Issuer Country Indicator, Card Type Indicator), Network Response Data, and the Insights Analytics Dashboard. 1.8.1 Issuer Insights Secure Scheduled Report Every merchant wants to maximize their approval rate and with it their customer conversion rate and sales. Unfortunately, issuing banks do not all use the same criteria and/or algorithms when approving or declining transactions. Getting an approval on an authorization is not a one size fits all proposition. The weekly Issuer Insights report provides a range of data points that breakdown authorization approvals and declines by card type, BIN (i.e. Issuing Bank), and account ranges (indicating card product types). It also provides data about the four of the most often seen reasons for declines (i.e., Non-sufficient Funds, Do Not Honor, Invalid Account, and Lost/Stolen Card), as well as benchmark data for your MCC(s) across the Vantiv eComm portfolio, and Issuer participation in AU, as well as account update counts per account range across our portfolio. Using this data, you can create a wide range of useful analytics, such as approval/decline trending by BIN, account updates trending by account range, new card issuance/portfolio changes, or customer lifetime value by card type to name a few. For additional information about this report please refer to the Vantiv Scheduled Secure Reports Reference Guide. 1.8.2 Real Time Indicators The Real Time Indicators provide six data points in the Authorization/Sale transaction response message. This information includes the Prepaid Indicator, Affluence Indicator, Issuer Country Indicator, Card Type Indicator, Funding Source Indicator, and Virtual Account Number Indicator. Each of these pieces of information allows you to make a real time decision about how to proceed with the transaction. The sections that follow explain each indicator along with possible uses in your decision making process. 1.8.2.1 Prepaid Indicator Studies show that branded prepaid cards are growing in popularity with consumers. These cards are available in the form of non-reloadable Gift cards, Consumer Rebate/Incentive cards, and Teen cards among others. The Prepaid Indicator feature acts to determine if the submitted card is a prepaid card. If so, the system returns the type element with a value of Prepaid and the 24 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Issuer Insights Introduction availableBalance element stating the outstanding balance remaining on the card (if available). Knowing that the card is prepaid at the time of sale, as well as if it is reloadable and the available balance, is especially useful for merchants engaged in recurring payment, installment payment, or deferred billing scenarios. Merchants in these situations can use the information made available by this feature to make intelligent decisions concerning the profitable management of prepaid card usage by avoiding several factors that may contribute to lost revenue, while taking advantage of other opportunities that may add to revenue and enhance the customer experience. For example, one possible situation merchant can avoid is fraudulent deferred/installment payment purchases made with a prepaid card that does not have enough available balance to cover the subsequent payments. With the available balance known, merchants can determine if the card can meet the required payment structure. If the card’s balance does not meet the required threshold, the merchant can request another payment method, which may result in eliminating fraudsters, while retaining legitimate customers. If the card is non-reloadable, it is advisable to not accept the card at all for recurring payments regardless of the available balance. Another more common situation occurs when the consumer is unaware of the card balance. If the transaction is rejected due to inadequate balance, perhaps repeatedly, it could result in an unsatisfied customer and an abandoned purchase. Alternately, the card could have slightly more that the required balance, which the consumer would spend, if they had the knowledge. If the available balance is insufficient for the purchase, the merchant can obtain a second or alternate payment method. If the balance is higher than required for the purchase, the merchant may be able to encourage additional purchases. In addition to indicating if the submitted card is a prepaid card and the available balance, this feature includes information about whether the card is reloadable and the specific type of prepaid card (i.e., TEEN, GIFT, PAYROLL, etc.). You can use this information to further refine your sales and marketing strategies. 1.8.2.2 Affluence Indicator Visa, MasterCard, and Discover provide enhanced credit card products for consumers with high disposable incomes and high card spending. These cards encourage usage by offering the cardholders additional benefits usually including reward incentives, no pre-set spending limit, higher authorization approval rates, faster access to a customer service representatives, and dedicated chargeback resolution support. Vantiv analysis of payments data indicates that consumers using these cards types typically spend more per order than consumers using traditional credit and debit cards. The Affluence Indicator feature provides the ability for merchants to segment their consumers based on the affluence level as determined by the issuer. Within the cnpAPI Authorization response, consumers using these enhanced card products are classified either as Mass Affluent or Affluent. Based upon the specific card type, high income consumers are classified as Mass Affluent, while high income-high spending consumers are classified as Affluent. Having this information at the time of authorization, allows merchants the opportunity to adjust their sales approach to the needs and spending patterns of the consumer, potentially generating Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 25 cnpAPI Reference Guide Introduction Issuer Insights additional sales. Having this information on file for later analysis also may provide the opportunity for targeted marketing campaigns and future sales. 1.8.2.3 Issuer Country Indicator Knowing the country of the Issuing bank helps you in two respects. From a sales and marketing standpoint, this knowledge allows you to better analyze the purchasing patterns of your customers based upon their country of origin. Knowing these customer demographics can allow you to tailor marketing campaigns to take advantage of this geographic information. Likewise, you can use this information to analyze the successfulness of tailored campaigns. The second advantage to having this information readily available is that you can use it to help determine possible patterns of fraud. With this knowledge in hand, you can use the International Card Filtering feature to limit your exposure to international fraud originating in particular geographic locations. 1.8.2.4 Cardholder Type Indicator The Card Holder Type indicator is an additional data point Vantiv provides as part of Issuer Insights. This indicator returns an element specifying whether the submitted card is a commercial or consumer card, providing you with additional data useful when analyzing sales patterns and/or planning marketing campaigns, such as offering different products/services to a corporate customer as opposed to a regular consumer. 1.8.3 Extended Network Data In an effort to provide more data for use in analyzing your transactions and customers, Vantiv added a number of data elements originating directly from the ISO 8583 network response messages. If you use V11.0 or above of the Vantiv cnpXML, you can receive up to 17 data elements as part of the Enhanced Auth Response ( element). These elements provide more granular data, allowing you to gain a more nuanced understanding of the approval/decline behavior of particular Issuers. Table 1-7 provides information about the fields returned. NOTE: 26 To receive the Extended Network Data elements you must code to Version V11.0 or above. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Issuer Insights Introduction TABLE 1-7 Possible Extended Network Data ISO 8583 Fields Data Element Field Name Type 4 Transaction Amount n 12 5 Settlement Amount n 12 Data Element 4 * Data Element 9 6 Cardholder Billing Amount n 12 Data Element 4 * Data Element 10 9 Settlement Conversion Rate n8 Two subfields indicating decimal position and value 10 Cardholder Billing Conversion Rate n8 Two subfields indicating decimal position and value 15 Settlement Date n4 MMDD format 38 Authorization Identification Response an 6 39 Response Code an 2 44 Additional Response Data an..25 48 Private Use Additional Data an...999 50 Settlement Currency Code n3 51 Cardholder Billing Currency Code n3 54 Additional Amounts an...120 63 Reserved Private an...999 104 Transaction Description an...100 116 Reserved for National Use an...999 123 Reserved for Private Use an...999 Notes Defines the currency of Data Element 5 Example: Extended Network Data . . . 1.8.4 Insights Analytics Dashboard The Insights Dashboard provides insight into the quality of customers your organization acquires, based on the number and percentage of authorizations by card type or other indicator, and contrasts that with the number of customers whose authorizations are successfully converted to deposits. There are four categories of indicators: Affluence, Prepaid, Corporate Customers, and Country of Issuing Bank. Using these values and the related charts, your organization can decide whether the customer mix you attract yields maximum revenue potential, or if a change in marketing is required. By using the adjustable date range and reporting groups, you can compare the quality of customers between different business units and affiliates, or monitor the response to marketing campaigns. Please refer to the Vantiv eCommerce Reporting and Analytics User Guide. 28 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Fraud Toolkit 1.9 Introduction Fraud Toolkit Just because a credit card network/company returns a valid authorization for a purchase does not always mean that completing the transaction is in your best interest. There are multiple reasons you may wish to decline a sale on a particular card at a particular time. In many cases there are indicators that the transaction could be or likely is fraudulent. Acting to stop these transactions at submission prevents loss, as well as reducing the number fraud related chargebacks in the future. Vantiv offers a robust fraud solution, the Fraud Toolkit, to assist you in reducing the number of possibly fraudulent transactions inflicted upon you by bad actors. The Fraud Toolkit has three tiers or levels of implementation, each providing more rigorous examination of transaction properties and data points, as well as valuable information and guidance. The table below provide an overview of the tool provided at each level. The items highlighted in blue require the inclusion of a small snippet of code on your checkout page. TABLE 1-8 Fraud Toolkit Implementation Levels Filter/Feature Essential Extended Premium AVS Filter X X X CVV No-Match Filter X X X International BIN Filter X X X Prepaid Non-Reloadable Filter X X X Prior Chargeback Filter X X X Prior Fraud Advice Filter X X X Card Velocity Filter (Approved or Attempted) X X X Email Velocity Filter X X X Phone Velocity Filter X X X IP Velocity Filter X X X Device Velocity Filter X X X IP Address, Geolocation, and Proxy Detection X X Merchant Customizable Rules Template X X ThreatMetrix Cybercrime Dashboard X X (Asynch) Transaction Review Queues X X Rule Management and Portal Training X X Standalone Transaction API Access X X Cybercrime Industry Report (Quarterly) X X Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 29 cnpAPI Reference Guide Introduction Fraud Toolkit TABLE 1-8 Fraud Toolkit Implementation Levels Filter/Feature Essential Access to Fraud Consultant 1.9.1 Extended Premium X Essential Tier The Essential tier includes a suite of eleven Fraud Filters that you can apply individually or in combination. Nine of the eleven filters, based on card/submitted data, potentially require no additional integration on your part, assuming you already submit the necessary information. The remaining two filters require you to add a a small snippet of code on your checkout page. NOTE: 1.9.1.1 Technically, you can make use of the IP Velocity filter without integrating the code snippet on your checkout page. Instead you can simply include the originating IP Address that you detect in your transaction by submitting it as a customAttribute. Please note that this method will likely be less effective than making use of the ThreatMetrix functionality, which includes IP piercing to determine the true IP of the consumer’s device. Prepaid Card Filtering Many merchants engaged in recurring payment, installment payment, or deferred billing experience some loss due to fraud schemes that make use of prepaid cards. Consider the case of a consumer using a prepaid card with a balance of $100 to make a purchase that involves an initial charge of $50 followed by three installments of $50 each. The authorization would be approved for the initial transaction, and the card might have adequate balance for an additional charge, but if the consumer was attempting to defraud the merchant or simply used the card for other purchases, the card may not have sufficient balance for any additional payments. While the Prepaid Indicator feature provides you with the information necessary to make a decision at the time of the sale, and to request a secondary or different payment method, instead you may wish to have Vantiv filter these transactions automatically when you send the Authorization transaction. If you elect to use the Prepaid Card Filtering Service, you can select one of two methods of implementation. Using the first filtering method, our system declines all Authorization and Sale transactions when the consumer uses a prepaid card. Upon a decline, the system returns a Response Reason Code of 309 - Restricted Card - Prepaid Card Filtering Service. This method also allows you to disable the filtering logic on a transactional basis by including theVISA Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 27 cnpAPI Reference Guide Introduction Issuer Insights000000000962 5 element set to a value of false, allowing you to accept any prepaid card for these transactions. The second method of implementing the Prepaid Card Filtering Service is per transaction. To enable the filter on a particular transaction, set the element to a value of true. This method is useful to a merchant who offers products with both one-time payments and installment 30 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Fraud Toolkit Introduction payments. For products involving a single payment, you may want to allow the use of prepaid cards, while for the product with multiple payments you may want to filter prepaid cards. NOTE: 1.9.1.2 Within either implementation method, you can elect to filter all prepaid cards, or only non-reloadable prepaid cards. Please speak to your Implementation Consultant for additional information about setting these global parameters. International BIN Filtering An examination of your historical fraud data may show a high percentage of fraudulent transactions originating with certain international cards. You can limit your exposure to this type of fraud by taking advantage of the International Card Filtering Service. This feature allows you to filter MasterCard and Visa cards originating in either all foreign countries or selected foreign countries based upon the country of the card issuer. If you elect to use this feature, when you submit an Authorization/Sale transaction, the system determines the country of origin of the card. If the card originates outside the United States and you have elected to filter all international cards, the system declines the transaction. Likewise, if you have elected to filter a specific country or countries and the card originates from a designated country, the system declines the transaction. Upon a decline, the system returns a Response Reason Code of 312 - Restricted Card - International Card Filtering Service. You can override your settings on a transactional basis by including the element set to false when you submit the Authorization/Sale transaction. In this case, the system ignores the filtering service and processes the transaction normally. 1.9.1.3 Prior Chargeback Filtering If you elect to use the Chargeback Filter Service, there are two configuration options. You can elect to filter all transactions using a card for which you received a chargeback, or you can elect to filter only the subset of transactions for which you received a fraud related chargeback (determine by the associated chargeback reason code). In both cases, the system checks your historical data to see if you received an applicable chargeback from the same account within the last 90 days. Upon a decline, the system returns a Response Reason Code of 308 - Restricted Card - Chargeback. 1.9.1.4 Security Code No-Match Filter The Card brands added the 3- or 4-digit security code to act as a verification that the person ordering your product in a card-not-present environment has physical possession of the card. While this validation can be a useful anti-fraud tool, typically, many issuing banks do not decline the transaction based upon a failure to match the security code. Declining the transaction is left to the discretion of the merchant. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 31 cnpAPI Reference Guide Introduction Fraud Toolkit NOTE: Since American Express declines the transaction when the security code does not match, the Security Code No-Match filter does not apply to American Express transactions. Transactions declined by American Express for a failure to match the security code use the Response Reason Code of 352 - Decline CVV2/CID Fail. Similarly, if Visa, MasterCard, or Discover decline a transaction based upon the security code results, Vantiv does not apply the filter and the transaction response contains the 352 Reason Code. If you elect to use the Security Code No-Match Filter Service, the system takes action only if the issuer approves the submitted authorization/sale transaction, but includes a no-match code for the CVV2/CVC2/CID card validation check. In this case, the Vantiv declines the transaction with a Response Reason Code of 358 - Restricted by Vantiv due to security code mismatch. The system also issues an Auth Reversal transaction on your behalf to remove the funds hold on the account. 1.9.1.5 Card Velocity Filtering Often, when a person attempts to use a stolen credit card successfully, they will follow the initial purchase with a number of additional purchases within a short period of time. If you elect to use the Card Velocity Filter, the system filters the transaction based upon the number of previously approved Auth/Sale transactions plus the number of Auth/Sale transactions declined by another Basic Filter, for the same account within a configurable time period. Both the total number of transactions and the time period are configured in the Vantiv Merchant Profile. Upon a decline, the system returns a Response Reason Code of 315 - Restricted Card - Auth Fraud Velocity Filtering Service. 1.9.1.6 Prior Fraud Advice Filtering Vantiv maintains a database of Fraud Advice information received from the Visa and MasterCard networks for transactions you processed in the last 200 days. If you use the Prior Fraud Advice Filter, the system compares the account information from the new transaction against the database of accounts with prior Fraud Advice and filters the transaction if there is a match. Upon a decline, the system returns a Response Reason Code of 318 - Restricted Card - Auth Fraud Advice Filtering Service. 1.9.1.7 AVS Filter One of the fraud prevention tools provided by all card networks is an Address Verification System. By submitting the customer’s address information in the billToAddress section of the cnpAPI message, you can verify that the address/zip code supplied by the consumer matches the issuer’s records. The card networks, however, do not decline transactions based upon the failure 32 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Fraud Toolkit Introduction to match the address or zip code. Using the AVS Filter, you can filter potentially fraudulent transactions based upon failure to match any of the following: • the address • the zip/postal code • the address + zip/postal code (ANDed) • the address or zip/postal code (ORed). Upon a decline, the system returns a Response Reason Code of 319 - Restricted Card - Fraud AVS Filtering Service. 1.9.1.8 Email Velocity Filter Often, card testers or other bad actors submit a number of transaction using multiple cards, but with a common email address. The only requirement to make use of this filter is that you collect and include the consumer’s email address with each transaction. We communicate the email address to our fraud partner, ThreatMetrix, who tracks and analyzes the information. If the filter detects the same email used in the configured number of transactions within the configured period of time, the system declines new transactions (using the same email) on your behalf and returns Response Code 550 - Restricted Device or IP - ThreatMetrix Fraud Score Below Threshold. 1.9.1.9 Phone Velocity Filter Similar to email, card testers or other bad actors often submit a number of transaction using multiple cards, but with a common phone number. The only requirement to make use of this filter is that you collect and include the consumer’s phone number with each transaction. We communicate the phone number to our fraud partner, ThreatMetrix, who tracks and analyzes the information. If the filter detects the same phone number used in the configured number of transactions within the configured period of time, the system declines new transactions (using the same email) on your behalf and returns Response Code 550 - Restricted Device or IP ThreatMetrix Fraud Score Below Threshold. 1.9.1.10 IP Velocity Filter The IP Velocity filter is one of the two filter in the Essential tier that requires (see note below) the addition of a code snippet to your checkout page. This snippet, which you also need to implement for the higher tiers of Fraud Toolkit, allows our partner, ThreatMetrix, to perform IP interrogation/piercing t determine the true IP Address of the device originating the order. As with the other velocity filters, if the filter detects the same IP Address used in the configured number of transactions within the configured period of time, the system declines new transactions from the same IP Address on your behalf and returns Response Code 550 - Restricted Device or IP ThreatMetrix Fraud Score Below Threshold. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 33 cnpAPI Reference Guide Introduction Fraud Toolkit NOTE: 1.9.1.11 Technically, you can make use of the IP Velocity filter without integrating the code snippet on your checkout page. Instead you can simply include the originating IP Address that you detect in your transaction. Please note that this method will likely be less effective than making use of the ThreatMetrix functionality, which includes IP piercing to determine the true IP of the consumer’s device. Device Velocity Filter The Device Velocity filter is the second Essential tier filter in the that requires the addition of a code snippet to your checkout page. In this case, the snippet allows ThreatMetrix to construct a device fingerprint of the system originating the order. As with the other velocity filters, if the filter detects the same device used in the configured number of transactions within the configured period of time, the system declines new transactions from the same device on your behalf and returns Response Code 550 - Restricted Device or IP - ThreatMetrix Fraud Score Below Threshold. 1.9.1.12 Application of Filters - Filtering Rules NOTE: Filter Rules are defined as part of your Merchant Profile. Please consult with your Relationship Manager and/or your Implementation Consultant concerning the provisioning of Filter Rules. While you can have all submitted transactions flow through the Fraud toolkit, you likely want to exercise a finer control over the application of the filters based upon a particular product, service or other criteria. The system provides you the flexibility of restricting which transactions are submitted to the filtering service and which filters the system applies to which groups. This is accomplished by defining Filtering Rules. For each Filtering Rule you first define a subgroup of transactions by selecting one of the following Flow Selectors: Report Group, Billing Descriptor, orderSource, or MID (for PayFacs, flow control by MID or order source only). Only one selector can be applied per rule. After selecting a particular Flow Selector, you then select which filters to have applied to that subset of transactions. You can define the Filter Rules so that filters are ORed (transaction filtered when any one of the filters conditions met), or ANDed (transaction filtered when multiple filter conditions met). Table 1-9 defines five rules that a merchant might define. TABLE 1-9 34 Example - Fraud Filtering Service Rules Filter Flow Selector Filters 1 Report Group = "XYZ" Prepaid Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Fraud Toolkit Introduction TABLE 1-9 Example - Fraud Filtering Service Rules Filter Flow Selector Filters 2 Report Group = "XYZ" International 3 orderSource = "recurring" Prepaid + Prior Chargeback 4 orderSource = "ecommerce" Fraud Velocity + Security Code No-match 5 Billing Descriptor = "GoldMember" Prepaid + International Table 1-9 defines five Filter Rules that a merchant might use. These rules would be applied as follows: • Filters 1 and 2 are applied to the subset of transactions that are members of Report Group XYZ and use the Prepaid and International Filters. Since the Filter Rules are defined separately, the rules are ORed. So, if a transaction uses either a Prepaid card or a card of International origin, the transaction is filtered. • Filter 3 is applied to the subset of transactions that have an orderSource value set to recurring. These transactions are filtered only if both the criteria for the Prepaid Filter AND the Prior Chargeback Filter are met. • Filter 4 is applied to the subset of transactions that have an orderSource value set to ecommerce. These transactions are filtered only if both the criteria for the Fraud Velocity Filter AND the Security Code No-Match Filter are met. Filter 5 is applied to the subset of transactions that have an Billing Descriptor value set to GoldMember. These transactions are filtered only if both the criteria for the Prepaid Filter AND the International Filter are met. 1.9.2 Extended Tier The Extended Tier include all of the Essential Tier filters, but offers an additional levels of fraud detection made available through Vantiv’s partnership with ThreatMetrix. The addition of the same code snippet used for the IP and Device Velocity filters to your checkout page allows ThreatMetrix to gather additional data points, such as the consumer’s device, proxy use, and location. Unlike the filters in the Essential Tier, which are basic accept/decline filters, the Extended Tier takes the data and compares the information to a rule list. Vantiv supplies an initial, Best Practices rules list designed for your business type (i.e., Retail, Digital, Non-profit, etc.), which you can modify and refine for you particular business model. Each rule, when triggered, add or subtract a preset value from the transaction score. If the score fall below a set threshold, the system declines the transaction, unless you prefer to make the final decision yourself. In either case, Vantiv returns the score and a list of triggered rules in the transaction response message. In addition to the ThreatMetrix rules engine, you get access to the ThreatMetrix Portal allowing you to customize your rules list and scoring values. This level also allows you to white list/black list items, such as email addresses and phone numbers. Other items included in this tier are: • ThreatMetrix Cybercrime Dashboard Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 35 cnpAPI Reference Guide Introduction Fraud Toolkit • Asynchronous Transaction Review Queues • Monthly Rules and Portal training • API Access to Standalone Fraudcheck transaction. 1.9.3 Premium Tier The Premium Tier provides all of the tools from the Essential and Extended Tiers, and most importantly, access to the Vantiv eComm Fraud Consulting service. With the service, the Fraud Consultant assigned to you helps analyze your transactional data, recommend rule changes to fine-tune your results, and advises you on fraud detection strategy. 1.9.4 Modifications to Your Web Page For ThreatMetrix to gather information for analysis, you must add certain profiling tags (see example below) to selected pages served by you web application. These tags allow ThreatMetrix to collect information by loading objects used for detection into the consumer’s browser. These tags are invisible to the consumer and add only a fraction of a second to your page’s rendering time. Once loaded, these objects require only 3-5 seconds to gather profiling information from the consumer device. Place the tags as early as possible on the page, inside the tags of the page HTML. Example: ThreatMetrix Profiling Tags NOTE: Replace UNIQUE_SESSION_ID with a uniquely generated handle that includes the Vantiv supplied prefix. The value for ORG-ID is a Vantiv supplied value. The pageid tag is not used at this time. The value for PAGE-ID defaults to 1. For production, replace h.online-metrix.net with a local URL and configure your web server to redirect to h.online-metrix.net. 1.9.4.1 cnpAPI Transactions To subject a transaction to the advanced fraud checks performed by ThreatMetrix and retrieve the results, you simply submit the element as part of your cnpAPI Authorization (or Sale) transaction. This session Id is the same unique value you assigned and sent to ThreatMetrix when your web page called the application (designated as UNIQUE_SESSION_ID in the ThreatMetrix Profiling Tags example). When we receive an Authorization/Sale that includes the , our system automatically queries the ThreatMetrix platform for the associated results. The cnpAPI response message includes the element containing the score and status and information about any triggered rules. The following two examples show a standard Authorization transaction, including a and a pass response. Example: Authorization including Element Example: Authorization Response including User Name password 10102013_sessionId_app 1002 ecommerce John Doe 15 Main Street San Jose CA 95032-1234 USA 9782750000 nobody@vantiv.com MC 5405102001000003 1115 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 37 cnpAPI Reference Guide Introduction Fraud Toolkit ASDFG-AXXXXAB999 Element NOTE: The other possible values for the 82823534116454639 10102013_sessionId_app 000 2017-10-08T21:36:50 2017-10-08 Approved 000003 00 pass 50 FlashImagesCookiesDisabled element are fail, review, unavailable, and invalid_session. The value can range from -100 to 100. The resulting pass, fail, or review value depends upon your profile settings. The element can occur multiple times, once for each rule triggered. 38 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Fraud Toolkit Introduction 1.9.4.2 Information Only Option If you wish to retain full control of the decision to accept or decline transactions, Vantiv offers the option of using the Advanced Fraud Tools in an Information Only mode. In this configuration, you receive the same information in the response as you would with the full implementation; however, Vantiv will not automatically decline transactions with a failing score. If the authorization is declined by the network, you can choose to recycle the transaction or do nothing. If an authorization with a failing score receives approval from the network, it would be up to you to reverse the authorization should you decide not to proceed with the transaction. This is similar to the case of an approved transaction that has a status of Review, but you decide not to proceed. Issuing an authorization reversal allows you to avoid any misuse of Auth fees otherwise imposed by the card networks. 1.9.4.3 Fraud Check Transactions If you wish to retrieve the Advanced Fraud results without introducing a Authorization or Sale transactions, use a Fraud Check transaction as shown in the example below. Fraud Check transactions are only supported as Online transactions. Example: Fraud Check Transaction 40 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Tokenization Feature Introduction 1.10 Tokenization Feature Tokenization is the process by which a credit card number or eCheck account number is replaced by a reference number, referred to as a token. Unlike the card or account number, you can store the token on your system without concern of a security breach exposing critical customer information. Vantiv stores the information in a secure vault and accesses it only when you submit a transaction using the supplied token. NOTE: You must be enabled for card tokenization in order to use the eCheck tokenization feature. In the case of credit cards, since you do not store the customer’s account information, the scope of PCI requirements to which you must comply may be minimized. This may greatly reduce the cost of compliance and may limit your liability if your systems are breached. You can further reduce the requirements, as well as the possibility of exposure from a breach through the use of the Vantiv eProtect. By sending the card information from your page directly to our systems you eliminate one more facet of handling the card information. NOTE: Vantiv recommends you consult your own PCI Compliance and Legal departments to determine the specific advantages of tokenization for your company. This section discusses the following topics: • How Tokenization Works • Token Formats • Obtaining Tokens • Supported Token Transactions NOTE: Information about the use of and integration to the Vantiv Pay Page is contained in the Vantiv Pay Page Integration Guide. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 41 cnpAPI Reference Guide Introduction 1.10.1 Tokenization Feature How Tokenization Works In a non-tokenized environment, customer data, including the card/eCheck account number, is handled and stored by multiple parties for each transaction. From a merchant standpoint, they receive the information, store it in their own database, and transmit it to their processor with the transaction request, as Figure 1-5 shows for card information. While the access and transmission of the data may occur a single time, as in the case of a Sale transaction, frequently the data is transmitted multiple times in order to complete a single sale, as in the case of an Auth followed by a Capture or several partial Captures. The local storage and repeated transmission of the information creates additional possible breach points, where the information might be compromised by a malicious third party. FIGURE 1-5 Card Information Flow in Non-Token Environment Card Assn. Merchant Account # Account # Account # Account # Issuing Bank Cardholder Account # Account # Database Account # Database Database Account # Database In a tokenized environment customer data is ideally transmitted a single time and is never stored locally by the merchant, as Figure 1-6 shows for card data. Once the account number is registered, using either a registerTokenRequest or by submitting it with any supported transaction, Vantiv returns a token. You store the token locally and use it for all future transactions concerning that account. Vantiv takes responsibility for storing and safeguarding the account information. NOTE: 42 The difference between card data flow and eCheck data flow is that the entities upstream of Vantiv are different. The principles remain the same from a merchant standpoint. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Tokenization Feature FIGURE 1-6 Introduction Card Information Flow in Tokenized Environment Card Assn. Merchant Issuing Bank Account # Token Cardholder Account # Token Database NOTE: 1.10.2 Account # Account # Account # Vantiv Vault Account # Database Account # Database Depending upon implementation, the use of a pay page can allow the account information to come directly to Vantiv, so the merchant handles the token only. Token Formats For credit cards, in an effort to minimize development requirements on the merchant side, Vantiv elected to use a format-preserving tokenization scheme. In simple terms this means that the length of the original card number is reflected in the token, so a submitted 16-digit number results in a 16-digit token. Also, all tokens use only numeric characters, so you do not have to change your systems to accept alpha-numeric characters. The credit card token numbers themselves have two parts. The last four digits match the last four digits of the card number. The remaining digits (length can vary based upon original card number length) are a randomly generated. Unlike credit card numbers, which are Mod 10 compliant, tokens are Mod 10 + 1 compliant. FIGURE 1-7 Token Format - Card For an eCheck token, since the account number length can vary widely, we elected to make the tokens a uniform length of 17 digits. Unlike card tokens, the entire eCheck token number is a randomly generated. The system supplies the last three characters of the account number in a separate element. As with credit card tokens, eCheck tokens are Mod 10 + 1 compliant. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 43 cnpAPI Reference Guide Introduction 1.10.3 Tokenization Feature Obtaining Tokens NOTE: You must be token enabled and certified prior to using the Vault feature. Please consult your Customer Experience Manager concerning the requirements and details of this process. There are three ways for you to obtain tokens for account numbers. First, you can submit an existing card number/eCheck account information (account number and routing number) using a Register Token request. When Vantiv receives this transaction type, we generate a token and return it to you via a Register Token response (see Register Token Transactions on page 291.) Although you can use this method to tokenize an account number at any time, it is most useful when initially tokenizing your customer database. Vantiv recommends that you collect all distinct credit card numbers in your database and submit the information in one or more large Batch. When you receive the response file, parse the returned token information to your database, replacing the card numbers. The second method you can use to obtain a token is to submit a supported transaction with the card information. If you are a tokenized merchant, Vantiv will automatically convert the submitted card number to a token and return it to you in the transaction response. Typically, you would use this method when taking and submitting a transaction during the normal course of business. When you receive the response, you store the token instead of the card information. NOTE: Once a card number has been converted to a token for a particular merchant, subsequent submissions of the same card number will return the same token. The third method of obtaining a token applies only to merchants using the Vantiv Pay Page feature. In this case, upon submission of an account number via the Pay Page API, Vantiv issues a Registration Id. You then submit the Registration Id in an Authorization or Sale transaction and receive the token in the response message. 1.10.3.1 Bulk Token Registration If you are new to Vantiv, and have utilized tokens with a previous processor, Vantiv can perform a bulk token registration on all the card numbers that were vaulted with your previous processor. The following is an example of the process: 1. During your implementation with Vantiv, you contact your previous processor and request an encrypted mapping file containing the card and token numbers for your customers. A Implementation Consultant will work with you and your previous processor to facilitate the secure transfer of this file without impacting your PCI compliance. The file can be comma-delimited, tab-delimited, or any other common format. 2. Vantiv performs a bulk token registration of all of the card numbers contained in the file. 44 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Tokenization Feature Introduction 3. Vantiv returns a mapping file to your organization containing the old tokens and the new Vantiv-issued tokens, so that you can update your order processing system. Note that Vantiv supports token-extractor formats of all major token service providers. Contact your Implementation Consultant for more information or to initiate this process. 1.10.4 Supported Token Transactions The following transactions support the generation and use of tokens: • Authorization - You can submit the transaction either with a token or card information. If you submit card information, Vantiv automatically generates the token and returns it in the response. • Capture Given Auth - You can submit the transaction either with a token or card information. If you submit card information, Vantiv automatically generates the token and returns it in the response. • Credit - You can submit the transaction either with a token or card information. If you submit card information, Vantiv automatically generates the token and returns it in the response. • Force Capture - You can submit the transaction either with a token or card information. If you submit card information, Vantiv automatically generates the token and returns it in the response. • Register Token - You use this transaction to convert a card number or eCheck account number to a Vantiv token without an associated authorization, verification or payment transaction. • Sale - You can submit the transaction either with a token or card information. If you submit card information, Vantiv automatically generates the token and returns it in the response. • eCheck Credit - You can submit the transaction either with a token or account information. If you submit account information, Vantiv automatically generates the token and returns it in the response. • eCheck Redeposit - You can submit the transaction either with a token or account information. If you submit account information, Vantiv automatically generates the token and returns it in the response. • eCheck Sale - You can submit the transaction either with a token or account information. If you submit account information, Vantiv automatically generates the token and returns it in the response. • eCheck Verification - You can submit the transaction either with a token or account information. If you submit account information, Vantiv automatically generates the token and returns it in the response. • Update Card Validation Number - This is a special transaction type provided to allow the update of a CVV2/CVC2/CID code supplied at the time of the token registration. You should only use this transaction type if you had previously submitted the account number and Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 45 cnpAPI Reference Guide Introduction Tokenization Feature security code in a registerTokenRequest transaction and now need to change the CVV2/CVC2/CID value. 1.10.5 Compliance with Visa Best Practices for Tokenization As shown below, the Vault tokenization solution complies with 11 of the 12 items listed in the Visa Best Practices for Tokenization document. The twelfth item concerns the management of stored historical data (that may contain card information) within your systems. Tokenizing all historical card info when implementing the Vantiv solution would satisfy this item, as would protecting it per PCI DSS requirements. TABLE 1-10 Visa Best Practices for Tokenization Compliance Item # Who Domain Best Practice Complies? 1 Vantiv Tokenization System Network Segmentation Yes 2 Vantiv Tokenization System Authentication Yes 3 Vantiv Tokenization System Monitoring Yes 4 Vantiv Tokenization System Token Distinguishability Yes 5 Vantiv Token Generation Token Generation Yes 6 Vantiv Token Generation Single- vs. Multi- use Tokens Yes 7 Vantiv Token Mapping PAN Processing Yes 8 Vantiv Card Data Vault PAN Encrypted in Storage Yes 9 Vantiv Card Data Vault Covered by PCI DSS Yes 10 Vantiv Cryptographic Keys Key Strength Yes 11 Vantiv Cryptographic Keys Covered by PCI DSS Yes 12 Merchant Historical Data Management Non-tokenized data protected Merchant Implementation Decision 46 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCheck Processing Introduction 1.11 eCheck Processing An eCheck is an alternative payment method that directly debits a consumer's account via the Automatic Clearing House (ACH) network. From a merchant’s standpoint offering eCheck as a payment method has several advantages, including a large consumer base in excess of 130 million accounts in the United States and no interchange fees. This section provides information about several Vantiv eCheck processing features. Please consult with your Customer Experience Manager for additional information. NOTE: 1.11.1 Vantiv also supports eCheck processing for our merchants doing business in Canada. All eCheck transaction types, except Verification and Prenotification transaction are supported. Please consult your Customer Experience Manager for additional information. Validation Feature Vantiv performs a validation of the eCheck routing number. This is done both to verify that the routing number is correctly formatted and that it exists in the routing number database. If the routing number fails this validation, Vantiv rejects the transaction. Vantiv performs this validation on all eCheck transactions automatically. 1.11.2 Verification Feature Since there is no authorization process associated with eChecks allowing you to confirm the availability of funds and hold the purchase amount, there is a higher risk of certain types of fraud. The optional eCheck Verification feature allows you to submit an eCheck account number for comparison to a database containing historical information about the account, as well as the account holder. When you submit an eCheck Verification transaction the information you provide is compared to a negative database to see if the account is associated with activities, such as fraud, over drafts, or other items determined to be risk factors. NOTE: Vantiv makes use of a third party service, Certegy Check Services Inc., for all verification operations. The verification service is not supported for Canadian eChecks. The verification service is not available for PayFacs. You can also initiate an account verification operation as part of an eCheck Sale transaction by setting the User Name password ASDFG-AXXXXAB999 Attribute passed to ThreatMetrix Attribute passed to ThreatMetrix Attribute passed to ThreatMetrix Attribute passed to ThreatMetrix Attribute passed to ThreatMetrix John Doe 15 Main Street San Jose CA 95032-1234 USA 9782750000 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 39 cnpAPI Reference Guide Introduction Fraud Toolkitjdoe@vantiv.com Jane Doe 15 Main Street San Jose CA 95032-1234 USA 9782750000 jdoe@vantiv.com element to true. In this case, the eCheck Sale transaction is conditional upon the verification passing. If the verification fails, the sale is not processed. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 47 cnpAPI Reference Guide Introduction eCheck Processing 1.11.2.1 Required Contents of Decline Notice In the event you elect to perform verification on a transaction and also elect not to proceed with the transaction based upon a verification failure, you must provide your customer with the following Decline Notice. You can provide the notice orally, electronically, via e-mail, and/or via U.S Mail, depending upon the type of transaction. The notice must be substantially as the notice set forth below that contains the disclosures required under the Fair Credit Reporting Act and instructs your customer how to contact Certegy directly. NOTE: If the required language of the Decline Notice changes, Vantiv will notify you of the change. You must enact the changes within 10 days. Example: Decline Notice We're sorry, but we are unable to proceed with your transaction. This determination was based on information provided by Certegy Check Services, Inc. (“Certegy”). To protect your privacy, Certegy did not provide any financial information to [Client's Name] during the authorization process. The reason your transaction was not authorized was due to [mark one of the following based on applicable decline code transmitted by Certegy]: • account closed • dishonored check or transfer information contained in Certegy's files • Certegy had insufficient information available • the identification information you entered did not conform to established guidelines You have the right under the Fair Credit Reporting Act to know the information Certegy utilized to make a determination regarding your check. If you find that any information Certegy utilized in its decision is inaccurate or incomplete, you have a right to dispute it with Certegy. You may call Certegy toll free at 800-695-1854, or write to Certegy Check Services, Inc., P.O. Box 30046, Tampa, FL 33680-3046. If you contact Certegy, please provide the following information so they can respond promptly to your request: 48 • First Name • Driver’s License Number & State • Current Address • Home Telephone Number • Date Declined • Date of Birth • Dollar Amount • Social Security Number • Check/Draft/Transfer Number • Merchant Name Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCheck Processing • 1.11.3 Introduction Checking Account Number • Name of Financial Institution Automatic Notice of Change (NoC) Updates Similar to an issuing bank providing credit card Account Updater information, RDFIs provide Notification of Change (NoC) files and deliver them through the ACH network. These NoCs include updated account information including bank routing numbers, account numbers, and account names. Vantiv makes available the NoC information to you for your use in updating your customer files. Additionally, if you submit a transaction containing information that has changed, we automatically update the information and forward the corrected transaction to the ACH network. The cnpAPI response message to you also contains the updated information for your use in correcting your database. NOTE: 1.11.4 While we always make the NoC information available to you, Vantiv does not support automatic updating of account information for PayFacs. Auto Redeposit Feature NACHA rules allow merchants to redeposit entries when the initial deposit was returned for either Insufficient Funds or Uncollected Funds. Two redeposit attempts are allowed within 180 days of the settlement date of the initial deposit. Vantiv offers an optional service that allows you to pre-configure automatic redeposits of transactions returned for the those reasons. You define the number of days from the initial return for Vantiv to resubmit the transaction. You also define the number of days from the return of the first resubmission for the attempt of a second resubmission. NOTE: You track the current state of your transactions, returns, and resubmissions via the iQ User Interface. Please refer to the eCommerce iQ Reporting and Analytics User Guide for additional information. For example, you submitted an eCheck Sale transaction on 29 January that is returned for Return Reason Code R01 - Insufficient Funds. The return occurs on 1 February. With the Auto Redeposit feature enabled and a preset period of 5 days for the first redeposit, the system would automatically generate a resubmission of the deposit on 6 February. If this transaction is also returned for the same reason code on 7 February and you have a preset time period for the second redeposit on 7 days, the system generates the second redeposit on 14 February. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 49 cnpAPI Reference Guide Introduction 1.11.5 eCheck Processing eCheck Prenotification An eCheck Prenotification is a non-monetary transaction used to verify the account information supplied by the consumer is valid. These transactions are sent to the ACH network to help ensure subsequent entries are posted appropriately. Since this is a verification of account information, typically, you would submit a Prenotification transaction in advance of processing the order, during the customer set-up process. There are two types of Prenotification transaction types: echeckPreNoteCredit and eCheckPreNoteSale. Per NACHA requirements, you must submit the Prenotification transaction that corresponds to the intended, subsequent transaction. For example, if you are planning to submit an echeckSale transaction and want to verify the account information, you should submit a echeckPreNoteSale. The possible ACH network responses to a prenotification are as follows: • No response - applies when the account is open and the account information is correct. • Notification of Change - provides updated account information, including correct routing number, e.g. C02 Incorrect routing/transit number (visible in the SSR eCheck NOC report). • Return code - provides account status, e.g. R02 Account is closed, R03 No account on file, R04 Invalid account number. NOTE: Prenotification transactions are only supported in cnpAPI V9.1 or above and only in Batch submissions. Prenotification transactions are not supported for PayFacs or Canadian eChecks. When you submit either of the Prenotification transaction types, the system sends an acknowledgment in the Batch response file. This response file does not provide the results of the prenotification check, but rather a verification that we received the transaction and it was properly formatted. You receive the results to the check in the SSR eCheck Notification of Change report. This report is run daily and you can expect to see the results for submitted prenotification checks by the second or third business day after the settlement day. The settlement day for a Prenotification transaction is defined as the next business day after submission to the ACH network. Remember, if the account you are attempting to verify is open and the account information is correct, the report will not contain an entry for that transaction. The report only contains NOCs (update information). Per NACHA regulations, you can submit the eCheck Sale or eCheck Credit transaction on the third business day after the settlement day; however, there might still be a forthcoming NOC on that day. Due to the timing of the responses from NACHA, the generation of the reports, and the movement of the transactions, you should wait until the fourth day after the settlement day to submit the live transaction unless you receive a NOC earlier. This timing is illustrated in the example below. 1. You submit a Prenotification transaction on Monday prior to your cut-off time. 2. Our system forwards the transaction to NACHA on Tuesday. Note, this makes Wednesday the settlement day. 3. NACHA responds with a NOC/return, if any, by Thursday night. 50 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCheck Processing Introduction 4. On Friday, the information from NACHA is processed by our systems. 5. On Saturday morning, the SSR NOC report containing the information is available to you. 6. You can submit the eCheck Sale or eCheck Credit transaction before your cut-off time on Saturday night. This is the fourth day after settlement, the fifth day after submission. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 51 cnpAPI Reference Guide Introduction SEPA Direct Debit 1.12 SEPA Direct Debit When building a robust international ecommerce offering, you should always consider regional, preferred payment methods. Enabling payment methods with which consumers are both familiar and comfortable may provide a significant bump in your conversion rates and sales. In Europe there are dozens of regionally popular alternative payment methods. SEPA (Single Euro Payments Area) Direct Debit is a Pan-European network facilitating direct debit transactions in 34 countries. Currently, SEPA Direct Debit accounts for approximately 10% of all eCommerce sales in Europe and leads all alternative payment methods in Germany, accounting for more than 35% of eCommerce spending. Although similar to eCheck transaction in the US, in that they are both direct debit methods of collecting funds, there are several differences in the process. Most of the difference concern the requirement for the presentation of a Mandate to the consumer. A Mandate is basically an agreement between the consumer and the merchant allowing the merchant to debit the consumer’s account for the required funds. The agreement can specify either a one-time payment or recurring payments. The consumer must agree to the Mandate (Usually, by clicking a Confirm button on the Mandate page.) for the transaction to succeed. The Vantiv eComm platform allows for two different Mandate scenarios. The first, and recommended method, involves the redirect from your site to a Vantiv provided Mandate page. Alternatively, you can provide your own Mandate page. The following sections discuss the purchase/order flow for each scenario. 1.12.1 SEPA Direct Debit - Vantiv Supplied Mandate You cannot complete a SEPA Direct Debit transaction without an approved (by the consumer) Mandate. While you can produce your own Mandate page, Vantiv makes the implementation of SEPA Direct Debit easier for you by providing Mandates in various languages, for either single payments or recurring transactions. Figure 1-8 provides an overview of the order flow, when using a Vantiv supplied Mandate for a one-time payment, or the first payment in a recurring stream. The steps provide additional information. 52 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide SEPA Direct Debit Introduction FIGURE 1-8 1 Order Flow for Vantiv Supplied Mandate Consumer enters their IBAN and clicks Submit button on Checkout page. 2 Consumer Merchant sends Sale transaction to Vantiv. Merchant Merchant redirects consumer to the Mandate page. Response includes link to Mandate page and redirectToken. 4 5 3 Consumer Accepts or Rejects the Mandate. Mandate Page Consumer redirected back to Merchant Checkout page. If the consumer accepted the Mandate, redirectToken appears as a URL parameter. If Mandate rejected, redirectToken not included. 6 . 1. On your checkout page, the consumer selects SEPA Direct Debit as the payment method, enters their IBAN (International Banking Account Number), selects a preferred language for the Mandate (optional), and clicks the Submit button. NOTE: If you do not specify a preferred language, or you specify an unavailable language, the Mandate page appears in English. 2. You create a Sale transaction and submit it to the Vantiv eComm platform, using sepaDirectDebit as the payment method and including its child elements shown below (preferredLanguage optional). In addition to the required child elements of sepaDirectDebit you must include the name, email, and country child elements of billToAddress. Example: SEPA Direct Debit Sale Request Message - Vantiv Supplied Mandate 3. The response message (example shown below) includes the redirectUrl element, which hosts the Mandate. The redirectToken returned in the response allows you to verify the consumer accepted the Mandate. If this transaction is the first of a recurring stream, you use the mandateReference element in subsequent payments to reference the agreed to (recurring) Mandate. Example: SEPA Direct Debit Sale Response Message - Vantiv Supplied Mandate SDD password Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 53 cnpAPI Reference Guide Introduction SEPA Direct DebitsddSale 1001 ecommerce Johann Schmidt 10 Hoch Strasse Hanover 30159 DE jschmidt@phoenixprocessing.com 781-270-1111 Vantiv OneTime DE79850503003100180568 DE 4. You redirect the consumer from your checkout page to the redirectUrl. 5. The consumer either accepts or rejects the Mandate. 6. After the consumer either accepts or declines the Mandate, they are redirected back to your checkout page, or alternate page upon decline. If they accepted the Mandate, the URL contains a parameter exposing the redirectToken value (redirectToken=token_value). By comparing this value to the value you received in the Sale response message you can verify that the consumer accepted the Mandate. If they declined the Mandate, the URL does not include the parameter. 1.12.2 SEPA Direct Debit - Merchant Supplied Mandate If you elect to produce and provide your own Mandate to the consumer, the order flow differs from the Vantiv supplied Mandate flow, as shown in Figure 1-9 and explained in the steps that follow. FIGURE 1-9 Order Flow for Merchant Supplied Mandate Consumer enters their IBAN and clicks Submit button on Checkout page. 1 5 Consumer Merchant presents Mandate terms. 3a Merchant sends Sale transaction to Vantiv, including mandateSignatureDate, mandateUrl, etc. Response Merchant 6 2 3b Consumer Accepts or Rejects the Mandate. Accept/Reject info to Merchant Mandate Page Consumer redirected back to Merchant Checkout page. If the consumer accepted the Mandate, the Merchant constructs a Sale transaction to Vantiv. 4 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 55 cnpAPI Reference Guide Introduction SEPA Direct Debit 1. On your checkout page, the consumer selects SEPA Direct Debit as the payment method, enters their IBAN (International Banking Account Number), selects a preferred language for the Mandate (optional), and clicks the Submit button. 2. You redirect the consumer from your checkout page to your Mandate page. 3. The consumer take action on the Mandate page. a. The consumer either accepts or rejects the Mandate. b. Your Mandate page provides the Accept or Decline information to your servers. 4. Once the consumer takes action on the Mandate page, you return them to your checkout page. If the consumer rejected the Mandate, you can ask for a different payment method. If the consumer accepted the Mandate, you record the signature date and use it to construct a Sale transaction. Also, if this is the first of a series of recurring payments, you assign a mandateReference value. 5. You submit the Sale transaction to the Vantiv eComm platform, as shown in the example below. In addition to the required child elements of sepaDirectDebit you must include the mandateReference, mandateUrl, and mandateSignatureDate, as well as the name, email, and country child elements of billToAddress. Example: SEPA Direct Debit Sale Request Message - Merchant Supplied Mandate 82830949823203015 sddSale 000 2017-01-21T17:07:27 2017-01-21 Approved http://MandateHostURL/DE evr0kij413g8r85e32v7deov0c 54 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide SEPA Direct Debit Introduction1ABCA43 6. The Vantiv eComm platform returns a Sales response message. This message does not include the sepaDirectDebitResponse element, since Vantiv does not return any additional SEPA Direct Debit related information, such as a redirectToken. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 57 cnpAPI Reference Guide Introduction iDEAL, SOFORT, and Giropay 1.13 iDEAL, SOFORT, and Giropay iDEAL, SOFORT, and Giropay are International alternative payment methods. iDEAL services over 10 million consumers in the Netherlands, Giropay services German consumers, and SOFORT services consumers in several countries (predominantly Germany and other German speaking countries). Each of these alternative payment methods initiate a real-time transfer of funds from the consumer account to the merchant account. This method differs from credit cards and several other alternate payment methods in that the consumer is not agreeing to pay the settlement at a future time, rather they communicate directly with their bank and approve the transfer of fund from their account to yours. After their approval, their bank displays to them a confirmation of payment and debits their account within a few seconds. NOTE: Although the bank debits the consumer’s account immediately, the funds may not appear in your account for a few days, depending upon your settlement agreement. The graphic and steps below illustrate the iDEAL, SOFORT, and Giropay processes. FIGURE 1-10 1 iDEAL, SOFORT, adn Giropay Order Flow Consumer selects the payment method on the Checkout page. 2 Consumer Merchant Merchant redirects consumer to the bank selection page. 4 5 Consumer Accepts or Rejects transaction using the Bank authentication process. Merchant sends Sale transaction to Vantiv. Response includes link to page for bank selection and redirectToken. 3 Bank Consumer redirected back to Merchant Checkout page. If the consumer accepted the agreement, redirectToken appears as a URL parameter. If agreement rejected, redirectToken not included. 6 . 58 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide iDEAL, SOFORT, and Giropay Introduction 1. On your checkout page, the consumer selects iDEAL, SOFORT or Giropay as the payment method and clicks the Submit button. 2. You create a Sale transaction (iDEAL example below) and submit it to the Vantiv eComm platform, using ideal as the payment method and including its child elements, preferredLanguage if specified. Example: iDEAL Sale Request SDD password sddSale 1001 ecommerce Johann Schmidt 10 Hoch Strasse Hanover 30159 DE jschmidt@phoenixprocessing.com 781-270-1111 Merchant FirstRecurring ABCD1234 56 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide SEPA Direct Debit Introductionhttp://MerchantMandateHostURL 2017-01-21 DE79850503003100180568 3. The saleResponse includes a redirectURL, which you use to redirect the consumer to a bank selection page. It also contains a redirectToken, which you use later to verify the acceptance and bank transfer by the consumer. Example: iDEAL Sale Response user_name password p1_idealSale 10011 ecommerce David Berman 10 Noorderstraat Amsterdam 1000 AP NL dberman@phoenixprocessing.com 020-1234567 NL 4. The consumer selects their bank on the bank selection page. 5. The consumer accepts or rejects the transaction on their bank page. The bank determines the actual process of accepting the transaction. 6. The consumer gets redirected back to your checkout page. If they accepted the agreement, the URL contains a parameter exposing the redirectToken value (redirectToken=token_value). By comparing this value to the value you received in the Sale response message you can verify that the consumer accepted the agreement and the bank transferred the funds. If they declined, the URL does not include the parameter. NOTE: 60 Although the consumer does not have chargeback rights when using these alternate payment methods, Vantiv recommends you maintain a robust and well documented returns system. European regulations require that you credit your customer’s account within 30 days of a return. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ Introduction 1.14 eCommerce Solution for Apple Pay™ Vantiv supports Apple Pay for in-app and in-store purchases initiated on compatible versions of iPhone and iPad, as well as purchases from your desktop or mobile website initiated from compatible versions of iPhone, iPad, Apple Watch, MacBook and iMac (Apple Pay on the Web). For in-store transactions, a consumer can use the Near Field Communications (NFC) chip in their device to make a purchase by simply touching the device to an NFC-compliant terminal. Identity verification is provided by Touch ID, a fingerprint reading application built into the device. If you wish to allow Apple Pay transactions from your native iOS mobile application, you must build the capability to make secure purchases using Apple Pay into your mobile application. If you wish to allow Apple Pay payments on your desktop or mobile website, your website must be configured to work with Apple to request authorization from the consumers iPhone or iPad via Touch ID. See Table 1-11, "Apple Pay on the Web Compatible Devices" for more information. This section provides an overview of the operation of Apple Pay and Apple Pay on the web, along with the several methods you can use to submit Apple Pay purchases to the Vantiv eCommerce platform. The topics discussed are: • Overview of Apple Pay Operation • Vantiv Decryption of Apple Pay PKPaymentToken • Using the Vantiv Mobile API for Apple Pay • Merchant Decryption of Apple Pay PKPaymentToken • Recurring Payments with Apple Pay 1.14.1 Overview of Apple Pay Operation The operation of Apple Pay and Apple Pay on the web is relatively simple, but will require either the development of new native iOS applications or the modification of your existing applications or website that include the use of the Apple PassKit Framework (or Apple Pay JavaScript for Apple Pay web) and the handling of the encrypted data returned to your application by Apple Pay. The basic steps that occur when a consumer initiates an Apple Pay purchase using your mobile application or website are: 1. When the consumer selects the Apple Pay option from your application, your application makes use of the Apple PassKit Framework (or Apple Pay JavaScript) to request payment data from Apple Pay. 2. When Apple Pay receives the call from your application and after the consumer approves the Payment Sheet (using Touch ID), Apple creates a PKPaymentToken using your public key. Included in the PKPaymentToken is a network (Visa, MasterCard, Discover, or American Express) payment token and a cryptogram. 3. Apple Pay returns the Apple PKPaymentToken (defined in Apple documentation; please refer to Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 61 cnpAPI Reference Guide Introduction eCommerce Solution for Apple Pay™ https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSO N/PaymentTokenJSON.html). The remainder of this section discusses the various options for handling the PKPaymentToken in the transaction flow. 1.14.2 Vantiv Decryption of Apple Pay PKPaymentToken Vantiv recommends using one of the Vantiv Decryption methods. This transaction process relieves you from the burden of creating and maintaining public and private keys, as well as decrypting the PKPaymentToken. If you have already implemented eProtect in a mobile application, you should use eProtect for Apple Pay. A second, similar method, which still allows you to submit the PKPaymentToken without decryption, involves you sending the Authorization/Sale transaction with the PKPaymentToken key values in a new cnpAPI element structure (see applepay), typically from your server. You can use this method even if you are not tokenized with Vantiv. In all of these implementations, your Vantiv Implementation Consultant will provide a CSR (Certificate Signing Request) you use in your registration process with Apple Pay. The CSR provides Apple Pay with the public key used for encryption, while Vantiv retains the private key used for decryption. 1.14.2.1 Using the Browser JavaScript API for Apple Pay on the Web In this scenario, the Vantiv eProtect Customer Browser JavaScript API controls the fields on your checkout page that hold sensitive card data. When the cardholder clicks the Apple Pay button, communication is exchanged with Apple Pay via the JavaScript API to obtain the PKPaymentToken. From this point forward, your handling of the transaction is identical to any other eProtect transaction. The eProtect server returns a Registration ID (low-value token) and your server constructs the cnpAPI transaction using that ID. See the Vantiv eProtect Integration Guide for JavaScript and HTML page examples and more information on using the browser JavaScript API. Step 1, Step 2, and Step 3 are the same as those outlined in Overview of Apple Pay Operation on page 61. The process after Step 3 is detailed below (and shown in Figure 1-11): 4. Your website sends the PKPaymentToken to our secure server via the JavaScript Browser API and eProtect returns a Registration ID. 5. Your website forwards the transaction data along with the Registration ID to your order processing server, as it would with any eProtect transaction. 6. Your server constructs/submits a standard cnpAPI Authorization/Sale transaction using the Registration ID, setting the 84568456 p1_idealSale 000 2017-04-03T10:24:31 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 59 cnpAPI Reference Guide Introduction iDEAL, SOFORT, and Giropay2017-04-03 Approved http://ideal.bank.com 1234567890 123456YourCompanyName element to applepay. 7. Using the private key, Vantiv decrypts the PKPaymentToken associated with the Registration ID and submits the transaction with the appropriate information to the card networks for approval. 62 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ Introduction 8. Vantiv sends the Approval/Decline message back to your system. This message is the standard format for an Authorization or Sale response and includes the Vantiv token. 9. You return the Approval/Decline message to your website. Table 1-11 lists the requirements for your customers’ Apple devices when making purchases via Apple Pay on the Web. NOTE: Table 1-11 represents data available at the time of publication of this document, and is subject to change. See the latest Apple documentation for current information. TABLE 1-11 Apple Pay on the Web Compatible Devices Apple Device Operating System iPhone 6 and later iPhone SE iOS 10 and later iPad Pro iPad Air 2 and later iPad Mini 3 and later iOS 10 and later Apple Watch Paired with iPhone 6 and later Watch OS 3 and later iMac Paired with any of the above mobile devices with ID Touch for authentication macOS Sierra and later MacBook Paired with any of the above mobile devices with ID Touch for authentication macOS Sierra and later Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. Browser Safari only 63 cnpAPI Reference Guide Introduction eCommerce Solution for Apple Pay™ FIGURE 1-11 1.14.3 Data/Transaction Flow using Browser JavaScript API for Apple Pay on the Web Using the Vantiv Mobile API for Apple Pay In this scenario, your native iOS application performs an HTTPS POST of the Apple Pay PKPaymentToken using the Vantiv Mobile API for Apple Pay. From this point forward, your handling of the transaction is identical to any other eProtect transaction. The eProtect server returns a PayPage Registration ID and your Mobile App (or server) constructs the cnpAPI transaction using that ID. Step 1, Step 2, and Step 3 are the same as those outlined in Overview of Apple Pay Operation on page 61. The process after Step 3 is detailed below and in Figure 1-12. 4. Your native iOS application sends the PKPaymentToken to our secure server via an HTTPS POST and eProtect returns a PayPage Registration ID. Please refer to the Vantiv eProtect Integration Guide for additional information. 5. Your native iOS application forwards the transaction data along with the PayPage Registration ID to your order processing server, as it would with any eProtect transaction. 64 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ NOTE: Introduction If you plan to use a registerTokenRequest instead of submitting an Authorization/Sale transaction skip to Alternate Flow using a Register Token Request on page 66 6. Your server constructs/submits a standard cnpAPI Authorization/Sale transaction using the PayPage Registration ID, setting the element to applepay. 7. Using the private key, Vantiv decrypts the PKPaymentToken associated with the PayPage Registration ID and submits the transaction with the appropriate information to the card networks for approval. 8. Vantiv sends the Approval/Decline message back to your system. This message is the standard format for an Authorization or Sale response and includes the Vantiv token. 9. You return the Approval/Decline message to your mobile application. FIGURE 1-12 Data/Transaction Flow using the Vantiv Mobile API for Apple Pay Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 65 cnpAPI Reference Guide Introduction 1.14.3.1 eCommerce Solution for Apple Pay™ Alternate Flow using a Register Token Request If you plan to use a registerTokenRequest transaction to obtain a token prior to submitting an Auth/Sale, follow the steps below (after step 5 of Using the Vantiv Mobile API for Apple Pay). 6. Submit a registerTokenRequest using the PayPage Registration ID. Vantiv returns a token along with Apple Pay data including the cryptogram. 7. Your server constructs/submits a standard cnpAPI Authorization/Sale transaction with the element set to applepay and the field populated with the cryptogram. 8. Vantiv sends the Approval/Decline message back to your system. 1.14.3.2 Submitting the Apple Pay PKPaymentToken in cnpAPI In this scenario, you submit the Apple Pay PKPaymentToken to the Vantiv eCommerce platform using a new structure in cnpAPI (see applepay), typically from your server. As with the previous scenario, Vantiv decrypts the PKPaymentToken from Apple Pay using the private key. Step 1, Step 2, and Step 3 are the same as those outlined in Overview of Apple Pay Operation on page 61. The process after Step 3 is detailed below and in Figure 1-13. 4. Your mobile application forwards the PKPaymentToken from Apple Pay, along with other normal information from the transaction (such as Bill To and Ship To Address), to your order processing server. 5. You do not decrypt the PKPaymentToken, but rather forward the data to Vantiv in the Authorization/Sale transaction using the cnpAPI element structure instead of (Server-side API submit) and setting the element to applepay. 6. Using the private key retained by Vantiv, we decrypt the PKPaymentToken and submit the transaction with the appropriate information to the card networks for approval. 7. Vantiv sends the Approval/Decline message back to your system. This message is the standard format for an Authorization or Sale response. 8. You return the Approval/Decline message to you mobile application. 66 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ FIGURE 1-13 cnpAPI 1.14.4 Introduction Data/Transaction Flow with Direct Submission of Apple Pay PKPaymentToken via Merchant Decryption of Apple Pay PKPaymentToken Using this process, the responsibility for the decryption of the PKPaymentToken from Apple Pay falls to you. After completing the first three steps of the process as detailed in the Overview of Apple Pay Operation section and depicted by the green and blue arrows in Figure 1-14, the process continues as follows: 4. Your mobile application forwards the PKPaymentToken from Apple Pay, along with other normal information from the transaction (such as Bill To and Ship To Address), to your order processing server. 5. Using your private key, you decrypt the PKPaymentToken, construct the Authorization/Sale transaction, and submit it to Vantiv. In this case, you would populate the cnpAPI element with the device primary account number, the element with the expiration date, and the field with the cryptogram extracted from the PKPaymentToken. Also, set the element to applepay (Server-side API submit). Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 67 cnpAPI Reference Guide Introduction eCommerce Solution for Apple Pay™ 6. Vantiv detects that this is an Apple Pay transaction and submits the transaction with the appropriate information to the card networks for approval. 7. Vantiv sends the Approval/Decline message back to your system. This message is the standard format for an Authorization or Sale response. 8. You return the Approval/Decline message to your mobile application. FIGURE 1-14 1.14.5 Data/Transaction Flow with Merchant Decryption of Apple Pay PKPaymentToken Recurring Payments with Apple Pay When you submit the first transaction in a recurring/installment stream, you must set the element to either initialRecurring or initialInstallment, as applicable. If the transaction involves a Visa or Discover card, the XML response message includes the element. You must retain the value returned for use in future transactions. When you submit the next and all subsequent transactions in the recurring stream, set the to recurring or installment as appropriate, and include the networkTransactionId value in the element. If it is a Discover transaction also include the element. Since the original payment token was only for a single use and is not available for additional transactions, this allows Visa to tie the new transaction to the original approved transaction. 68 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Android Pay™ Introduction 1.15 eCommerce Solution for Android Pay™ Android Pay is an in-store and in-app (mobile or web) payment method, providing a secure process for consumers to purchase goods and services. In-store purchases are done by using Near Field Communication (NFC) technology built into the Android Smart phone with any NFC-enabled terminal at the retail POS. For in-app purchases, the consumer need only select Android Pay as the payment method in your application. You will need to modify your application to use Android Pay as a payment method. Vantiv supports two methods for merchants to submit Android Pay transactions from Web/Mobile applications to the eComm platform. The preferred method involves you sending certain Vantiv specific parameters to Google. The response from Google® includes a Vantiv paypageRegistrationId, which you use normally in you payment transaction submission to Vantiv. With the alternate method, you receive encrypted information from Google, decrypt it on your servers, and submit the information to Vantiv in a payment transaction. This section provides an overview of both methods and includes the following sections: • Android Pay using eProtect • Merchant Decryption Method 1.15.1 Android Pay using eProtect This is the recommended and typical method of implementing Android Pay for Web and Mobile Applications on the Vantiv eComm platform. The steps that follow, along with Figure 1-15, illustrate the high level flow of messages associated with an Android Pay purchase, when utilizing the Vantiv eProtect service. NOTE: This process assumes you have integrated with Google using the method that returns the Vantiv low-value token (paypageRegistrationId) from Google following the Full Wallet request. 1. When the consumer clicks the Android Pay button in your application, the action triggers a MaskedWalletRequest to Google. In the MaskedWalletRequest, you must set a new object PaymentMethodTokenizationParameters indicating that you are using Vantiv. Use the following code sample as a guide to setting this field. Setting the PaymentMethodTokenizationParameters PaymentMethodTokenizationParameters parameters = PaymentMethodTokenizationParameters .newBuilder() .setPaymentMethodTokenizationType(PaymentMethodTokenizationType.PAYMENT_GATEWAY) .addParameter("gateway","vantiv") Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 69 cnpAPI Reference Guide Introduction eCommerce Solution for Android Pay™ .addParameter("vantiv:merchantPayPageId",payPageId) .addParameter("vantiv:merchantOrderId",orderId) .addParameter("vantiv:merchantTransactionId",id) .addParameter("vantiv:merchantReportGroup",reportGroup) .build(); IMPORTANT: You must use the same orderId value on all calls (i.e., Google, Register Token, Authorization, Sale, etc.). Failure to use the same orderId can prevent customers from tracking their orders using the Android Pay application. Setting New Object in the MaskedWalletRequest MaskedWalletRequest request = MaskedWalletRequest.newBuilder() .setMerchantName(Constants.MERCHANT_NAME) .setPhoneNumberRequired(true) .setShippingAddressRequired(true) .setCurrencyCode(Constants.CURRENCY_CODE_USD) .setEstimatedTotalPrice(cartTotal) .setCart(Car.newBuilder() .setCurrencyCode(Constants.CURRENCY_CODE_USD) .setTotalPrice(cartTotal) .setLineItems(lineItems) .build()) .setPaymentMethodTokenizationParameters(parameters) .build(); The information returned by Google in the MaskedWallet object may include a masked card number (last-four digits exposed) and shipping information. The consumer has the option of changing this information. If any info changes, Android Pay returns an updated MaskedWallet object. 2. Upon confirmation of the order by the consumer your application initiates a FullWalletRequest to Google. 3. After receiving the FullWalletRequest from your application, Google submits the card information to Vantiv eProtect. The eProtect servers return a low-value token (paypageRegistrationId). 4. Google returns the low-value token to your application along with the Full Wallet information. 70 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Android Pay™ Introduction 5. Your applications sends the transaction information to your servers along with the low-value token. Your servers submit the Auth/Sale transaction to the Vantiv eComm platform. You must set the orderSource to androidpay in the transaction. NOTE: Instead of submitting a Auth/Sale transaction, you can submit a Register Token transaction to convert the low-value token to a Vantiv high-value token. You would then use the high-value token in subsequent transactions submitted to the eComm platform. 6. Vantiv processes your transaction normally and returns the results along with a high-value token. FIGURE 1-15 Web App/ Mobil App High Level Message Flow for Android Pay using eProtect Merchant Server eProtect eComm Card Networks 1 2 3 4 5 6 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 71 cnpAPI Reference Guide Introduction 1.15.2 eCommerce Solution for Android Pay™ Merchant Decryption Method Using this process, the responsibility for the decryption of the encrypted payload from Android Pay falls to you. The steps that follow, along with Figure 1-16, illustrate the high level flow of messages associated with an Android Pay purchase, when you perform the decryption of the encrypted payload. NOTE: The process assumes you have integrated with Google using the method that returns the encrypted payload from Google following the Full Wallet request. 1. When the consumer clicks the Android Pay button in your application, the action triggers a MaskedWalletRequest to Google. The information returned by Google in the MaskedWallet object may include a masked card number (last-four digits exposed) and shipping information. The consumer has the option of changing this information. If any info changes, Android Pay returns an updated MaskedWallet object. 2. Upon confirmation of the order by the consumer your application initiates a FullWalletRequest to Google. Google also returns the encrypted payload. The encrypted payload is a UTF-8 encoded serialized JSON dictionary with the following keys: • encryptedMessage (string base64) - an encrypted message containing the payment credentials • ephemeralPublicKey (string base64) - the ephemeral public key associated with the private key to encrypt the message • tag (string base64) - MAC of encryptedMessage 3. Your application sends the encrypted payload along with the transaction information to your server. 4. Your server decrypts the encrypted payload extracting the payment, which is a UTF-8 encoded, serialized JSON dictionary with the following keys: • dpan (string (digits only)) - the device-specific personal account number (i.e., device token) • expirationMonth (number) - the expiration month of the dpan (1 = January, 2 = February, etc.) • expirationYear (number) - The four-digit expiration year of the dpan (e.g., 2021) • authMethod (string) - the constant 3DS (may change in future releases). • 3dsCryptogram (string) - the 3DSecure cryptogram • 3dsEciIndicator ((optional) string) - ECI indicator per 3DSecure specification 72 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Android Pay™ Introduction Example of Decrypted Credentials in JSON { “dpan”: “4444444444444444”, “expirationMonth”: 10, “expirationYear”: 2015, “authMethod”: “3DS”, “3dsCryptogram”: “AAAAAA...”, “3dsEciIndicator”: “eci indicator” } After decryption, submit the Authorization/Sale transaction to Vantiv, setting the orderSource element to androidpay and populating the following cnpAPI elements with the decrypted information: • number - dpan value • expDate - MMYY derived from the expirationMonth and expirationYear values • authenticationValue - the 3dsCryptogram value 5. Vantiv processes your transaction normally and returns the results in the response message. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 73 cnpAPI Reference Guide Introduction eCommerce Solution for Android Pay™ FIGURE 1-16 Web App/ Mobil App High Level Message Flow for Android Pay using Merchant Decryption Merchant Server Vantiv eComm Card Networks 1 2 3 4 5 74 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Android Pay™ 1.15.3 Introduction Recurring Payments with Android Pay When you submit the first transaction in a recurring/installment stream, you must set the element to either initialRecurring or initialInstallment, as applicable. If the transaction involves a Visa card, the XML response message includes the element. You must retain the value returned for use in future transactions. When you submit the next and all subsequent transactions in the recurring stream, include the networkId value in the element. Since the original payment token was only for a single use and is not available for additional transactions, this allows Visa to tie the new transaction to the original approved transaction. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 75 cnpAPI Reference Guide Introduction Supported Transaction Types 1.16 Supported Transaction Types cnpAPI Batch processing supports all transaction types except Voids, eCheck Voids and Private Label Gift Card reversal transactions, which are handled as Online transactions only. Online processing handles all transaction types. This section provides a description of each transaction type, information concerning its use, and any special considerations. 1.16.1 Authorization Transaction The Authorization transaction enables you to confirm that a customer has submitted a valid payment method with their order and has sufficient funds to purchase the goods or services they ordered. Setting the element to true in the Authorization request enables the system to return authorizations for a portion of the order amount for cases where the card does not have an adequate credit limit or balance available for the full amount. An approved Authorization reduces the customer's credit limit (or bank balance, in the case of a debit card) by the amount of the approval by placing the amount on hold. If you have the Prepaid Indicator feature enabled, the Authorization response also includes an element that indicates if the card is Prepaid, as well as an element indicating the available balance on the card. NOTE: To obtain better interchange rates, you should always perform an AVS check either as a standalone transaction, or as part of the Authorization/Sale transaction. While most merchants perform Authorizations as Online transactions, there is no requirement to do so. The lifespan of an Authorization depends upon the payment method. Table 1-12 provides information concerning Authorization lifespans for various card types and alternate payment methods. TABLE 1-12 Lifespan of Payment Authorizations 76 Payment Type Lifespan of Authorization MasterCard 7 days Visa 7 days American Express 7 days Discover 10 days PayPal 29 days total by default; Vantiv recommends capture submission within three days. For more information, see the Vantiv PayPal Integration Guide. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction As long as the authorization has not expired, or the amount exhausted, you can use it repeatedly to fulfill an order. This would be the case if the Authorization covered multiple items with staggered deliveries. In this scenario, you would issue a Partial Capture transaction as each item shipped until the order was completely fulfilled. NOTE: 1.16.1.1 If you obtain an Authorization through approved vendors for voice and terminal authorizations, you would use a Capture Given Auth transaction to deposit the funds (see Capture Given Auth Transaction on page 80). AVS Only Transaction An AVS Only transaction is a variation of an Authorization transaction that uses the Address Verification System to enable you to verify that a customer supplied address matches the billing address associated with the card. To submit an AVS Only transaction, submit an Authorization transaction with the element set to 000 and the optional billToAddress element with appropriate child values. NOTE: 1.16.2 To obtain better interchange rates, you should always perform an AVS check either as a standalone transaction, or as part of the Authorization/Sale transaction. Authorization Reversal Transactions The primary use of Authorization Reversal transactions is to eliminate any unused amount on an unexpired Authorization. Issuing an Authorization Reversal has the benefit of freeing any remaining held amount that reduces the buying power of your customer. Potentially, this both increases customer satisfaction and can allow them to proceed with additional purchases that may otherwise be blocked by credit limits. It also helps you avoid any misuse of Auth fees imposed by the card associations. NOTE: For American Express transactions, the reversal amount must match the authorization amount. Partial reversals and reversals against remaining amount after a partial capture are not allowed. Attempts to perform these types of reversals result in a Response Code of 336 - Reversal amount does not match Authorization amount. For example, consider the following scenario. A customer with a $6,000 credit limit orders a $3,000 stereo system, but the stereo is a discontinued item. The merchant notifies the customer, but does not perform and Authorization Reversal. The customer attempts to submit a new order for a $3,001 stereo. • If the customer uses the same credit card for both orders, the second order could be denied, since the account’s remaining credit limit is only $3,000. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 77 cnpAPI Reference Guide Introduction • Supported Transaction Types If the customer had used the same debit card for both orders, the second order places the customer’s bank account in an overdraft situation (assuming a starting balance of $6,000). Either of these situations can result in the merchant losing a sale, as well as receiving a call from an angry customer. Another advantage of Authorization Reversal transactions occurs on Visa transactions. In order for you to qualify for the best possible interchange rates from Visa, the amount of the Capture must match the amount of the associated Authorization. In order to take advantage of this situation for you, if the Capture amount is less than the associated Authorization amount, Vantiv automatically performs a partial Authorization Reversal for the unused amount (also see Capture Request on page 229). 1.16.2.1 Notes on the Use of Authorization Reversal Transactions This section provides additional information concerning the requirements of and exceptions to the use of Authorization Reversal transactions. 78 • Authorization Reversal transactions are supported for the following methods of payment: PayPal, MasterCard, Visa, Discover, Diners Club, and JC and American Express, but American Express and PayPal only support reversals of the entire Authorized amount (no partial reversals). • All transactional data, including associated Authorizations, Captures, and Refunds, must use cnpAPI format. • Vantiv recommends that you send the Authorization Reversal transaction using the same submission method (Batch or Online) as used for the Capture transaction. This is to eliminate a possible race condition that may occur if you submit an Online Authorization Reversal prior to the processing of a Batch containing the associate Capture transaction. • For Batch transactions, send Authorization Reversal transactions in a session separate from the both the associated Authorization and the associated Capture transactions. • For Online transactions, when following an Authorization with an Auth Reversal, allow a minimum of one minute between the transactions. • For Visa transactions and MasterCard, Vantiv automatically performs a partial Authorization Reversal, if the Capture amount is less than the associated Authorization amount. • If you do not specify an amount ( element) in the Authorization Reversal, Vantiv reverses the total amount of the associated Authorization. • Do not send an Authorization Reversal against an expired Authorization. This results in a 306 - Auth expired, so amount does not need to be reversed error. When an Authorization expires, the hold amount is automatically reversed. • Do not send an Authorization Reversal against an Authorization that does not exist in our system. For example, if you sends a reversal against an Authorization that failed or an Authorization that was declined, the Authorization Reversal returns a 360 - No transaction found with specified transaction Id error. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction • Do not send an Authorization Reversal against a payment type that does not support Authorization Reversals. This results in a 335 - This method of payment does not support reversals error. • Do not send an Authorization Reversal for a fully depleted Authorization. This results in a 111 - Authorization amount has already been depleted error. 1.16.2.2 Using Authorization Reversal to Halt Recycling Engine If you are using the Recycling Engine to optimize your authorizations and need to discontinue the automatic recycling of the transaction, you use an Authorization Reversal transaction to halt the retries. For example, if a customer cancels an order and the authorization for the order is being retried by the Recycling Engine, you submit an Authorization Reversal transaction to halt the automatic recycling of the authorization. NOTE: 1.16.3 If the initial transaction you submitted is a Sale (conditional deposit) rather than an Authorization, you use a Void transaction to halt the recycling. Activate Transaction You use an Activate transaction to change the status of a (Closed Loop) Gift Card from an inactive to an active state with a value as specified by the amount element. You can also use this transaction type to create a Virtual Gift Card. 1.16.4 Activate Reversal Transaction (Online Only) You use as Activate Reversal transaction to change the status of a newly activated (Closed Loop) Gift Card from active to inactive, thus reversing the operation of an Active transaction. The Activate Reversal references the associated Activate transaction by means of the litleTxnId element returned in the Activate response. 1.16.5 Balance Inquiry Transaction You use the Balance Inquiry transaction to determine the balance available for use on a (Closed Loop) Gift Card. 1.16.6 Cancel Subscription Transaction If you are using the Recurring Engine, you create Subscriptions as part of an Authorization or Sale transaction. You use the Cancel Subscription transaction to cancel the specified subscription, removing the transaction stream managed by the Recurring Engine. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 79 cnpAPI Reference Guide Introduction 1.16.7 Supported Transaction Types Capture Transaction You use a Capture transaction to transfer previously authorized funds from the customer to you after order fulfillment. You can submit a Capture transaction for the full amount of the Authorization, or for a lesser amount by setting the partial attribute to true. NOTE: 1.16.8 For a Visa transaction, if you submit a Capture for an amount less than the Authorized amount, Vantiv automatically issues a partial Authorization Reversal for the balance of the Authorized amount. Capture Given Auth Transaction Similar to a Capture transaction, you use a Capture Given Auth transaction to transfer previously authorized funds from the customer to you after fulfillment. However, you typically use a Capture Given Auth transaction if the associated Authorization occurred outside of the system (for example, if you received a telephone Authorization). Another possible use for a Capture Given Auth transaction is if the Authorization transaction occurred within the system, but the litletxnId is unknown by the submitting party (for example, if the Auth was submitted by a merchant, but a fulfiller submits a Capture Given Auth). Whenever you submit a Capture Given Auth transaction, Vantiv attempts to match it to an existing Authorization using COMAAR data (Card Number, Order Id, Merchant Id, Amount, Approval Code, and (Auth) Response Date) in order to obtain a better Interchange rate for the transaction. The application uses the following matching logic: • If the Order Id was either not submitted (blank, spaces, or null) or does not match any Auth in the system, it is ignored and the matching attempt proceeds using the remaining COMAAR data. • If the matching operation results in multiple possible matches, the application selects the Authorization with the lowest amount that is greater than or equal to the Capture Given Auth amount. NOTE: • In all cases, the Authorization amount must always be greater than or equal to the Capture Given Auth amount. If necessary, the application further narrows the match candidates to the one with the most recent response date. NOTE: If Vantiv is able to match the Capture Given Auth to an Authorization and the following conditions are met: the card type is Visa and the Capture Given Auth amount is less than the Authorization amount, then Vantiv will issue an Auth Reversal transaction for the balance of the Authorization. This is done to obtain the best possible interchange rates from Visa. 80 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types 1.16.9 Introduction Create Plan Transaction You use the Create Plan transaction to define several attributes of a recurring payment schedule. Later, as part of an Authorization or sale transaction, you can associate existing, active plans with Subscriptions. This association establishes a recurring payment schedule managed by the Vantiv Recurring Engine. 1.16.10 Credit Transaction You use a Credit transaction to refund money to a customer, even if the original transaction occurred outside of the system. You can submit refunds against any of the following payment transactions: • Capture Transaction • Capture Given Auth Transaction • Force Capture Transaction • Sale Transaction • External Sale or Capture NOTE: Vantiv recommends that all Credit transactions in a Batch be sent separate from the associated Capture or Sale transactions. 1.16.11 Deactivate Transaction You use a Deactivate transaction to change the status of a (Closed Loop) Gift Card from an active to an inactive state. 1.16.12 Deactivate Reversal Transaction (Online Only) You use a Deactivate Reversal transaction to change the status of a newly deactivated Gift Card from inactive to active, thus reversing the operation of an Deactivate transaction. The Deactivate Reversal references the associated Deactivate transaction by means of the litleTxnId element returned in the Deactivate response. 1.16.13 Deposit Reversal Transaction (Online Only) Used only for (Closed Loop) Gift Card related transactions, a Deposit Reversal transaction to reverse the funds capture initiate by either a Capture or Sale transaction. The Deposit Reversal references the associated Capture/Sale transaction by means of the litleTxnId element returned in the Capture/Sale response. You should never attempt to use this transaction type to reverse credit card or eCheck transactions. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 81 cnpAPI Reference Guide Introduction Supported Transaction Types 1.16.14 eCheck Credit Transaction Similar to a Credit transaction, you use an eCheck Credit transaction to refund money to a customer, but only when the method of payment was an eCheck. You can submit an eCheck Credit transaction regardless of whether the original transaction occurred in or out of the system. 1.16.15 eCheck Prenotification Credit Transaction You use this non-monetary transaction to verify the consumer’s account information prior to submitting an eCheck Credit transaction (also see eCheck Prenotification on page 50). This transaction type is only supported for US transactions. 1.16.16 eCheck Prenotification Sale Transaction You use this non-monetary transaction to verify the consumer’s account information prior to submitting an eCheck Sale transaction (also see eCheck Prenotification on page 50). This transaction type is only supported for US transactions. 1.16.17 eCheck Redeposit Transaction You use this transaction type to manually attempt redeposits of eChecks returned for either Insufficient Funds or Uncollected Funds. You can use this element in either Online or Batch transactions. NOTE: Do not use this transaction type if you are enabled for the Auto Redeposit feature. If you are enabled for the Auto Redeposit feature, the system will reject any echeckRedeposit transaction you submit. 1.16.18 eCheck Sales Transaction You use an eCheck Sales transaction to transfer funds from the customer to you after order fulfillment. It is the eCheck equivalent of a Capture transaction. Funding usually occurs within two days. You can also submit this transaction type as a conditional capture, which makes the processing of the deposit conditional upon a successful verification. If the verification fails, the deposit is not processed. 1.16.19 eCheck Verification Transaction You use an eCheck Verification transaction to initiate a comparison to a database containing information about checking accounts. The database may include information as to whether the 82 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction account has been closed, as well as whether there is a history of undesirable behavior associated with the account/account holder. This transaction type is only supported for US transactions. 1.16.20 eCheck Void Transaction (Online Only) You use an eCheck Void transaction to either halt automatic redeposit attempts of eChecks returned for either Insufficient Funds or Uncollected Funds, or cancel an eCheck Sale transaction, as long as the transaction has not yet settled. This also applies to merchant initiated redeposits. You can use this element only in Online transactions. 1.16.21 Force Capture Transaction A Force Capture transaction is a Capture transaction used when you do not have a valid Authorization for the order, but have fulfilled the order and wish to transfer funds. CAUTION: Merchants must be authorized by Vantiv before processing this transaction. In some instances, using a Force Capture transaction can lead to chargebacks and fines. 1.16.22 Load Transaction You use a Load transaction to add funds to an active Gift Card. The load amount cannot exceed the maximum allowed amount for the Gift Card. If you attempt to load more than the maximum amount, the transaction will be declined with a response Code of 221 - Over Max Balance. 1.16.23 Load Reversal Transaction (Online Only) You use a Load Reversal transaction to reverse the operation of a Load transaction, removing the newly loaded amount from the Gift Card. The Load Reversal references the associated Load transaction by means of the litleTxnId element returned in the Load response. You cannot perform a partial Load Reversal. This transaction always reverses the full amount of the referenced Load transaction. 1.16.24 Refund Reversal Transaction (Online Only) The Refund Reversal transaction is a (Closed Loop) Gift Card only transaction that reverses the operation of a Refund transaction on the Gift Card. The Refund Reversal references the associated Credit transaction by means of the litleTxnId element returned in the Credit response. You cannot perform a partial Refund Reversal. This transaction always reverses the full amount of the referenced Refund transaction. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 83 cnpAPI Reference Guide Introduction Supported Transaction Types 1.16.25 Sale Transaction The Sale transaction enables you to both authorize fund availability and deposit those funds by means of a single transaction. The Sale transaction is also known as a conditional deposit, because the deposit takes place only if the authorization succeeds. If the authorization is declined, the deposit will not be processed. NOTE: If the authorization succeeds, the deposit will be processed automatically, regardless of the AVS or CVV2 response. To obtain better interchange rates, you should always perform an AVS check either as a standalone transaction, or as part of the Authorization/Sale transaction. 1.16.26 Unload Transaction You use an Unload transaction to remove funds from an active Gift Card. The unload amount cannot exceed the available balance on the Gift Card. If you attempt to unload more than the available balance, the transaction will be declined with a response Code of 209 - Invalid Amount. 1.16.27 Unload Reversal Transaction (Online Only) The Unload Reversal transaction reverses the operation of a Unload transaction, returning the value removed from the Gift Card by the Unload transaction. The Unload Reversal references the associated Unload transaction by means of the litleTxnId element returned in the Unload response. You cannot perform a partial Unload Reversal. This transaction always reverses the full amount of the referenced Unload transaction. 1.16.28 Update Plan Transaction You use the Update Plan transaction to activate/deactivate Plans associated with recurring payments. When you deactivate a Plan, by setting the active flag to false, you can no longer reference that Plan for use with subscriptions. Existing subscriptions already using the deactivated Plan will continue to use the Plan until the subscription is either modified or completed. You can also reactivate a deactivated Plan by updating the Plan and setting the active flag to true. 1.16.29 Update Subscription Transaction You use an Update Subscription transaction to change certain subscription information associated with a recurring payment. Using this transaction type you can change the plan, card, billing information, and/or billing date. You can also create, update, or delete a Discount and/or an Add On. 84 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction 1.16.30 Void Transaction (Online Only) The Void transaction enables you to cancel any settlement transaction as long as the transaction has not yet settled and the original transaction occurred within the system (Voids require a reference to a litleTxnId). Before submitting a Void, please allow a minimum of 60 seconds to elapse after submitting the transaction you wish to void. This timing ensures our system fully records the first (to be voided) transaction in our database. NOTE: Do not use Void transactions to void an Authorization. To remove an Authorization use an Authorization reversal transaction (see Authorization Reversal Transactions on page 77.) 1.16.30.1 Using Void to Halt Recycling Engine If you use Recovery or the Recycling Engine service and use Sale transactions (conditional deposits) to authorize and capture the funds, you must use a Void transaction to discontinue the automatic recycling of the transaction should the need arise. For example, if a customer cancels an order and the Sale transaction is being retried by the Recycling Engine, you submit a Void transaction to halt the automatic recycling of the transaction. NOTE: If the initial transaction you submitted is an Authorization rather than an Sale, you use an Authorization Reversal transaction to halt the recycling. When using a Void transaction to halt recycling, there is a possibility that the recycled transaction has already been approved and captured. If this condition occurs, depending upon your configuration, the system takes one of two actions: • If you are not configured for the Automatic Refund option (default = disabled), the system declines the Void transaction. You must issue the Credit transaction to refund the money to the consumer. The daily Recycling file will include the approved/captured transaction. • If you are configured for the Automatic Refund option, the system issues a Credit transaction on your behalf. The system returns the transaction Id for the Credit transaction in the Void response message (creditLitleTnxId element). The daily Recycling file will include the approved/captured transaction only if the file was generated prior to the system receiving the Void and issuing the automatic refund. 1.16.31 Instruction-Based Dynamic Payout Transactions If you are a PayFac using the Instruction-Based Dynamic Payout model, there are a number of Batch only transaction types you use to move funds between various accounts, including funding Sub-merchants. This section provides information about these transaction types. For additional information, please refer to the Appendix D, "PayFac™ Dynamic Payout". Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 85 cnpAPI Reference Guide Introduction 86 Supported Transaction Types • PayFac Credit Transaction - You use this transaction type to move funds from the PayFac Settlement Account to your Operating Account. • PayFac Debit Transaction - You use this transaction type to move funds from your Operating Account to the PayFac Settlement Account. • Physical Check Credit - You use this transaction type to move funds from the PayFac Settlement Account to the account of a third party that issues physical checks on your behalf. • Physical Check Debit - You use this transaction type to move funds from the physical check issuer’s Account to the PayFac Settlement Account. • Reserve Credit Transaction - You use this transaction type to move funds from the PayFac Settlement Account to the Reserve Account. • Reserve Debit Transaction - You use this transaction type to move funds from the Reserve Account to the PayFac Settlement Account. • Sub-merchant Credit Transaction - You use this transaction type to move funds from the PayFac Settlement Account to the Sub-merchant Account, funding the Sub-merchant. • Sub-merchant Debit Transaction - You use this transaction type to move funds from the Sub-merchant Account to the PayFac Settlement Account. • Vendor Credit - You use this transaction type to move funds from the PayFac Settlement Account to the account of a third party involved in the sale transactions, but are not the sub-merchant. • Vendor Debit - You use this transaction type to move funds from the Vendor Account to the PayFac Settlement Account. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 2 TESTING YOUR CNPAPI TRANSACTIONS The information provided in this chapter enables you to test and verify that your submitted transaction data conforms to the required cnpAPI schema. This chapter contains the following topics: • Certification and Testing Environments • Overview of Testing • Transferring Files • Performing the Required Certification Tests • Performing the Optional Tests IMPORTANT: Per PCI DSS Requirements and Security Assessment Procedure, Section 6.4.3, "Production data (live PANs) are not used for testing or development." NOTE: This chapter does not include Certification tests for the PayFac Instruction-Based Dynamic Payout transaction types. Additional information about these transactions, as well as the Certification tests are in Appendix D, "PayFac™ Dynamic Payout". Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 87 cnpAPI Reference Guide Testing Your cnpAPI Transactions 2.1 Certification and Testing Environments Certification and Testing Environments Vantiv has several testing and certification platforms optimized for different uses. These environments are called: Sandbox, Pre-Live, and Post-Live. This section discusses the various environments, their uses, and limitations. The certification and testing environments do not have the full capacity, performance, or availability of the Vantiv Production platform. 2.1.1 Sandbox Environment The Sandbox environment is a simulator that provides a basic interface for functional level testing of transaction messages. Typically, merchants using one of the available Software Development Kits (SDKs) would use the Sandbox to test basic functionality, but it could also be used by any merchant using the cnpAPI. This is a stateless simulator, so it has no historical transactional data, and does not provide full functionality. This environment is not intended for certification or regression testing. NOTE: At his time, the Sandbox does not support Batch transactions (Online transactions only). Use of the Sandbox does not require a password. The environment is available on the public internet (at www.testvantivcnp.com/sandbox/communicator/online). Supporting documentation, including test case documentation, is available at vantiv-ecommerce.github.io/sandbox. 2.1.2 Pre-Live Environment The Pre-Live test environment is the platform used for all merchant Certification testing. Both newly on-boarding Vantiv merchants (for example, coding a direct XML integration for the first time), and existing Vantiv merchants seeking to incorporate additional features or functionalities into their current XML integrations should use this environment. While the Pre-Live system provides a working version of the Vantiv production system, it does not have the full capacity or performance of the production platform and operates using simulators rather than communicating with the card associations. The Pre-Live environment provides for the self-provisioning of a basic test account via www.testvantivcnp.com/sandbox. Using this account, you can submit most standard transaction types, including those specified in the Certification test sections provided later in this chapter. You will not be able to test many of the Vantiv eCommerce Value Added Services (VAS) using this basic account. To add the capability to perform test scenarios for the VAS services, please contact a Vantiv Implementation Consultant. They will adjust the configuration of your test account to enable the additional, desired features. 88 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Certification and Testing Environments 2.1.2.1 Testing Your cnpAPI Transactions Pre-Live Environment Limitations and Maintenance Schedules When using the Pre-Live environment for testing, please keep in mind the following limitations and maintenance schedules: • We limit the number of merchants configured per organization to the number necessary to perform the required certification testing. • Data retention is limited to a maximum of 30 days. NOTE: Depending upon overall system capacity and/or system maintenance requirements, data purges may occur frequently. Whenever possible, advanced notification will be provided. • Merchant profile and data deleted after 7 consecutive days with no activity. • Maintenance window - each Tuesday and Thursday from 4:00-8:00 AM ET. • Maintenance window (Enterprise eProtect) - every other Thursday from 10:00 PM to 6:00 AM ET. • Daily limit of 1000 Online transactions. • Daily limit of 10000 Batch transactions. NOTE: 2.1.3 Due to the planned maintenance windows, you should avoid using this environment for continuous regression testing. Post-Live Environment The Post-Live testing environment is intended for merchants that are already fully certified and submitting transactions to the Vantiv production platform, but wish to perform regression or other tests to confirm the operational readiness of modifications to their own systems. Upon completion of the initial certification and on-boarding process, Vantiv migrates merchants that are Production-enabled to the Post-Live environment for any on-going testing needs. In Post-Live, the merchant profile matches your profile from the Vantiv Production environment. Similar to Pre-Live, the Post-Live system provides a working version of the Vantiv production system, but it does not have the full capacity or performance of the production platform and operates using simulators rather than communicating with the card associations. Unlike the Pre-live platform, all Merchant accounts/IDs are synchronized with the Vantiv production environment. 2.1.3.1 Post-Live Environment Limitations and Maintenance Schedules When using the Post-Live environment for testing, please keep in mind the following limitations and maintenance schedules: Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 89 cnpAPI Reference Guide Testing Your cnpAPI Transactions Certification and Testing Environments • Daily limit of 1000 Online transactions. • Daily limit of 10000 Batch transactions. • Maintenance window - each Tuesday and Thursday from 4:00-8:00 AM ET. • Data retention limited to a maximum of 30 days. NOTE: Depending upon overall system capacity and/or system maintenance requirements, data purges may occur frequently. Whenever possible, Vantiv will provide advanced notification. Also, due to the planned maintenance windows, you should not use this environment for continuous regression testing. 90 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Overview of Testing 2.2 Testing Your cnpAPI Transactions Overview of Testing The purpose of the testing and certification process is to verify that your order entry and supporting systems construct and send XML messages that comply with the cnpAPI requirements. The testing process involves submitting Vantiv supplied data for specific fields in a request, and receiving specific data back in a response. The response returned by Vantiv allows you to verify that you parse the cnpAPI Response file correctly. Various tables in this chapter provide the data you use while testing, including card numbers, expiration dates, transaction amounts, and other values as required by the testing process. You use this data as input to your systems resulting in structured requests that conform to the required cnpAPI schema. IMPORTANT: The test data supplied does not necessarily account for all data fields/xml elements in a particular request. Where test data is not supplied, you should provide appropriate information. You should never override your own system to enter supplied data. If you are unable to enter the supplied data without overriding your system, please consult your Implementation Consultant concerning the test and how to proceed. Typically, Vantiv assigns an Implementation Consultant to work with you after the completion of contract negotiations. Before you begin the testing phase, your assigned Implementation Consultant establishes a test account and supplies you with instruction for accessing the account along with the username and password. You must supply the IP address from which the data originates so we can grant access. NOTE: Until you complete all required testing, you will only have access to the test and certification environment. The testing process involves the following steps: 2.2.1 Planning for Certification Testing Before you begin testing, determine which transaction types you will use according to your business needs. Virtually everyone will make use of the following basic transaction types: Authorization, Capture, Sale, Credit, and Void. There are several other transaction types and most transaction types offer many options/optional fields that you may wish to utilize and therefore test. For example, if you decide to offer eChecks as a alternate payment method, there are several associated certification tested required. Similarly, if you elect to make use of the Insights feature set, there are additional Authorization tests required for certification. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 91 cnpAPI Reference Guide Testing Your cnpAPI Transactions NOTE: Overview of Testing For information about certification testing for PayPal, eProtect, Chargeback API, and the PayFac API, please refer to the following documents: – Vantiv PayPal Integration Guide – Vantiv eProtect Integration Guide – Vantiv Chargeback API Reference Guide – Vantiv PayFac API Reference Guide 2.2.2 Required Certification Testing Certification testing is a required phase of implementing the cnpAPI format. During the certification testing, a Vantiv, LLC Implementation Consultant works with you to verify that your transaction submissions meet the requirements of the cnpAPI specifications. Each transaction type has specific test scenarios that use specific data sets simulating real transactions. The Vantiv Certification environment responds to each submission with an XML response message, allowing you to verify that you have coded correctly to parse and store the transaction data returned to you. For more detailed information, see Performing the Required Certification Tests on page 101. 2.2.3 Optional Testing Vantiv, LLC provides you with test data, test scenarios, a test environment, and credentials for using that test environment so you can perform these tests on your own keeping in mind the limitations of the certification environment (see Certification and Testing Environments on page 88). During unattended testing, you use these resources to perform all of the tests that apply to your business needs. NOTE: 2.2.4 If you have questions or need assistance while performing unattended testing, feel free to call your assigned Implementation Consultant or email implementation@vantiv.com. System Doctor The System Doctor is a tool you can use to both verify the operation of the Pre-Live environment and to verify operation and message structures of individual certification tests. Every 30 minutes the System Doctor runs each certification test specified in this chapter, except the Recycling and Recurring tests. You access the System Doctor through the Pre-Live iQ (Operations>System Doctor). 92 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Overview of Testing FIGURE 2-1 Testing Your cnpAPI Transactions System Doctor As shown in Figure 2-1, the system displays an overall assessment of the system status in the top panel and the results from each test set in the Test Execution History section (bottom panel). The center panel has a list of all individual tests by Order Id (pull-down), which you can filter by clicking on or more of the Search Tag buttons. Selecting one of the Order Ids from the list displays the XML request and response for that test (see Figure 2-2). You can also display the XML request and response information by selecting a test run from the Test Execution History and then selecting an individual test from the expanded list. NOTE: The search tags filter the Order Ids shown in the selection pull-down, but do so in an ORed manner. For example, if you select the Visa Filter and the Prepaid Filter, the pull-down displays Order Ids for tests that either use a Visa card OR a Prepaid card, rather than tests for a Prepaid Visa card. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 93 cnpAPI Reference Guide Testing Your cnpAPI Transactions FIGURE 2-2 Overview of Testing XML Request and Response Messages If one of your certification tests did not yield the expected results, you can use the System Doctor to determine if the test is performing as expected in the environment and if there is a discrepancy between your submitted XML and the XML message used in the automated test. If the test failed in the last automated run, you will know that there is a system issue and can contact your Implementation Consultant to determine when it will be resolved. If the test passed in the automated run, you can compare the automated XML message to your submission to determine why you are not receiving the expected results. 94 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transferring Files 2.3 Testing Your cnpAPI Transactions Transferring Files As discussed in Communications Protocols on page 2, there are several protocols you can use to submit your transactions to Vantiv for processing. This section provides additional information concerning the recommended methods for transferring your cnpAPI Batch and Online transaction files. 2.3.1 Transferring Session Files This section describes how to FTP your files (not test system specific) and includes the following topics: • Submitting a Session File for Processing • Retrieving Processed Session Files NOTE: 2.3.1.1 Before you begin transferring files via FTP, Vantiv provides the FTP Host and a username/password for the Vantiv test system. Submitting a Session File for Processing CAUTION: File naming conventions are crucial to the file submission process. Incorrect file names will prevent the file from being processed or may stop processing due to an incomplete file transfer. Do not append .asc to the end of the filename (Step 3). You must replace the .prg extension with .asc. If .prg appears in the filename, the system will not process the file 1. On your local system, add the extension .prg (lowercase) to the name of the file you want to submit. For example, you could name the file MerchantName_YYMMDD.prg. Keep in mind the following rules: • Spaces are not allowed in the file name • The .prg extension must be lower case 2. Open your FTP connection to the Vantiv inbound directory and move your file to the Vantiv directory. 3. After the FTP process completes, change the extension of the transmitted file (in the Vantiv inbound directory) from .prg to .asc (lowercase). The system polls the directory for files with an .asc extension every thirty seconds. When the system encounters files with the proper extension, it retrieves them for processing. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 95 cnpAPI Reference Guide Testing Your cnpAPI Transactions 2.3.1.2 Transferring Files Retrieving Processed Session Files Depending on the size of your file, your response should be ready within a few minutes. Batches containing large number of transactions take longer. For example, a batch of 10,000 transactions may require as long as ten minutes to process. The initial response represents an acknowledgment that we received the transactions and notification that we will deliver them upstream to Visa and/or MasterCard for review. Since we perform validation operations against the credit card number and the expiration date, you may also receive a decline responses containing the appropriate response code. To retrieve response files from the outbound directory: NOTE: Vantiv removes response files from the outbound directory after 24 hours. Plan to retrieve your files daily. 1. Open your FTP connection to the Vantiv outbound directory. 2. Locate the response file, which will have the same name as the file you submitted. If the response file has a .prg extension, it is still transferring. The extension changes to .asc when the transfer to the outbound directory completes. 3. Retrieve the response file. 2.3.2 Transferring Online Files The recommended method for submitting Online transactions is via HTTPS POST. The sections that follow provide examples of ASP and Java programming methods for submitting your data using HTTPS POST. • ASP Programming Example • Java Programming Example • Helpful Web Sites NOTE: 96 Before you begin testing, Vantiv provides the test system URL, a username/password, and any additional information required to test your XML transactions. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transferring Files 2.3.2.1 Testing Your cnpAPI Transactions ASP Programming Example The following code is an example of a cnpAPI Authorization transaction submitted via HTTPS Post using ASP. Dim xml Dim strXML strXML = strXML & " " strXML = strXML & " " set xml = CreateObject("Microsoft.XMLHTTP") xml.setRequestHeader "Content-type", "text/html; charset=UTF-8" xml.Open "POST", "https://site.info.com/from_Vantiv", False xml.Send strXML Response.write (xml.responseText) set xml = Nothing 2.3.2.2 Java Programming Example The following is an example of Java code used for HTTPS Post. PostMethod and HttpClient are both part of the Apache HttpClient library located at http://jakarta.apache.org/commons/httpclient/. PostMethod post = new PostMethod(url); // url = fully qualified url of the server to which you are posting post.setRequestHeader("Content-type", "text/html; charset=UTF-8"); post.setRequestBody(data); //data = request data in XML format HttpClient client = new HttpClient(); client.setTimeout(10000); //10 second timeout (in milliseconds) is suggested minimum, 30 second recommended for alternate payment methods client.executeMethod(post); String response = post.getResponseBodyAsString(); //if the server throws an exception you get a null response //to get around this set it to "" if (response == null) { response = ""; } post.releaseConnection(); 98 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transferring Files 2.3.2.3 Testing Your cnpAPI Transactions Notes on Timeout Settings While Vantiv optimizes our systems to ensure the return of Authorization responses as quickly as possible, some portions of the process are beyond our control. The round-trip time of an Authorization can be broken down into three parts, as follows: 1. Transmission time (across the internet) to Vantiv and back to the merchant 2. Processing time by the card association or authorization provider 3. Processing time Vantiv Under normal operating circumstances, the transmission time to and from Vantiv does not exceed 0.6 seconds and processing time by Vantiv occurs in 0.1 seconds. Typically, the processing time by the card association or authorization provider can take between 0.5 and 3 seconds, but some percentage of transactions may take significantly longer. Because the total processing time can vary due to a number of factors, Vantiv recommends using a timeout setting of 10 seconds minimum for card transactions and 30 seconds minimum for alternate payment methods. These settings should ensure that you do not frequently disconnect prior to receiving a valid authorization causing dropped orders and/or re-auths and duplicate auths. NOTE: While it is uncommon, under certain circumstances network latency may cause a duplicate Online Sale transaction to go undetected as a duplicate. This can occur if you submit a second, duplicate Sale transaction while the response from the network for the Authorization portion of the first transaction is sufficiently delayed such that the first Sale has not been recorded as a valid transaction in the system. If you elect to submit Online Sale transactions, Vantiv recommends a timeout setting of not less than 60 seconds to reduce the chances of undetected duplicate Sale transactions. 2.3.2.4 Notes on Persistent Connections In order to provide a highly scalable service that meets the needs of high-throughput merchants, while reducing the number of idle connections that could result in some merchants exceeding their connection limits, Vantiv systems allow for 10 seconds of idle time before closing a connection. We selected this value because it is the midpoint between the Apache httpd 2.0 default value of 15 seconds and the Apache 2.2 default value of 5 seconds. Also, HTTP/1.1, which most modern HTTP client libraries use, employ persistent connections by default. When using a persistent connection, please keep the 10 second idle time limit in mind, when coding. If you do not use persistent connections, to avoid connection limit issues, please validate that your default configuration closes connections after each request. NOTE: Proper use of persistent connections is considerably faster than opening and closing connections with each request. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 99 cnpAPI Reference Guide Testing Your cnpAPI Transactions 2.3.2.5 Transferring Files Helpful Web Sites The following web sites provide additional information, helpful hints, and examples of different programming methods used in combination with HTTPS POST. 100 • http://p2p.wrox.com • http://en.allexperts.com/q/Active-Server-Pages-1452/XML-ASP-Parser-2.htm • http://www.java-samples.com/java/POST-toHTTPS-url-free-java-sample-program.htm Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Performing the Required Certification Tests 2.4 Testing Your cnpAPI Transactions Performing the Required Certification Tests You are required to complete a number of certification tests prior to submitting real transactions to the Vantiv production system. This testing process allows you to verify that your system not only submits correctly formatted transaction data, but also correctly parses the data returned to you in the response messages. To facilitate the certification process, Vantiv has established a certification environment that simulates the production environment. During certification testing, a Vantiv, LLC Implementation Consultant will guide you through each required test scenario. For each transaction type specific data is supplied that you must use in your cnpAPI transactions. Use of this data allows the validation of your transaction structure/syntax, as well as the return of a response file containing known data. IMPORTANT: The test data supplied does not account for all data fields/xml elements in a particular request. Where data is not supplied, you should provide appropriate information. You should never override your own system to enter supplied data. If you are unable to enter the supplied data without overriding your system, please consult your Implementation Consultant concerning the test and how to proceed. Never use the supplied test data in the production environment. 2.4.1 Testing Authorization (including Indicators), AVS Only, Capture, Credit, Sale, and Void Transactions Table 2-1 provides 26 data sets you use to test your construction of Authorization, AVS Only, Sale and Force Capture transactions, as well as your ability to parse the information contained in the XML response messages. You also use some of the approved authorizations as the basis for testing Capture and Credit transactions. You do not necessarily have to perform all Authorization test. The tests you perform depend upon the Vantiv features you have elected to use. The tests are divided as follows: • Order Ids 1 through 9 - used to test standard Authorization requests and responses. Also used for AVS Only test and Sale test. (Capture test use the litleTxnId returned in the response messages.) • Order Ids 10 through 13 - include if you plan to use Partial Authorization • Order Ids 14 and 20 - include if you plan to use the Prepaid Indicator feature (see Prepaid Indicator on page 24) • Order Ids 21 through 24 - include if you plan to use the Affluence Indicator feature (see Affluence Indicator on page 25) • Order Id 25 - include if you plan to use the Issuer Country feature (see Issuer Country Indicator on page 26) Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 101 cnpAPI Reference Guide Testing Your cnpAPI Transactions • Performing the Required Certification Tests Order Ids 26 through 31 - include if you plan to use the Healthcare Card feature (see eCommerce Solution for Apple Pay™ on page 61) To test Authorization transactions: 1. Verify that your Authorization XML template is coded correctly (refer to Authorization Transactions on page 206.) 2. Submit authorization transactions using the data shown in the Supplied Data Elements of Order Ids 1 through 9 of Table 2-1. 3. Verify that your response values match those shown in Key Response Elements for Order Ids 1 through 9 as shown in Table 2-1. 4. If you wish to test AVS only transactions, re-submit Order Ids 1 through 5, 7, 8, and 9 (skip order 6), but substitute 000 for the amount. The AVS result returned will be the value shown in the Key Response Elements section. 5. If you plan to use Partial Authorizations, submit authorization transactions using the data shown in the Supplied Data Elements of Order Ids 10 through 13 of Table 2-1. 6. Verify that your response values match those shown in Key Response Elements for Order Ids 10 through 13 as shown in Table 2-1. 7. If you elected to receive Prepaid Indicators, submit authorization transactions using the data shown in the Supplied Data Elements of Order Ids 14 through 20 of Table 2-1. Verify that your response values match those shown in Key Response Elements for Order Ids 14 and 15 as shown in Table 2-1. 8. If you elected to receive Affluence Indicators, submit authorization transactions using the data shown in the Supplied Data Elements of Order Ids 21through 24 of Table 2-1. Verify that your response values match those shown in Key Response Elements for Order Ids 16 through 19 as shown in Table 2-1. 9. If you elected to receive Issuer Country information, submit an authorization transaction using the data shown in the Supplied Data Elements of Order Id 25 of Table 2-1. Verify that your response values match those shown in Key Response Elements for Order Id 25 as shown in Table 2-1. NOTE: 102 Some Issuers do not return an Auth Code for $0 Authorizations. You should code your systems to handle this possibility. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Performing the Required Certification Tests Testing Your cnpAPI Transactions To Test Sale transactions: 1. Verify that your Sale XML template is coded correctly (refer to Sale Transactions on page 299.) 2. Submit sale transactions using the data shown in the Supplied Data Elements of Order Ids 1 through 9 of Table 2-1. 3. Verify that your response values match those shown in Key Response Elements for Order Ids 1 through 9 as shown in Table 2-1. To Test Capture transactions: 1. Verify that your Capture XML template is coded correctly (refer to Capture Transactions on page 229.). 2. Submit capture transactions for Order Ids 1A through 5A using the litleTnxId value returned in the response messages for Authorization Order Ids 1 through 5. 3. Verify that your response values match those shown in Key Response Elements for Order Ids 1A through 5A as shown in Table 2-1. To test Credit transactions: 1. Verify that your Credit XML template is coded correctly (refer to Credit Transactions on page 245.) 2. Submit credit transactions for Order Ids 1B through 5B using the litleTnxId value returned in the response messages for Capture Order Ids 1A through 5A. 3. Verify that your response values match those shown in Key Response Elements for Order Ids 1B through 5B as shown in Table 2-1. To test Void transactions (in this test you have the option of voiding either Credit or Sale transactions): 1. Verify that your Void XML template is coded correctly (refer to Void Transactions (Online Only) on page 319.) 2. Submit void transactions for Order Ids 1C through 5C (and 6Bif voiding Sale transactions) using the litleTnxId value returned in either the response messages for Credit Order Ids 1B through 5B, or the response messages for Sale (not Auth) Order Id 1 through 6. 3. Verify that your response values match those shown in Key Response Elements for Order Ids 1C through 5C (include 6B only if you elect to void the Sales transactions) as shown in Table 2-1. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 103 cnpAPI Reference Guide Testing Your cnpAPI Transactions TABLE 2-1 Performing the Required Certification Tests Authorization Test Data Supplied Data Elements orderId 1 Element Key Response Elements Value Authorization/Sale/AVS: Element Authorization Response:" strXML = strXML & " " strXML = strXML & "USERNAME " strXML = strXML & "######## " strXML = strXML & "" strXML = strXML & " " strXML = strXML & "3235059 " strXML = strXML & "54399 " strXML = strXML & "ecommerce " strXML = strXML & "" strXML = strXML & " " strXML = strXML & "Todd Wilson " strXML = strXML & "123 Blue Street " strXML = strXML & "Suite 108 " strXML = strXML & "Address Line 3 " strXML = strXML & "Lowell " strXML = strXML & "MA " strXML = strXML & "01851 " strXML = strXML & "USA " strXML = strXML & "twilson@email.com " strXML = strXML & "323-222-2222 " strXML = strXML & "" strXML = strXML & " " Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 97 cnpAPI Reference Guide Testing Your cnpAPI Transactions Transferring Files strXML = strXML & "VI " strXML = strXML & "############# " strXML = strXML & "0521 " strXML = strXML & "### " strXML = strXML & "000 10100 Approved John & Mary Smith 11111 1 Main St. 01 Burlington MA Value M 01803-3747 US VI 4457010000000009 0121 349 1A Capture Response: Capture: 000 Value returned in Auth response for Order Id 1 1B Approved Credit Response: Credit: 000 Value returned in Capture response for Order Id 1A 1C Approved Void Response: Void: 000 Use either the value returned in the Credit response for Order Id 1B, or the value returned in the Sale response (not Auth) for Order Id 1. 104 Approved Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Performing the Required Certification Tests TABLE 2-1 Testing Your cnpAPI Transactions Authorization Test Data (Continued) Supplied Data Elements orderId 2 Element Key Response Elements Value Authorization/Sale/AVS: Element Authorization Response: 10100 000 Mike J. Hammer Approved 2 Main St. 22222 Apt. 222 10 Riverside RI 02915 Value M Note: Not returned for MasterCard US MC 5112010000000003 0221 261 BwABBJQ1AgAAA AAgJDUCAAAAAA A= 2A Capture Response: Capture: 000 Value returned in Auth response for Order Id 2 2B Approved Credit Response: Credit: 000 Value returned in Capture response for Order Id 2A 2C Approved Void Response: Void: Use either the value returned in the Credit response for Order Id 2B, or the value returned in the Sale response (not Auth) for Order Id 2. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 000 Approved 105 cnpAPI Reference Guide Testing Your cnpAPI Transactions TABLE 2-1 Performing the Required Certification Tests Authorization Test Data (Continued) Supplied Data Elements orderId 3 Element Key Response Elements Value Authorization/Sale/AVS: Element Authorization Response: 000 10100 Approved Eileen Jones 33333 3 Main St. 10 Bloomfield CT Value M 06002 US DI 6011010000000003 0321 758 3A Capture Response: Capture: 000 Value returned in Auth response for Order Id 3 3B Approved Credit Response: Credit: 000 Value returned in Capture response for Order Id 3A 3C Approved Void Response: Void: 000 Use either the value returned in the Credit response for Order Id 3B, or the value returned in the Sale response (not Auth) for Order Id 3. 106 Approved Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Performing the Required Certification Tests TABLE 2-1 Testing Your cnpAPI Transactions Authorization Test Data (Continued) Supplied Data Elements orderId 4 Element Key Response Elements Value Authorization/Sale/AVS: Element Value Authorization Response: 000 10100 Approved Bob Black 44444 4 Main St. 13 Laurel MD 20708 US AX 375001000000005 0421 4A Capture Response: Capture: 000 Value returned in Auth response for Order Id 4 4B Approved Credit Response: Credit: 000 Value returned in Capture response for Order Id 4A 4C Approved Void Response: Void: Use either the value returned in the Credit response for Order Id 4B, or the value returned in the Sale response (not Auth) for Order Id 4. Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 000 Approved 107 cnpAPI Reference Guide Testing Your cnpAPI Transactions TABLE 2-1 Performing the Required Certification Tests Authorization Test Data (Continued) Supplied Data Elements orderId 5 Element Key Response Elements Value Authorization/Sale/AVS: Element Authorization Response: 10100 000 VI Approved 4100200300011001 55555 32 0521 463 Value M BwABBJQ1AgAAA AAgJDUCAAAAAA A= 5A Capture Response: Capture: 000 Value returned in Auth response for Order Id 5 5B Approved Credit Response: Credit: 000 Value returned in Capture response for Order Id 5A 5C Approved Void Response: Void: 000 Use either the value returned in the Credit response for Order Id 5B, or the value returned in the Sale response (not Auth) for Order Id 5. 108 Approved Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Performing the Required Certification Tests TABLE 2-1 Testing Your cnpAPI Transactions Authorization Test Data (Continued) Supplied Data Elements orderId 6 Element Key Response Elements Value Element Value Authorization Response: Authorization/Sale: 110 10100 Insufficient Funds Joe Green 34 6 Main St. Derry P NH 03038 US VI 4457010100000008 0621 992 6A Void Response: Void: 360 Use the value returned in the Sale response (not Auth) for Order Id 6. 7 Authorization/Sale/AVS: No transaction found with specified litleTxnId Authorization Response: 301 10100 Invalid Account Number Jane Murray 7 Main St. 34 Amesbury MA N 01913 US MC 5112010100000002 0721 251 Document Version: 1.32 — XML Release: 9.14 © 2018 Vantiv, LLC - All Rights Reserved. 109 cnpAPI Reference Guide Testing Your cnpAPI Transactions TABLE 2-1 Performing the Required Certification Tests Authorization Test Data (Continued) Supplied Data Elements orderId 8 Element Key Response Elements Value Authorization/Sale/AVS: Element Authorization Response: 123 10100 Call Discover Mark Johnson 34 8 Main St. Manchester Value P NH 03101 US DI 6011010100000002 0821 184 9 Authorization/Sale/AVS: Authorization Response: 303 10100 Pick Up Card