Vantiv CnpAPI Reference Guide Cnp API API11.3 V1.8
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 944
| Download | |
| Open PDF In Browser | View PDF |
cnpAPI Reference Guide November 2017 cnpAPI Release: 11.3 Document Version: 1.8 Vantiv cnpAPI Reference Guide Document Version: 1.8 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-2017, Vantiv, LLC - ALL RIGHTS RESERVED. CONTENTS About This Guide Intended Audience ........................................................................................................ xxiii Revision History ............................................................................................................ xxiii Document Structure ...................................................................................................... xxvi Documentation Set ....................................................................................................... xxvi Typographical Conventions .........................................................................................xxviii Contact Information....................................................................................................... xxix Chapter 1 Introduction The cnpAPI Data Format .................................................................................................. 2 Communications Protocols ......................................................................................... 2 General XML Coding Requirements ........................................................................... 3 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 Batch Dupe Checking for Dynamic Payout Funding Instructions.......................... 8 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 ...................................................................................... 16 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. iii cnpAPI Reference Guide Contents Prepaid Indicator ................................................................................................. 24 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 ...................................................................................................... 40 How Tokenization Works .......................................................................................... 41 Token Formats .......................................................................................................... 42 Obtaining Tokens ...................................................................................................... 42 Bulk Token Registration ...................................................................................... 43 Supported Token Transactions ................................................................................. 44 Compliance with Visa Best Practices for Tokenization ............................................. 45 eCheck Processing ......................................................................................................... 46 Validation Feature ..................................................................................................... 46 Verification Feature ................................................................................................... 46 Required Contents of Decline Notice .................................................................. 47 Automatic Notice of Change (NoC) Updates ............................................................ 48 Auto Redeposit Feature ............................................................................................ 48 eCheck Prenotification .............................................................................................. 49 SEPA Direct Debit .......................................................................................................... 51 iv Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents SEPA Direct Debit - Vantiv Supplied Mandate.......................................................... 51 SEPA Direct Debit - Merchant Supplied Mandate..................................................... 54 iDEAL, SOFORT, and Giropay ....................................................................................... 57 eCommerce Solution for Apple Pay™ ............................................................................ 60 Overview of Apple Pay Operation ............................................................................. 60 Vantiv Decryption of Apple Pay PKPaymentToken................................................... 61 Using the Browser JavaScript API for Apple Pay on the Web ............................ 61 Using the Vantiv Mobile API for Apple Pay ......................................................... 63 Submitting the Apple Pay PKPaymentToken in a cnpAPI Message ................... 64 Merchant Decryption of Apple Pay PKPaymentToken........................................ 65 Recurring Payments with Apple Pay......................................................................... 67 eCommerce Solution for Android Pay™ ......................................................................... 68 Android Pay using eProtect....................................................................................... 68 Merchant Decryption Method .................................................................................... 71 Recurring Payments with Android Pay...................................................................... 74 Supported Transaction Types ......................................................................................... 75 Authorization Transaction ......................................................................................... 75 AVS Only Transaction ......................................................................................... 76 Authorization Reversal Transactions ........................................................................ 76 Notes on the Use of Authorization Reversal Transactions.................................. 77 Using Authorization Reversal to Halt Recycling Engine...................................... 78 Activate Transaction.................................................................................................. 78 Activate Reversal Transaction (Online Only) ............................................................ 79 Balance Inquiry Transaction...................................................................................... 79 Cancel Subscription Transaction .............................................................................. 79 Capture Transaction.................................................................................................. 79 Capture Given Auth Transaction............................................................................... 79 Create Plan Transaction ........................................................................................... 80 Credit Transaction..................................................................................................... 80 Deactivate Transaction ............................................................................................. 81 Deactivate Reversal Transaction (Online Only) ........................................................ 81 Deposit Reversal Transaction (Online Only)............................................................. 81 eCheck Credit Transaction........................................................................................ 81 eCheck Prenotification Credit Transaction................................................................ 81 eCheck Prenotification Sale Transaction .................................................................. 82 eCheck Redeposit Transaction ................................................................................. 82 eCheck Sales Transaction ........................................................................................ 82 eCheck Verification Transaction ............................................................................... 82 eCheck Void Transaction (Online Only).................................................................... 82 Force Capture Transaction ....................................................................................... 83 Gift Card Auth Reversal ............................................................................................ 83 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. v cnpAPI Reference Guide Contents Gift Card Capture ...................................................................................................... 83 Gift Card Credit ......................................................................................................... 83 Load Transaction ...................................................................................................... 83 Load Reversal Transaction (Online Only) ................................................................. 83 Refund Reversal Transaction (Online Only) ............................................................. 84 Register Token Transaction ...................................................................................... 84 Sale Transaction ....................................................................................................... 84 Status Query Transaction ........................................................................................ 84 Unload Transaction ................................................................................................... 85 Unload Reversal Transaction (Online Only).............................................................. 85 Update Card Validation Number Transaction ........................................................... 85 Update Plan Transaction........................................................................................... 85 Update Subscription Transaction .............................................................................. 85 Void Transaction (Online Only) ................................................................................. 86 Using Void to Halt Recycling Engine................................................................... 86 Instruction-Based Dynamic Payout Transactions .................................................... 86 Chapter 2 Testing Your cnpAPI Transactions Certification and Testing Environments .......................................................................... 90 Sandbox Environment............................................................................................... 90 Pre-Live Environment................................................................................................ 90 Pre-Live Environment Limitations and Maintenance Schedules ......................... 91 Post-Live Environment .............................................................................................. 91 Post-Live Environment Limitations and Maintenance Schedules ....................... 91 Overview of Testing ........................................................................................................ 93 Planning for Certification Testing .............................................................................. 93 Required Certification Testing................................................................................... 94 Optional Testing ........................................................................................................ 94 System Doctor........................................................................................................... 94 Transferring Files ............................................................................................................ 97 Transferring Session Files ........................................................................................ 97 Submitting a Session File for Processing............................................................ 97 Retrieving Processed Session Files.................................................................... 98 Transferring Online Files........................................................................................... 98 ASP Programming Example ............................................................................... 99 Java Programming Example ............................................................................. 100 Notes on Timeout Settings ................................................................................ 101 Notes on Persistent Connections ...................................................................... 101 Helpful Web Sites.............................................................................................. 102 Performing the Required Certification Tests ................................................................. 103 vi Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents Testing Authorization (including Indicators), AVS Only, Capture, Credit, Sale, and Void Transactions............................................................................................................ 103 Testing Authorization Reversal Transactions.......................................................... 116 Testing eCheck Transactions.................................................................................. 119 Testing Token Transactions.................................................................................... 126 Testing Query Transactions .................................................................................... 131 Testing Online Duplicate Transaction Processing .................................................. 132 Performing the Optional Tests ...................................................................................... 134 Testing AVS and Card Validation............................................................................ 135 Testing Address Responses ................................................................................... 136 Testing Advanced AVS Response Codes............................................................... 138 Testing Response Reason Codes and Messages .................................................. 139 Testing 3DS Responses ......................................................................................... 142 Testing the Prepaid Filtering Feature...................................................................... 144 Testing the International Card Filter Feature .......................................................... 146 Testing Security Code No-Match Filtering .............................................................. 147 Testing Advanced Fraud Tools ............................................................................... 149 Testing Account Updater......................................................................................... 151 Testing Account Updater Extended Response Codes ...................................... 152 Testing Account Updater for Tokenized Merchants .......................................... 153 Testing Tax Billing................................................................................................... 153 Testing Convenience Fees ..................................................................................... 154 Testing the Recycling Engine.................................................................................. 156 Testing Recycling Engine Cancellation ............................................................. 164 Testing Recurring Engine Transactions .................................................................. 166 Testing Gift Card Transactions ............................................................................... 179 Testing MasterPass Transactions........................................................................... 189 Testing Apple Pay Transaction Processing ............................................................ 189 Testing the Submission of the Decrypted PKPaymentToken in cnpAPI ........... 190 Testing the Submission of PKPaymentToken in cnpAPI .................................. 190 Testing Android Pay Transaction Processing ......................................................... 192 Testing Android Pay using eProtect .................................................................. 192 Testing checkoutId .................................................................................................. 193 Testing SEPA Direct Debit Transaction .................................................................. 195 Testing iDEAL Transactions.................................................................................... 197 Testing Giropay Transactions ................................................................................. 198 Testing SOFORT Transactions............................................................................... 199 Testing Transaction Volume Capacity .................................................................... 200 Chapter 3 cnpAPI Transaction Examples Overview of Online and Batch Processing Formats ..................................................... 202 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. vii cnpAPI Reference Guide Contents Batch Process Format............................................................................................. 202 Supported Communication Protocols................................................................ 203 Batch Processing Request Format ................................................................... 203 Batch Processing Response Format................................................................. 203 Online Processing Format ............................................................................................ 204 Supported Communication Protocols...................................................................... 205 Online Processing Request Format ........................................................................ 205 Online Processing Response Format ..................................................................... 205 Transaction Types and Examples................................................................................. 206 Authorization Transactions...................................................................................... 208 Authorization Request Structure ....................................................................... 208 Authorization Response Structure .................................................................... 215 Authorization Reversal Transactions ...................................................................... 220 Authorization Reversal Requests ...................................................................... 220 Authorization Reversal Responses ................................................................... 222 Activate Transactions.............................................................................................. 223 Activate Request ............................................................................................... 223 Activate Response ............................................................................................ 224 Activate Reversal Transactions (Online Only) ........................................................ 226 Activate Reversal Request ................................................................................ 226 Activate Reversal Response ............................................................................. 227 Balance Inquiry Transactions.................................................................................. 228 Balance Inquiry Request ................................................................................... 228 Balance Inquiry Response ................................................................................ 229 Cancel Subscription Transactions........................................................................... 230 Cancel Subscription Request............................................................................ 230 Cancel Subscription Response ......................................................................... 231 Capture Transactions.............................................................................................. 231 Capture Request ............................................................................................... 232 Capture Response ............................................................................................ 239 Capture Given Auth Transactions ........................................................................... 240 Capture Given Auth Request ............................................................................ 240 Capture Given Auth Response ......................................................................... 244 Create Plan Transactions........................................................................................ 246 Create Plan Request......................................................................................... 246 Create Plan Response ...................................................................................... 247 Credit Transactions ................................................................................................. 247 Credit Request for a Vantiv Processed Transaction ......................................... 248 Credit Request for a Non-Vantiv Processed Transaction ................................. 252 Credit Response ............................................................................................... 256 Deactivate Transactions.......................................................................................... 257 viii Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents Deactivate Request........................................................................................... 257 Deactivate Response ........................................................................................ 258 Deactivate Reversal Transactions (Online Only) .................................................... 259 Deactivate Reversal Request............................................................................ 259 Deactivate Reversal Response......................................................................... 260 Deposit Reversal Transactions (Online Only) ......................................................... 261 Deposit Reversal Request ................................................................................ 261 Deposit Reversal Response.............................................................................. 262 eCheck Credit Transactions.................................................................................... 263 eCheck Credit Request Against a Vantiv Transaction ...................................... 263 eCheck Credit Request for a Non-Vantiv Processed Sale ................................ 265 eCheck Credit Response .................................................................................. 266 eCheck Prenotification Credit Transactions (Batch Only) ....................................... 266 eCheck Prenotification Credit Request ............................................................. 267 eCheck Prenotification Credit Response .......................................................... 268 eCheck Prenotification Sale Transactions (Batch Only) ......................................... 269 eCheck Prenotification Sale Request................................................................ 269 eCheck Prenotification Sale Response ............................................................. 270 eCheck Redeposit Transactions ............................................................................. 271 eCheck Redeposit Request .............................................................................. 271 eCheck Redeposit Response............................................................................ 273 eCheck Sale Transactions ...................................................................................... 274 eCheck Sale Request ....................................................................................... 274 eCheck Sale Response..................................................................................... 276 eCheck Verification Transactions............................................................................ 277 eCheck Verification Request ............................................................................. 278 eCheck Verification Response .......................................................................... 280 eCheck Void Transactions (Online Only) ................................................................ 281 eCheck Void Request ....................................................................................... 281 eCheck Void Response..................................................................................... 282 Force Capture Transactions.................................................................................... 283 Force Capture Request..................................................................................... 283 Force Capture Response .................................................................................. 286 Fraud Check Transaction........................................................................................ 288 Fraud Check Request ....................................................................................... 288 Fraud Check Response .................................................................................... 289 Gift Card Auth Reversal Transactions..................................................................... 290 Gift Card Auth Reversal Request ...................................................................... 290 Gift Card Auth Reversal Response ................................................................... 291 Gift Card Capture Transactions .............................................................................. 292 Gift Card Capture Request................................................................................ 292 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. ix cnpAPI Reference Guide Contents Gift Card Capture Response ............................................................................. 293 Gift Card Credit Transactions.................................................................................. 294 Gift Card Credit Request................................................................................... 294 Gift Card Credit Response ................................................................................ 295 Load Transactions................................................................................................... 296 Load Request.................................................................................................... 296 Load Response ................................................................................................. 297 Load Reversal Transactions (Online Only) ............................................................. 298 Load Reversal Request..................................................................................... 298 Load Reversal Response.................................................................................. 299 Status Query Transactions (Online Only) .............................................................. 300 Query Transaction Request .............................................................................. 301 Query Transaction Response ........................................................................... 301 Refund Reversal Transactions (Online Only).......................................................... 304 Refund Reversal Request ................................................................................. 305 Refund Reversal Response .............................................................................. 306 Register Token Transactions .................................................................................. 307 Register Token Request ................................................................................... 307 Register Token Response................................................................................. 310 RFR Transactions (Batch Only) .............................................................................. 312 RFR Request .................................................................................................... 312 RFR Response.................................................................................................. 313 Sale Transactions ................................................................................................... 314 Sale Request..................................................................................................... 314 Sale Response.................................................................................................. 319 Unload Transactions ............................................................................................... 325 Unload Request ................................................................................................ 325 Unload Response.............................................................................................. 326 Unload Reversal Transactions (Online Only).......................................................... 326 Unload Reversal Request ................................................................................. 327 Unload Reversal Response .............................................................................. 328 Update Plan Transactions....................................................................................... 329 Update Plan Request ........................................................................................ 329 Update Plan Response ..................................................................................... 329 Update Subscription Transactions .......................................................................... 330 Update Subscription Request ........................................................................... 330 Update Subscription Response......................................................................... 332 Update Card Validation Number Transactions........................................................ 332 Update Card Validation Number Request ......................................................... 333 Update Card Validation Number Response ...................................................... 333 Void Transactions (Online Only) ............................................................................. 334 x Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents Void Request..................................................................................................... 335 Void Response.................................................................................................. 335 Chapter 4 cnpAPI Elements accNum ........................................................................................................................ 338 accountInfo .................................................................................................................. 339 accountInformation ...................................................................................................... 340 accountNumber ............................................................................................................ 341 accountNumberLength ................................................................................................. 342 accountUpdate ............................................................................................................. 343 accountUpdateFileRequestData .................................................................................. 344 accountUpdater ............................................................................................................ 345 accountUpdateResponse ............................................................................................. 349 accType ........................................................................................................................ 350 actionReason ............................................................................................................... 351 activate ......................................................................................................................... 352 activateResponse ........................................................................................................ 353 activateReversal .......................................................................................................... 354 activateReversalResponse .......................................................................................... 355 active ............................................................................................................................ 356 addOnCode .................................................................................................................. 357 addressIndicator ........................................................................................................... 358 addressLine1, addressLine2, addressLine3 ................................................................. 359 advancedAVSResult ..................................................................................................... 360 advancedFraudChecks ................................................................................................ 361 advancedFraudResults ................................................................................................ 362 affiliate........................................................................................................................... 363 affluence ....................................................................................................................... 364 allowPartialAuth ............................................................................................................ 365 amexAggregatorData.................................................................................................... 366 amount .......................................................................................................................... 367 androidpayResponse ................................................................................................... 369 applepay ....................................................................................................................... 370 applepayResponse ....................................................................................................... 371 applicationData ............................................................................................................. 372 applicationExpirationDate ............................................................................................. 373 applicationPrimaryAccountNumber............................................................................... 374 approvedAmount........................................................................................................... 375 authAmount................................................................................................................... 376 authCode ...................................................................................................................... 377 authDate ....................................................................................................................... 378 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xi cnpAPI Reference Guide Contents authenticatedByMerchant ............................................................................................. 379 authentication................................................................................................................ 380 authenticationResult ..................................................................................................... 381 authenticationTransactionId.......................................................................................... 382 authenticationValue ...................................................................................................... 383 authInformation ............................................................................................................. 384 authorization ................................................................................................................. 385 authorizationResponse ................................................................................................. 386 authorizationSourcePlatform......................................................................................... 387 authReversal................................................................................................................. 388 authReversalResponse................................................................................................. 389 availableBalance........................................................................................................... 390 avsResult ...................................................................................................................... 391 balanceInquiry .............................................................................................................. 392 balanceInquiryResponse ............................................................................................. 393 batchRequest................................................................................................................ 394 batchResponse ............................................................................................................. 402 beginningBalance ........................................................................................................ 403 billingDate .................................................................................................................... 404 billMeLaterRequest ....................................................................................................... 405 billMeLaterResponseData............................................................................................. 407 billToAddress ................................................................................................................ 408 bin ................................................................................................................................. 410 bmlMerchantId .............................................................................................................. 411 bmlProductType............................................................................................................ 412 bypassVelocityCheck .................................................................................................... 413 campaign ...................................................................................................................... 414 cancelSubscription ....................................................................................................... 415 cancelSubscriptionResponse ....................................................................................... 416 capability ....................................................................................................................... 417 capture .......................................................................................................................... 418 captureAmount.............................................................................................................. 419 captureGivenAuth ......................................................................................................... 420 captureGivenAuthResponse ......................................................................................... 421 captureResponse.......................................................................................................... 422 card ............................................................................................................................... 423 cardAcceptorTaxId........................................................................................................ 425 cardholderAuthentication .............................................................................................. 426 cardholderId .................................................................................................................. 427 cardholderName ........................................................................................................... 428 cardOrToken ................................................................................................................. 429 xii Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents cardProductType........................................................................................................... 430 cardSuffix ..................................................................................................................... 431 cardValidationNum........................................................................................................ 432 cardValidationResult ..................................................................................................... 433 cashBackAmount ......................................................................................................... 434 catLevel ........................................................................................................................ 435 ccdPaymentInformation ............................................................................................... 436 chargeback ................................................................................................................... 437 checkNum .................................................................................................................... 438 checkoutId .................................................................................................................... 439 city................................................................................................................................. 440 clinicOtherAmount......................................................................................................... 441 code .............................................................................................................................. 442 commodityCode ............................................................................................................ 443 companyName.............................................................................................................. 444 country .......................................................................................................................... 445 createAddOn ................................................................................................................ 446 createDiscount ............................................................................................................. 447 createPlan .................................................................................................................... 448 createPlanResponse .................................................................................................... 449 credit ............................................................................................................................. 450 creditAmount................................................................................................................. 451 creditLine ...................................................................................................................... 452 creditLitleTxnId ............................................................................................................. 453 creditResponse ............................................................................................................. 454 cryptogram ................................................................................................................... 455 currencyCode ............................................................................................................... 456 customAttribute1 .......................................................................................................... 457 customBilling................................................................................................................. 458 customIdentifier ............................................................................................................ 460 customerInfo ................................................................................................................. 461 customerIpAddress ....................................................................................................... 462 customerReference....................................................................................................... 463 customerRegistrationDate ............................................................................................ 464 customerType ............................................................................................................... 465 customerWorkTelephone.............................................................................................. 466 data ............................................................................................................................... 467 deactivate ..................................................................................................................... 468 deactivateResponse .................................................................................................... 469 deactivateReversal ...................................................................................................... 470 deactivateReversalResponse ...................................................................................... 471 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xiii cnpAPI Reference Guide Contents debtRepayment............................................................................................................. 472 deleteAddOn ................................................................................................................ 473 deleteDiscount ............................................................................................................. 474 deliveryType.................................................................................................................. 475 dentalAmount................................................................................................................ 476 depositReversal ........................................................................................................... 477 depositReversalResponse ........................................................................................... 478 description .................................................................................................................... 479 descriptor ...................................................................................................................... 480 destinationCountryCode ............................................................................................... 481 destinationPostalCode .................................................................................................. 482 detailTax ....................................................................................................................... 483 deviceManufacturerIdentifier......................................................................................... 484 deviceReputationScore ................................................................................................ 485 deviceReviewStatus...................................................................................................... 486 discountAmount ............................................................................................................ 487 discountCode ............................................................................................................... 488 dob ................................................................................................................................ 489 dutyAmount................................................................................................................... 490 echeck........................................................................................................................... 491 eCheckAccountSuffix ................................................................................................... 492 echeckCredit ................................................................................................................. 493 echeckCreditResponse................................................................................................. 494 echeckForToken ........................................................................................................... 495 echeckOrEcheckToken................................................................................................. 496 echeckPreNoteCredit ................................................................................................... 497 echeckPreNoteCreditResponse ................................................................................... 498 echeckPreNoteSale ..................................................................................................... 499 echeckPreNoteSaleResponse ..................................................................................... 500 echeckRedeposit .......................................................................................................... 501 echeckRedepositResponse .......................................................................................... 502 echeckSale ................................................................................................................... 503 echeckSalesResponse ................................................................................................. 504 echeckToken................................................................................................................. 505 echeckVerification......................................................................................................... 506 echeckVerificationResponse......................................................................................... 507 echeckVoid ................................................................................................................... 508 echeckVoidResponse ................................................................................................... 509 eciIndicator.................................................................................................................... 510 email ............................................................................................................................. 511 employerName.............................................................................................................. 512 xiv Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents encryptedTrack ............................................................................................................ 513 endDate ....................................................................................................................... 514 endingBalance ............................................................................................................. 515 endpoint ....................................................................................................................... 516 enhancedAuthResponse............................................................................................... 517 enhancedData............................................................................................................... 519 entryMode ..................................................................................................................... 523 ephemeralPublicKey ..................................................................................................... 524 expDate......................................................................................................................... 525 expMonth ..................................................................................................................... 526 expYear ........................................................................................................................ 527 extendedCardResponse .............................................................................................. 528 fastAccessFunding ....................................................................................................... 529 fastAccessFundingResponse ...................................................................................... 530 fieldValue ..................................................................................................................... 531 filtering .......................................................................................................................... 532 finalPayment ................................................................................................................ 533 firstName....................................................................................................................... 534 forceCapture ................................................................................................................. 535 forceCaptureResponse ................................................................................................. 536 formatId ........................................................................................................................ 537 fraudCheck ................................................................................................................... 538 fraudCheckResponse .................................................................................................. 539 fraudFilterOverride ....................................................................................................... 540 fraudResult ................................................................................................................... 541 fundingInstructionVoid ................................................................................................. 542 fundingInstructionVoidResponse ................................................................................. 543 fundingSource............................................................................................................... 544 fundingSubmerchantId ................................................................................................. 545 fundsTransferId............................................................................................................. 546 giftCardAuthReversal .................................................................................................... 547 giftCardAuthReversalResponse.................................................................................... 548 giftCardBin ................................................................................................................... 549 giftCardCapture............................................................................................................. 550 giftCardCaptureResponse ............................................................................................ 551 giftCardCredit................................................................................................................ 552 giftCardCreditResponse................................................................................................ 553 giftCardResponse ........................................................................................................ 554 giropay .......................................................................................................................... 555 giropayResponse .......................................................................................................... 556 header .......................................................................................................................... 557 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xv cnpAPI Reference Guide Contents healthcareAmounts ....................................................................................................... 558 healthcareIIAS .............................................................................................................. 559 iban .............................................................................................................................. 560 ideal .............................................................................................................................. 561 idealResponse .............................................................................................................. 562 IIASFlag ........................................................................................................................ 563 incomeAmount .............................................................................................................. 564 incomeCurrency............................................................................................................ 565 international .................................................................................................................. 567 intervalType ................................................................................................................. 568 invoiceReferenceNumber ............................................................................................. 569 issuerCountry................................................................................................................ 570 itemCategoryCode ........................................................................................................ 571 itemDescription ............................................................................................................. 572 itemDiscountAmount..................................................................................................... 573 itemSequenceNumber .................................................................................................. 574 ksn ................................................................................................................................ 575 lastName....................................................................................................................... 576 lineItemData.................................................................................................................. 577 lineItemTotal ................................................................................................................. 579 lineItemTotalWithTax .................................................................................................... 580 litleInternalRecurringRequest ....................................................................................... 581 litleOnlineRequest......................................................................................................... 582 litleOnlineResponse ..................................................................................................... 583 litleRequest ................................................................................................................... 585 litleResponse ................................................................................................................ 586 litleSessionId................................................................................................................. 588 litleToken....................................................................................................................... 589 litleTxnId........................................................................................................................ 590 load .............................................................................................................................. 592 loadResponse .............................................................................................................. 593 loadReversal ................................................................................................................ 594 loadReversalResponse ................................................................................................ 595 mandateProvider .......................................................................................................... 596 mandateReference ...................................................................................................... 597 mandateSignatureDate ................................................................................................ 598 mandateURL ................................................................................................................ 599 matchCount................................................................................................................... 600 merchantData ............................................................................................................... 601 merchantGroupingId ..................................................................................................... 602 merchantId .................................................................................................................... 603 xvi Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents message ....................................................................................................................... 604 middleInitial ................................................................................................................... 605 mpos ............................................................................................................................. 606 name ............................................................................................................................. 607 networkField ................................................................................................................. 608 networkResponse ........................................................................................................ 610 networkSubField .......................................................................................................... 611 networkTransactionId ................................................................................................... 612 newAccountInfo ............................................................................................................ 613 newCardInfo ................................................................................................................. 614 newCardTokenInfo ....................................................................................................... 615 newTokenInfo ............................................................................................................... 616 nextRecycleTime ......................................................................................................... 617 number.......................................................................................................................... 618 numberOfPayments ..................................................................................................... 619 onlinePaymentCryptogram ........................................................................................... 620 orderDate ...................................................................................................................... 621 orderId........................................................................................................................... 622 orderSource .................................................................................................................. 623 originalAccountInfo ....................................................................................................... 625 origAccountNumber ..................................................................................................... 626 origActionType ............................................................................................................. 627 origId ............................................................................................................................ 629 originalAmount .............................................................................................................. 630 originalCard................................................................................................................... 631 originalCardInfo ............................................................................................................ 632 originalCardTokenInfo .................................................................................................. 633 originalNetworkTransactionId ...................................................................................... 634 originalRefCode ............................................................................................................ 635 originalSequenceNumber ............................................................................................. 636 originalSystemTraceId .................................................................................................. 637 originalToken ............................................................................................................... 638 originalTokenInfo ......................................................................................................... 639 originalTransactionAmount .......................................................................................... 640 originalTxnTime ............................................................................................................ 641 origLitleTxnId ............................................................................................................... 642 origOrderId ................................................................................................................... 643 password ...................................................................................................................... 644 payerId ......................................................................................................................... 645 payFacCredit ................................................................................................................ 646 payFacCreditResponse ............................................................................................... 647 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xvii cnpAPI Reference Guide Contents payFacDebit ................................................................................................................. 648 payFacDebitResponse ................................................................................................. 649 paymentDataType ........................................................................................................ 650 paymentPurpose........................................................................................................... 651 paypage ........................................................................................................................ 652 paypageRegistrationId .................................................................................................. 653 paypal ........................................................................................................................... 654 payPalNotes ................................................................................................................. 655 payPalOrderComplete .................................................................................................. 656 phone ............................................................................................................................ 657 phone as a child of billToAddress and shipToAddress ..................................... 657 phone as a child of customBilling...................................................................... 657 physicalCheckCredit .................................................................................................... 658 physicalCheckCreditResponse .................................................................................... 659 physicalCheckDebit ...................................................................................................... 660 physicalCheckDebitResponse ..................................................................................... 661 pin ................................................................................................................................ 662 planCode ...................................................................................................................... 663 pos ................................................................................................................................ 664 postDate........................................................................................................................ 665 postDay ........................................................................................................................ 666 preapprovalNumber ...................................................................................................... 667 preferredLanguage ...................................................................................................... 668 prepaid .......................................................................................................................... 669 prepaidCardType .......................................................................................................... 670 processingInstructions .................................................................................................. 671 processingType ............................................................................................................ 672 productCode ................................................................................................................. 673 publicKeyHash ............................................................................................................. 674 quantity ......................................................................................................................... 675 queryTransaction ......................................................................................................... 676 queryTransactionResponse ......................................................................................... 677 queryTransactionUnavailableResponse ...................................................................... 678 recurringRequest ......................................................................................................... 679 recurringResponse ....................................................................................................... 680 recurringTxnId .............................................................................................................. 681 recycleAdvice................................................................................................................ 682 recycleAdviceEnd ........................................................................................................ 683 recycleBy ...................................................................................................................... 684 recycleEngineActive ..................................................................................................... 685 recycleId ....................................................................................................................... 686 xviii Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents recycling ....................................................................................................................... 687 recycling Element as a Child of authorizationResponse or saleResponse ............. 687 recycling Element as a Child of voidResponse ....................................................... 687 recyclingRequest .......................................................................................................... 689 redirectToken ............................................................................................................... 690 redirectUrl .................................................................................................................... 691 refCode ......................................................................................................................... 692 refundReversal ............................................................................................................. 693 refundReversalResponse ............................................................................................ 694 registerTokenRequest................................................................................................... 695 registerTokenResponse................................................................................................ 696 reloadable ..................................................................................................................... 697 reserveCredit ............................................................................................................... 698 reserveCreditResponse ............................................................................................... 699 reserveDebit ................................................................................................................. 700 reserveDebitResponse ................................................................................................. 701 residenceStatus ............................................................................................................ 702 response ....................................................................................................................... 703 responseCode .............................................................................................................. 704 responseMessage ........................................................................................................ 705 responseTime ............................................................................................................... 706 results_Max10 .............................................................................................................. 707 RFRRequest ................................................................................................................. 710 RFRResponse .............................................................................................................. 711 routingNum ................................................................................................................... 712 RxAmount ..................................................................................................................... 713 sale ............................................................................................................................... 714 saleResponse ............................................................................................................... 715 salesTax........................................................................................................................ 716 secondaryAmount ........................................................................................................ 717 sellerId .......................................................................................................................... 718 sellerMerchantCategoryCode ....................................................................................... 719 sepaDirectDebit ........................................................................................................... 720 sepaDirectDebitResponse ........................................................................................... 721 sequenceNumber.......................................................................................................... 722 sequenceType ............................................................................................................. 723 shipFromPostalCode .................................................................................................... 724 shippingAmount ............................................................................................................ 725 shipToAddress .............................................................................................................. 726 signature ....................................................................................................................... 727 sofort ............................................................................................................................. 728 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xix cnpAPI Reference Guide Contents sofortResponse............................................................................................................. 729 ssn ................................................................................................................................ 730 startDate ...................................................................................................................... 731 state .............................................................................................................................. 732 submerchantCredit ....................................................................................................... 733 submerchantCreditResponse ...................................................................................... 734 submerchantDebit ........................................................................................................ 735 submerchantDebitResponse ........................................................................................ 736 submerchantName........................................................................................................ 737 subscription .................................................................................................................. 738 subscriptionId ............................................................................................................... 740 surchargeAmount ......................................................................................................... 741 systemTraceId .............................................................................................................. 742 taxAmount..................................................................................................................... 743 taxExempt ..................................................................................................................... 744 taxIncludedInTotal......................................................................................................... 745 taxRate.......................................................................................................................... 746 taxType ......................................................................................................................... 747 taxTypeIdentifier ........................................................................................................... 748 terminalId ..................................................................................................................... 749 termsAndConditions...................................................................................................... 750 threatMetrixSessionId .................................................................................................. 751 token ............................................................................................................................. 752 token (Vantiv generated card number replacement)............................................... 752 token (PayPal generated) ....................................................................................... 753 tokenMessage............................................................................................................... 754 tokenResponse ............................................................................................................. 755 tokenResponseCode .................................................................................................... 756 totalHealthcareAmount ................................................................................................. 757 track .............................................................................................................................. 758 track1Status ................................................................................................................. 759 track2Status ................................................................................................................. 760 transactionAmount ....................................................................................................... 761 transactionId ................................................................................................................. 762 transactionId as a Child of the paypal element ....................................................... 762 transactionId as a Child of the header element....................................................... 762 trialIntervalType ........................................................................................................... 764 trialNumberOfIntervals ................................................................................................. 765 triggeredRule ............................................................................................................... 766 txnTime ......................................................................................................................... 767 type ............................................................................................................................... 768 xx Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Contents type Element as a Child of the parent elements listed below.................................. 768 type Element as a Child of fundingSource .............................................................. 769 unitCost......................................................................................................................... 770 unitOfMeasure .............................................................................................................. 771 unload .......................................................................................................................... 772 unloadResponse .......................................................................................................... 773 unloadReversal ............................................................................................................ 774 unloadReversalResponse ............................................................................................ 775 updateAddOn ............................................................................................................... 776 updatedCard ................................................................................................................. 777 updateCardValidationNumOnToken ............................................................................. 778 updateCardValidationNumOnTokenResponse............................................................. 779 updateDiscount ............................................................................................................ 780 updatePlan ................................................................................................................... 781 updatePlanResponse ................................................................................................... 782 updateSubscription ...................................................................................................... 783 updateSubscriptionResponse ...................................................................................... 787 updatedToken ............................................................................................................... 788 url .................................................................................................................................. 789 user ............................................................................................................................... 790 vendorCredit ................................................................................................................ 791 vendorCreditResponse ................................................................................................ 792 vendorDebit .................................................................................................................. 793 vendorDebitResponse ................................................................................................. 794 vendorName ................................................................................................................ 795 verificationCode ............................................................................................................ 796 verify ............................................................................................................................. 797 version ......................................................................................................................... 798 virtualAccountNumber .................................................................................................. 799 virtualAuthenticationKeyData........................................................................................ 800 virtualAuthenticationKeyPresenceIndicator .................................................................. 801 virtualGiftCard .............................................................................................................. 802 virtualGiftCardBin ......................................................................................................... 803 virtualGiftCardResponse .............................................................................................. 804 visionAmount ................................................................................................................ 805 void ............................................................................................................................... 806 voidResponse ............................................................................................................... 807 wallet ............................................................................................................................ 808 walletSourceType ........................................................................................................ 809 walletSourceTypeId ..................................................................................................... 810 yearsAtEmployer........................................................................................................... 811 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xxi cnpAPI Reference Guide Contents yearsAtResidence......................................................................................................... 812 zip ................................................................................................................................. 813 Appendix A Payment Transaction Response Codes Payment Transaction Response Codes ....................................................................... 816 3DS Authentication Result Codes................................................................................. 840 AVS Response Codes .................................................................................................. 842 AAVS Response Codes................................................................................................ 843 Card Validation Response Codes ................................................................................. 846 Advanced Fraud Tools Triggered Rules ....................................................................... 847 XML Validation Error Messages ................................................................................... 864 Additional Response Header Error Messages .............................................................. 866 ACH Return Reason Codes .......................................................................................... 868 ACH NoC Change Codes ............................................................................................. 871 Canadian eCheck Return Codes .................................................................................. 872 Appendix B Credit Card Number Formats Appendix C Test Card Numbers Appendix D PayFac™ Dynamic Payout Advantages of Using Dynamic Payout.......................................................................... 884 Overview of Dynamic Payout ....................................................................................... 885 Timing of Transactions, Reports, and Money Movement........................................ 886 Money Movement and Accounts ............................................................................ 887 Same Day Funding .......................................................................................... 888 FastAccess Funding™ ..................................................................................... 889 Account Balance Verifications........................................................................... 890 Example of Funding Instructions .................................................................................. 891 Funding Instruction Void Transactions.................................................................... 895 Funding Instruction Certification Testing....................................................................... 896 SSR Reports ................................................................................................................. 898 Tax ID Validation Process ............................................................................................ 900 xxii Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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 Doc. Version Document Revision History Description Location(s) 1.0 Initial release of LitleXML Reference Guide for schema V11.0, including new Gift Card transactions and international alternate payment methods. N/A 1.1 Addedto several eCheck transactions. Chapters 3 and 4 Added information about the iDEAL international payment method, which is now GA. Chapters 1, 2, and 4 Corrected maintenance window times for Pre-/Post-Live. Chapter 2 Added "Appears in Declined Transaction report." note to certain Response Codes. Appendix A 1.2 Document Version: 1.8 xxiii © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide About This Guide TABLE 1 Revision History Document Revision History Doc. Version Description Location(s) 1.3 Replaced LitleXML with cnpAPI. All Added three new tests for new MC 3DS behavior. Chapter 2 Moved Dupe Tests from Optional to Required test group. Chapter 2 Added info about checkoutId element (not GA) Chapter 3 Added info about sameDayFunding Batch Request attribute. Chapter 4 & Appendix D Added info about SOFORT and Giropay alternate payment methods. Chapters 1, 2, and 4 Revised/renamed Customer Insights to Issuer Insights. Chapter 1 Corrected several examples, replacing Response Code 001 Transaction Received with 000 - Approved. Chapter 3 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 orderId element added to accountUpdateResponse. Chapter 4 Removed " not yet supported " note from checkoutId element and added Cert tests Chapters 2 and 4 Modified requirements for Level 2/3 data (enhancedData element). Chapter 4 Added Response Codes 940 and 941. Appendix A Added text clarifying limit of 25K for Same day Funding transaction and removed debit transaction restrictions. Appendix D Added note about 30 minute wait for funds to be restored to Settlement account balance after issuing a Funding Instruction Void transaction. Appendix D Removed Mobile Point of Sale sections from guide Chapters 1 and 2 Updated document for release of V11.3, including Online Dynamic Payout Funding Instructions and Fast Funding transaction. All Fixed various links to github and test environments. 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 1.4 1.5 1.6 1.7 xxiv Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Revision History TABLE 1 About This Guide Document Revision History Doc. Version Description Location(s) 1.8 Remove reference to Recurring Snapshot report. Chapter 1 Updated Android Pay Certification test results. Chapter 2 Corrected maxLength of id attribute, which increased from 25 to 36 in V11.3. Chapter 4 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xxv cnpAPI Reference Guide About This Guide Document Structure Document Structure This manual contains the following sections: Chapter 1, "Introduction" This chapter provides an introduction to transaction processing using 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. 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. Documentation Set For additional information concerning the Vantiv application, see any of the following guides in the documentation set: xxvi • 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Documentation Set About This 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 XML Differences Guide • Vantiv Secure Scheduled Reports Reference Guide Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xxvii 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: • • xxviii 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. xxix 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 xxx TechPubs@vantiv.com Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 1 cnpAPI Reference Guide Introduction 1.1 The cnpAPI Data Format The cnpAPI Data Format There are several advantages to using the cnpAPI format 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 Relationship 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 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide The cnpAPI Data Format TABLE 1-1 Introduction 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. 1.1.2 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-2). 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. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 3 cnpAPI Reference Guide Introduction The cnpAPI Data Format TABLE 1-2 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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. NOTE: For information about duplicate checking of Dynamic Payout Funding Instructions see Batch Dupe Checking for Dynamic Payout Funding Instructions on page 8. 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 7 cnpAPI Reference Guide Introduction Duplicate Transaction Detection 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 neither threshold is met, Vantiv continues processing the Batch, including any transactions that may have been duplicates. 1.4.1.1 Batch Dupe Checking for Dynamic Payout Funding Instructions Duplicate checking for funding instructions takes place at the Batch level. The system compares a submitted Batch of instructions to other Batches submitted and accepted on the same day. If a submitted Batch has the same totals and counts as a Batch accepted on the same day, the system rejects the new Batch as a duplicate. If you resubmit a previously rejected Batch, it will not fail dupe checking, because the initial submission was not accepted and is not included in dupe checking comparisons. NOTE: 1.4.2 If you believe we rejected a funding instruction Batch in error, please contact your Partner Account Manager. If necessary, we can disable the dupe check feature for a particular Batch. 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, eCheck Void, and Void, as well as Gift Card transactions. 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. 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. 8 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Duplicate Transaction Detection NOTE: Introduction While it is uncommon, under certain circumstances network latency may cause a duplicate Sale transaction to go undetected. 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, The duplicate transactions appears in the Declined Transaction report with a Response Reason Code of 251 - Duplicate Transaction. You can access this report in Vantiv iQ or via the Vantiv Secure Scheduled Report. The iQ version provides information in near real-time, while the SSR version runs daily, providing information for the transaction submitted the previous day. NOTE: If you do not receive a response for a submitted transaction, Vantiv recommends you use the queryTransaction to determine the status of the original transaction (see Status Query Transactions (Online Only) on page 300) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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 Relationship 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.8 — cnpAPI Release: 11.3 © 2017 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. NOTE: The merchantData element and its children were add to the schema in V8.8 and backported to V7.3. If you are using a schema version between 7.0 and 8.7, you can code for the use of these elements and still pass the cnpAPI validation. 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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-3 below. The element in the response files indicates if the transaction is being handled by the Recycling Engine. TABLE 1-3 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.8 — cnpAPI Release: 11.3 © 2017 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 Relationship 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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 Relationship 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 1.6.2.2 Auth Auth Decline if updated info not yet on file Auth Auth Approval w/New Card Info Auth Submit for Auth Merchant Requirements In order to use the Account Updater service, you must first apply for membership to the following: 16 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recovery Introduction • 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 Relationship 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recurring Engine Introduction TABLE 1-4 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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 2016-09-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 323). Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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-5 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 2016-10-14 4GB_Extra Four_GB_Extra 2000 2016-09-15 2016-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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Recurring Engine TABLE 1-5 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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 (e.g., 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.8 — cnpAPI Release: 11.3 © 2017 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-6 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Issuer Insights Introduction TABLE 1-6 Possible Extended Network Data ISO 8583 Fields Data Element Field Name Type 4 Transaction Amount n 12 15 Settlement Date n4 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 MMDD format Defines the currency of the settlement 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.8 — cnpAPI Release: 11.3 © 2017 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-7 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 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 29 cnpAPI Reference Guide Introduction Fraud Toolkit TABLE 1-7 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 000000000962 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 27 cnpAPI Reference Guide Introduction Issuer Insights 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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 Fraud 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 filter, for the same account within a designated 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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-8 defines five rules that a merchant might define. TABLE 1-8 34 Example - Fraud Filtering Service Rules Filter Flow Selector Filters 1 Report Group = "XYZ" Prepaid Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Fraud Toolkit Introduction TABLE 1-8 Example - Fraud Filtering Service Rules Filter Flow Selector Filters 2 Report Group = "XYZ" International 3 orderSource = "recurring" Prepaid + Prior Chargeback 4 orderSource = "ecommerce" Card Velocity + Security Code No-match 5 Billing Descriptor = "GoldMember" Prepaid + International Table 1-8 defines five Filter Rules that a merchant might use. These rules would be applied as follows: • Filters 1 and 2 apply 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 filtering occurs. • Filter 3 applies to the subset of transactions that have an orderSource value set to recurring. Filtering occurs only if both the criteria for the Prepaid Filter AND the Prior Chargeback Filter are met. • Filter 4 applies to the subset of transactions that have an orderSource value set to ecommerce. Filtering occurs only if both the criteria for the Card Velocity Filter AND the Security Code No-Match Filter are met. • Filter 5 applies to the subset of transactions that have an Billing Descriptor value set to GoldMember. Filtering occurs 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Fraud Toolkit 1.9.4.2 Introduction 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 (see Fraud Check Transaction on page 288). Fraud Check transactions are only supported as Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 39 cnpAPI Reference Guide Introduction Tokenization Feature 1.10 Tokenization Feature Tokenization is the process by which a reference number, referred to as a token, replaces a credit card number or eCheck account number. Unlike the card or account number, you can store the token on your system without concern of a security breach exposing critical customer information. Instead, 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 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 in the event of a breach. You can reduce the requirements further, as well as the possibility of exposure from a breach, through the use of the Vantiv eProtect™. By sending the card information from your checkout 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: 40 Please refer to the Vantiv eProtect Integration Guide for additional information about the use of and integration to the Vantiv eProtect value added service. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Tokenization Feature 1.10.1 Introduction How Tokenization Works In a non-tokenized environment, multiple parties handle and store customer data, including the card/eCheck account number, 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 shown in Figure 1-5 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 data transmission occurs 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 a malicious third party could compromise the information. FIGURE 1-5 Card Information Flow in Non-Token Environment Card Assn. Merchant Account # Account # Account # Account # Issuing Bank Cardholder Account # Account # Database Database Account # Database Account # Database In a tokenized environment transmission of customer data ideally occurs a single time and the merchant never stores it locally, as shown in Figure 1-6 for card data. Once account number registration occurs, using either a registerTokenRequest or by submitting the account number (or low value token, when using eProtect) with any supported transaction, Vantiv returns a (high value) 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: FIGURE 1-6 The difference between card data flow and eCheck data flow is that the entities upstream of Vantiv are different. The operation remains the same from a merchant standpoint. Card Information Flow in Tokenized Environment Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 41 cnpAPI Reference Guide Introduction Tokenization Feature NOTE: 1.10.2 The use of eProtect 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 Last four digits of the card 0123456789012345 Randomly generated number 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. 1.10.3 Obtaining Tokens NOTE: You must be token enabled and certified prior to using the Vault feature. Please consult your Relationship 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 307.) 42 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Tokenization Feature Introduction 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 we convert a card number to a token for a particular merchant, subsequent submissions of the same card number return the same token. The third method of obtaining a token applies only to merchants using the Vantiv eProtect feature. In this case, upon submission of an account number via the eProtect 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. 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. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 43 cnpAPI Reference Guide Introduction 1.10.4 Tokenization Feature Supported Token Transactions The following transactions support the generation and use of tokens: 44 • 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 security code in a registerTokenRequest transaction and now need to change the CVV2/CVC2/CID value. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Tokenization Feature 1.10.5 Introduction 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-9 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 45 cnpAPI Reference Guide Introduction eCheck Processing 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 Relationship Manager for additional information. NOTE: 1.11.1 Beginning in March, 2015, 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 Relationship 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 Fed database. If the routing number fails this validation, the transaction is rejected. 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 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. 46 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCheck Processing Introduction 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: • 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 47 cnpAPI Reference Guide Introduction eCheck Processing • 1.11.3 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 preconfigure 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 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. 48 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCheck Processing 1.11.5 Introduction 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 for 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. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 49 cnpAPI Reference Guide Introduction eCheck Processing 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. 50 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide SEPA Direct Debit Introduction 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. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 51 cnpAPI Reference Guide Introduction SEPA Direct Debit FIGURE 1-8 1 Order Flow for Vantiv Supplied Mandate Consumer selects iDEAL payment method on the Checkout page. 2 Consumer Merchant Merchant redirects consumer to the bank selection page. 4 5 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. Consumer Accepts or Rejects transaction using iDEAL/Bank authentication process. Merchant sends Sale transaction to Vantiv. Response includes link to page for bank selection and redirectToken. 3 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 52 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide SEPA Direct Debit IntroductionsddSale 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. 54 4 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide SEPA Direct Debit Introduction 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 53 cnpAPI Reference Guide Introduction SEPA Direct Debit1ABCA43 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. 56 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide iDEAL, SOFORT, and Giropay Introduction 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, and 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 . Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 57 cnpAPI Reference Guide Introduction iDEAL, SOFORT, and Giropay 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 55 cnpAPI Reference Guide Introduction SEPA Direct Debithttp://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 authenticating the user and 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: 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 59 cnpAPI Reference Guide Introduction eCommerce Solution for Apple Pay™ 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-10, "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 • Merchant Decryption of Apple Pay PKPaymentToken • cnpAPI 84568456 p1_idealSale 000 2017-04-03T10:24:31 58 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide iDEAL, SOFORT, and Giropay Introduction2017-04-03 Approved http://ideal.bank.com 1234567890 123456YourCompanyName Structure • Vantiv Mobile API for Apple Pay HTTPS POST Components • 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. 60 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ Introduction 3. Apple Pay returns the Apple PKPaymentToken (defined in Apple documentation; please refer to 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. This method can be used 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 60. 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 element to applepay. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 61 cnpAPI Reference Guide Introduction eCommerce Solution for Apple Pay™ 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. 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-10 lists the requirements for your customers’ Apple devices when making purchases via Apple Pay on the Web. NOTE: Table 1-10 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-10 Apple Pay on the Web Compatible Devices 62 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 Browser Safari only Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ FIGURE 1-11 1.14.2.2 Introduction 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 PayPage transaction. The PayPage 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 60. 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 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 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 element to applepay. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 63 cnpAPI Reference Guide Introduction eCommerce Solution for Apple Pay™ 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. 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 1.14.2.3 Data/Transaction Flow using the Vantiv Mobile API for Apple Pay Submitting the Apple Pay PKPaymentToken in a cnpAPI Message In this scenario, you submit the Apple Pay PKPaymentToken to the Vantiv eCommerce platform using a new cnpAPI structure (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 60. The process after Step 3 is detailed below and in Figure 1-13. 64 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ Introduction 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. FIGURE 1-13 1.14.2.4 Data/Transaction Flow with Direct Submission of PKPaymentToken via cnpAPI 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 65 cnpAPI Reference Guide Introduction eCommerce Solution for Apple Pay™ 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). 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 66 Data/Transaction Flow with Merchant Decryption of Apple Pay PKPaymentToken Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Apple Pay™ 1.14.3 Introduction 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/Discover to tie the new transaction to the original approved transaction. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 67 cnpAPI Reference Guide Introduction eCommerce Solution for Android Pay™ 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 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") 68 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Android Pay™ Introduction .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. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 69 cnpAPI Reference Guide Introduction eCommerce Solution for Android Pay™ 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 70 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Android Pay™ 1.15.2 Introduction 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., 2015) • authMethod (string) - the constant 3DS (may change in future releases). • 3dsCryptogram (string) - the 3DSecure cryptogram • 3dsEciIndicator ((optional) string) - ECI indicator per 3DSecure specification Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 71 cnpAPI Reference Guide Introduction eCommerce Solution for Android Pay™ 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. 72 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide eCommerce Solution for Android Pay™ FIGURE 1-16 Web App/ Mobil App Introduction High Level Message Flow for Android Pay using Merchant Decryption Merchant Server Vantiv eComm Card Networks 1 2 3 4 5 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 73 cnpAPI Reference Guide Introduction 1.15.3 eCommerce Solution for Android Pay™ 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 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 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. 74 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction 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. NOTE: 1.16.1 For information about Dynamic Payout Funding Instructions please refer to Appendix D, "PayFac™ Dynamic Payout". 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. If you settle in a currency other than US or Canada, you cannot use partial Authorizations. 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-11 provides information concerning Authorization lifespans for various card types and alternate payment methods. TABLE 1-11 Lifespan of Payment Authorizations Payment Type Lifespan of Authorization MasterCard 7 days Visa 7 days Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 75 cnpAPI Reference Guide Introduction Supported Transaction Types TABLE 1-11 Lifespan of Payment Authorizations Payment Type Lifespan of Authorization 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. 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 79). 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. 76 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types NOTE: Introduction For American Express transactions, the reversal amount must match the authorization amount. American Express does not allow partial reversals and reversals against remaining amounts after a partial capture. 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. • 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 232). 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. • 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. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 77 cnpAPI Reference Guide Introduction Supported Transaction Types • For Online transactions, when following an Authorization with an Auth Reversal, allow a minimum of one minute between the transactions. • For Visa transactions, 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. • 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. • Do not use an Authorization Reversal to reverse an Authorization on a (Closed Loop) Gift Card. Use a Gift Card Auth Reversal instead (see Gift Card Auth Reversal Transactions on page 290). 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. 78 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types 1.16.4 Introduction 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. 1.16.7 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: If you settle in a currency other than US or Canada, you cannot use partial captures. 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. Do not use a Capture transaction to capture funds on a (Closed Loop) Gift Card transaction; use a Gift Card Capture instead (see Gift Card Capture Transactions on page 292). 1.16.8 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). Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 79 cnpAPI Reference Guide Introduction Supported Transaction Types 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. 1.16.9 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: 80 • Capture Transaction • Capture Given Auth Transaction • Force Capture Transaction • Sale Transaction Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types • Introduction External Sale or Capture NOTE: Vantiv recommends you send all Credit transactions in a Batch 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. 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 49). This transaction type is only supported for US transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 81 cnpAPI Reference Guide Introduction Supported Transaction Types 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 49). 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 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. 82 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction 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 Gift Card Auth Reversal You use the Gift Card Auth Reversal transaction to reverse an Authorization on a (Closed-loop) Gift Card. This removes the hold on the previously authorized amount, freeing those funds for additional purchases by the cardholder. 1.16.23 Gift Card Capture You use the Gift Card Capture transaction to capture or deposit previously authorized funds on a (Closed-loop) Gift Card. 1.16.24 Gift Card Credit You use a Gift Card Credit transaction to refund money to a customer that used a (Closed Loop) Gift Card for the purchase, even if Vantiv did not process the purchase. You have a choice of two structures. You use the message type containing a transaction Id to apply a credit for a transaction processed by Vantiv. You use the message type containing a order Id to apply a credit for a transaction not processed by Vantiv. 1.16.25 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.26 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. You cannot perform a partial Load Reversal. This transaction always reverses the full amount of the referenced Load transaction. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 83 cnpAPI Reference Guide Introduction Supported Transaction Types 1.16.27 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. You cannot perform a partial Refund Reversal. This transaction always reverses the full amount of the referenced Refund transaction. 1.16.28 Register Token Transaction You use the Register Token transaction to submit a credit card number, eCheck account number, or Registration Id to us and receive a token in return. While you can submit Register Token transactions at any time, typically, you would make use of this transactions when initially converting to the use of tokens. In this case you would submit large quantities of credit cards/eCheck account numbers in Batches and replace them in your database with the tokens returned. 1.16.29 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.30 Status Query Transaction The Status Query Transaction allows you to verify that an Online transaction submitted within the prior 24 hours exists in the system. The response will be one of the following: • A single transaction matching the search criteria • Multiple transactions matching the search criteria • Empty results, if no transactions matched the criteria • A limited response, if a transaction was found, but processing was not complete As search criteria, you must submit, at a minimum, the id (id attribute) and transaction type (i.e., authorization, deposit, void, etc.) of the original transaction, but to narrow the search, you can also include the transaction id, order id, and the account number (credit, debit, or gift card) from 84 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction the original transaction. The response message contains one of four response codes, 150 through 153 (see Payment Transaction Response Codes on page 816), and the results for the search. NOTE: Use of this transaction type requires specific permissions. Please speak to your Vantiv Implementation Consultant for additional information. 1.16.31 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.32 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. You cannot perform a partial Unload Reversal. This transaction always reverses the full amount of the referenced Unload transaction. 1.16.33 Update Card Validation Number Transaction When you submit the CVV2/CVC2/CID in a registerTokenRequest, the platform encrypts and stores the value on a temporary basis for later use in a tokenized Auth/Sale transaction submitted without the value. This is done to accommodate merchant systems/workflows where the security code is available at the time of token registration, but not at the time of the Auth/Sale. If for some reason you need to change the value of the security code supplied at the time of the token registration, use an updateCardValidationNumOntoken transaction. 1.16.34 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.35 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 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 85 cnpAPI Reference Guide Introduction Supported Transaction Types information, and/or billing date. You can also create, update, or delete a Discount and/or an Add On. 1.16.36 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). 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 76.) 1.16.36.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.37 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 86 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Supported Transaction Types Introduction Sub-merchants. This section provides information about these transaction types. For additional information, please refer to the Appendix D, "PayFac™ Dynamic Payout". • Funding Instruction Void - You use this transaction type to void a submitted funding instruction. You must submit the void prior to your daily cutoff time for an instruction not yet processed. • 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 87 cnpAPI Reference Guide Introduction 88 Supported Transaction Types Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 89 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 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. This environment should be used by 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. 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. 90 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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: • The number of merchants configured per organization will be limited 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, we will provide advanced notification. • 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 not use 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 91 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. 92 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 93 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 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 103. 2.2.3 Optional Testing Vantiv 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 90). 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). 94 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 95 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. 96 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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: When submitting a file via FTP/sFTP, verify that the file permission is set to 664. Also, 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). Also, change the file permission to 664. the 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 97 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: 98 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.8 — cnpAPI Release: 11.3 © 2017 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_Litle", 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(); 100 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 101 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. 102 • 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.8 — cnpAPI Release: 11.3 © 2017 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. IMPORTANT: To determine the final status and response Code of a declined or duplicate transactions, please refer to the Declined Transaction Report in Vantiv iQ. Once in the production environment, you can also obtain this daily report via Secure Scheduled Reports. During certification testing, a Vantiv 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. NOTE: 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 NOTE: To test your handling of 2-series (BIN) number for MasterCard, you can substitute a 2-series test card number (see Appendix C, "Test Card Numbers") in any Auth/Sale test and you will receive a 000 - Approved Response Code in the response message. 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: Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 103 cnpAPI Reference Guide Testing Your cnpAPI Transactions Performing the Required Certification Tests • 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) To test Authorization transactions: 1. Verify that your Authorization XML template is coded correctly (refer to Authorization Transactions on page 208.) 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: 104 Some Issuers do not return an Auth Code for $0 Authorizations. You should code your systems to handle this possibility. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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 314.) 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 231.). 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 247.) 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 334.) 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 105 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 99 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. 106 Approved Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 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 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. 108 Approved Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 000 Approved 109 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. 110 Approved Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 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: 000 Use the value returned in the Sale response (not Auth) for Order Id 6. Approved Declined Transaction report result = 360 - No transaction found with specified litleTxnId 7 Authorization/Sale/AVS: 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.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 111 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