Vantiv CnpAPI Reference Guide Cnp API API9.14 V1.32

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 882 [warning: Documents this large are best viewed by clicking the View PDF Link!]

cnpAPI Reference Guide
January 2018
XML Release: 9.14
Document Version: 1.32
Vantiv cnpAPI Reference Guide Document Version: 1.32
All information whether text or graphics, contained in this manual is confidential and proprietary information of Vantiv, LLC and is
provided to you solely for the purpose of assisting you in using a Vantiv, LLC product. All such information is protected by copyright laws
and international treaties. No part of this manual may be reproduced or transmitted in any form or by any means, electronic, mechanical or
otherwise for any purpose without the express written permission of Vantiv, LLC. The possession, viewing, or use of the information
contained in this manual does not transfer any intellectual property rights or grant a license to use this information or any software
application referred to herein for any purpose other than that for which it was provided. Information in this manual is presented "as is" and
neither Vantiv, LLC or any other party assumes responsibility for typographical errors, technical errors, or other inaccuracies contained in
this document. This manual is subject to change without notice and does not represent a commitment on the part Vantiv, LLC or any other
party. Vantiv, LLC does not warrant that the information contained herein is accurate or complete.
All trademarks are the property of their respective owners and all parties herein have consented to their trademarks appearing in this
manual. Any use by you of the trademarks included herein must have express written permission of the respective owner.
Copyright © 2003-2018, Vantiv, LLC - ALL RIGHTS RESERVED.
Document Version: 1.32 — XML Release: 9.14 iii
CONTENTS
© 2018 Vantiv, LLC - All Rights Reserved.
About This Guide
Intended Audience........................................................................................................ xxiii
Revision History............................................................................................................ xxiii
Document Structure..................................................................................................... xxvii
Documentation Set xxix
Typographical Conventions ...........................................................................................xxx
Contact Information....................................................................................................... xxxi
Chapter 1 Introduction
The cnpAPI Data Format .................................................................................................. 2
Communications Protocols ......................................................................................... 2
General XML Coding Requirements ........................................................................... 4
Other XML Resources................................................................................................. 4
Batch Transaction Processing .......................................................................................... 5
Recommended Session File Size ............................................................................... 5
Payment Integration Platform (cnpAPI SDKs) .................................................................. 6
Duplicate Transaction Detection....................................................................................... 7
Batch Duplicate Checking........................................................................................... 7
Online Duplicate Checking.......................................................................................... 8
Coding for Report Groups............................................................................................... 10
Additional/Alternate Methods of Tagging Transactions ............................................ 11
Recovery......................................................................................................................... 12
Authorization/Sale Recycling .................................................................................... 12
Recycling Engine ................................................................................................ 12
Account Updater Service ......................................................................................... 14
Match Back ......................................................................................................... 15
Merchant Requirements...................................................................................... 17
Account Updater Features .................................................................................. 17
Recurring Engine ............................................................................................................ 18
Payment Plans.......................................................................................................... 18
Subscriptions............................................................................................................. 19
Add Ons and Discounts ...................................................................................... 21
Recurring Reports..................................................................................................... 21
Transaction Types and Uses .................................................................................... 22
Issuer Insights.................................................................................................................24
Issuer Insights Secure Scheduled Report................................................................. 24
Real Time Indicators ................................................................................................. 24
Prepaid Indicator................................................................................................. 24
cnpAPI Reference Guide Contents
iv Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
Affluence Indicator .............................................................................................. 25
Issuer Country Indicator...................................................................................... 26
Cardholder Type Indicator................................................................................... 26
Extended Network Data ............................................................................................ 26
Insights Analytics Dashboard.................................................................................... 28
Fraud Toolkit ..................................................................................................................29
Essential Tier ............................................................................................................ 30
Prepaid Card Filtering ........................................................................................ 30
International BIN Filtering ................................................................................... 31
Prior Chargeback Filtering ................................................................................. 31
Security Code No-Match Filter ........................................................................... 31
Card Velocity Filtering ........................................................................................ 32
Prior Fraud Advice Filtering ................................................................................ 32
AVS Filter ........................................................................................................... 32
Email Velocity Filter............................................................................................. 33
Phone Velocity Filter ........................................................................................... 33
IP Velocity Filter .................................................................................................. 33
Device Velocity Filter........................................................................................... 34
Application of Filters - Filtering Rules ................................................................. 34
Extended Tier............................................................................................................ 35
Premium Tier............................................................................................................. 36
Modifications to Your Web Page............................................................................... 36
cnpAPI Transactions........................................................................................... 37
Information Only Option ...................................................................................... 39
Fraud Check Transactions ................................................................................. 39
Tokenization Feature ...................................................................................................... 41
How Tokenization Works .......................................................................................... 42
Token Formats.......................................................................................................... 43
Obtaining Tokens...................................................................................................... 44
Bulk Token Registration...................................................................................... 44
Supported Token Transactions................................................................................. 45
Compliance with Visa Best Practices for Tokenization ............................................. 46
eCheck Processing......................................................................................................... 47
Validation Feature..................................................................................................... 47
Verification Feature................................................................................................... 47
Required Contents of Decline Notice.................................................................. 48
Automatic Notice of Change (NoC) Updates ............................................................ 49
Auto Redeposit Feature ............................................................................................ 49
eCheck Prenotification .............................................................................................. 50
SEPA Direct Debit........................................................................................................... 52
SEPA Direct Debit - Vantiv Supplied Mandate.......................................................... 52
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 v
© 2018 Vantiv, LLC - All Rights Reserved.
SEPA Direct Debit - Merchant Supplied Mandate..................................................... 55
iDEAL, SOFORT, and Giropay ...................................................................................... 58
eCommerce Solution for Apple Pay™ ............................................................................ 61
Overview of Apple Pay Operation............................................................................. 61
Vantiv Decryption of Apple Pay PKPaymentToken................................................... 62
Using the Browser JavaScript API for Apple Pay on the Web ............................ 62
Using the Vantiv Mobile API for Apple Pay............................................................... 64
Alternate Flow using a Register Token Request................................................. 66
Submitting the Apple Pay PKPaymentToken in cnpAPI ..................................... 66
Merchant Decryption of Apple Pay PKPaymentToken.............................................. 67
Recurring Payments with Apple Pay......................................................................... 68
eCommerce Solution for Android Pay™......................................................................... 69
Android Pay using eProtect....................................................................................... 69
Merchant Decryption Method.................................................................................... 72
Recurring Payments with Android Pay...................................................................... 75
Supported Transaction Types......................................................................................... 76
Authorization Transaction ......................................................................................... 76
AVS Only Transaction......................................................................................... 77
Authorization Reversal Transactions ........................................................................ 77
Notes on the Use of Authorization Reversal Transactions.................................. 78
Using Authorization Reversal to Halt Recycling Engine...................................... 79
Activate Transaction.................................................................................................. 79
Activate Reversal Transaction (Online Only) ............................................................ 79
Balance Inquiry Transaction...................................................................................... 79
Cancel Subscription Transaction .............................................................................. 79
Capture Transaction.................................................................................................. 80
Capture Given Auth Transaction............................................................................... 80
Create Plan Transaction ........................................................................................... 81
Credit Transaction..................................................................................................... 81
Deactivate Transaction ............................................................................................. 81
Deactivate Reversal Transaction (Online Only)........................................................ 81
Deposit Reversal Transaction (Online Only)............................................................. 81
eCheck Credit Transaction........................................................................................ 82
eCheck Prenotification Credit Transaction................................................................ 82
eCheck Prenotification Sale Transaction .................................................................. 82
eCheck Redeposit Transaction................................................................................. 82
eCheck Sales Transaction ........................................................................................ 82
eCheck Verification Transaction ............................................................................... 82
eCheck Void Transaction (Online Only).................................................................... 83
Force Capture Transaction ....................................................................................... 83
Load Transaction ...................................................................................................... 83
cnpAPI Reference Guide Contents
vi Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
Load Reversal Transaction (Online Only)................................................................. 83
Refund Reversal Transaction (Online Only) ............................................................. 83
Sale Transaction ....................................................................................................... 84
Unload Transaction................................................................................................... 84
Unload Reversal Transaction (Online Only).............................................................. 84
Update Plan Transaction........................................................................................... 84
Update Subscription Transaction.............................................................................. 84
Void Transaction (Online Only)................................................................................. 85
Using Void to Halt Recycling Engine................................................................... 85
Instruction-Based Dynamic Payout Transactions .................................................... 85
Chapter 2 Testing Your cnpAPI Transactions
Certification and Testing Environments .......................................................................... 88
Sandbox Environment............................................................................................... 88
Pre-Live Environment................................................................................................ 88
Pre-Live Environment Limitations and Maintenance Schedules ......................... 89
Post-Live Environment.............................................................................................. 89
Post-Live Environment Limitations and Maintenance Schedules ....................... 89
Overview of Testing ........................................................................................................ 91
Planning for Certification Testing .............................................................................. 91
Required Certification Testing................................................................................... 92
Optional Testing........................................................................................................ 92
System Doctor........................................................................................................... 92
Transferring Files............................................................................................................ 95
Transferring Session Files ........................................................................................ 95
Submitting a Session File for Processing............................................................ 95
Retrieving Processed Session Files.................................................................... 96
Transferring Online Files........................................................................................... 96
ASP Programming Example ............................................................................... 97
Java Programming Example ............................................................................... 98
Notes on Timeout Settings.................................................................................. 99
Notes on Persistent Connections........................................................................ 99
Helpful Web Sites.............................................................................................. 100
Performing the Required Certification Tests ................................................................. 101
Testing Authorization (including Indicators), AVS Only, Capture, Credit, Sale, and Void
Transactions............................................................................................................ 101
Testing Recycling Advice .................................................................................. 116
Testing Authorization Reversal Transactions.......................................................... 117
Testing eCheck Transactions.................................................................................. 121
Testing Token Transactions.................................................................................... 128
Performing the Optional Tests ...................................................................................... 133
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 vii
© 2018 Vantiv, LLC - All Rights Reserved.
Testing AVS and Card Validation............................................................................ 134
Testing Address Responses ................................................................................... 135
Testing Advanced AVS Response Codes............................................................... 137
Testing Response Reason Codes and Messages.................................................. 138
Testing 3DS Responses ......................................................................................... 141
Testing the Prepaid Filtering Feature...................................................................... 142
Testing the International Card Filter Feature .......................................................... 144
Testing Security Code No-Match Filtering .............................................................. 145
Testing Advanced Fraud Tools ............................................................................... 147
Testing Account Updater......................................................................................... 149
Testing Account Updater Extended Response Codes...................................... 150
Testing Account Updater for Tokenized Merchants .......................................... 151
Testing Tax Billing................................................................................................... 151
Testing Convenience Fees ..................................................................................... 152
Testing the Recycling Engine.................................................................................. 155
Testing Recycling Engine Cancellation............................................................. 163
Testing Recurring Engine Transactions.................................................................. 165
Testing Gift Card Transactions ............................................................................... 178
Testing MasterPass Transactions........................................................................... 186
Testing Apple Pay Transaction Processing ............................................................ 187
Testing the Submission of the Decrypted PKPaymentToken in cnpAPI ........... 187
Testing the Submission of PKPaymentToken in cnpAPI .................................. 187
Testing Android Pay Transaction Processing ......................................................... 189
Testing Android Pay using eProtect.................................................................. 189
Testing SEPA Direct Debit Transactions ................................................................ 190
Testing iDEAL Transactions.................................................................................... 192
Testing Giropay Transactions ................................................................................. 193
Testing SOFORT Transactions............................................................................... 194
Testing Online Duplicate Transaction Processing .................................................. 196
Testing Transaction Volume Capacity .................................................................... 197
Chapter 3 cnpAPI Transaction Examples
Overview of Online and Batch Processing Formats ..................................................... 200
Batch Process Format............................................................................................. 200
Supported Communication Protocols................................................................ 201
Batch Processing Request Format ................................................................... 201
Batch Processing Response Format................................................................. 201
Online Processing Format ............................................................................................ 202
Supported Communication Protocols...................................................................... 203
Online Processing Request Format ........................................................................ 203
Online Processing Response Format ..................................................................... 203
cnpAPI Reference Guide Contents
viii Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
Transaction Types and Examples................................................................................. 204
Authorization Transactions...................................................................................... 206
Authorization Request Structure ....................................................................... 206
Authorization Response Structure .................................................................... 213
Authorization Reversal Transactions ...................................................................... 218
Authorization Reversal Requests...................................................................... 218
Authorization Reversal Responses................................................................... 219
Activate Transactions.............................................................................................. 221
Activate Request............................................................................................... 221
Activate Response ............................................................................................ 222
Activate Reversal Transactions (Online Only) ........................................................ 224
Activate Reversal Request................................................................................ 224
Activate Reversal Response ............................................................................. 224
Balance Inquiry Transactions.................................................................................. 225
Balance Inquiry Request................................................................................... 225
Balance Inquiry Response ................................................................................ 226
Cancel Subscription Transactions........................................................................... 227
Cancel Subscription Request............................................................................ 227
Cancel Subscription Response......................................................................... 228
Capture Transactions.............................................................................................. 229
Capture Request............................................................................................... 229
Capture Response ............................................................................................ 236
Capture Given Auth Transactions........................................................................... 237
Capture Given Auth Request ............................................................................ 237
Capture Given Auth Response ......................................................................... 242
Create Plan Transactions........................................................................................ 243
Create Plan Request......................................................................................... 243
Create Plan Response...................................................................................... 244
Credit Transactions................................................................................................. 245
Credit Request for a Vantiv Processed Transaction ......................................... 245
Credit Request for a Non-Vantiv Processed Transaction ................................. 249
Credit Response ............................................................................................... 254
Deactivate Transactions.......................................................................................... 255
Deactivate Request........................................................................................... 255
Deactivate Response ........................................................................................ 256
Deactivate Reversal Transactions (Online Only) .................................................... 257
Deactivate Reversal Request............................................................................ 257
Deactivate Reversal Response......................................................................... 258
Deposit Reversal Transactions (Online Only)......................................................... 259
Deposit Reversal Request ................................................................................ 259
Deposit Reversal Response.............................................................................. 259
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 ix
© 2018 Vantiv, LLC - All Rights Reserved.
eCheck Credit Transactions.................................................................................... 260
eCheck Credit Request Against a Vantiv Transaction ...................................... 261
eCheck Credit Request for a Non-Vantiv Processed Sale................................ 262
eCheck Credit Response .................................................................................. 263
eCheck Prenotification Credit Transactions (Batch Only)....................................... 264
eCheck Prenotification Credit Request ............................................................. 264
eCheck Prenotification Credit Response .......................................................... 265
eCheck Prenotification Sale Transactions (Batch Only) ......................................... 266
eCheck Prenotification Sale Request................................................................ 266
eCheck Prenotification Sale Response............................................................. 267
eCheck Redeposit Transactions ............................................................................. 268
eCheck Redeposit Request .............................................................................. 268
eCheck Redeposit Response............................................................................ 270
eCheck Sale Transactions ...................................................................................... 271
eCheck Sale Request ....................................................................................... 272
eCheck Sale Response..................................................................................... 273
eCheck Verification Transactions............................................................................ 275
eCheck Verification Request............................................................................. 275
eCheck Verification Response.......................................................................... 278
eCheck Void Transactions (Online Only)................................................................ 279
eCheck Void Request ....................................................................................... 279
eCheck Void Response..................................................................................... 280
Force Capture Transactions.................................................................................... 280
Force Capture Request..................................................................................... 280
Force Capture Response.................................................................................. 284
Load Transactions................................................................................................... 286
Load Request.................................................................................................... 286
Load Response................................................................................................. 287
Load Reversal Transactions (Online Only) ............................................................. 288
Load Reversal Request..................................................................................... 288
Load Reversal Response.................................................................................. 288
Refund Reversal Transactions (Online Only).......................................................... 289
Refund Reversal Request................................................................................. 290
Refund Reversal Response .............................................................................. 290
Register Token Transactions .................................................................................. 291
Register Token Request ................................................................................... 291
Register Token Response................................................................................. 294
RFR Transactions (Batch Only) .............................................................................. 297
RFR Request .................................................................................................... 297
RFR Response.................................................................................................. 298
Sale Transactions ................................................................................................... 299
cnpAPI Reference Guide Contents
xDocument Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
Sale Request..................................................................................................... 299
Sale Response.................................................................................................. 304
Unload Transactions ............................................................................................... 310
Unload Request ................................................................................................ 310
Unload Response.............................................................................................. 311
Unload Reversal Transactions (Online Only).......................................................... 312
Unload Reversal Request ................................................................................. 312
Unload Reversal Response .............................................................................. 313
Update Plan Transactions....................................................................................... 314
Update Plan Request........................................................................................ 314
Update Plan Response ..................................................................................... 315
Update Subscription Transactions .......................................................................... 315
Update Subscription Request ........................................................................... 315
Update Subscription Response......................................................................... 317
Update Card Validation Number Transactions........................................................ 318
Update Card Validation Number Request......................................................... 318
Update Card Validation Number Response ...................................................... 318
Void Transactions (Online Only) ............................................................................. 319
Void Request..................................................................................................... 320
Void Response.................................................................................................. 320
Chapter 4 cnpAPI Elements
accNum......................................................................................................................... 324
accountInfo ................................................................................................................... 325
accountInformation ....................................................................................................... 326
accountNumber............................................................................................................. 327
accountNumberLength ................................................................................................. 328
accountUpdate.............................................................................................................. 329
accountUpdateFileRequestData ................................................................................... 330
accountUpdater............................................................................................................. 331
accountUpdateResponse.............................................................................................. 335
accType ........................................................................................................................ 336
actionReason................................................................................................................ 337
activate ......................................................................................................................... 338
activateResponse ........................................................................................................ 339
activateReversal .......................................................................................................... 340
activateReversalResponse .......................................................................................... 341
active ............................................................................................................................ 342
addOnCode .................................................................................................................. 343
addressIndicator ........................................................................................................... 344
addressLine1, addressLine2, addressLine3 ................................................................. 345
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 xi
© 2018 Vantiv, LLC - All Rights Reserved.
advancedAVSResult ..................................................................................................... 346
advancedFraudChecks ................................................................................................ 347
advancedFraudResults ................................................................................................ 348
affiliate........................................................................................................................... 349
affluence .......................................................................................................................350
allowPartialAuth ............................................................................................................ 351
amexAggregatorData.................................................................................................... 352
amount..........................................................................................................................353
androidpayResponse ................................................................................................... 354
applepay ....................................................................................................................... 355
applepayResponse ....................................................................................................... 356
applicationData ............................................................................................................. 357
applicationExpirationDate ............................................................................................. 358
applicationPrimaryAccountNumber............................................................................... 359
approvedAmount........................................................................................................... 360
authAmount................................................................................................................... 361
authCode ...................................................................................................................... 362
authDate ....................................................................................................................... 363
authenticatedByMerchant ............................................................................................. 364
authentication................................................................................................................ 365
authenticationResult ..................................................................................................... 366
authenticationTransactionId.......................................................................................... 367
authenticationValue ...................................................................................................... 368
authInformation ............................................................................................................. 369
authorization ................................................................................................................. 370
authorizationResponse ................................................................................................. 371
authorizationSourcePlatform......................................................................................... 372
authReversal................................................................................................................. 373
authReversalResponse................................................................................................. 374
availableBalance........................................................................................................... 375
avsResult ...................................................................................................................... 376
balanceInquiry .............................................................................................................. 377
balanceInquiryResponse ............................................................................................. 378
batchRequest................................................................................................................ 379
batchResponse ............................................................................................................. 386
beginningBalance ........................................................................................................ 387
billingDate ....................................................................................................................388
billMeLaterRequest ....................................................................................................... 389
billMeLaterResponseData............................................................................................. 391
billToAddress ................................................................................................................ 392
bin ................................................................................................................................. 394
cnpAPI Reference Guide Contents
xii Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
bmlMerchantId .............................................................................................................. 395
bmlProductType............................................................................................................ 396
bypassVelocityCheck.................................................................................................... 397
campaign ...................................................................................................................... 398
cancelSubscription ....................................................................................................... 399
cancelSubscriptionResponse ....................................................................................... 400
capability ....................................................................................................................... 401
capture.......................................................................................................................... 402
captureGivenAuth ......................................................................................................... 403
captureGivenAuthResponse ......................................................................................... 405
captureResponse.......................................................................................................... 406
card............................................................................................................................... 407
cardAcceptorTaxId........................................................................................................ 409
cardholderAuthentication .............................................................................................. 410
cardholderId.................................................................................................................. 411
cardholderName ........................................................................................................... 412
cardOrToken ................................................................................................................. 413
cardProductType........................................................................................................... 414
cardSuffix......................................................................................................................415
cardValidationNum........................................................................................................ 416
cardValidationResult ..................................................................................................... 417
cashBackAmount ......................................................................................................... 418
catLevel ........................................................................................................................ 419
ccdPaymentInformation ................................................................................................ 420
chargeback ................................................................................................................... 421
checkNum..................................................................................................................... 422
city................................................................................................................................. 423
clinicOtherAmount......................................................................................................... 424
code .............................................................................................................................. 425
commodityCode............................................................................................................ 426
companyName.............................................................................................................. 427
country .......................................................................................................................... 428
createAddOn ................................................................................................................ 429
createDiscount ............................................................................................................. 430
createPlan .................................................................................................................... 431
createPlanResponse .................................................................................................... 432
credit ............................................................................................................................. 433
creditLine ......................................................................................................................435
creditLitleTxnId ............................................................................................................. 436
creditResponse ............................................................................................................. 437
cryptogram ................................................................................................................... 438
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 xiii
© 2018 Vantiv, LLC - All Rights Reserved.
currencyCode................................................................................................................ 439
customAttribute1........................................................................................................... 440
customBilling................................................................................................................. 441
customerInfo ................................................................................................................. 443
customerIpAddress....................................................................................................... 445
customerReference....................................................................................................... 446
customerRegistrationDate ............................................................................................ 447
customerType ............................................................................................................... 448
customerWorkTelephone.............................................................................................. 449
data............................................................................................................................... 450
deactivate .....................................................................................................................451
deactivateResponse .................................................................................................... 452
deactivateReversal ...................................................................................................... 453
deactivateReversalResponse ...................................................................................... 454
debtRepayment............................................................................................................. 455
deleteAddOn ................................................................................................................ 456
deleteDiscount ............................................................................................................. 457
deliveryType.................................................................................................................. 458
dentalAmount................................................................................................................ 459
depositReversal ........................................................................................................... 460
depositReversalResponse ........................................................................................... 461
description ....................................................................................................................462
descriptor ......................................................................................................................463
destinationCountryCode ............................................................................................... 464
destinationPostalCode .................................................................................................. 465
detailTax .......................................................................................................................466
deviceManufacturerIdentifier......................................................................................... 467
deviceReputationScore ................................................................................................ 468
deviceReviewStatus...................................................................................................... 469
discountAmount ............................................................................................................ 470
discountCode ............................................................................................................... 471
dob................................................................................................................................ 472
dutyAmount................................................................................................................... 473
echeck........................................................................................................................... 474
eCheckAccountSuffix ................................................................................................... 475
echeckCredit ................................................................................................................. 476
echeckCreditResponse................................................................................................. 478
echeckForToken ........................................................................................................... 479
echeckOrEcheckToken................................................................................................. 480
echeckPreNoteCredit ................................................................................................... 481
echeckPreNoteCreditResponse ................................................................................... 482
cnpAPI Reference Guide Contents
xiv Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
echeckPreNoteSale ..................................................................................................... 483
echeckPreNoteSaleResponse ..................................................................................... 484
echeckRedeposit .......................................................................................................... 485
echeckRedepositResponse .......................................................................................... 486
echeckSale ................................................................................................................... 487
echeckSalesResponse ................................................................................................. 488
echeckToken................................................................................................................. 489
echeckVerification......................................................................................................... 490
echeckVerificationResponse......................................................................................... 491
echeckVoid ................................................................................................................... 492
echeckVoidResponse ................................................................................................... 493
eciIndicator....................................................................................................................494
email ............................................................................................................................. 495
employerName.............................................................................................................. 496
encryptedTrack ............................................................................................................ 497
endDate ....................................................................................................................... 498
endingBalance ............................................................................................................. 499
enhancedAuthResponse............................................................................................... 500
enhancedData............................................................................................................... 502
entryMode..................................................................................................................... 506
ephemeralPublicKey ..................................................................................................... 507
expDate.........................................................................................................................508
expMonth ..................................................................................................................... 509
expYear ........................................................................................................................510
extendedCardResponse .............................................................................................. 511
filtering .......................................................................................................................... 512
finalPayment ................................................................................................................ 513
firstName.......................................................................................................................514
forceCapture ................................................................................................................. 515
forceCaptureResponse................................................................................................. 516
formatId ........................................................................................................................ 517
fraudCheck ................................................................................................................... 518
fraudCheckResponse .................................................................................................. 519
fraudFilterOverride ....................................................................................................... 520
fraudResult ................................................................................................................... 521
fundingSource............................................................................................................... 522
fundingSubmerchantId ................................................................................................. 523
fundsTransferId............................................................................................................. 524
giftCardBin ................................................................................................................... 525
giftCardResponse ........................................................................................................ 526
giropay ......................................................................................................................... 527
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 xv
© 2018 Vantiv, LLC - All Rights Reserved.
giropayResponse ......................................................................................................... 528
header .......................................................................................................................... 529
healthcareAmounts....................................................................................................... 530
healthcareIIAS .............................................................................................................. 531
iban .............................................................................................................................. 532
ideal .............................................................................................................................. 533
idealResponse ............................................................................................................. 534
IIASFlag ........................................................................................................................535
incomeAmount .............................................................................................................. 536
incomeCurrency............................................................................................................ 537
international .................................................................................................................. 539
intervalType ................................................................................................................. 540
invoiceReferenceNumber ............................................................................................. 541
issuerCountry................................................................................................................ 542
itemCategoryCode ........................................................................................................ 543
itemDescription ............................................................................................................. 544
itemDiscountAmount..................................................................................................... 545
itemSequenceNumber .................................................................................................. 546
ksn ................................................................................................................................ 547
lastName....................................................................................................................... 548
lineItemData.................................................................................................................. 549
lineItemTotal ................................................................................................................. 551
lineItemTotalWithTax .................................................................................................... 552
litleInternalRecurringRequest ....................................................................................... 553
litleOnlineRequest......................................................................................................... 554
litleOnlineResponse ...................................................................................................... 555
litleRequest ................................................................................................................... 557
litleResponse ................................................................................................................ 558
litleSessionId................................................................................................................. 560
litleToken....................................................................................................................... 561
litleTxnId........................................................................................................................ 562
load .............................................................................................................................. 563
loadResponse .............................................................................................................. 564
loadReversal ................................................................................................................ 565
loadReversalResponse ................................................................................................ 566
mandateProvider .......................................................................................................... 567
mandateReference ...................................................................................................... 568
mandateSignatureDate ................................................................................................ 569
mandateURL ................................................................................................................ 570
merchantData ............................................................................................................... 571
merchantGroupingId ..................................................................................................... 572
cnpAPI Reference Guide Contents
xvi Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
merchantId.................................................................................................................... 573
message ....................................................................................................................... 574
middleInitial...................................................................................................................575
mpos ............................................................................................................................. 576
name............................................................................................................................. 577
networkTransactionId ................................................................................................... 578
newAccountInfo ............................................................................................................ 579
newCardInfo ................................................................................................................. 580
newCardTokenInfo ....................................................................................................... 581
newTokenInfo ............................................................................................................... 582
nextRecycleTime ......................................................................................................... 583
number..........................................................................................................................584
numberOfPayments ..................................................................................................... 585
onlinePaymentCryptogram ........................................................................................... 586
orderDate...................................................................................................................... 587
orderId........................................................................................................................... 588
orderSource .................................................................................................................. 589
originalAccountInfo ....................................................................................................... 591
originalCard................................................................................................................... 592
originalCardInfo ............................................................................................................ 593
originalCardTokenInfo .................................................................................................. 594
originalToken ................................................................................................................ 595
originalTokenInfo .......................................................................................................... 596
originalTransactionAmount .......................................................................................... 597
originalNetworkTransactionId ...................................................................................... 598
password....................................................................................................................... 599
payerId.......................................................................................................................... 600
payFacCredit................................................................................................................. 601
payFacCreditResponse ............................................................................................... 602
payFacDebit ................................................................................................................. 603
payFacDebitResponse ................................................................................................. 604
paymentDataType ........................................................................................................ 605
paymentPurpose........................................................................................................... 606
paypage ........................................................................................................................ 607
paypageRegistrationId .................................................................................................. 608
paypal ........................................................................................................................... 609
payPalNotes.................................................................................................................. 610
payPalOrderComplete .................................................................................................. 611
phone............................................................................................................................ 612
phone as a child of billToAddress and shipToAddress ..................................... 612
phone as a child of customBilling...................................................................... 612
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 xvii
© 2018 Vantiv, LLC - All Rights Reserved.
physicalCheckCredit .................................................................................................... 613
physicalCheckCreditResponse .................................................................................... 614
physicalCheckDebit ...................................................................................................... 615
physicalCheckDebitResponse ..................................................................................... 616
pin ................................................................................................................................ 617
planCode ...................................................................................................................... 618
pos ................................................................................................................................ 619
postDate........................................................................................................................620
postDay ........................................................................................................................621
preapprovalNumber ...................................................................................................... 622
preferredLanguage ...................................................................................................... 623
prepaid.......................................................................................................................... 624
prepaidCardType .......................................................................................................... 625
processingInstructions .................................................................................................. 626
processingType............................................................................................................. 627
productCode ................................................................................................................. 628
publicKeyHash ............................................................................................................. 629
quantity ......................................................................................................................... 630
recurringRequest ......................................................................................................... 631
recurringResponse ....................................................................................................... 632
recurringTxnId .............................................................................................................. 633
recycleAdvice................................................................................................................ 634
recycleAdviceEnd ........................................................................................................ 635
recycleBy ...................................................................................................................... 636
recycleEngineActive ..................................................................................................... 637
recycleId ....................................................................................................................... 638
recycling ....................................................................................................................... 639
recycling Element as a Child of authorizationResponse or saleResponse............. 639
recycling Element as a Child of voidResponse....................................................... 640
recyclingRequest .......................................................................................................... 641
redirectToken ............................................................................................................... 642
redirectUrl ....................................................................................................................643
refundReversal ............................................................................................................. 644
refundReversalResponse ............................................................................................ 645
registerTokenRequest................................................................................................... 646
registerTokenResponse................................................................................................ 647
reloadable ..................................................................................................................... 648
reserveCredit ............................................................................................................... 649
reserveCreditResponse ............................................................................................... 650
reserveDebit ................................................................................................................. 651
reserveDebitResponse ................................................................................................. 652
cnpAPI Reference Guide Contents
xviii Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
residenceStatus ............................................................................................................ 653
response ....................................................................................................................... 654
responseCode .............................................................................................................. 655
responseMessage ........................................................................................................ 656
responseTime ............................................................................................................... 657
RFRRequest ................................................................................................................. 658
RFRResponse .............................................................................................................. 659
routingNum ................................................................................................................... 660
RxAmount ..................................................................................................................... 661
sale ............................................................................................................................... 662
saleResponse ............................................................................................................... 664
salesTax........................................................................................................................666
secondaryAmount ........................................................................................................ 667
sellerId .......................................................................................................................... 668
sellerMerchantCategoryCode ....................................................................................... 669
sepaDirectDebit ........................................................................................................... 670
sepaDirectDebitResponse ........................................................................................... 671
sequenceType ............................................................................................................. 672
shipFromPostalCode .................................................................................................... 673
shippingAmount ............................................................................................................ 674
shipToAddress .............................................................................................................. 675
signature .......................................................................................................................676
sofort ............................................................................................................................ 677
sofortResponse ............................................................................................................ 678
ssn ................................................................................................................................ 679
startDate ......................................................................................................................680
state .............................................................................................................................. 681
submerchantCredit ....................................................................................................... 682
submerchantCreditResponse ...................................................................................... 683
submerchantDebit ........................................................................................................ 684
submerchantDebitResponse ........................................................................................ 685
submerchantName........................................................................................................ 686
subscription .................................................................................................................. 687
subscriptionId ............................................................................................................... 689
surchargeAmount ......................................................................................................... 690
taxAmount..................................................................................................................... 691
taxExempt..................................................................................................................... 692
taxIncludedInTotal......................................................................................................... 693
taxRate.......................................................................................................................... 694
taxType .........................................................................................................................695
taxTypeIdentifier ........................................................................................................... 696
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 xix
© 2018 Vantiv, LLC - All Rights Reserved.
terminalId .....................................................................................................................697
termsAndConditions...................................................................................................... 698
threatMetrixSessionId .................................................................................................. 699
token ............................................................................................................................. 700
token (Vantiv generated card number replacement)............................................... 700
token (PayPal generated) ....................................................................................... 700
tokenMessage............................................................................................................... 702
tokenResponse ............................................................................................................. 703
tokenResponseCode .................................................................................................... 704
totalHealthcareAmount ................................................................................................. 705
track .............................................................................................................................. 706
track1Status ................................................................................................................. 707
track2Status ................................................................................................................. 708
transactionAmount ....................................................................................................... 709
transactionId ................................................................................................................. 710
transactionId as a Child of the paypal element ....................................................... 710
transactionId as a Child of the header element....................................................... 710
trialIntervalType ........................................................................................................... 712
trialNumberOfIntervals ................................................................................................. 713
triggeredRule ............................................................................................................... 714
type ............................................................................................................................... 715
type Element as a Child of the parent elements listed below.................................. 715
type Element as a Child of fundingSource.............................................................. 716
unitCost......................................................................................................................... 717
unitOfMeasure .............................................................................................................. 718
unload .......................................................................................................................... 719
unloadResponse .......................................................................................................... 720
unloadReversal ............................................................................................................ 721
unloadReversalResponse ............................................................................................ 722
updateAddOn ............................................................................................................... 723
updatedCard ................................................................................................................. 724
updateCardValidationNumOnToken ............................................................................. 725
updateCardValidationNumOnTokenResponse............................................................. 726
updateDiscount ............................................................................................................ 727
updatePlan ................................................................................................................... 728
updatePlanResponse ................................................................................................... 729
updateSubscription ...................................................................................................... 730
updateSubscriptionResponse ...................................................................................... 734
updatedToken............................................................................................................... 735
url.................................................................................................................................. 736
user............................................................................................................................... 737
cnpAPI Reference Guide Contents
xx Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
vendorCredit ................................................................................................................ 738
vendorCreditResponse ................................................................................................ 739
vendorDebit .................................................................................................................. 740
vendorDebitResponse ................................................................................................. 741
vendorName ................................................................................................................ 742
verificationCode ............................................................................................................ 743
verify ............................................................................................................................. 744
version ......................................................................................................................... 745
visionAmount ................................................................................................................ 746
virtualAccountNumber .................................................................................................. 747
virtualAuthenticationKeyData........................................................................................ 748
virtualAuthenticationKeyPresenceIndicator .................................................................. 749
virtualGiftCard .............................................................................................................. 750
virtualGiftCardResponse .............................................................................................. 751
void ............................................................................................................................... 752
voidResponse ............................................................................................................... 754
wallet ............................................................................................................................ 755
walletSourceType ........................................................................................................ 756
walletSourceTypeId ..................................................................................................... 757
yearsAtEmployer........................................................................................................... 758
yearsAtResidence......................................................................................................... 759
zip ................................................................................................................................. 760
Appendix A Payment Transaction Response Codes
Payment Transaction Response Codes ....................................................................... 762
3DS Authentication Result Codes................................................................................. 784
AVS Response Codes .................................................................................................. 786
AAVS Response Codes................................................................................................ 787
Card Validation Response Codes................................................................................. 790
Advanced Fraud Tools Triggered Rules ....................................................................... 791
XML Validation Error Messages ................................................................................... 806
Additional Response Header Error Messages.............................................................. 808
ACH Return Reason Codes.......................................................................................... 809
ACH NoC Change Codes ............................................................................................. 813
Canadian eCheck Return Codes .................................................................................. 814
cnpAPI Reference Guide Contents
Document Version: 1.32 — XML Release: 9.14 xxi
© 2018 Vantiv, LLC - All Rights Reserved.
Appendix B Credit Card Number Formats
Appendix C Test Card Numbers
Appendix D PayFac™ Dynamic Payout
Advantages of Using Dynamic Payout.......................................................................... 826
Overview of Dynamic Payout........................................................................................ 827
Timing of Transactions, Reports, and Money Movement........................................ 828
Money Movement and Accounts............................................................................. 829
Account Balance Verifications........................................................................... 830
Example of Funding Instruction Session File................................................................ 832
Funding Instruction Certification Testing....................................................................... 835
SSR Reports................................................................................................................. 837
cnpAPI Reference Guide Contents
xxii Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
Document Version: 1.32 — XML Release: 9.14 xxiii
© 2018 Vantiv, LLC - All Rights Reserved.
ABOUT THIS GUIDE
This manual serves as a reference to the cnpAPI transaction formats used for payment processing
with Vantiv, LLC. It also explains how to perform unattended transaction testing and attended
certification testing with Vantiv.
Intended Audience
This document is intended for technical personnel who will be setting up and maintaining
payment processing using the cnpAPI format.
Revision History
This document has been revised as follows:
TABLE 1 Document Revision History
Doc.
Version Description Location(s)
1.0 Initial release of LitleXML Reference Guide for schema V9.0.
Added information about PayFac Instruction-Based funding.
Added information about Mobile Point of Sale feature.
N/A
Chapter 1 & Appendix D
Chapter 1
1.1 Added Cert test cases for MasterCard MasterPass Chapter 2
1.2 Added information about new (Batch only) transaction types for
eCheck Prenotification. Note: These transaction types are not
yet Generally Available. Examples will be added later.
Chapter 4
Added applepay enum to the orderSource element. Also,
changed MaxLength of authenticationValue element from
32 to 56.
Chapter 4
About This Guide Revision History
xxiv Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.3 Added several new elements for Apple Pay transactions and for
convenience Fees added in schema version V9.2. Chapter 4
Added info about new transaction types associated with the
PayFac Instruction-Based Dynamic Payout.
Added explanations and examples of eCheck Prenotification
transactions, as well as Cert test info.
Chapter 4 and Appendix
D
Chapters 1, 2, and 3
1.4 Added secondaryAmount element for Convenience Fees credit
and echeckCredit transaction types. Also added certification
tests for Convenience fees and Response Reason Codes
(380-385).
Chapters 2,and 4
Appendix A
Added account markers for use with Advanced Fraud Tools.
Augmented the description of eCheck Prenotification.
Added ccdPaymentInformation to the echeck element for use
by PayFacs using Instruction-Based Dynamic Payout.
Chapters 1 and 4
Chapter 1
Chapter 4
1.5 Minor corrections and change to recommended Batch size.
Updated info about several ApplePay elements. Also added
cardSuffix element.
Chapter1
Chapter 4
Added two new Response Codes (530 and 531) for Apple Pay. Appendix A
1.6 Added sections about Apple Pay options and Certification tests. Chapters 1 and 2
Added more Triggered Rule Definitions for Advanced Fraud
Tools. Appendix A
Added info about front-end check performed on funding
instruction batches. Appendix D
1.7 Added information about support for eChecks in Canada.
Changed maxLength of terminalId element from 10 to 8.
Changed applicationData element from required to optional.
Removed test for Unknown Session response from Advanced
fraud Tools tests.
All
Chapter 4
Chapter 4
Chapter 2
1.8 Miscellaneous minor corrections.
Added Note about use of pipe character, "|", in orderId.
Added two new Advanced Fraud Triggered Rules.
Chapters 2, 3, & 4
Chapter 4
Appendix A
TABLE 1 Document Revision History
Doc.
Version Description Location(s)
Revision History About This Guide
Document Version: 1.32 — XML Release: 9.14 xxv
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.9 Miscellaneous minor corrections.
Added note about Visa Level 3 data requirements.
Added applepayResponse element to structural examples.
Also, added notes about structure of the applepayResponse
element for Register token transactions.
All
Chapter 4
Chapters 3 & 4
1.10 Eliminated references to self-certification.
Eliminated references to white-listed IP Address requirement.
Minor corrections.
Added list of Canadian eCheck Return Codes
Chapter 2
Chapter 2
All
Appendix A
1.11 Added XML example of saleResponse with recurring info.
General update to Appendix D.
Chapter 3
Appendix D
1.12 Clarified definition of fundingSubmerchantId element. Chapter 4
1.13 Added new Triggered Rules to Table A-6.
Added info about new processingType element (XML V9.6).
Corrected definitions of transactionId and
applicationData elements (child of header).
Appendix A
Chapters 3 & 4
Chapter 4
1.14 Added VisaCheckout enum to the walletSourceType
element. Chapter 4
1.15 Changed all 2016 expiration dates in tests to 2021.
Added information about Vantiv eComm support for Android
Pay, as well as certification test and element information.
Chapter 2
Chapters 1, 2, and 4
1.16 Added information about the pin element (Gift Card) and
updated various examples to include the new element. Chapters 3 and 4
1.17 Corrected definitions of <wallet> element and its child elements.
Added information about Response Code 823.
Chapter 4
Appendix A
1.18 Purged info about PayPal Credit (aka BillMeLater) support and
added notes to PayPal Credit elements in schema. All
1.19 Corrected <amount> in Cert tests cases 10 through 13.
Added 2-series MC test card numbers to list.
Chapter 2
Appendix C
1.20 Added info to Apple Pay section.
Added information about new networkId and related elements
introduced in XML V9.10.
Chapter 1
Chapters 1 and 4
TABLE 1 Document Revision History
Doc.
Version Description Location(s)
About This Guide Revision History
xxvi Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.21 Corrected minor typos in some examples and Notes.
Added eciIndicator element to anodroidpayResponse.
Corrected Apple Pay and Android Pay recurring sections to
reflect correct element names.
All
Chapter 4
Chapter 1
1.22 Removed section about Health Care card support feature.
Added more Convenience Fee test (partial capture).
Added section about SEPA payments and new SEP elements.
Added new elements for iDeal method of payment (not GA).
Chapter 1
Chapter 2
Chapters 1, 3, and 4
Chapters 3 and 4
1.23 Added example of Sessionless Advanced Fraud request.
Add info about new Report Group creation limits.
Augment information about SEPA capabilities.
Added SEPA Cert test info.
Added info to Apple Pay section about using a Register Token
Request prior to submitting an Auth/Sale.
Added code R900 to list of Canadian eCheck Return Codes
Added SEPA related Response Codes 379, 386, and 901
through 916.
Chapter 1
Chapter 1
Chapter 1
Chapter 2
Chapter 1
Appendix A
Appendix A
1.24 Augment information about SEPA capabilities.
Revamped Fraud Toolkit section
Changed salesTax requirements for Level 2 and Level 3 data.
Removed R900 eCheck Return Code and added 900-x series.
Chapter 1
Chapter 1
Chapter 4
Appendix A
1.25 Added information about the iDEAL international payment
method, which is now GA. Chapters 1, 2, and 4
1.26 Corrected times for Pre/Post-Live Maintenance Windows. Chapter 2
1.27 Replaced LitleXML with cnpAPI.
Added information about SOFORT and Giropay.
Replaced Customer Insights section with Issuer Insights
section.
All
Chapters 1, 2, and 4
Chapter 1
1.28 Corrected Response Code for Test GC17 - 281 changed to 218.
Updated Litle to Vantiv in Response messages.
Added Note about expDate to token element definition.
Chapter 2
All
Chapter 4
1.29 Added/modified information in section 2.1.
Modified requirements for Level 2/3 data (enhancedData
element).
Chapter 2
Chapter 4
TABLE 1 Document Revision History
Doc.
Version Description Location(s)
Document Structure About This Guide
Document Version: 1.32 — XML Release: 9.14 xxvii
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Document Structure
This manual contains the following sections:
Chapter 1, "Introduction"
This chapter provides an introduction to transaction processing using the cnpAPI.
Chapter 2, "Testing Your cnpAPI Transactions"
This chapter provides information concerning the testing and certification process, which you
must complete prior to submitting transactions to the Vantiv production environment.
Chapter 3, "cnpAPI Transaction Examples"
This chapter provides information concerning the cnpAPI structure for transaction submission, as
well as examples.
Chapter 4, "cnpAPI Elements"
This chapter provides definitions and other information concerning each cnpAPI element.
1.30 Removed Mobile Point of Sale material from Guide.
Fix Sandbox/github links to point at new domains.
Fixed error in definition of customerReference element.
Added info about support for Visa token transactions with 3-D
Secure (TAVV and DTVV), as well as new 3-DS response code
definitions.
Chapters 1 and 2
Chapter 2
Chapter 4
Chapter 4 & Appendix A
1.31 Removed reference to Recurring Snapshot report.
Updated Android Pay Certification test results.
Modified the descriptions of several elements associated with
the use of Network Transaction Id (processingType,
networkTransactionId,
originalnetworkTransactionId, and
originalTransactionAmount).
Chapter 1
Chapter 2
Chapter 4
1.32 Added info about Response Reason Code 825.
Added info about allowing 60 second gap between a
transaction and submitting a Void.
Added processingType enums for Card on File transactions.
Appendix A
Chapters 1, 3, & 4
Chapter 4
TABLE 1 Document Revision History
Doc.
Version Description Location(s)
About This Guide Document Structure
xxviii Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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.
Document Structure About This Guide
Document Version: 1.32 — XML Release: 9.14 xxix
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Documentation Set
For additional information concerning the Vantiv application, see any of the following guides in
the documentation set:
iQ Reporting and Analytics User Guide
Vantiv Chargeback API Reference Guide
Vantiv Chargeback Process Guide
Vantiv eCommerce Partner Integration Overview Guide
Vantiv PayPal™ Integration Guide
Vantiv PayFac™ API Reference Guide
Vantiv PayFac™ Portal User Guide
Vantiv PayFac™ Integration Overview Guide
Vantiv eProtect™ Integration Guide
Vantiv Enterprise eProtect™ Integration Guide
Vantiv cnpAPI Differences Guide
Vantiv Secure Scheduled Reports Reference Guide
About This Guide Typographical Conventions
xxx Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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:
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.
Contact Information About This Guide
Document Version: 1.32 — XML Release: 9.14 xxxi
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference 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.
Chargebacks - For business-related issues and questions regarding financial transactions and
documentation associated with chargeback cases, contact the Chargebacks Department.
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.
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.
Implementation Contact Information
E-mail implementation@vantiv.com
Hours Available Monday – Friday, 8:30 A.M.– 5:30 P.M. EST
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 Contact Information
E-mail eCommerceSupport@vantiv.com
Hours Available 24/7 (seven days a week, 24 hours a day)
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
About This Guide Contact Information
xxxii Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Technical Publications - For questions or comments about this document, please address your
feedback to the Technical Publications Department. All comments are welcome.
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 Contact Information
E-mail TechPubs@vantiv.com
Document Version: 1.32 — XML Release: 9.14 1
© 2018 Vantiv, LLC - All Rights Reserved.
1
INTRODUCTION
The cnpAPI data format supports two types of transaction submission methods: Online and
Batch. With the Online method, you submit each transaction independently and receive a
response in real-time. Typically, merchants use the Online method for Authorization transactions,
as well as transactions available only via Online (for example, Void). The Batch method enables
you to submit multiple transactions simultaneously in a single Session file. Vantiv recommends
the Batch method for all transaction submissions except Authorizations and the transaction
available only via Online.
This chapter provides an overview of the cnpAPI data format, including some basic XML coding
requirements. Also discussed are the advantages of using batch processing, duplicate transaction
detection, report groups, Value Added Services, and supported transaction types.
The topics discussed in this chapter are:
The cnpAPI Data Format Fraud Toolkit
Batch Transaction Processing Tokenization Feature
Payment Integration Platform (cnpAPI
SDKs) eCheck Processing
Duplicate Transaction Detection SEPA Direct Debit
Coding for Report Groups iDEAL, SOFORT, and Giropay
Recovery eCommerce Solution for Apple Pay™
Recurring Engine eCommerce Solution for Android Pay™
Issuer Insights Supported Transaction Types
Introduction The cnpAPI Data Format
2Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.1 The cnpAPI Data Format
Although Vantiv supports transaction processing via many data formats, there are several
advantages to using the cnpAPI format. Some of the advantages are as follows:
Easier Implementation, Operations, and Debugging - Compared to fixed length or binary
formats, the XML format is considerably easier for operations staff to read and edit, using
virtually any text editor. This allows Vantivs Implementation, First Line Support, and
Customer Experience Managers to quickly communicate any issues and work with your own
operations staff to make necessary corrections without worrying about line lengths, padding
or encoding.
Fewer Downgrades - Since the cnpAPI format allows you to explicitly tie deposits to their
associated authorizations via the <litleTxnId> 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 <litleTxnId> element, our format does not require
you to resubmit all of the authorization information on a deposit nor all of the deposit
information on a refund. When you submit the unique transaction id, Vantiv automatically
pulls the information from the original transaction. Most other formats require you to
resubmit the related data with each transaction.
Superior Reporting - The cnpAPI format allows you to separate your transactions into
different categories by specifying a Report Group on each transaction. When accessing your
data on the iQ reporting and Analytics Interface, this feature allows you to filter your
financial reports by Report Groups, providing more granular detail based on a reporting
hierarchy the Report Groups create. Most other formats restrict reporting categories to a batch
or specific merchant id.
Improved Chargeback Management - Unlike most other formats where transactional
relationships can be a “best guess” proposition, the cnpAPI format explicitly ties related
transactions, allowing you and Vantiv to see authorization-to-deposit and deposit-to-refund
relationships with precision. This knowledge is indispensable when fighting chargebacks.
New Features - New features developed for the Vantiv eCommerce platform are first
exposed via the XML API. While the SDKs and DevHub add new capabilities shortly after
development, direct coding to the XML API gains access to these feature and capabilities
earlier.
1.1.1 Communications Protocols
There are two communication protocols supported for the submission of Batch transactions to
Vantiv eCommerce platform for processing and one for Online submissions as shown in
Table 1-1. For Batch submissions Vantiv recommends that you use one of the two FTP methods.
Use the HTTPS Post method for Online transactions.
The cnpAPI Data Format Introduction
Document Version: 1.32 — XML Release: 9.14 3
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
If you use the standard FTP method, you must use either the Pretty Good Privacy (PGP) or the
open source GNU Privacy Guard (GPG) encryption for your submissions. Both of these
encryption methods use key cryptography and support message authentication and integrity
checking. The alternate method, Secure FTP (sFTP), uses Secure Shell (SSH) to secure the
transmission.
The Vantiv eComm platform supports the following ciphers for the TLS 1.2 encryption protocol:
NOTE:Although the Vantiv eComm platform currently supports both TLS 1.1 and
TLS 1.2, Vantiv strongly recommends the use of TLS 1.2 to ensure the
best encryption security.
TABLE 1-1 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
TABLE 1-2 Supported TLS Ciphers
Server
Priority Ciphe
r Id Cipher Name TLS 1.2
Support TLS 1.1
Support
1 c030 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 Yes No
2 c02f TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 Yes No
3 c028 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 Yes No
4 c014 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA Yes Yes
5 c027 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 Yes No
6 c013 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA Yes Yes
7 009d TLS_RSA_WITH_AES_256_GCM_SHA384 Yes No
8 009c TLS_RSA_WITH_AES_128_GCM_SHA256 Yes No
9 003d TLS_RSA_WITH_AES_256_CBC_SHA256 Yes No
10 003c TLS_RSA_WITH_AES_128_CBC_SHA256 Yes No
11 0035 TLS_RSA_WITH_AES_256_CBC_SHA Yes Yes
12 002f TLS_RSA_WITH_AES_128_CBC_SHA Yes No
Introduction The cnpAPI Data Format
4Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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-3). For example, the
less than (<) and greater than (>) symbols define element tags in the XML code. Using the
entity names &lt; and &gt; 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 &amp; Main" (including quotes) before
being submitted via XML. Failure to quote this type of input causes rejection of XML
submissions due to syntax errors.
1.1.3 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:
http://www.w3schools.com/xml/xml_syntax.asp
http://www.w3.org/
http://www.utf-8.com/
TABLE 1-3 Coding for Special Characters
Character Description Entity Reference (case sensitive)
<less than &lt;
>greater than &gt;
quotation &quot;
apostrophe &apos;
&ampersand &amp;
Batch Transaction Processing Introduction
Document Version: 1.32 — XML Release: 9.14 5
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.2 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 <litleRequest> element. A single
<litleRequest>, 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.
Introduction Payment Integration Platform (cnpAPI SDKs)
6Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.3 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.
Duplicate Transaction Detection Introduction
Document Version: 1.32 — XML Release: 9.14 7
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.4 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.
1.4.1 Batch Duplicate Checking
When processing a Batch, the system acts to detect duplicate transactions for the following
transaction types: Authorization, Auth Reversal, Capture, Force Capture, Capture Given Auth,
Credit, Sales, eCheck Credit, and eCheck Sales.
For each of these transaction types, the application compares the transaction type, transaction
amount, the <orderId> element from the request, credit card number, and credit card expiration
date against transactions in other Batch processed within the previous five days. If the
characteristics of the new transaction match a previously processed transaction, the system marks
it as a duplicate.
The system only performs duplicate detection against valid transactions from the previous five
days. For example, if an Authorization request matches a declined Authorization from the
previous day, the system would not count it as a duplicate, because the declined Authorization
was not a valid Authorization.
Also, a Batch must be processed completely to be included in the previous five days of data. For
example, if multiple submitted Batches are processing simultaneously, the system will not
compare the transactions in one batch with the transactions in the other, because neither has
completed processing. For this same reason the system cannot detect duplicate transactions within
the same Batch.
If the system detects ten consecutive duplicate transactions or if the number of duplicate
transactions is greater than or equal to 25% of the total transactions in the batch, the system flags
the Batch as a duplicate. When either threshold is met, Vantiv will not process the Batch. If
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 (consumers)
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.
Introduction Duplicate Transaction Detection
8Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
neither threshold is met, Vantiv continues processing the Batch, including any transactions that
may have been duplicates.
1.4.2 Online Duplicate Checking
When processing an Online transaction, the system acts to detect duplicate transactions for the
following transaction types: Auth Reversal, Capture, Force Capture, Capture Given Auth, Credit,
Sales, eCheck Credit, eCheck Sales, eCheckVoid, and Void.
For most transactions, the system compares the transaction type, the id attribute from the request,
and the credit card number against other Online transactions processed within the previous two
days. For transactions that reference other transactions (for example, a deposit referencing an
authorization or a refund referencing a deposit), the system compares the transaction type, id
attribute, and the card number from the referenced transaction (i.e. the transaction identified by
the <litleTxnId> 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.
If the system determines a transaction to be a duplicate, it returns the original response message
with the duplicate attribute set to true (see example below). This attribute indicates that the
response was returned on a previous transaction.
IMPORTANT:For Online transactions, if you do not include the id attribute in the
request, or if you set the id attribute to null (id=""), duplicate Checking is
not performed.
NOTE:While it is uncommon, under certain circumstances network latency may
cause a duplicate Sale transaction to go undetected as a duplicate. This
can occur if you submit a second, duplicate Sale transaction while the
response from the network for the Authorization portion of the first
transaction is sufficiently delayed such that the first Sale has not been
recorded as a valid transaction in the system.
If you elect to submit Online Sale transactions, Vantiv recommends a
timeout setting of not less than 60 seconds to reduce the chances of
undetected duplicate Sale transactions.
Duplicate Transaction Detection Introduction
Document Version: 1.32 — XML Release: 9.14 9
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Example: captureResponse for a duplicate Capture
<litleOnlineResponse version="9.13" xmlns="http://www.litle.com/schema"
response="0" message="Valid Format">
<captureResponse id="2" duplicate="true" reportGroup="ABC Division">
<litleTxnId>1100030204</litleTxnId>
<orderId>65347567</orderId>
<response>000</response>
<responseTime>2016-08-11T14:48:48</responseTime>
<postDate>2016-08-11</postDate>
<message>Approved</message>
</captureResponse>
</litleOnlineResponse>
NOTE:If you do not receive a response for a submitted transaction, Vantiv
recommends you re-send the transaction. If Vantiv received and
processed the original transaction, you will receive a duplicate response.
If Vantiv did not receive the original transaction, the new submission will
be processed.
Introduction Coding for Report Groups
10 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.5 Coding for Report Groups
You use Report Groups (reportGroup attribute) to separate your transactions into different
categories, so you can view the financial reports by your specific report group names. If you are
unsure what groupings to use, your Customer Experience Manager can help you determine the
best practice for your business.
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.
FIGURE 1-1 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.
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.
NOTE:The reportGroup attribute is case and space sensitive. A reportGroup =
“Picture Frame” is a different report group than a reportGroup =
“pictureframe”.
Coding for Report Groups Introduction
Document Version: 1.32 — XML Release: 9.14 11
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
FIGURE 1-2 Report Group Example - Expanded to Show Child Groups
1.5.1 Additional/Alternate Methods of Tagging Transactions
If you are using schema version 7.x or above you can use the merchantData element and its
children to tag transactions (Authorization, Sale, Credit, Force Capture, Capture Given Auth,
eCheck Sale, and eCheck Credit) with additional information. The three children of
merchantData: campaign, affiliate, and merchantGroupingId, allow you to designate
transactions as members of different groups enabling a deeper analysis of sales patterns.
For example, if the merchant from the previous example were trying a new sales initiative for
Product 2 during the month of September. They plan to run ads in Boston and New York to test
the new offering. To allow a deeper analysis of sales resulting from the new campaign, they can
add the campaign element with a value of "September Ads" to the transactions originating in
both test market. They can also include the merchantgroupingId with values that reflect the
city where the order originates. By exporting either the Session report or the NSS by Transaction
report from the iQ, the company can sort their sales data based upon these fields and gain a better
understanding of the effectiveness of the sales campaign.
NOTE:The transaction tagging elements described above appear in the exported
Session and NSS by Transaction reports. They are also visible within the
iQ in the new Transaction Detail reports.
Introduction Recovery
12 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.6 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.
Recovery Introduction
Document Version: 1.32 — XML Release: 9.14 13
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Vantiv provides the results of the recycling efforts to you in a Batch posted daily to your Vantiv
sFTP account. This file contains transactions that either approved or exhausted the recycling
pattern on the previous day. If you submit an Authorization for a transaction in the recycling
queue, Vantiv returns the response from the last automatic recycling attempt. To halt recycling of
a particular transaction, submit either an Authorization reversal transaction, if the original
transaction was an Auth, or a Void transaction, if the original transaction was a Sale.
Declined Transactions Not Recycled
The system does not recycle transactions declined with one of the Response Codes listed in
Table 1-4 below. The <recycleEngineActive> element in the response files indicates if the
transaction is being handled by the Recycling Engine.
1. Not recycled for MasterCard, unless updated account information is available.
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.
TABLE 1-4 Response Codes Not Recycled
Response Code Message
213 Pickup Card - Lost Card
214 Pickup Card - Stolen Card
303 Pick up Card1
304 Lost/Stolen Card1
305 Expired Card1
308 Restricted Card - Chargeback
309 Restricted Card - Prepaid Card Filtering Service
312 Restricted Card - International Card Filtering Service
315 Restricted Card - Auth Fraud Velocity Filtering Service
318 Restricted Card - Auth Fraud Advice Filtering Service
323 No such Issuer1
328 Cardholder requested that recurring or installment payment be stopped
358 Restricted by Vantiv due to security code mismatch
550 Restricted Device or IP - ThreatMetrix Fraud Score Below Threshold
Introduction Recovery
14 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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 <recycleId> element
Value of the <orderId> element
Values of the <orderId>, <number>, and <amount> elements
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 <recycleBy>
element set to None. There are also global controls that allow you to exclude transactions based
upon either submission by a particular presenter, or based upon the transaction type (authorization
or sale). Please consult your Customer Experience Manager about the global options, since they
must be configured in your Vantiv Merchant Profile.
1.6.2 Account Updater Service
Credit and debit card numbers change for a variety of reasons including card expirations, card
product type upgrades, portfolio conversions, and compromised account numbers among others.
For merchants who offer services that are billed on a recurring or installment basis (for example,
web hosting, gym memberships, specialized social networking, career services, monthly donation
plans, etc.) out-of-date payment information can result in lost revenue, involuntary churn and
decreased customer satisfaction.
Prior to the development of the Account Updater service, the standard method for merchants to
obtain updated account information was to submit a Batch containing existing card information,
requesting that Vantiv check for updates. Typically, merchants request updates for customer
accounts scheduled to be billed in the next billing cycle. This legacy method is a relatively slow
process, requiring several days for Vantiv to accumulate responses from the card networks/issuers
and then to make the response file available to the merchant. Merchants must then update their
billing systems with the new information, requiring IT processing cost. Failure to update their
files can result in multiple requests (and charges) for the update information, as well as delays in
or lost revenue, higher Authorization expenses, and possibly chargebacks when old account
information is used.
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.
Recovery Introduction
Document Version: 1.32 — XML Release: 9.14 15
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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
1.6.2.1 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,
Merchant Card Networks
Submit
Transaction
Scheduled
AU Requests
Process
and
Store
Matches
Response
with
updates
from
Network
Re-Submit
Transaction
(+ 3 days)
Auth
Vantiv Submits
Auth w/Repaired
Card Info (if info
on file)
Auth
Vantiv Repairs
Card Info and
Submits Auth
Vantiv Adds
Account Info to
Next Scheduled
AU Request
Auth Decline if updated
info not yet on file
Auth Approval
Auth Approval
Introduction Recovery
16 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
after receiving an update, you submit a transaction with the old information, systems detect that
you are using the old data and update the transaction for you prior to submitting it to the networks
for authorization.
Please consult your Customer Experience Manager for additional information and configuration
options.
FIGURE 1-4 Match Back Overview
Merchant Card Networks
Scheduled
AU Requests
Process
and Store
Matches
(Next
Payment)
Submit
Transaction
w/New Info
Submit for Auth Auth
Submit
Transaction
Re-Submit
Transaction
(+ 3 days)
Auth
Vantiv Submits
Auth w/Repaired
Card Info (if info
on file)
Auth
Vantiv Repairs
Card Info and
Submits Auth
Vantiv Adds
Account Info to
Next Scheduled
AU Request
Auth Decline if updated
info not yet on file
Auth Approval w/New
Card Info
Auth Approval w/New
Card Info
Response
with
updates
from
Network
Recovery Introduction
Document Version: 1.32 — XML Release: 9.14 17
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.6.2.2 Merchant Requirements
In order to use the Account Updater service, you must first apply for membership to the
following:
MasterCard Automatic Billing Updater
Visa Account Updater
Discover Account Updater (not required by Discover for Vantiv acquired merchants)
Your Account Updater Welcome Kit includes the required application forms. If you have any
questions about these forms, contact your Customer Experience Manager, who can walk you
through the application process. Approval from Visa and MasterCard typically takes between
10-15 business days. Normally, merchants are approved without issue; however, you can be
declined for a variety of reasons. For example, merchants on a risk mitigation program typically
are not accepted.
1.6.2.3 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.
NOTE: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
Introduction Recurring Engine
18 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.7 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.
Recurring Engine Introduction
Document Version: 1.32 — XML Release: 9.14 19
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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
<createPlan>
<planCode>3_Year_Monthly</planCode>
<name>3Year_Monthly</name>
<description>3 Year, monthly Payments, 1 month trial</description>
<intervalType>MONTHLY</intervalType>
<amount>4166</amount>
<numberOfPayments>36</numberOfPayments>
<trialNumberOfIntervals>1</trialNumberOfIntervals>
<trialIntervalType>MONTH</trialIntervalType>
<active>true</active>
</createPlan>
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 <recurringRequest> 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.
TABLE 1-5 Example Pans
Plan Code Payment
Interval 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
Introduction Recurring Engine
20 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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
<authorization id="834262" reportGroup="ABC Division" customerId="038945">
<orderId>65347567</orderId>
<amount>0</amount>
<orderSource>ecommerce</orderSource>
<billToAddress>
.
.
.
</billToAddress>
<card>
.
.
.
</card>
<recurringRequest>
<subscription>
<planCode>1_Year_Monthly</planCode>
<numberOfPayments>10</numberOfPayments>
<startDate>2017-06-21</startDate>
<amount>6000</amount>
</subscription>
</recurringRequest>
</authorization>
Recurring Engine Introduction
Document Version: 1.32 — XML Release: 9.14 21
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.7.2.1 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
<updateSubscription>
<subscriptionId>1234</subscriptionId>
<createDiscount>
<discountCode>4GBExtraDeal</discountCode>
<name>Half-Off 1st Payment 4GB Extra</name>
<amount>1000<amount>
<startDate>2016-09-15</startDate>
<endDate>2017-09-14</endDate>
</createDiscount>
<createAddOn>
<addOnCode>4GB_Extra</addOnCode>
<name>Four_GB_Extra</name>
<amount>2000<amount>
<startDate>2016-09-15</startDate>
<endDate>2017-04-15</endDate>
</createAddOn>
</updateSubscription>
1.7.3 Recurring Reports
In addition to recurring transactions appearing in the normal Vantiv reports (i.e., Payment Detail,
Reconciliation report, etc.), there is an additional report associated specifically with the Recurring
Engine. Available via sFTP, this report is in Batch format and contains cnpAPI saleResponse
messages for all recurring transactions run that day, including all approvals and declines (see the
example, Batch Sales Response with Recurring Info on page 308).
Introduction Recurring Engine
22 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.7.4 Transaction Types and Uses
The table below provides information about the various Recurring Engine transaction types and
their uses.
TABLE 1-6 Recurring Engine Transaction Types
Use Case/Intent Parent Element Description/Uses
Create Plan createPlan Used to create new Plans.
Update Plan
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.
Create Subscription
<authorization> or <sale>
<recurringRequest>
<subscription>
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 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.
Cancel Subscription cancelSubscription Used to cancel an existing Subscription.
Create Add On
<authorization> or <sale>
<recurringRequest>
<subscription>
<createAddOn>
Or
<updateSubscription>
<createAddOn>
Used to create an Add On charge
associated with the Subscription.
Update Add On <updateSubscription>
<updateAddOn>
Used to modify one or more of the
parameters associated with the Add On.
Recurring Engine Introduction
Document Version: 1.32 — XML Release: 9.14 23
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Delete Add On <updateSubscription>
<deleteAddOn>
Used to delete an Add On charge from
the associated Subscription.
Create Discount
<authorization> or <sale>
<recurringRequest>
<subscription>
<createDiscount>
Or
<updateSubscription>
<createDiscount>
Used to create a Discount charge
associated with the Subscription.
Update Discount <updateSubscription>
<updateDiscount>
Used to modify one or more of the
parameters associated with the
Discount.
Delete Discount <updateSubscription>
<deleteDiscount>
Used to delete a Discount from the
associated Subscription.
TABLE 1-6 Recurring Engine Transaction Types
Use Case/Intent Parent Element Description/Uses
Introduction Issuer Insights
24 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.8 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
Issuer Insights Introduction
Document Version: 1.32 — XML Release: 9.14 25
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
availableBalance element stating the outstanding balance remaining on the card (if
available).
Knowing that the card is prepaid at the time of sale, as well as if it is reloadable and the available
balance, is especially useful for merchants engaged in recurring payment, installment payment, or
deferred billing scenarios. Merchants in these situations can use the information made available
by this feature to make intelligent decisions concerning the profitable management of prepaid
card usage by avoiding several factors that may contribute to lost revenue, while taking advantage
of other opportunities that may add to revenue and enhance the customer experience.
For example, one possible situation merchant can avoid is fraudulent deferred/installment
payment purchases made with a prepaid card that does not have enough available balance to
cover the subsequent payments. With the available balance known, merchants can determine if
the card can meet the required payment structure. If the card’s balance does not meet the required
threshold, the merchant can request another payment method, which may result in eliminating
fraudsters, while retaining legitimate customers. If the card is non-reloadable, it is advisable to
not accept the card at all for recurring payments regardless of the available balance.
Another more common situation occurs when the consumer is unaware of the card balance. If the
transaction is rejected due to inadequate balance, perhaps repeatedly, it could result in an
unsatisfied customer and an abandoned purchase. Alternately, the card could have slightly more
that the required balance, which the consumer would spend, if they had the knowledge. If the
available balance is insufficient for the purchase, the merchant can obtain a second or alternate
payment method. If the balance is higher than required for the purchase, the merchant may be
able to encourage additional purchases.
In addition to indicating if the submitted card is a prepaid card and the available balance, this
feature includes information about whether the card is reloadable and the specific type of prepaid
card (i.e., TEEN, GIFT, PAYROLL, etc.). You can use this information to further refine your sales
and marketing strategies.
1.8.2.2 Affluence Indicator
Visa, MasterCard, and Discover provide enhanced credit card products for consumers with high
disposable incomes and high card spending. These cards encourage usage by offering the
cardholders additional benefits usually including reward incentives, no pre-set spending limit,
higher authorization approval rates, faster access to a customer service representatives, and
dedicated chargeback resolution support.
Vantiv analysis of payments data indicates that consumers using these cards types typically spend
more per order than consumers using traditional credit and debit cards. The Affluence Indicator
feature provides the ability for merchants to segment their consumers based on the affluence level
as determined by the issuer. Within the cnpAPI Authorization response, consumers using these
enhanced card products are classified either as Mass Affluent or Affluent. Based upon the specific
card type, high income consumers are classified as Mass Affluent, while high income-high
spending consumers are classified as Affluent.
Having this information at the time of authorization, allows merchants the opportunity to adjust
their sales approach to the needs and spending patterns of the consumer, potentially generating
Introduction Issuer Insights
26 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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 (<enhancedAuthResponse> element). These
elements provide more granular data, allowing you to gain a more nuanced understanding of the
approval/decline behavior of particular Issuers. Table 1-7 provides information about the fields
returned.
NOTE:To receive the Extended Network Data elements you must code to Version
V11.0 or above.
Issuer Insights Introduction
Document Version: 1.32 — XML Release: 9.14 27
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Example: Extended Network Data
<enhancedAuthResponse>
.
.
.
<networkResponse>
<endpoint>VISA</endpoint>
TABLE 1-7 Possible Extended Network Data ISO 8583 Fields
Data
Element Field Name Type Notes
4 Transaction Amount n 12
5 Settlement Amount n 12 Data Element 4 * Data Element 9
6 Cardholder Billing Amount n 12 Data Element 4 * Data Element 10
9 Settlement Conversion Rate n 8 Two subfields indicating decimal
position and value
10 Cardholder Billing
Conversion Rate n 8 Two subfields indicating decimal
position and value
15 Settlement Date n 4 MMDD format
38 Authorization Identification
Response an 6
39 Response Code an 2
44 Additional Response Data an..25
48 Private Use Additional Data an...999
50 Settlement Currency Code n 3 Defines the currency of Data Element 5
51 Cardholder Billing Currency
Code n 3
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
Introduction Issuer Insights
28 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
<networkField fieldNumber="4" fieldName="Transaction Amount">
<fieldValue>000000000962</fieldValue>
</networkField>
<networkField fieldNumber="44" fieldName="Additional Response Data">
<networkSubField fieldNumber="0">
<fieldValue></fieldValue>
</networkSubField>
<networkSubField fieldNumber="1">
<fieldValue>5</fieldValue>
</networkSubField>
</networkField>
</networkResponse>
</enhancedAuthResponse>
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.
Fraud Toolkit Introduction
Document Version: 1.32 — XML Release: 9.14 29
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.9 Fraud Toolkit
Just because a credit card network/company returns a valid authorization for a purchase does not
always mean that completing the transaction is in your best interest. There are multiple reasons
you may wish to decline a sale on a particular card at a particular time. In many cases there are
indicators that the transaction could be or likely is fraudulent. Acting to stop these transactions at
submission prevents loss, as well as reducing the number fraud related chargebacks in the future.
Vantiv offers a robust fraud solution, the Fraud Toolkit, to assist you in reducing the number of
possibly fraudulent transactions inflicted upon you by bad actors.
The Fraud Toolkit has three tiers or levels of implementation, each providing more rigorous
examination of transaction properties and data points, as well as valuable information and
guidance. The table below provide an overview of the tool provided at each level. The items
highlighted in blue require the inclusion of a small snippet of code on your checkout page.
TABLE 1-8 Fraud Toolkit Implementation Levels
Filter/Feature Essential Extended Premium
AVS Filter X X X
CVV No-Match Filter X X X
International BIN Filter X X X
Prepaid Non-Reloadable Filter X X X
Prior Chargeback Filter X X X
Prior Fraud Advice Filter X X X
Card Velocity Filter (Approved or Attempted) X X X
Email Velocity Filter X X X
Phone Velocity Filter X X X
IP Velocity Filter X X X
Device Velocity Filter X X X
IP Address, Geolocation, and Proxy Detection X X
Merchant Customizable Rules Template X X
ThreatMetrix Cybercrime Dashboard X X
(Asynch) Transaction Review Queues X X
Rule Management and Portal Training X X
Standalone Transaction API Access X X
Cybercrime Industry Report (Quarterly) X X
Introduction Fraud Toolkit
30 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.9.1 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.
1.9.1.1 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 the
<prepaid> 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 <prepaid> element to a value of true. This
method is useful to a merchant who offers products with both one-time payments and installment
Access to Fraud Consultant X
NOTE: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 consumers
device.
TABLE 1-8 Fraud Toolkit Implementation Levels
Filter/Feature Essential Extended Premium
Fraud Toolkit Introduction
Document Version: 1.32 — XML Release: 9.14 31
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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.
1.9.1.2 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 <international>
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.
NOTE: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.
Introduction Fraud Toolkit
32 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
If you elect to use the Security Code No-Match Filter Service, the system takes action only if the
issuer approves the submitted authorization/sale transaction, but includes a no-match code for the
CVV2/CVC2/CID card validation check. In this case, the Vantiv declines the transaction with a
Response Reason Code of 358 - Restricted by Vantiv due to security code mismatch. The
system also issues an Auth Reversal transaction on your behalf to remove the funds hold on the
account.
1.9.1.5 Card Velocity Filtering
Often, when a person attempts to use a stolen credit card successfully, they will follow the initial
purchase with a number of additional purchases within a short period of time. If you elect to use
the Card Velocity Filter, the system filters the transaction based upon the number of previously
approved Auth/Sale transactions plus the number of Auth/Sale transactions declined by another
Basic Filter, for the same account within a configurable time period. Both the total number of
transactions and the time period are configured in the Vantiv Merchant Profile.
Upon a decline, the system returns a Response Reason Code of 315 - Restricted Card - Auth
Fraud Velocity Filtering Service.
1.9.1.6 Prior Fraud Advice Filtering
Vantiv maintains a database of Fraud Advice information received from the Visa and MasterCard
networks for transactions you processed in the last 200 days. If you use the Prior Fraud Advice
Filter, the system compares the account information from the new transaction against the database
of accounts with prior Fraud Advice and filters the transaction if there is a match.
Upon a decline, the system returns a Response Reason Code of 318 - Restricted Card - Auth
Fraud Advice Filtering Service.
1.9.1.7 AVS Filter
One of the fraud prevention tools provided by all card networks is an Address Verification
System. By submitting the customers address information in the billToAddress section of the
cnpAPI message, you can verify that the address/zip code supplied by the consumer matches the
issuers records. The card networks, however, do not decline transactions based upon the failure
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.
Fraud Toolkit Introduction
Document Version: 1.32 — XML Release: 9.14 33
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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 consumers 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 consumers 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.
Introduction Fraud Toolkit
34 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.9.1.11 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
While you can have all submitted transactions flow through the Fraud toolkit, you likely want to
exercise a finer control over the application of the filters based upon a particular product, service
or other criteria. The system provides you the flexibility of restricting which transactions are
submitted to the filtering service and which filters the system applies to which groups. This is
accomplished by defining Filtering Rules.
For each Filtering Rule you first define a subgroup of transactions by selecting one of the
following Flow Selectors: Report Group, Billing Descriptor, orderSource, or MID (for PayFacs,
flow control by MID or order source only). Only one selector can be applied per rule. After
selecting a particular Flow Selector, you then select which filters to have applied to that subset of
transactions. You can define the Filter Rules so that filters are ORed (transaction filtered when
any one of the filters conditions met), or ANDed (transaction filtered when multiple filter
conditions met). Table 1-9 defines five rules that a merchant might define.
NOTE: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 consumers device.
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.
TABLE 1-9 Example - Fraud Filtering Service Rules
Filter Flow Selector Filters
1 Report Group = "XYZ" Prepaid
Fraud Toolkit Introduction
Document Version: 1.32 — XML Release: 9.14 35
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
Table 1-9 defines five Filter Rules that a merchant might use. These rules would be applied as
follows:
Filters 1 and 2 are applied to the subset of transactions that are members of Report Group
XYZ and use the Prepaid and International Filters. Since the Filter Rules are defined
separately, the rules are ORed. So, if a transaction uses either a Prepaid card or a card of
International origin, the transaction is filtered.
Filter 3 is applied to the subset of transactions that have an orderSource value set to recurring.
These transactions are filtered only if both the criteria for the Prepaid Filter AND the Prior
Chargeback Filter are met.
Filter 4 is applied to the subset of transactions that have an orderSource value set to
ecommerce. These transactions are filtered only if both the criteria for the Fraud Velocity
Filter AND the Security Code No-Match Filter are met.
Filter 5 is applied to the subset of transactions that have an Billing Descriptor value set to
GoldMember. These transactions are filtered only if both the criteria for the Prepaid Filter AND
the International Filter are met.
1.9.2 Extended Tier
The Extended Tier include all of the Essential Tier filters, but offers an additional levels of fraud
detection made available through Vantiv’s partnership with ThreatMetrix. The addition of the
same code snippet used for the IP and Device Velocity filters to your checkout page allows
ThreatMetrix to gather additional data points, such as the consumer’s device, proxy use, and
location. Unlike the filters in the Essential Tier, which are basic accept/decline filters, the
Extended Tier takes the data and compares the information to a rule list. Vantiv supplies an initial,
Best Practices rules list designed for your business type (i.e., Retail, Digital, Non-profit, etc.),
which you can modify and refine for you particular business model. Each rule, when triggered,
add or subtract a preset value from the transaction score. If the score fall below a set threshold,
the system declines the transaction, unless you prefer to make the final decision yourself. In either
case, Vantiv returns the score and a list of triggered rules in the transaction response message.
In addition to the ThreatMetrix rules engine, you get access to the ThreatMetrix Portal allowing
you to customize your rules list and scoring values. This level also allows you to white list/black
list items, such as email addresses and phone numbers. Other items included in this tier are:
ThreatMetrix Cybercrime Dashboard
2 Report Group = "XYZ" International
3 orderSource = "recurring" Prepaid + Prior Chargeback
4 orderSource = "ecommerce" Fraud Velocity + Security Code No-match
5 Billing Descriptor = "GoldMember" Prepaid + International
TABLE 1-9 Example - Fraud Filtering Service Rules
Filter Flow Selector Filters
Introduction Fraud Toolkit
36 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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 consumers 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 <body></body> tags of the page
HTML.
Example: ThreatMetrix Profiling Tags
<!-- Begin ThreatMetrix profiling tags below -->
<script type="text/javascript"
src="https://h.online-metrix.net/fp/tags.js?org_id=ORG_ID&session_id=UNIQUE_SESS
ION_ID&pageid=PAGE_ID"></script>
<noscript>
<iframe style="width: 100px; height: 100px; border: 0; position: absolute; top:
-5000px;"
src="https://h.online-metrix.net/tags?org_id=ORG_ID&session_id=UNIQUE_SESSION_ID
&pageid=PAGE_ID"></iframe>
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.
Fraud Toolkit Introduction
Document Version: 1.32 — XML Release: 9.14 37
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
</noscript>
<!-- End profiling tags -->
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 <threatMetrixSessionId> 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 <threatMetrixSessionId>, our system automatically
queries the ThreatMetrix platform for the associated results. The cnpAPI response message
includes the <advancedFraudResults> element containing the score and status and
information about any triggered rules. The following two examples show a standard
Authorization transaction, including a <threatMetrixSessionId> and a pass response.
Example: Authorization including <threatMetrixSessionId> Element
<cnpOnlineRequest version="12.0" xmlns="http://www.vnativcnp.com/schema"
merchantId="81601">
<authentication>
<user>User Name</user>
<password>password</password>
</authentication>
<authorization id="002" reportGroup="001601">
<orderId>10102013_sessionId_app</orderId>
<amount>1002</amount>
<orderSource>ecommerce</orderSource>
<billToAddress>
<name>John Doe</name>
<addressLine1>15 Main Street</addressLine1>
<city>San Jose</city>
<state>CA</state>
<zip>95032-1234</zip>
<country>USA</country>
<phone>9782750000</phone>
<email>nobody@vantiv.com</email>
</billToAddress>
<card>
<type>MC</type>
<number>5405102001000003</number>
<expDate>1115</expDate>
</card>
<advancedFraudChecks>
Introduction Fraud Toolkit
38 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
<threatMetrixSessionId>ASDFG-AXXXXAB999</threatMetrixSessionId>
</advancedFraudChecks>
</authorization>
</cnpOnlineRequest>
Example: Authorization Response including <advancedFraudResults>
Element
<cnpOnlineResponse version="12.0"
xmlns="http://www.vantivcnp.com/schema" response="0" message="Valid
Format">
<authorizationResponse id="002" reportGroup="001601">
<cnpTxnId>82823534116454639</cnpTxnId>
<orderId>10102013_sessionId_app</orderId>
<response>000</response>
<responseTime>2017-10-08T21:36:50</responseTime>
<postDate>2017-10-08</postDate>
<message>Approved</message>
<authCode>000003</authCode>
<fraudResult>
<avsResult>00</avsResult>
<advancedFraudResults>
<deviceReviewStatus>pass</deviceReviewStatus>
<deviceReputationScore>50</deviceReputationScore>
<triggeredRule>
FlashImagesCookiesDisabled
</triggeredRule>
</advancedFraudResults>
</fraudResult>
</authorizationResponse>
</cnpOnlineResponse>
NOTE:The other possible values for the <deviceReviewStatus> element are fail,
review, unavailable, and invalid_session.
The <deviceReputationScore> value can range from -100 to 100. The
resulting pass, fail, or review value depends upon your profile settings.
The <triggeredRule> element can occur multiple times, once for each rule
triggered.
Fraud Toolkit Introduction
Document Version: 1.32 — XML Release: 9.14 39
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.9.4.2 Information Only Option
If you wish to retain full control of the decision to accept or decline transactions, Vantiv offers the
option of using the Advanced Fraud Tools in an Information Only mode. In this configuration,
you receive the same information in the response as you would with the full implementation;
however, Vantiv will not automatically decline transactions with a failing score.
If the authorization is declined by the network, you can choose to recycle the transaction or do
nothing. If an authorization with a failing score receives approval from the network, it would be
up to you to reverse the authorization should you decide not to proceed with the transaction. This
is similar to the case of an approved transaction that has a status of Review, but you decide not to
proceed. Issuing an authorization reversal allows you to avoid any misuse of Auth fees otherwise
imposed by the card networks.
1.9.4.3 Fraud Check Transactions
If you wish to retrieve the Advanced Fraud results without introducing a Authorization or Sale
transactions, use a Fraud Check transaction as shown in the example below. Fraud Check
transactions are only supported as Online transactions.
Example: Fraud Check Transaction
<cnpOnlineRequest version="12.0" xmlns="http://www.vantivcnp.com/schema"
merchantId="81601">
<authentication>
<user>User Name</user>
<password>password</password>
</authentication>
<fraudCheck id="002" reportGroup="001601">
<advancedFraudChecks>
<threatMetrixSessionId>ASDFG-AXXXXAB999</threatMetrixSessionId>
<customAttribute1>Attribute passed to ThreatMetrix</customAttribute1>
<customAttribute2>Attribute passed to ThreatMetrix</customAttribute2>
<customAttribute3>Attribute passed to ThreatMetrix</customAttribute3>
<customAttribute4>Attribute passed to ThreatMetrix</customAttribute4>
<customAttribute5>Attribute passed to ThreatMetrix</customAttribute5>
</advancedFraudChecks>
<billToAddress>
<name>John Doe</name>
<addressLine1>15 Main Street</addressLine1>
<city>San Jose</city>
<state>CA</state>
<zip>95032-1234</zip>
<country>USA</country>
<phone>9782750000</phone>
Introduction Fraud Toolkit
40 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
<email>jdoe@vantiv.com</email>
</billToAddress>
<shipToAddress>
<name>Jane Doe</name>
<addressLine1>15 Main Street</addressLine1>
<city>San Jose</city>
<state>CA</state>
<zip>95032-1234</zip>
<country>USA</country>
<phone>9782750000</phone>
<email>jdoe@vantiv.com</email>
</shipToAddress>
</fraudCheck>
</cnpOnlineRequest>
Tokenization Feature Introduction
Document Version: 1.32 — XML Release: 9.14 41
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.10 Tokenization Feature
Tokenization is the process by which a credit card number or eCheck account number is replaced
by a reference number, referred to as a token. Unlike the card or account number, you can store
the token on your system without concern of a security breach exposing critical customer
information. Vantiv stores the information in a secure vault and accesses it only when you submit
a transaction using the supplied token.
In the case of credit cards, since you do not store the customers account information, the scope of
PCI requirements to which you must comply may be minimized. This may greatly reduce the cost
of compliance and may limit your liability if your systems are breached. You can further reduce
the requirements, as well as the possibility of exposure from a breach through the use of the
Vantiv eProtect. By sending the card information from your page directly to our systems you
eliminate one more facet of handling the card information.
This section discusses the following topics:
How Tokenization Works
Token Formats
Obtaining Tokens
Supported Token Transactions
NOTE:You must be enabled for card tokenization in order to use the eCheck
tokenization feature.
NOTE:Vantiv recommends you consult your own PCI Compliance and Legal
departments to determine the specific advantages of tokenization for your
company.
NOTE:Information about the use of and integration to the Vantiv Pay Page is
contained in the Vantiv Pay Page Integration Guide.
Introduction Tokenization Feature
42 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.10.1 How Tokenization Works
In a non-tokenized environment, customer data, including the card/eCheck account number, is
handled and stored by multiple parties for each transaction. From a merchant standpoint, they
receive the information, store it in their own database, and transmit it to their processor with the
transaction request, as Figure 1-5 shows for card information. While the access and transmission
of the data may occur a single time, as in the case of a Sale transaction, frequently the data is
transmitted multiple times in order to complete a single sale, as in the case of an Auth followed
by a Capture or several partial Captures. The local storage and repeated transmission of the
information creates additional possible breach points, where the information might be
compromised by a malicious third party.
FIGURE 1-5 Card Information Flow in Non-Token Environment
In a tokenized environment customer data is ideally transmitted a single time and is never stored
locally by the merchant, as Figure 1-6 shows for card data. Once the account number is
registered, using either a registerTokenRequest or by submitting it with any supported
transaction, Vantiv returns a token. You store the token locally and use it for all future
transactions concerning that account. Vantiv takes responsibility for storing and safeguarding the
account information.
NOTE:The difference between card data flow and eCheck data flow is that the
entities upstream of Vantiv are different. The principles remain the same
from a merchant standpoint.
Tokenization Feature Introduction
Document Version: 1.32 — XML Release: 9.14 43
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
FIGURE 1-6 Card Information Flow in Tokenized Environment
1.10.2 Token Formats
For credit cards, in an effort to minimize development requirements on the merchant side, Vantiv
elected to use a format-preserving tokenization scheme. In simple terms this means that the length
of the original card number is reflected in the token, so a submitted 16-digit number results in a
16-digit token. Also, all tokens use only numeric characters, so you do not have to change your
systems to accept alpha-numeric characters.
The credit card token numbers themselves have two parts. The last four digits match the last four
digits of the card number. The remaining digits (length can vary based upon original card number
length) are a randomly generated. Unlike credit card numbers, which are Mod 10 compliant,
tokens are Mod 10 + 1 compliant.
FIGURE 1-7 Token Format - Card
For an eCheck token, since the account number length can vary widely, we elected to make the
tokens a uniform length of 17 digits. Unlike card tokens, the entire eCheck token number is a
randomly generated. The system supplies the last three characters of the account number in a
separate element. As with credit card tokens, eCheck tokens are Mod 10 + 1 compliant.
NOTE:Depending upon implementation, the use of a pay page can allow the
account information to come directly to Vantiv, so the merchant handles
the token only.
Cardholder
Merchant
Account #
Database
Token
Account #
Token
Issuing Bank
Card Assn.
Account # Account #
Database
Account # Account #
Database
Account #
Vantiv
Vault
Introduction Tokenization Feature
44 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.10.3 Obtaining Tokens
There are three ways for you to obtain tokens for account numbers. First, you can submit an
existing card number/eCheck account information (account number and routing number) using a
Register Token request. When Vantiv receives this transaction type, we generate a token and
return it to you via a Register Token response (see Register Token Transactions on page 291.)
Although you can use this method to tokenize an account number at any time, it is most useful
when initially tokenizing your customer database. Vantiv recommends that you collect all distinct
credit card numbers in your database and submit the information in one or more large Batch.
When you receive the response file, parse the returned token information to your database,
replacing the card numbers.
The second method you can use to obtain a token is to submit a supported transaction with the
card information. If you are a tokenized merchant, Vantiv will automatically convert the
submitted card number to a token and return it to you in the transaction response. Typically, you
would use this method when taking and submitting a transaction during the normal course of
business. When you receive the response, you store the token instead of the card information.
The third method of obtaining a token applies only to merchants using the Vantiv Pay Page
feature. In this case, upon submission of an account number via the Pay Page API, Vantiv issues a
Registration Id. You then submit the Registration Id in an Authorization or Sale transaction and
receive the token in the response message.
1.10.3.1 Bulk Token Registration
If you are new to Vantiv, and have utilized tokens with a previous processor, Vantiv can perform a
bulk token registration on all the card numbers that were vaulted with your previous processor.
The following is an example of the process:
1. During your implementation with Vantiv, you contact your previous processor and request an
encrypted mapping file containing the card and token numbers for your customers. A
Implementation Consultant will work with you and your previous processor to facilitate the
secure transfer of this file without impacting your PCI compliance. The file can be
comma-delimited, tab-delimited, or any other common format.
2. Vantiv performs a bulk token registration of all of the card numbers contained in the file.
NOTE:You must be token enabled and certified prior to using the Vault feature.
Please consult your Customer Experience Manager concerning the
requirements and details of this process.
NOTE:Once a card number has been converted to a token for a particular
merchant, subsequent submissions of the same card number will return
the same token.
Tokenization Feature Introduction
Document Version: 1.32 — XML Release: 9.14 45
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
3. Vantiv returns a mapping file to your organization containing the old tokens and the new
Vantiv-issued tokens, so that you can update your order processing system.
Note that Vantiv supports token-extractor formats of all major token service providers. Contact
your Implementation Consultant for more information or to initiate this process.
1.10.4 Supported Token Transactions
The following transactions support the generation and use of tokens:
• Authorization - You can submit the transaction either with a token or card information. If
you submit card information, Vantiv automatically generates the token and returns it in the
response.
Capture Given Auth - You can submit the transaction either with a token or card
information. If you submit card information, Vantiv automatically generates the token and
returns it in the response.
•Credit - You can submit the transaction either with a token or card information. If you submit
card information, Vantiv automatically generates the token and returns it in the response.
Force Capture - You can submit the transaction either with a token or card information. If
you submit card information, Vantiv automatically generates the token and returns it in the
response.
•Register Token - You use this transaction to convert a card number or eCheck account
number to a Vantiv token without an associated authorization, verification or payment
transaction.
•Sale - You can submit the transaction either with a token or card information. If you submit
card information, Vantiv automatically generates the token and returns it in the response.
eCheck Credit - You can submit the transaction either with a token or account information. If
you submit account information, Vantiv automatically generates the token and returns it in the
response.
eCheck Redeposit - You can submit the transaction either with a token or account
information. If you submit account information, Vantiv automatically generates the token and
returns it in the response.
eCheck Sale - You can submit the transaction either with a token or account information. If
you submit account information, Vantiv automatically generates the token and returns it in the
response.
eCheck Verification - You can submit the transaction either with a token or account
information. If you submit account information, Vantiv automatically generates the token and
returns it in the response.
Update Card Validation Number - This is a special transaction type provided to allow the
update of a CVV2/CVC2/CID code supplied at the time of the token registration. You should
only use this transaction type if you had previously submitted the account number and
Introduction Tokenization Feature
46 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
security code in a registerTokenRequest transaction and now need to change the
CVV2/CVC2/CID value.
1.10.5 Compliance with Visa Best Practices for Tokenization
As shown below, the Vault tokenization solution complies with 11 of the 12 items listed in the
Visa Best Practices for Tokenization document. The twelfth item concerns the management of
stored historical data (that may contain card information) within your systems. Tokenizing all
historical card info when implementing the Vantiv solution would satisfy this item, as would
protecting it per PCI DSS requirements.
TABLE 1-10 Visa Best Practices for Tokenization Compliance
Item # Who Domain Best Practice Complies?
1 Vantiv Tokenization System Network Segmentation Yes
2 Vantiv Tokenization System Authentication Yes
3 Vantiv Tokenization System Monitoring Yes
4 Vantiv Tokenization System Token Distinguishability Yes
5 Vantiv Token Generation Token Generation Yes
6 Vantiv Token Generation Single- vs. Multi- use Tokens Yes
7 Vantiv Token Mapping PAN Processing Yes
8 Vantiv Card Data Vault PAN Encrypted in Storage Yes
9 Vantiv Card Data Vault Covered by PCI DSS Yes
10 Vantiv Cryptographic Keys Key Strength Yes
11 Vantiv Cryptographic Keys Covered by PCI DSS Yes
12 Merchant Historical Data
Management Non-tokenized data protected Merchant
Implementation
Decision
eCheck Processing Introduction
Document Version: 1.32 — XML Release: 9.14 47
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.11 eCheck Processing
An eCheck is an alternative payment method that directly debits a consumer's account via the
Automatic Clearing House (ACH) network. From a merchant’s standpoint offering eCheck as a
payment method has several advantages, including a large consumer base in excess of 130 million
accounts in the United States and no interchange fees.
This section provides information about several Vantiv eCheck processing features. Please
consult with your Customer Experience Manager for additional information.
1.11.1 Validation Feature
Vantiv performs a validation of the eCheck routing number. This is done both to verify that the
routing number is correctly formatted and that it exists in the routing number database. If the
routing number fails this validation, Vantiv rejects the transaction. Vantiv performs this validation
on all eCheck transactions automatically.
1.11.2 Verification Feature
Since there is no authorization process associated with eChecks allowing you to confirm the
availability of funds and hold the purchase amount, there is a higher risk of certain types of fraud.
The optional eCheck Verification feature allows you to submit an eCheck account number for
comparison to a database containing historical information about the account, as well as the
account holder. When you submit an eCheck Verification transaction the information you provide
is compared to a negative database to see if the account is associated with activities, such as
fraud, over drafts, or other items determined to be risk factors.
You can also initiate an account verification operation as part of an eCheck Sale transaction by
setting the <verify> 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.
NOTE:Vantiv also supports eCheck processing for our merchants doing
business in Canada. All eCheck transaction types, except Verification and
Prenotification transaction are supported. Please consult your Customer
Experience Manager for additional information.
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.
Introduction eCheck Processing
48 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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.
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:
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.
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
eCheck Processing Introduction
Document Version: 1.32 — XML Release: 9.14 49
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.11.3 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.
1.11.4 Auto Redeposit Feature
NACHA rules allow merchants to redeposit entries when the initial deposit was returned for
either Insufficient Funds or Uncollected Funds. Two redeposit attempts are allowed within 180
days of the settlement date of the initial deposit. Vantiv offers an optional service that allows you
to pre-configure automatic redeposits of transactions returned for the those reasons. You define
the number of days from the initial return for Vantiv to resubmit the transaction. You also define
the number of days from the return of the first resubmission for the attempt of a second
resubmission.
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.
Checking Account Number Name of Financial Institution
NOTE:While we always make the NoC information available to you, Vantiv does
not support automatic updating of account information for PayFacs.
NOTE:You track the current state of your transactions, returns, and
resubmissions via the iQ User Interface. Please refer to the eCommerce iQ
Reporting and Analytics User Guide for additional information.
Introduction eCheck Processing
50 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.11.5 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.
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.
NOTE:Prenotification transactions are only supported in cnpAPI V9.1 or above
and only in Batch submissions. Prenotification transactions are not
supported for PayFacs or Canadian eChecks.
eCheck Processing Introduction
Document Version: 1.32 — XML Release: 9.14 51
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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.
Introduction SEPA Direct Debit
52 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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 consumers
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.
SEPA Direct Debit Introduction
Document Version: 1.32 — XML Release: 9.14 53
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
FIGURE 1-8 Order Flow for Vantiv Supplied Mandate
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 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
<litleOnlineRequest version="9.13" xmlns="http://www.litle.com/schema"
merchantId="SddMer1">
<authentication>
<user>SDD</user>
<password>password</password>
NOTE:If you do not specify a preferred language, or you specify an unavailable
language, the Mandate page appears in English.
Merchant
Consumer enters their
IBAN and clicks
Submit button on
Checkout page.
Consumer
Mandate Page
Merchant sends Sale
transaction to Vantiv.
Response includes
link to Mandate page
and redirectToken.
Merchant redirects
consumer to the
Mandate page.
Consumer Accepts or
Rejects the Mandate.
Consumer redirected back to
Merchant Checkout page. If
the consumer accepted the
Mandate, redirectToken
appears as a URL parameter.
If Mandate rejected,
redirectToken not included.
1 2
34
5
6
.
Introduction SEPA Direct Debit
54 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
</authentication>
<sale id="SEPA_Sale" reportGroup="SddMer1" customerId="SEPA_Customer1">
<orderId>sddSale</orderId>
<amount>1001</amount>
<orderSource>ecommerce</orderSource>
<billToAddress>
<name>Johann Schmidt</name>
<addressLine1>10 Hoch Strasse</addressLine1>
<city>Hanover</city>
<zip>30159</zip>
<country>DE</country>
<email>jschmidt@phoenixprocessing.com</email>
<phone>781-270-1111</phone>
</billToAddress>
<sepaDirectDebit>
<mandateProvider>Vantiv</mandateProvider>
<sequenceType>OneTime</sequenceType>
<iban>DE79850503003100180568</iban>
<preferredLanguage>DE</preferredLanguage>
</sepaDirectDebit>
</sale>
</litleOnlineRequest>
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
<litleOnlineResponse version="9.13" xmlns="http://www.litle.com/schema"
response="0" message="Valid Format">
<saleResponse id="SEPA_Sale" reportGroup="SddMer1">
<litleTxnId>82830949823203015</litleTxnId>
<orderId>sddSale</orderId>
<response>000</response>
<responseTime>2017-01-21T17:07:27</responseTime>
<postDate>2017-01-21</postDate>
<message>Approved</message>
<sepaDirectDebitResponse>
<redirectUrl>http://MandateHostURL/DE</redirectUrl>
<redirectToken>evr0kij413g8r85e32v7deov0c</redirectToken>
SEPA Direct Debit Introduction
Document Version: 1.32 — XML Release: 9.14 55
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
<mandateReference>1ABCA43</mandateReference>
</sepaDirectDebitResponse>
</saleResponse>
</litleOnlineResponse>
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
Merchant
Consumer enters their
IBAN and clicks
Submit button on
Checkout page.
Consumer
Mandate Page
Merchant sends Sale
transaction to Vantiv,
including
mandateSignatureDate,
mandateUrl, etc.
Response
Merchant presents
Mandate terms.
Consumer Accepts or
Rejects the Mandate.
Consumer redirected back to
Merchant Checkout page. If
the consumer accepted the
Mandate, the Merchant
constructs a Sale transaction
to Vantiv.
1
2
4
5
6
3b
3a Accept/Reject info to
Merchant
Introduction SEPA Direct Debit
56 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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
<litleOnlineRequest version="9.13" xmlns="http://www.litle.com/schema"
merchantId="SddMer1">
<authentication>
<user>SDD</user>
<password>password</password>
</authentication>
<sale id="SEPA_Sale" reportGroup="SddMer1" customerId="SEPA_Customer1">
<orderId>sddSale</orderId>
<amount>1001</amount>
<orderSource>ecommerce</orderSource>
<billToAddress>
<name>Johann Schmidt</name>
<addressLine1>10 Hoch Strasse</addressLine1>
<city>Hanover</city>
<zip>30159</zip>
<country>DE</country>
<email>jschmidt@phoenixprocessing.com</email>
<phone>781-270-1111</phone>
</billToAddress>
<sepaDirectDebit>
<mandateProvider>Merchant</mandateProvider>
<sequenceType>FirstRecurring</sequenceType>
<mandateReference>ABCD1234</mandateReference>
SEPA Direct Debit Introduction
Document Version: 1.32 — XML Release: 9.14 57
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
<mandateUrl>http://MerchantMandateHostURL</mandateUrl>
<mandateSignatureDate>2017-01-21</mandateSignatureDate>
<iban>DE79850503003100180568</iban>
</sepaDirectDebit>
</sale>
</litleOnlineRequest>
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.
Introduction iDEAL, SOFORT, and Giropay
58 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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.
The graphic and steps below illustrate the iDEAL, SOFORT, and Giropay processes.
FIGURE 1-10 iDEAL, SOFORT, adn Giropay Order Flow
NOTE:Although the bank debits the consumers account immediately, the funds
may not appear in your account for a few days, depending upon your
settlement agreement.
Merchant
Consumer
Merchant sends Sale
transaction to Vantiv.
Response includes
link to page for bank
selection and
redirectToken.
Merchant redirects
consumer to the bank
selection page. Consumer Accepts or
Rejects transaction
using the Bank
authentication
process.
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 selects the
payment method on
the Checkout page.
1 2
34
5
6
.
Bank
iDEAL, SOFORT, and Giropay Introduction
Document Version: 1.32 — XML Release: 9.14 59
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
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
<litleOnlineRequest version="9.13" xmlns="http://www.litle.com/schema"
merchantId="12345">
<authentication>
<user>user_name</user>
<password>password</password>
</authentication>
<sale id="TC6900_1" reportGroup="Mer1" customerId="pproPosResponse">
<orderId>p1_idealSale</orderId>
<amount>10011</amount>
<orderSource>ecommerce</orderSource>
<billToAddress>
<name>David Berman</name>
<addressLine1>10 Noorderstraat</addressLine1>
<city>Amsterdam</city>
<zip>1000 AP</zip>
<country>NL</country>
<email>dberman@phoenixprocessing.com</email>
<phone>020-1234567</phone>
</billToAddress>
<ideal>
<preferredLanguage>NL</preferredLanguage>
<ideal/>
</sale></litleOnlineRequest>
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
<litleOnlineResponse version="9.13" xmlns="http://www.litle.com/schema"
response="0" message="Valid Format">
<saleResponse id="TC6900_1" reportGroup="PayProMer1">
<litleTxnId>84568456</litleTxnId>
<orderId>p1_idealSale</orderId>
<response>000</response>
<responseTime>2017-04-03T10:24:31</responseTime>
Introduction iDEAL, SOFORT, and Giropay
60 Document Version: 1.32 — XML Release: 9.14
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
<postDate>2017-04-03</postDate>
<message>Approved</message>
<idealResponse>
<redirectUrl>http://ideal.bank.com</redirectUrl>
<redirectToken>1234567890</redirectToken>
<paymentPurpose>123456YourCompanyName</paymentPurpose>
</idealResponse>
</saleResponse>
</litleOnlineResponse>
4. The consumer selects their bank on the bank selection page.
5. The consumer accepts or rejects the transaction on their bank page. The bank determines the
actual process of accepting the transaction.
6. The consumer gets redirected back to your checkout page. If they accepted the agreement, the
URL contains a parameter exposing the redirectToken value
(redirectToken=token_value). By comparing this value to the value you received in the
Sale response message you can verify that the consumer accepted the agreement and the bank
transferred the funds. If they declined, the URL does not include the parameter.
NOTE: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 customers account within 30 days of a return.
eCommerce Solution for Apple Pay™ Introduction
Document Version: 1.32 — XML Release: 9.14 61
© 2018 Vantiv, LLC - All Rights Reserved.
cnpAPI Reference Guide
1.14 eCommerce Solution for Apple Pay™
Vantiv supports Apple Pay for in-app and in-store purchases initiated on compatible versions of
iPhone and iPad, as well as purchases from your desktop or mobile website initiated from
compatible versions of iPhone, iPad, Apple Watch, MacBook and iMac (Apple Pay on the Web).
For in-store transactions, a consumer can use the Near Field Communications (NFC) chip in their
device to make a purchase by simply touching the device to an NFC-compliant terminal. Identity
verification is provided by Touch ID, a fingerprint reading application built into the device. If you
wish to allow Apple Pay transactions from your native iOS mobile application, you must build
the capability to make secure purchases using Apple Pay into your mobile application.
If you wish to allow Apple Pay payments on your desktop or mobile website, your website must
be configured to work with Apple to request authorization from the consumers iPhone or iPad via
Touch ID. See Table 1-11, "Apple Pay on the Web Compatible Devices" for more information.
This section provides an overview of the operation of Apple Pay and Apple Pay on the web,
along with the several methods you can use to submit Apple Pay purchases to the Vantiv
eCommerce platform. The topics discussed are:
Overview of Apple Pay Operation
Vantiv Decryption of Apple Pay PKPaymentToken
Using the Vantiv Mobile API for Apple Pay
Merchant Decryption of Apple Pay PKPaymentToken
Recurring Payments with Apple Pay
1.14.1 Overview of Apple Pay Operation
The operation of Apple Pay and Apple Pay on the web is relatively simple, but will require either
the development of new nativ