Vantiv CnpAPI Reference Guide Cnp API API11.3 V1.8

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 944

DownloadVantiv CnpAPI Reference Guide Cnp API API11.3 V1.8
Open PDF In BrowserView PDF
cnpAPI Reference Guide

November 2017
cnpAPI Release: 11.3
Document Version: 1.8

Vantiv cnpAPI Reference Guide Document Version: 1.8
All information whether text or graphics, contained in this manual is confidential and proprietary information of Vantiv, LLC and is
provided to you solely for the purpose of assisting you in using a Vantiv, LLC product. All such information is protected by copyright laws
and international treaties. No part of this manual may be reproduced or transmitted in any form or by any means, electronic, mechanical or
otherwise for any purpose without the express written permission of Vantiv, LLC. The possession, viewing, or use of the information
contained in this manual does not transfer any intellectual property rights or grant a license to use this information or any software
application referred to herein for any purpose other than that for which it was provided. Information in this manual is presented "as is" and
neither Vantiv, LLC or any other party assumes responsibility for typographical errors, technical errors, or other inaccuracies contained in
this document. This manual is subject to change without notice and does not represent a commitment on the part Vantiv, LLC or any other
party. Vantiv, LLC does not warrant that the information contained herein is accurate or complete.

All trademarks are the property of their respective owners and all parties herein have consented to their trademarks appearing in this
manual. Any use by you of the trademarks included herein must have express written permission of the respective owner.
Copyright © 2003-2017, Vantiv, LLC - ALL RIGHTS RESERVED.

CONTENTS
About This Guide
Intended Audience ........................................................................................................ xxiii
Revision History ............................................................................................................ xxiii
Document Structure ...................................................................................................... xxvi
Documentation Set ....................................................................................................... xxvi
Typographical Conventions .........................................................................................xxviii
Contact Information....................................................................................................... xxix

Chapter 1 Introduction
The cnpAPI Data Format .................................................................................................. 2
Communications Protocols ......................................................................................... 2
General XML Coding Requirements ........................................................................... 3
Other XML Resources................................................................................................. 4
Batch Transaction Processing .......................................................................................... 5
Recommended Session File Size ............................................................................... 5
Payment Integration Platform (cnpAPI SDKs) .................................................................. 6
Duplicate Transaction Detection ....................................................................................... 7
Batch Duplicate Checking ........................................................................................... 7
Batch Dupe Checking for Dynamic Payout Funding Instructions.......................... 8
Online Duplicate Checking.......................................................................................... 8
Coding for Report Groups............................................................................................... 10
Additional/Alternate Methods of Tagging Transactions ............................................ 11
Recovery......................................................................................................................... 12
Authorization/Sale Recycling .................................................................................... 12
Recycling Engine ............................................................................................... 12
Account Updater Service ......................................................................................... 14
Match Back ......................................................................................................... 15
Merchant Requirements ...................................................................................... 16
Account Updater Features .................................................................................. 17
Recurring Engine ........................................................................................................... 18
Payment Plans .......................................................................................................... 18
Subscriptions............................................................................................................. 19
Add Ons and Discounts ...................................................................................... 21
Recurring Reports ..................................................................................................... 21
Transaction Types and Uses .................................................................................... 22
Issuer Insights................................................................................................................. 24
Issuer Insights Secure Scheduled Report................................................................. 24
Real Time Indicators ................................................................................................. 24

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

iii

cnpAPI Reference Guide

Contents

Prepaid Indicator ................................................................................................. 24
Affluence Indicator .............................................................................................. 25
Issuer Country Indicator ...................................................................................... 26
Cardholder Type Indicator................................................................................... 26
Extended Network Data ............................................................................................ 26
Insights Analytics Dashboard.................................................................................... 28
Fraud Toolkit .................................................................................................................. 29
Essential Tier ............................................................................................................ 30
Prepaid Card Filtering ........................................................................................ 30
International BIN Filtering ................................................................................... 31
Prior Chargeback Filtering ................................................................................. 31
Security Code No-Match Filter ........................................................................... 31
Card Velocity Filtering ........................................................................................ 32
Prior Fraud Advice Filtering ................................................................................ 32
AVS Filter ........................................................................................................... 32
Email Velocity Filter............................................................................................. 33
Phone Velocity Filter ........................................................................................... 33
IP Velocity Filter .................................................................................................. 33
Device Velocity Filter........................................................................................... 34
Application of Filters - Filtering Rules ................................................................. 34
Extended Tier............................................................................................................ 35
Premium Tier............................................................................................................. 36
Modifications to Your Web Page............................................................................... 36
cnpAPI Transactions ........................................................................................... 37
Information Only Option ...................................................................................... 39
Fraud Check Transactions ................................................................................. 39
Tokenization Feature ...................................................................................................... 40
How Tokenization Works .......................................................................................... 41
Token Formats .......................................................................................................... 42
Obtaining Tokens ...................................................................................................... 42
Bulk Token Registration ...................................................................................... 43
Supported Token Transactions ................................................................................. 44
Compliance with Visa Best Practices for Tokenization ............................................. 45
eCheck Processing ......................................................................................................... 46
Validation Feature ..................................................................................................... 46
Verification Feature ................................................................................................... 46
Required Contents of Decline Notice .................................................................. 47
Automatic Notice of Change (NoC) Updates ............................................................ 48
Auto Redeposit Feature ............................................................................................ 48
eCheck Prenotification .............................................................................................. 49
SEPA Direct Debit .......................................................................................................... 51

iv

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

SEPA Direct Debit - Vantiv Supplied Mandate.......................................................... 51
SEPA Direct Debit - Merchant Supplied Mandate..................................................... 54
iDEAL, SOFORT, and Giropay ....................................................................................... 57
eCommerce Solution for Apple Pay™ ............................................................................ 60
Overview of Apple Pay Operation ............................................................................. 60
Vantiv Decryption of Apple Pay PKPaymentToken................................................... 61
Using the Browser JavaScript API for Apple Pay on the Web ............................ 61
Using the Vantiv Mobile API for Apple Pay ......................................................... 63
Submitting the Apple Pay PKPaymentToken in a cnpAPI Message ................... 64
Merchant Decryption of Apple Pay PKPaymentToken........................................ 65
Recurring Payments with Apple Pay......................................................................... 67
eCommerce Solution for Android Pay™ ......................................................................... 68
Android Pay using eProtect....................................................................................... 68
Merchant Decryption Method .................................................................................... 71
Recurring Payments with Android Pay...................................................................... 74
Supported Transaction Types ......................................................................................... 75
Authorization Transaction ......................................................................................... 75
AVS Only Transaction ......................................................................................... 76
Authorization Reversal Transactions ........................................................................ 76
Notes on the Use of Authorization Reversal Transactions.................................. 77
Using Authorization Reversal to Halt Recycling Engine...................................... 78
Activate Transaction.................................................................................................. 78
Activate Reversal Transaction (Online Only) ............................................................ 79
Balance Inquiry Transaction...................................................................................... 79
Cancel Subscription Transaction .............................................................................. 79
Capture Transaction.................................................................................................. 79
Capture Given Auth Transaction............................................................................... 79
Create Plan Transaction ........................................................................................... 80
Credit Transaction..................................................................................................... 80
Deactivate Transaction ............................................................................................. 81
Deactivate Reversal Transaction (Online Only) ........................................................ 81
Deposit Reversal Transaction (Online Only)............................................................. 81
eCheck Credit Transaction........................................................................................ 81
eCheck Prenotification Credit Transaction................................................................ 81
eCheck Prenotification Sale Transaction .................................................................. 82
eCheck Redeposit Transaction ................................................................................. 82
eCheck Sales Transaction ........................................................................................ 82
eCheck Verification Transaction ............................................................................... 82
eCheck Void Transaction (Online Only).................................................................... 82
Force Capture Transaction ....................................................................................... 83
Gift Card Auth Reversal ............................................................................................ 83

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

v

cnpAPI Reference Guide

Contents

Gift Card Capture ...................................................................................................... 83
Gift Card Credit ......................................................................................................... 83
Load Transaction ...................................................................................................... 83
Load Reversal Transaction (Online Only) ................................................................. 83
Refund Reversal Transaction (Online Only) ............................................................. 84
Register Token Transaction ...................................................................................... 84
Sale Transaction ....................................................................................................... 84
Status Query Transaction ........................................................................................ 84
Unload Transaction ................................................................................................... 85
Unload Reversal Transaction (Online Only).............................................................. 85
Update Card Validation Number Transaction ........................................................... 85
Update Plan Transaction........................................................................................... 85
Update Subscription Transaction .............................................................................. 85
Void Transaction (Online Only) ................................................................................. 86
Using Void to Halt Recycling Engine................................................................... 86
Instruction-Based Dynamic Payout Transactions .................................................... 86

Chapter 2 Testing Your cnpAPI Transactions
Certification and Testing Environments .......................................................................... 90
Sandbox Environment............................................................................................... 90
Pre-Live Environment................................................................................................ 90
Pre-Live Environment Limitations and Maintenance Schedules ......................... 91
Post-Live Environment .............................................................................................. 91
Post-Live Environment Limitations and Maintenance Schedules ....................... 91
Overview of Testing ........................................................................................................ 93
Planning for Certification Testing .............................................................................. 93
Required Certification Testing................................................................................... 94
Optional Testing ........................................................................................................ 94
System Doctor........................................................................................................... 94
Transferring Files ............................................................................................................ 97
Transferring Session Files ........................................................................................ 97
Submitting a Session File for Processing............................................................ 97
Retrieving Processed Session Files.................................................................... 98
Transferring Online Files........................................................................................... 98
ASP Programming Example ............................................................................... 99
Java Programming Example ............................................................................. 100
Notes on Timeout Settings ................................................................................ 101
Notes on Persistent Connections ...................................................................... 101
Helpful Web Sites.............................................................................................. 102
Performing the Required Certification Tests ................................................................. 103

vi

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

Testing Authorization (including Indicators), AVS Only, Capture, Credit, Sale, and Void
Transactions............................................................................................................ 103
Testing Authorization Reversal Transactions.......................................................... 116
Testing eCheck Transactions.................................................................................. 119
Testing Token Transactions.................................................................................... 126
Testing Query Transactions .................................................................................... 131
Testing Online Duplicate Transaction Processing .................................................. 132
Performing the Optional Tests ...................................................................................... 134
Testing AVS and Card Validation............................................................................ 135
Testing Address Responses ................................................................................... 136
Testing Advanced AVS Response Codes............................................................... 138
Testing Response Reason Codes and Messages .................................................. 139
Testing 3DS Responses ......................................................................................... 142
Testing the Prepaid Filtering Feature...................................................................... 144
Testing the International Card Filter Feature .......................................................... 146
Testing Security Code No-Match Filtering .............................................................. 147
Testing Advanced Fraud Tools ............................................................................... 149
Testing Account Updater......................................................................................... 151
Testing Account Updater Extended Response Codes ...................................... 152
Testing Account Updater for Tokenized Merchants .......................................... 153
Testing Tax Billing................................................................................................... 153
Testing Convenience Fees ..................................................................................... 154
Testing the Recycling Engine.................................................................................. 156
Testing Recycling Engine Cancellation ............................................................. 164
Testing Recurring Engine Transactions .................................................................. 166
Testing Gift Card Transactions ............................................................................... 179
Testing MasterPass Transactions........................................................................... 189
Testing Apple Pay Transaction Processing ............................................................ 189
Testing the Submission of the Decrypted PKPaymentToken in cnpAPI ........... 190
Testing the Submission of PKPaymentToken in cnpAPI .................................. 190
Testing Android Pay Transaction Processing ......................................................... 192
Testing Android Pay using eProtect .................................................................. 192
Testing checkoutId .................................................................................................. 193
Testing SEPA Direct Debit Transaction .................................................................. 195
Testing iDEAL Transactions.................................................................................... 197
Testing Giropay Transactions ................................................................................. 198
Testing SOFORT Transactions............................................................................... 199
Testing Transaction Volume Capacity .................................................................... 200

Chapter 3 cnpAPI Transaction Examples
Overview of Online and Batch Processing Formats ..................................................... 202

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

vii

cnpAPI Reference Guide

Contents

Batch Process Format............................................................................................. 202
Supported Communication Protocols................................................................ 203
Batch Processing Request Format ................................................................... 203
Batch Processing Response Format................................................................. 203
Online Processing Format ............................................................................................ 204
Supported Communication Protocols...................................................................... 205
Online Processing Request Format ........................................................................ 205
Online Processing Response Format ..................................................................... 205
Transaction Types and Examples................................................................................. 206
Authorization Transactions...................................................................................... 208
Authorization Request Structure ....................................................................... 208
Authorization Response Structure .................................................................... 215
Authorization Reversal Transactions ...................................................................... 220
Authorization Reversal Requests ...................................................................... 220
Authorization Reversal Responses ................................................................... 222
Activate Transactions.............................................................................................. 223
Activate Request ............................................................................................... 223
Activate Response ............................................................................................ 224
Activate Reversal Transactions (Online Only) ........................................................ 226
Activate Reversal Request ................................................................................ 226
Activate Reversal Response ............................................................................. 227
Balance Inquiry Transactions.................................................................................. 228
Balance Inquiry Request ................................................................................... 228
Balance Inquiry Response ................................................................................ 229
Cancel Subscription Transactions........................................................................... 230
Cancel Subscription Request............................................................................ 230
Cancel Subscription Response ......................................................................... 231
Capture Transactions.............................................................................................. 231
Capture Request ............................................................................................... 232
Capture Response ............................................................................................ 239
Capture Given Auth Transactions ........................................................................... 240
Capture Given Auth Request ............................................................................ 240
Capture Given Auth Response ......................................................................... 244
Create Plan Transactions........................................................................................ 246
Create Plan Request......................................................................................... 246
Create Plan Response ...................................................................................... 247
Credit Transactions ................................................................................................. 247
Credit Request for a Vantiv Processed Transaction ......................................... 248
Credit Request for a Non-Vantiv Processed Transaction ................................. 252
Credit Response ............................................................................................... 256
Deactivate Transactions.......................................................................................... 257

viii

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

Deactivate Request........................................................................................... 257
Deactivate Response ........................................................................................ 258
Deactivate Reversal Transactions (Online Only) .................................................... 259
Deactivate Reversal Request............................................................................ 259
Deactivate Reversal Response......................................................................... 260
Deposit Reversal Transactions (Online Only) ......................................................... 261
Deposit Reversal Request ................................................................................ 261
Deposit Reversal Response.............................................................................. 262
eCheck Credit Transactions.................................................................................... 263
eCheck Credit Request Against a Vantiv Transaction ...................................... 263
eCheck Credit Request for a Non-Vantiv Processed Sale ................................ 265
eCheck Credit Response .................................................................................. 266
eCheck Prenotification Credit Transactions (Batch Only) ....................................... 266
eCheck Prenotification Credit Request ............................................................. 267
eCheck Prenotification Credit Response .......................................................... 268
eCheck Prenotification Sale Transactions (Batch Only) ......................................... 269
eCheck Prenotification Sale Request................................................................ 269
eCheck Prenotification Sale Response ............................................................. 270
eCheck Redeposit Transactions ............................................................................. 271
eCheck Redeposit Request .............................................................................. 271
eCheck Redeposit Response............................................................................ 273
eCheck Sale Transactions ...................................................................................... 274
eCheck Sale Request ....................................................................................... 274
eCheck Sale Response..................................................................................... 276
eCheck Verification Transactions............................................................................ 277
eCheck Verification Request ............................................................................. 278
eCheck Verification Response .......................................................................... 280
eCheck Void Transactions (Online Only) ................................................................ 281
eCheck Void Request ....................................................................................... 281
eCheck Void Response..................................................................................... 282
Force Capture Transactions.................................................................................... 283
Force Capture Request..................................................................................... 283
Force Capture Response .................................................................................. 286
Fraud Check Transaction........................................................................................ 288
Fraud Check Request ....................................................................................... 288
Fraud Check Response .................................................................................... 289
Gift Card Auth Reversal Transactions..................................................................... 290
Gift Card Auth Reversal Request ...................................................................... 290
Gift Card Auth Reversal Response ................................................................... 291
Gift Card Capture Transactions .............................................................................. 292
Gift Card Capture Request................................................................................ 292

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

ix

cnpAPI Reference Guide

Contents

Gift Card Capture Response ............................................................................. 293
Gift Card Credit Transactions.................................................................................. 294
Gift Card Credit Request................................................................................... 294
Gift Card Credit Response ................................................................................ 295
Load Transactions................................................................................................... 296
Load Request.................................................................................................... 296
Load Response ................................................................................................. 297
Load Reversal Transactions (Online Only) ............................................................. 298
Load Reversal Request..................................................................................... 298
Load Reversal Response.................................................................................. 299
Status Query Transactions (Online Only) .............................................................. 300
Query Transaction Request .............................................................................. 301
Query Transaction Response ........................................................................... 301
Refund Reversal Transactions (Online Only).......................................................... 304
Refund Reversal Request ................................................................................. 305
Refund Reversal Response .............................................................................. 306
Register Token Transactions .................................................................................. 307
Register Token Request ................................................................................... 307
Register Token Response................................................................................. 310
RFR Transactions (Batch Only) .............................................................................. 312
RFR Request .................................................................................................... 312
RFR Response.................................................................................................. 313
Sale Transactions ................................................................................................... 314
Sale Request..................................................................................................... 314
Sale Response.................................................................................................. 319
Unload Transactions ............................................................................................... 325
Unload Request ................................................................................................ 325
Unload Response.............................................................................................. 326
Unload Reversal Transactions (Online Only).......................................................... 326
Unload Reversal Request ................................................................................. 327
Unload Reversal Response .............................................................................. 328
Update Plan Transactions....................................................................................... 329
Update Plan Request ........................................................................................ 329
Update Plan Response ..................................................................................... 329
Update Subscription Transactions .......................................................................... 330
Update Subscription Request ........................................................................... 330
Update Subscription Response......................................................................... 332
Update Card Validation Number Transactions........................................................ 332
Update Card Validation Number Request ......................................................... 333
Update Card Validation Number Response ...................................................... 333
Void Transactions (Online Only) ............................................................................. 334

x

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

Void Request..................................................................................................... 335
Void Response.................................................................................................. 335

Chapter 4 cnpAPI Elements
accNum ........................................................................................................................ 338
accountInfo .................................................................................................................. 339
accountInformation ...................................................................................................... 340
accountNumber ............................................................................................................ 341
accountNumberLength ................................................................................................. 342
accountUpdate ............................................................................................................. 343
accountUpdateFileRequestData .................................................................................. 344
accountUpdater ............................................................................................................ 345
accountUpdateResponse ............................................................................................. 349
accType ........................................................................................................................ 350
actionReason ............................................................................................................... 351
activate ......................................................................................................................... 352
activateResponse ........................................................................................................ 353
activateReversal .......................................................................................................... 354
activateReversalResponse .......................................................................................... 355
active ............................................................................................................................ 356
addOnCode .................................................................................................................. 357
addressIndicator ........................................................................................................... 358
addressLine1, addressLine2, addressLine3 ................................................................. 359
advancedAVSResult ..................................................................................................... 360
advancedFraudChecks ................................................................................................ 361
advancedFraudResults ................................................................................................ 362
affiliate........................................................................................................................... 363
affluence ....................................................................................................................... 364
allowPartialAuth ............................................................................................................ 365
amexAggregatorData.................................................................................................... 366
amount .......................................................................................................................... 367
androidpayResponse ................................................................................................... 369
applepay ....................................................................................................................... 370
applepayResponse ....................................................................................................... 371
applicationData ............................................................................................................. 372
applicationExpirationDate ............................................................................................. 373
applicationPrimaryAccountNumber............................................................................... 374
approvedAmount........................................................................................................... 375
authAmount................................................................................................................... 376
authCode ...................................................................................................................... 377
authDate ....................................................................................................................... 378

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xi

cnpAPI Reference Guide

Contents

authenticatedByMerchant ............................................................................................. 379
authentication................................................................................................................ 380
authenticationResult ..................................................................................................... 381
authenticationTransactionId.......................................................................................... 382
authenticationValue ...................................................................................................... 383
authInformation ............................................................................................................. 384
authorization ................................................................................................................. 385
authorizationResponse ................................................................................................. 386
authorizationSourcePlatform......................................................................................... 387
authReversal................................................................................................................. 388
authReversalResponse................................................................................................. 389
availableBalance........................................................................................................... 390
avsResult ...................................................................................................................... 391
balanceInquiry .............................................................................................................. 392
balanceInquiryResponse ............................................................................................. 393
batchRequest................................................................................................................ 394
batchResponse ............................................................................................................. 402
beginningBalance ........................................................................................................ 403
billingDate .................................................................................................................... 404
billMeLaterRequest ....................................................................................................... 405
billMeLaterResponseData............................................................................................. 407
billToAddress ................................................................................................................ 408
bin ................................................................................................................................. 410
bmlMerchantId .............................................................................................................. 411
bmlProductType............................................................................................................ 412
bypassVelocityCheck .................................................................................................... 413
campaign ...................................................................................................................... 414
cancelSubscription ....................................................................................................... 415
cancelSubscriptionResponse ....................................................................................... 416
capability ....................................................................................................................... 417
capture .......................................................................................................................... 418
captureAmount.............................................................................................................. 419
captureGivenAuth ......................................................................................................... 420
captureGivenAuthResponse ......................................................................................... 421
captureResponse.......................................................................................................... 422
card ............................................................................................................................... 423
cardAcceptorTaxId........................................................................................................ 425
cardholderAuthentication .............................................................................................. 426
cardholderId .................................................................................................................. 427
cardholderName ........................................................................................................... 428
cardOrToken ................................................................................................................. 429

xii

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

cardProductType........................................................................................................... 430
cardSuffix ..................................................................................................................... 431
cardValidationNum........................................................................................................ 432
cardValidationResult ..................................................................................................... 433
cashBackAmount ......................................................................................................... 434
catLevel ........................................................................................................................ 435
ccdPaymentInformation ............................................................................................... 436
chargeback ................................................................................................................... 437
checkNum .................................................................................................................... 438
checkoutId .................................................................................................................... 439
city................................................................................................................................. 440
clinicOtherAmount......................................................................................................... 441
code .............................................................................................................................. 442
commodityCode ............................................................................................................ 443
companyName.............................................................................................................. 444
country .......................................................................................................................... 445
createAddOn ................................................................................................................ 446
createDiscount ............................................................................................................. 447
createPlan .................................................................................................................... 448
createPlanResponse .................................................................................................... 449
credit ............................................................................................................................. 450
creditAmount................................................................................................................. 451
creditLine ...................................................................................................................... 452
creditLitleTxnId ............................................................................................................. 453
creditResponse ............................................................................................................. 454
cryptogram ................................................................................................................... 455
currencyCode ............................................................................................................... 456
customAttribute1 .......................................................................................................... 457
customBilling................................................................................................................. 458
customIdentifier ............................................................................................................ 460
customerInfo ................................................................................................................. 461
customerIpAddress ....................................................................................................... 462
customerReference....................................................................................................... 463
customerRegistrationDate ............................................................................................ 464
customerType ............................................................................................................... 465
customerWorkTelephone.............................................................................................. 466
data ............................................................................................................................... 467
deactivate ..................................................................................................................... 468
deactivateResponse .................................................................................................... 469
deactivateReversal ...................................................................................................... 470
deactivateReversalResponse ...................................................................................... 471

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xiii

cnpAPI Reference Guide

Contents

debtRepayment............................................................................................................. 472
deleteAddOn ................................................................................................................ 473
deleteDiscount ............................................................................................................. 474
deliveryType.................................................................................................................. 475
dentalAmount................................................................................................................ 476
depositReversal ........................................................................................................... 477
depositReversalResponse ........................................................................................... 478
description .................................................................................................................... 479
descriptor ...................................................................................................................... 480
destinationCountryCode ............................................................................................... 481
destinationPostalCode .................................................................................................. 482
detailTax ....................................................................................................................... 483
deviceManufacturerIdentifier......................................................................................... 484
deviceReputationScore ................................................................................................ 485
deviceReviewStatus...................................................................................................... 486
discountAmount ............................................................................................................ 487
discountCode ............................................................................................................... 488
dob ................................................................................................................................ 489
dutyAmount................................................................................................................... 490
echeck........................................................................................................................... 491
eCheckAccountSuffix ................................................................................................... 492
echeckCredit ................................................................................................................. 493
echeckCreditResponse................................................................................................. 494
echeckForToken ........................................................................................................... 495
echeckOrEcheckToken................................................................................................. 496
echeckPreNoteCredit ................................................................................................... 497
echeckPreNoteCreditResponse ................................................................................... 498
echeckPreNoteSale ..................................................................................................... 499
echeckPreNoteSaleResponse ..................................................................................... 500
echeckRedeposit .......................................................................................................... 501
echeckRedepositResponse .......................................................................................... 502
echeckSale ................................................................................................................... 503
echeckSalesResponse ................................................................................................. 504
echeckToken................................................................................................................. 505
echeckVerification......................................................................................................... 506
echeckVerificationResponse......................................................................................... 507
echeckVoid ................................................................................................................... 508
echeckVoidResponse ................................................................................................... 509
eciIndicator.................................................................................................................... 510
email ............................................................................................................................. 511
employerName.............................................................................................................. 512

xiv

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

encryptedTrack ............................................................................................................ 513
endDate ....................................................................................................................... 514
endingBalance ............................................................................................................. 515
endpoint ....................................................................................................................... 516
enhancedAuthResponse............................................................................................... 517
enhancedData............................................................................................................... 519
entryMode ..................................................................................................................... 523
ephemeralPublicKey ..................................................................................................... 524
expDate......................................................................................................................... 525
expMonth ..................................................................................................................... 526
expYear ........................................................................................................................ 527
extendedCardResponse .............................................................................................. 528
fastAccessFunding ....................................................................................................... 529
fastAccessFundingResponse ...................................................................................... 530
fieldValue ..................................................................................................................... 531
filtering .......................................................................................................................... 532
finalPayment ................................................................................................................ 533
firstName....................................................................................................................... 534
forceCapture ................................................................................................................. 535
forceCaptureResponse ................................................................................................. 536
formatId ........................................................................................................................ 537
fraudCheck ................................................................................................................... 538
fraudCheckResponse .................................................................................................. 539
fraudFilterOverride ....................................................................................................... 540
fraudResult ................................................................................................................... 541
fundingInstructionVoid ................................................................................................. 542
fundingInstructionVoidResponse ................................................................................. 543
fundingSource............................................................................................................... 544
fundingSubmerchantId ................................................................................................. 545
fundsTransferId............................................................................................................. 546
giftCardAuthReversal .................................................................................................... 547
giftCardAuthReversalResponse.................................................................................... 548
giftCardBin ................................................................................................................... 549
giftCardCapture............................................................................................................. 550
giftCardCaptureResponse ............................................................................................ 551
giftCardCredit................................................................................................................ 552
giftCardCreditResponse................................................................................................ 553
giftCardResponse ........................................................................................................ 554
giropay .......................................................................................................................... 555
giropayResponse .......................................................................................................... 556
header .......................................................................................................................... 557

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xv

cnpAPI Reference Guide

Contents

healthcareAmounts ....................................................................................................... 558
healthcareIIAS .............................................................................................................. 559
iban .............................................................................................................................. 560
ideal .............................................................................................................................. 561
idealResponse .............................................................................................................. 562
IIASFlag ........................................................................................................................ 563
incomeAmount .............................................................................................................. 564
incomeCurrency............................................................................................................ 565
international .................................................................................................................. 567
intervalType ................................................................................................................. 568
invoiceReferenceNumber ............................................................................................. 569
issuerCountry................................................................................................................ 570
itemCategoryCode ........................................................................................................ 571
itemDescription ............................................................................................................. 572
itemDiscountAmount..................................................................................................... 573
itemSequenceNumber .................................................................................................. 574
ksn ................................................................................................................................ 575
lastName....................................................................................................................... 576
lineItemData.................................................................................................................. 577
lineItemTotal ................................................................................................................. 579
lineItemTotalWithTax .................................................................................................... 580
litleInternalRecurringRequest ....................................................................................... 581
litleOnlineRequest......................................................................................................... 582
litleOnlineResponse ..................................................................................................... 583
litleRequest ................................................................................................................... 585
litleResponse ................................................................................................................ 586
litleSessionId................................................................................................................. 588
litleToken....................................................................................................................... 589
litleTxnId........................................................................................................................ 590
load .............................................................................................................................. 592
loadResponse .............................................................................................................. 593
loadReversal ................................................................................................................ 594
loadReversalResponse ................................................................................................ 595
mandateProvider .......................................................................................................... 596
mandateReference ...................................................................................................... 597
mandateSignatureDate ................................................................................................ 598
mandateURL ................................................................................................................ 599
matchCount................................................................................................................... 600
merchantData ............................................................................................................... 601
merchantGroupingId ..................................................................................................... 602
merchantId .................................................................................................................... 603

xvi

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

message ....................................................................................................................... 604
middleInitial ................................................................................................................... 605
mpos ............................................................................................................................. 606
name ............................................................................................................................. 607
networkField ................................................................................................................. 608
networkResponse ........................................................................................................ 610
networkSubField .......................................................................................................... 611
networkTransactionId ................................................................................................... 612
newAccountInfo ............................................................................................................ 613
newCardInfo ................................................................................................................. 614
newCardTokenInfo ....................................................................................................... 615
newTokenInfo ............................................................................................................... 616
nextRecycleTime ......................................................................................................... 617
number.......................................................................................................................... 618
numberOfPayments ..................................................................................................... 619
onlinePaymentCryptogram ........................................................................................... 620
orderDate ...................................................................................................................... 621
orderId........................................................................................................................... 622
orderSource .................................................................................................................. 623
originalAccountInfo ....................................................................................................... 625
origAccountNumber ..................................................................................................... 626
origActionType ............................................................................................................. 627
origId ............................................................................................................................ 629
originalAmount .............................................................................................................. 630
originalCard................................................................................................................... 631
originalCardInfo ............................................................................................................ 632
originalCardTokenInfo .................................................................................................. 633
originalNetworkTransactionId ...................................................................................... 634
originalRefCode ............................................................................................................ 635
originalSequenceNumber ............................................................................................. 636
originalSystemTraceId .................................................................................................. 637
originalToken ............................................................................................................... 638
originalTokenInfo ......................................................................................................... 639
originalTransactionAmount .......................................................................................... 640
originalTxnTime ............................................................................................................ 641
origLitleTxnId ............................................................................................................... 642
origOrderId ................................................................................................................... 643
password ...................................................................................................................... 644
payerId ......................................................................................................................... 645
payFacCredit ................................................................................................................ 646
payFacCreditResponse ............................................................................................... 647

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xvii

cnpAPI Reference Guide

Contents

payFacDebit ................................................................................................................. 648
payFacDebitResponse ................................................................................................. 649
paymentDataType ........................................................................................................ 650
paymentPurpose........................................................................................................... 651
paypage ........................................................................................................................ 652
paypageRegistrationId .................................................................................................. 653
paypal ........................................................................................................................... 654
payPalNotes ................................................................................................................. 655
payPalOrderComplete .................................................................................................. 656
phone ............................................................................................................................ 657
phone as a child of billToAddress and shipToAddress ..................................... 657
phone as a child of customBilling...................................................................... 657
physicalCheckCredit .................................................................................................... 658
physicalCheckCreditResponse .................................................................................... 659
physicalCheckDebit ...................................................................................................... 660
physicalCheckDebitResponse ..................................................................................... 661
pin ................................................................................................................................ 662
planCode ...................................................................................................................... 663
pos ................................................................................................................................ 664
postDate........................................................................................................................ 665
postDay ........................................................................................................................ 666
preapprovalNumber ...................................................................................................... 667
preferredLanguage ...................................................................................................... 668
prepaid .......................................................................................................................... 669
prepaidCardType .......................................................................................................... 670
processingInstructions .................................................................................................. 671
processingType ............................................................................................................ 672
productCode ................................................................................................................. 673
publicKeyHash ............................................................................................................. 674
quantity ......................................................................................................................... 675
queryTransaction ......................................................................................................... 676
queryTransactionResponse ......................................................................................... 677
queryTransactionUnavailableResponse ...................................................................... 678
recurringRequest ......................................................................................................... 679
recurringResponse ....................................................................................................... 680
recurringTxnId .............................................................................................................. 681
recycleAdvice................................................................................................................ 682
recycleAdviceEnd ........................................................................................................ 683
recycleBy ...................................................................................................................... 684
recycleEngineActive ..................................................................................................... 685
recycleId ....................................................................................................................... 686

xviii

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

recycling ....................................................................................................................... 687
recycling Element as a Child of authorizationResponse or saleResponse ............. 687
recycling Element as a Child of voidResponse ....................................................... 687
recyclingRequest .......................................................................................................... 689
redirectToken ............................................................................................................... 690
redirectUrl .................................................................................................................... 691
refCode ......................................................................................................................... 692
refundReversal ............................................................................................................. 693
refundReversalResponse ............................................................................................ 694
registerTokenRequest................................................................................................... 695
registerTokenResponse................................................................................................ 696
reloadable ..................................................................................................................... 697
reserveCredit ............................................................................................................... 698
reserveCreditResponse ............................................................................................... 699
reserveDebit ................................................................................................................. 700
reserveDebitResponse ................................................................................................. 701
residenceStatus ............................................................................................................ 702
response ....................................................................................................................... 703
responseCode .............................................................................................................. 704
responseMessage ........................................................................................................ 705
responseTime ............................................................................................................... 706
results_Max10 .............................................................................................................. 707
RFRRequest ................................................................................................................. 710
RFRResponse .............................................................................................................. 711
routingNum ................................................................................................................... 712
RxAmount ..................................................................................................................... 713
sale ............................................................................................................................... 714
saleResponse ............................................................................................................... 715
salesTax........................................................................................................................ 716
secondaryAmount ........................................................................................................ 717
sellerId .......................................................................................................................... 718
sellerMerchantCategoryCode ....................................................................................... 719
sepaDirectDebit ........................................................................................................... 720
sepaDirectDebitResponse ........................................................................................... 721
sequenceNumber.......................................................................................................... 722
sequenceType ............................................................................................................. 723
shipFromPostalCode .................................................................................................... 724
shippingAmount ............................................................................................................ 725
shipToAddress .............................................................................................................. 726
signature ....................................................................................................................... 727
sofort ............................................................................................................................. 728

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xix

cnpAPI Reference Guide

Contents

sofortResponse............................................................................................................. 729
ssn ................................................................................................................................ 730
startDate ...................................................................................................................... 731
state .............................................................................................................................. 732
submerchantCredit ....................................................................................................... 733
submerchantCreditResponse ...................................................................................... 734
submerchantDebit ........................................................................................................ 735
submerchantDebitResponse ........................................................................................ 736
submerchantName........................................................................................................ 737
subscription .................................................................................................................. 738
subscriptionId ............................................................................................................... 740
surchargeAmount ......................................................................................................... 741
systemTraceId .............................................................................................................. 742
taxAmount..................................................................................................................... 743
taxExempt ..................................................................................................................... 744
taxIncludedInTotal......................................................................................................... 745
taxRate.......................................................................................................................... 746
taxType ......................................................................................................................... 747
taxTypeIdentifier ........................................................................................................... 748
terminalId ..................................................................................................................... 749
termsAndConditions...................................................................................................... 750
threatMetrixSessionId .................................................................................................. 751
token ............................................................................................................................. 752
token (Vantiv generated card number replacement)............................................... 752
token (PayPal generated) ....................................................................................... 753
tokenMessage............................................................................................................... 754
tokenResponse ............................................................................................................. 755
tokenResponseCode .................................................................................................... 756
totalHealthcareAmount ................................................................................................. 757
track .............................................................................................................................. 758
track1Status ................................................................................................................. 759
track2Status ................................................................................................................. 760
transactionAmount ....................................................................................................... 761
transactionId ................................................................................................................. 762
transactionId as a Child of the paypal element ....................................................... 762
transactionId as a Child of the header element....................................................... 762
trialIntervalType ........................................................................................................... 764
trialNumberOfIntervals ................................................................................................. 765
triggeredRule ............................................................................................................... 766
txnTime ......................................................................................................................... 767
type ............................................................................................................................... 768

xx

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide

Contents

type Element as a Child of the parent elements listed below.................................. 768
type Element as a Child of fundingSource .............................................................. 769
unitCost......................................................................................................................... 770
unitOfMeasure .............................................................................................................. 771
unload .......................................................................................................................... 772
unloadResponse .......................................................................................................... 773
unloadReversal ............................................................................................................ 774
unloadReversalResponse ............................................................................................ 775
updateAddOn ............................................................................................................... 776
updatedCard ................................................................................................................. 777
updateCardValidationNumOnToken ............................................................................. 778
updateCardValidationNumOnTokenResponse............................................................. 779
updateDiscount ............................................................................................................ 780
updatePlan ................................................................................................................... 781
updatePlanResponse ................................................................................................... 782
updateSubscription ...................................................................................................... 783
updateSubscriptionResponse ...................................................................................... 787
updatedToken ............................................................................................................... 788
url .................................................................................................................................. 789
user ............................................................................................................................... 790
vendorCredit ................................................................................................................ 791
vendorCreditResponse ................................................................................................ 792
vendorDebit .................................................................................................................. 793
vendorDebitResponse ................................................................................................. 794
vendorName ................................................................................................................ 795
verificationCode ............................................................................................................ 796
verify ............................................................................................................................. 797
version ......................................................................................................................... 798
virtualAccountNumber .................................................................................................. 799
virtualAuthenticationKeyData........................................................................................ 800
virtualAuthenticationKeyPresenceIndicator .................................................................. 801
virtualGiftCard .............................................................................................................. 802
virtualGiftCardBin ......................................................................................................... 803
virtualGiftCardResponse .............................................................................................. 804
visionAmount ................................................................................................................ 805
void ............................................................................................................................... 806
voidResponse ............................................................................................................... 807
wallet ............................................................................................................................ 808
walletSourceType ........................................................................................................ 809
walletSourceTypeId ..................................................................................................... 810
yearsAtEmployer........................................................................................................... 811

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xxi

cnpAPI Reference Guide

Contents

yearsAtResidence......................................................................................................... 812
zip ................................................................................................................................. 813

Appendix A Payment Transaction Response Codes
Payment Transaction Response Codes ....................................................................... 816
3DS Authentication Result Codes................................................................................. 840
AVS Response Codes .................................................................................................. 842
AAVS Response Codes................................................................................................ 843
Card Validation Response Codes ................................................................................. 846
Advanced Fraud Tools Triggered Rules ....................................................................... 847
XML Validation Error Messages ................................................................................... 864
Additional Response Header Error Messages .............................................................. 866
ACH Return Reason Codes .......................................................................................... 868
ACH NoC Change Codes ............................................................................................. 871
Canadian eCheck Return Codes .................................................................................. 872

Appendix B Credit Card Number Formats
Appendix C Test Card Numbers
Appendix D PayFac™ Dynamic Payout
Advantages of Using Dynamic Payout.......................................................................... 884
Overview of Dynamic Payout ....................................................................................... 885
Timing of Transactions, Reports, and Money Movement........................................ 886
Money Movement and Accounts ............................................................................ 887
Same Day Funding .......................................................................................... 888
FastAccess Funding™ ..................................................................................... 889
Account Balance Verifications........................................................................... 890
Example of Funding Instructions .................................................................................. 891
Funding Instruction Void Transactions.................................................................... 895
Funding Instruction Certification Testing....................................................................... 896
SSR Reports ................................................................................................................. 898
Tax ID Validation Process ............................................................................................ 900

xxii

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

ABOUT THIS GUIDE
This manual serves as a reference to the cnpAPI transaction formats used for payment processing
with Vantiv, LLC. It also explains how to perform unattended transaction testing and attended
certification testing with Vantiv.

Intended Audience
This document is intended for technical personnel who will be setting up and maintaining
payment processing using the cnpAPI format.

Revision History
This document has been revised as follows:

TABLE 1
Doc.
Version

Document Revision History

Description

Location(s)

1.0

Initial release of LitleXML Reference Guide for schema V11.0,
including new Gift Card transactions and international alternate
payment methods.

N/A

1.1

Added  to several eCheck transactions.

Chapters 3 and 4

Added information about the iDEAL international payment
method, which is now GA.

Chapters 1, 2, and 4

Corrected maintenance window times for Pre-/Post-Live.

Chapter 2

Added "Appears in Declined Transaction report." note to certain
Response Codes.

Appendix A

1.2

Document Version: 1.8

xxiii
© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
About This Guide

TABLE 1

Revision History

Document Revision History

Doc.
Version

Description

Location(s)

1.3

Replaced LitleXML with cnpAPI.

All

Added three new tests for new MC 3DS behavior.

Chapter 2

Moved Dupe Tests from Optional to Required test group.

Chapter 2

Added info about checkoutId element (not GA)

Chapter 3

Added info about sameDayFunding Batch Request attribute.

Chapter 4 & Appendix D

Added info about SOFORT and Giropay alternate payment
methods.

Chapters 1, 2, and 4

Revised/renamed Customer Insights to Issuer Insights.

Chapter 1

Corrected several examples, replacing Response Code 001 Transaction Received with 000 - Approved.

Chapter 3

Corrected Response Code for Test GC17 - 281 changed to 218.

Chapter 2

Updated Litle to Vantiv in Response messages.

All

Added Note about expDate to token element definition.

Chapter 4

Added/modified information in section 2.1.

Chapter 2

orderId element added to accountUpdateResponse.

Chapter 4

Removed " not yet supported " note from checkoutId element
and added Cert tests

Chapters 2 and 4

Modified requirements for Level 2/3 data (enhancedData
element).

Chapter 4

Added Response Codes 940 and 941.

Appendix A

Added text clarifying limit of 25K for Same day Funding
transaction and removed debit transaction restrictions.

Appendix D

Added note about 30 minute wait for funds to be restored to
Settlement account balance after issuing a Funding Instruction
Void transaction.

Appendix D

Removed Mobile Point of Sale sections from guide

Chapters 1 and 2

Updated document for release of V11.3, including Online
Dynamic Payout Funding Instructions and Fast Funding
transaction.

All

Fixed various links to github and test environments.

Chapter 2

Fixed error in definition of customerReference element.

Chapter 4

Added info about support for Visa token transactions with 3-D
Secure (TAVV and DTVV), as well as new 3-DS response code
definitions.

Chapter 4 & Appendix A

1.4

1.5

1.6

1.7

xxiv

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Revision History

TABLE 1

About This Guide

Document Revision History

Doc.
Version

Description

Location(s)

1.8

Remove reference to Recurring Snapshot report.

Chapter 1

Updated Android Pay Certification test results.

Chapter 2

Corrected maxLength of id attribute, which increased from 25 to
36 in V11.3.

Chapter 4

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xxv

cnpAPI Reference Guide
About This Guide

Document Structure

Document Structure
This manual contains the following sections:
Chapter 1, "Introduction"
This chapter provides an introduction to transaction processing using cnpAPI.
Chapter 2, "Testing Your cnpAPI Transactions"
This chapter provides information concerning the testing and certification process, which you
must complete prior to submitting transactions to the Vantiv production environment.
Chapter 3, "cnpAPI Transaction Examples"
This chapter provides information concerning the cnpAPI structure for transaction submission, as
well as examples.
Chapter 4, "cnpAPI Elements"
This chapter provides definitions and other information concerning each cnpAPI element.
Appendix A, "Payment Transaction Response Codes"
This appendix lists all of the possible response codes and messages.
Appendix B, "Credit Card Number Formats"
This appendix provides information about credit card number formats and Mod-10 validation.
Appendix C, "Test Card Numbers"
This appendix provides credit card number that can be used for testing.
Appendix D, "PayFac™ Dynamic Payout"
This appendix provides information about PayFac Dynamic Payout transactions.

Documentation Set
For additional information concerning the Vantiv application, see any of the following guides in
the documentation set:

xxvi

•

iQ Reporting and Analytics User Guide

•

Vantiv Chargeback API Reference Guide

•

Vantiv Chargeback Process Guide

•

Vantiv eCommerce Partner Integration Overview Guide

•

Vantiv PayPal Integration Guide

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Documentation Set

About This Guide

•

Vantiv PayFac™ API Reference Guide

•

Vantiv PayFac™ Portal User Guide

•

Vantiv PayFac™ Integration Overview Guide

•

Vantiv eProtect™ Integration Guide

•

Vantiv Enterprise eProtect™ Integration Guide

•

Vantiv XML Differences Guide

•

Vantiv Secure Scheduled Reports Reference Guide

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xxvii

cnpAPI Reference Guide
About This Guide

Typographical Conventions

Typographical Conventions
Table 2 describes the conventions used in this guide.

TABLE 2

Typographical Conventions

Convention
.
.
.

Meaning
Vertical ellipsis points in an example mean that information not
directly related to the example has been omitted.

...

Horizontal ellipsis points in statements or commands mean that
parts of the statement or command not directly related to the
example have been omitted.

<>

Angle brackets are used in the following situations:

•
•

xxviii

user-supplied values (variables)
XML elements

[]

Brackets enclose optional clauses from which you can choose one
or more option.

bold text

Bold text indicates emphasis.

Italicized text

Italic type in text indicates the name of a referenced external
document.

blue text

Blue text indicates either a hypertext link or an element name (in
xml examples).

monospaced text

Used in code examples and elsewhere to designate field/element
names.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Contact Information

About This Guide

Contact Information
This section provides contact information for organizations within Vantiv.
Implementation - For technical assistance to resolve issues encountered during the on-boarding
process, including cnpAPI certification testing.
Implementation Contact Information
E-mail

implementation@vantiv.com

Hours Available

Monday – Friday, 8:30 A.M.– 5:30 P.M. EST

Chargebacks - For business-related issues and questions regarding financial transactions and
documentation associated with chargeback cases, contact the Chargebacks Department.
Chargebacks Department Contact Information
Telephone

1-844-843-6111 (option 4)

E-mail

chargebacks@vantiv.com

Hours Available

Monday – Friday, 7:30 A.M.– 5:00 P.M. EST

Technical Support - For technical issues such as file transmission errors, email Technical
Support. A Technical Support Representative will contact you within 15 minutes to resolve the
problem.
Technical Support Contact Information
E-mail

eCommerceSupport@vantiv.com

Hours Available

24/7 (seven days a week, 24 hours a day)

Relationship Management/Customer Service - For non-technical issues, including questions
concerning iQ Reporting and Analytics, help with passwords, modifying merchant details, and
changes to user account permissions, contact the Relationship Management/Customer Service
Department. If you are a Payment Facilitator (PayFac), refer to the second table.
Relationship Management/Customer Service Contact Information - Merchants
Telephone

1-844-843-6111 (Option 3)

E-mail

ecc@vantiv.com

Hours Available

Monday – Friday, 8:00 A.M.– 6:00 P.M. EST

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

xxix

cnpAPI Reference Guide
About This Guide

Contact Information

Relationship Management/Customer Service Contact Information - Payment Facilitators
Telephone

1-844-843-6111 (Option 5)

E-mail

PayFacEComm@vantiv.com

Hours Available

Monday – Friday, 8:00 A.M.– 5:00 P.M. EST

Technical Publications - For questions or comments about this document, please address your
feedback to the Technical Publications Department. All comments are welcome.
Technical Publications Contact Information
E-mail

xxx

TechPubs@vantiv.com

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

1
INTRODUCTION
The cnpAPI data format supports two types of transaction submission methods: Online and
Batch. With the Online method, you submit each transaction independently and receive a
response in real-time. Typically, merchants use the Online method for Authorization transactions,
as well as transactions available only via Online (for example, Void). The Batch method enables
you to submit multiple transactions simultaneously in a single Session file. Vantiv recommends
the Batch method for all transaction submissions except Authorizations and the transaction
available only via Online.
This chapter provides an overview of the cnpAPI data format, including some basic XML coding
requirements. Also discussed are the advantages of using batch processing, duplicate transaction
detection, report groups, Value Added Services, and supported transaction types.
The topics discussed in this chapter are:

•

The cnpAPI Data Format

•

Fraud Toolkit

•

Batch Transaction Processing

•

Tokenization Feature

•

Payment Integration Platform (cnpAPI SDKs)

•

eCheck Processing

•

Duplicate Transaction Detection

•

SEPA Direct Debit

•

Coding for Report Groups

•

iDEAL, SOFORT, and Giropay

•

Recovery

•

eCommerce Solution for Apple Pay™

•

Recurring Engine

•

eCommerce Solution for Android Pay™

•

Issuer Insights

•

Supported Transaction Types

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

1

cnpAPI Reference Guide
Introduction

1.1

The cnpAPI Data Format

The cnpAPI Data Format
There are several advantages to using the cnpAPI format as follows:
•

Easier Implementation, Operations, and Debugging - Compared to fixed length or binary
formats, the XML format is considerably easier for operations staff to read and edit, using
virtually any text editor. This allows Vantiv’s Implementation, First Line Support, and
Relationship Managers to quickly communicate any issues and work with your own
operations staff to make necessary corrections without worrying about line lengths, padding
or encoding.

•

Fewer Downgrades - Since the cnpAPI format allows you to explicitly tie deposits to their
associated authorizations via the  element, your transactions qualify for the
best interchange rates at a higher frequency than with formats that do not support this
transaction cross-referencing.

•

Simpler Capture (Deposit) and Refund Transactions - Because the cnpAPI format
associates related transactions using the  element, our format does not require
you to resubmit all of the authorization information on a deposit nor all of the deposit
information on a refund. When you submit the unique transaction id, Vantiv automatically
pulls the information from the original transaction. Most other formats require you to
resubmit the related data with each transaction.

•

Superior Reporting - The cnpAPI format allows you to separate your transactions into
different categories by specifying a Report Group on each transaction. When accessing your
data on the iQ reporting and Analytics Interface, this feature allows you to filter your
financial reports by Report Groups, providing more granular detail based on a reporting
hierarchy the Report Groups create. Most other formats restrict reporting categories to a batch
or specific merchant id.

•

Improved Chargeback Management - Unlike most other formats where transactional
relationships can be a “best guess” proposition, the cnpAPI format explicitly ties related
transactions, allowing you and Vantiv to see authorization-to-deposit and deposit-to-refund
relationships with precision. This knowledge is indispensable when fighting chargebacks.

•

New Features - New features developed for the Vantiv eCommerce platform are first
exposed via the XML API. While the SDKs add new capabilities shortly after development,
direct coding to the XML API gains access to these feature and capabilities earlier.

1.1.1

Communications Protocols

There are two communication protocols supported for the submission of Batch transactions to
Vantiv eCommerce platform for processing and one for Online submissions as shown in
Table 1-1. For Batch submissions Vantiv recommends that you use one of the two FTP methods.
Use the HTTPS Post method for Online transactions.

2

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
The cnpAPI Data Format

TABLE 1-1

Introduction

Communication Protocol Support Matrix

Protocol

Encryption

Batch

Online

HTTPS Post

TLS 1.2

N/A

Required

TCP/IP Socket

TLS 1.2

N/A

N/A

FTP

PGP or GPG (open source)

Recommended

N/A

sFTP

SSH Key

Recommended

N/A

If you use the standard FTP method, you must use either the Pretty Good Privacy (PGP) or the
open source GNU Privacy Guard (GPG) encryption for your submissions. Both of these
encryption methods use key cryptography and support message authentication and integrity
checking. The alternate method, Secure FTP (sFTP), uses Secure Shell (SSH) to secure the
transmission.

1.1.2

General XML Coding Requirements

As part of the on-boarding process, you receive XML schema files from your Implementation
Consultant. Using those files and this document as a guide, you create the required XML
documents for submission of your transactions. You should validate all XML you create using the
supplied schema. Also, working with your Implementation Consultant, you are required to
perform various tests of your XML (see Chapter 2, "Testing Your cnpAPI Transactions") prior to
submitting transactions to the production environment.
In addition to the process outlined above, there are a few XML basics of which you should be
aware.
•

Encode all data using the UTF-8 format.

•

Although it is not required, Vantiv recommends that when formatting your XML, you keep
each element on its own line. This will aid in debugging situations where an error message
specifies an issue in a particular line of XML code (for example, line 20).

•

Be aware of special characters that require specific handling (see Table 1-2). For example, the
less than (<) and greater than (>) symbols define element tags in the XML code. Using the
entity names < and > instead of < and > prevents a browser from interpreting these
characters as element brackets.
Be sure to review data provided by customers for special character handling. For example, an
address of "4th & Main," must be rewritten as "4th & Main" (including quotes) before
being submitted via XML. Failure to quote this type of input causes rejection of XML
submissions due to syntax errors.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

3

cnpAPI Reference Guide
Introduction

The cnpAPI Data Format

TABLE 1-2
Character

1.1.3

Coding for Special Characters
Description

Entity Reference (case sensitive)

<

less than

<

>

greater than

>

“

quotation

"

‘

apostrophe

'

&

ampersand

&

Other XML Resources

There are several Internet sites that provide both reference and educational information that may
help you when implementing your XML. A few of these sites are:

4

•

http://www.w3schools.com/xml/xml_syntax.asp

•

http://www.w3.org/

•

http://www.utf-8.com/

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Batch Transaction Processing

1.2

Introduction

Batch Transaction Processing
Batch processing involves a group of transactions submitted in a single file. In the case of a
cnpAPI Batch the parent or root element is the  element. A single
, referred to as a Session, can contain many batches and each batch can contain
multiple transactions. We recommend that you use Batch processing for all transaction types
except Authorizations and Voids (Online only).
Some of the advantages of using Batch processing are:
•

Better Performance - We optimize batch processing by processing multiple transactions in
the batch simultaneously. This allows you to process thousands of transactions quickly
without writing complicated logic or managing complicated processes.

•

Easier Reconciliation - When processing a batch, all transactions within that batch post on
the same day. In the case of Online transactions, you could submit two transactions at the
same time and one could post today and the other tomorrow. This can cause confusion in your
accounting process.

•

Easier Error Recovery - A batch processes as a single unit, thus if you experience any
system or communication issue while processing a batch, you can easily determine if the file
was processed. With Online transactions, determining which individual transactions were not
processed can be more difficult.

1.2.1

Recommended Session File Size

As stated above, a Session file is a group of batches. A batch is a set of transactions for a single
merchant. Normally, you send in a single file which has one batch for each merchant. This works
well when the overall number of transactions is small. The number of transactions you should
submit in any individual Session or Batch depend on a number of factors, including whether or
not you are an individual merchant or a presenter submitting transactions for multiple merchants.
In general, you should keep the following recommendations and rules in mind when determining
the number of transactions you submit in an Session/Batch file:
•

A Batch should not exceed 20,000 transactions. If the number of transaction for a single
merchant exceeds 20,000, you should create multiple batches for the same merchant, each
batch containing not more than 20,000 transactions.

•

A Batch should not contain only one transaction, unless the merchant has only one
transaction for the day.

•

A Session file must never contain more than 9,999 Batches.

•

A Session file must never contain more than 1,000,000 transactions across all Batches.

•

Always allow sufficient time between your submission time and your cut-off time for the
processing of the Session. Larger files take longer to process.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

5

cnpAPI Reference Guide
Introduction

1.3

Payment Integration Platform (cnpAPI SDKs)

Payment Integration Platform (cnpAPI SDKs)
In order to facilitate integration to the platform, Vantiv provides several language specific SDKs
(Software Development Kits). The developers page on our website
(http://www.vantiv.com/developers) provides links to SDK libraries for several popular
languages, including:
•

PHP

•

Ruby

•

Java

•

.NET

•

Python

Extensions for:
•

Magento

•

Opencart

In addition to the SDKs and extensions, Vantiv provides examples of each supported transaction
type, as well as demonstration applications. Once you install the library appropriate to your
language, the Vantiv Sandbox, which functions as an emulator of our production environment, is
available to validate your transaction format.

6

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Duplicate Transaction Detection

1.4

Introduction

Duplicate Transaction Detection
In order to help you avoid transaction errors, Vantiv performs duplicate transaction checking for
both Online and Batch transaction submissions. While we use a robust duplicate checking
methodology, we cannot guarantee our system will catch all duplicates and bear no responsibility
for correcting the impact of erroneously submitted transactions. This section discusses the
different checking methodologies used depending upon the type of submission.
NOTE:

For tokenized transactions, the token is used in place of the card numbers
by the Duplicate Transaction Detection process.
For PayPal transactions a combination of the PayPal Id + the (consumer’s)
email is used by the Duplicate Transaction Detection process.
For transactions submitted using other formats (e.g., PTI, Nabanco, etc.),
the logic used to detect duplicates for these supported, but foreign APIs,
is less robust and may miss duplicates in certain scenarios. Vantiv
recommends, for better dupe checking, convert to the cnpAPI format, as
soon as possible.

1.4.1

Batch Duplicate Checking

When processing a Batch, the system acts to detect duplicate transactions for the following
transaction types: Authorization, Auth Reversal, Capture, Force Capture, Capture Given Auth,
Credit, Sales, eCheck Credit, and eCheck Sales.
NOTE:

For information about duplicate checking of Dynamic Payout Funding
Instructions see Batch Dupe Checking for Dynamic Payout Funding
Instructions on page 8.

For each of these transaction types, the application compares the transaction type, transaction
amount, the  element from the request, credit card number, and credit card expiration
date against transactions in other Batch processed within the previous five days. If the
characteristics of the new transaction match a previously processed transaction, the system marks
it as a duplicate.
The system only performs duplicate detection against valid transactions from the previous five
days. For example, if an Authorization request matches a declined Authorization from the
previous day, the system would not count it as a duplicate, because the declined Authorization
was not a valid Authorization.
Also, a Batch must be processed completely to be included in the previous five days of data. For
example, if multiple submitted Batches are processing simultaneously, the system will not
compare the transactions in one batch with the transactions in the other, because neither has

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

7

cnpAPI Reference Guide
Introduction

Duplicate Transaction Detection

completed processing. For this same reason the system cannot detect duplicate transactions within
the same Batch.
If the system detects ten consecutive duplicate transactions or if the number of duplicate
transactions is greater than or equal to 25% of the total transactions in the batch, the system flags
the Batch as a duplicate. When either threshold is met, Vantiv will not process the Batch. If
neither threshold is met, Vantiv continues processing the Batch, including any transactions that
may have been duplicates.

1.4.1.1

Batch Dupe Checking for Dynamic Payout Funding Instructions

Duplicate checking for funding instructions takes place at the Batch level. The system compares a
submitted Batch of instructions to other Batches submitted and accepted on the same day. If a
submitted Batch has the same totals and counts as a Batch accepted on the same day, the system
rejects the new Batch as a duplicate. If you resubmit a previously rejected Batch, it will not fail
dupe checking, because the initial submission was not accepted and is not included in dupe
checking comparisons.
NOTE:

1.4.2

If you believe we rejected a funding instruction Batch in error, please
contact your Partner Account Manager. If necessary, we can disable the
dupe check feature for a particular Batch.

Online Duplicate Checking

When processing an Online transaction, the system acts to detect duplicate transactions for the
following transaction types: Auth Reversal, Capture, Force Capture, Capture Given Auth, Credit,
Sales, eCheck Credit, eCheck Sales, eCheck Void, and Void, as well as Gift Card transactions.
For most transactions, the system compares the transaction type, the id attribute from the request,
and the credit card number against other Online transactions processed within the previous two
days. For transactions that reference other transactions (for example, a deposit referencing an
authorization or a refund referencing a deposit), the system compares the transaction type, id
attribute, and the card number from the referenced transaction (i.e. the transaction identified by
the  element) against other Online transactions processed within the previous two
days.
The system only performs duplicate detection against valid transactions. For example, if a
Capture request matches a declined Capture from the previous day, the system would not count it
as a duplicate, because the declined Capture was not a valid transaction.

8

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Duplicate Transaction Detection

NOTE:

Introduction

While it is uncommon, under certain circumstances network latency may
cause a duplicate Sale transaction to go undetected. This can occur if you
submit a second, duplicate Sale transaction while the response from the
network for the Authorization portion of the first transaction is sufficiently
delayed such that the first Sale has not been recorded as a valid
transaction in the system.
If you elect to submit Online Sale transactions, Vantiv recommends a
timeout setting of not less than 60 seconds to reduce the chances of
undetected duplicate Sale transactions.

If the system determines a transaction to be a duplicate, The duplicate transactions appears in the
Declined Transaction report with a Response Reason Code of 251 - Duplicate Transaction. You
can access this report in Vantiv iQ or via the Vantiv Secure Scheduled Report. The iQ version
provides information in near real-time, while the SSR version runs daily, providing information
for the transaction submitted the previous day.
NOTE:

If you do not receive a response for a submitted transaction, Vantiv
recommends you use the queryTransaction to determine the status of the
original transaction (see Status Query Transactions (Online Only) on page
300)

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

9

cnpAPI Reference Guide
Introduction

1.5

Coding for Report Groups

Coding for Report Groups
You use Report Groups (reportGroup attribute) to separate your transactions into different
categories, so you can view the financial reports by your specific report group names. If you are
unsure what groupings to use, your Relationship Manager can help you determine the best
practice for your business.
CAUTION:

Creation of an excessive number of Report Groups (in excess of 250) will
impact the amount of time require to compile various reports in the iQ.
Report Groups are intended to allow you to segregate transactions by
logically grouping them into the different segments of your business.
Report Groups are not intended to track sales or marketing programs that
exist for limited times. For this type of tracking, Vantiv provides other
transaction tagging methods detailed in Additional/Alternate Methods of
Tagging Transactions on page 11.

Example: Report Groups

The merchant, Demo, wants to separate their domestic and international sales information. To do
this the company submits all domestic transactions using reportGroup = "Domestic Business",
and all international transactions using reportGroup = "International Business". When they access
the Authorization Report in the iQ using the By Reporting Group tab, the transactions would be
separated as shown in Figure 1-1.
NOTE:

FIGURE 1-1

The reportGroup attribute is case and space sensitive. A reportGroup =
“Picture Frame” is a different report group than a reportGroup =
“pictureframe”.

Report Group Example - 2 Groups

The plus sign next to the Domestic Business report group signifies that there are child groups
present. When fully expanded (see Figure 1-2), the iQ shows a report group hierarchy with
information for the Domestic Business group further separated into Service A and Service B
groups and Service A containing two additional child groups. If you find it necessary to establish
this type of nested hierarchy, your Implementation Consultant will assist you.

10

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Coding for Report Groups

FIGURE 1-2

1.5.1

Introduction

Report Group Example - Expanded to Show Child Groups

Additional/Alternate Methods of Tagging Transactions

If you are using schema version 7.x or above you can use the merchantData element and its
children to tag transactions (Authorization, Sale, Credit, Force Capture, Capture Given Auth,
eCheck Sale, and eCheck Credit) with additional information. The three children of
merchantData: campaign, affiliate, and merchantGroupingId, allow you to designate
transactions as members of different groups enabling a deeper analysis of sales patterns.
NOTE:

The merchantData element and its children were add to the schema in
V8.8 and backported to V7.3. If you are using a schema version between
7.0 and 8.7, you can code for the use of these elements and still pass the
cnpAPI validation.

For example, if the merchant from the previous example were trying a new sales initiative for
Product 2 during the month of September. They plan to run ads in Boston and New York to test
the new offering. To allow a deeper analysis of sales resulting from the new campaign, they can
add the campaign element with a value of "September Ads" to the transactions originating in
both test market. They can also include the merchantgroupingId with values that reflect the
city where the order originates. By exporting either the Session report or the NSS by Transaction
report from the iQ, the company can sort their sales data based upon these fields and gain a better
understanding of the effectiveness of the sales campaign.
NOTE:

The transaction tagging elements described above appear in the exported
Session and NSS by Transaction reports. They are also visible within the
iQ in the new Transaction Detail reports.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

11

cnpAPI Reference Guide
Introduction

1.6

Recovery

Recovery
Recovery is a bundle of services that include both Account Updater and Recycling Engine. By
combining these two managed services into a single bundle, Vantiv simultaneously increases your
approval rates, optimizes customer lifetime value, and improves your cash flow, while reducing
the cost of implementing the individual features separately in terms of IT resources. For
additional information about the capabilities included in this bundle, please refer to Recycling
Engine on page 12, and (AAU) Account Updater Service on page 14.

1.6.1

Authorization/Sale Recycling

Authorization recycling is the process of retrying declined authorization attempts. Every
merchant, especially those with a business model that uses recurring or installment payments,
should devise a strategy for dealing with declined authorizations. As part of optimizing their
operations, merchants must devise plans for both the timing and number of recycling attempts
before contacting the cardholder or risking interruption of service. If a merchant does not recycle
enough, they risk losing customers and revenue; whereas, if the merchant recycles too often, they
risk increasing their total cost of payments. Implementing an optimal recycling strategy aids
customer retention and therefore yields higher revenues, while lowering the costs of payment
acceptance and improving cash flow.

1.6.1.1

Recycling Engine

The Recycling Engine is a managed service that automatically retries declined authorization
attempts on your behalf. It requires little or no IT investment on your part. Also, implementing
the Vantiv service removes the need to plan your own recycling strategy.
Recycling Engine has the following benefits:
•

Increases approval rates

•

Shortens time to approval, improving cash flow

•

Reduces the number of authorization retries

•

Lowers the risk of account/service cancellation

In order to determine the most effective recycle timing, Vantiv performs statistical analysis of past
recycling attempts across our entire merchant portfolio. This analysis examines many factors,
including method of payment, response codes, and transaction amount among others, to
determine the optimum intervals between attempts to obtain a successful authorization. When you
receive a declined Authorization, the system automatically queues the transaction for a retry at a
designated time. Recycling of the Auth continues until it is either successful or the algorithm
determines that it is no longer advantageous to retry.

12

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Recovery

Introduction

NOTE:

For Visa transactions, the Recycling Engine will retry declined
Authorizations a maximum of 4 times within 16 days, per Visa regulations.
For MasterCard and Discover transactions, we retry declined
Authorizations a maximum of 8 times within 28 days.

Vantiv provides the results of the recycling efforts to you in a Batch posted daily to your Vantiv
sFTP account. This file contains transactions that either approved or exhausted the recycling
pattern on the previous day. If you submit an Authorization for a transaction in the recycling
queue, Vantiv returns the response from the last automatic recycling attempt. To halt recycling of
a particular transaction, submit either an Authorization reversal transaction, if the original
transaction was an Auth, or a Void transaction, if the original transaction was a Sale.
Declined Transactions Not Recycled
The system does not recycle transactions declined with one of the Response Codes listed in
Table 1-3 below. The  element in the response files indicates if the
transaction is being handled by the Recycling Engine.

TABLE 1-3

Response Codes Not Recycled

Response Code

Message

213

Pickup Card - Lost Card

214

Pickup Card - Stolen Card

303

Pick up Card1

304

Lost/Stolen Card1

305

Expired Card1

308

Restricted Card - Chargeback

309

Restricted Card - Prepaid Card Filtering Service

312

Restricted Card - International Card Filtering Service

315

Restricted Card - Auth Fraud Velocity Filtering Service

318

Restricted Card - Auth Fraud Advice Filtering Service

323

No such Issuer1

328

Cardholder requested that recurring or installment payment be stopped

358

Restricted by Vantiv due to security code mismatch

550

Restricted Device or IP - ThreatMetrix Fraud Score Below Threshold

1. Not recycled for MasterCard, unless updated account information is available.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

13

cnpAPI Reference Guide
Introduction

Recovery

Transaction Signature
The Recycling Engine analyzes each Authorization or Sale request message to determine if it is a
new request. The result of the analysis determines if the transaction should be added to the
recycling pool upon decline or if the system should intercept the transaction to prevent a duplicate
transaction entering the recycling pool. To perform the analysis, the system checks the transaction
signature. Depending upon your configuration, the transaction signature can be:
•

Value of the  element

•

Value of the  element

•

Values of the , , and  elements
NOTE:

If you submit a transaction with the identical signature, but containing
new information (for example, a new card number), the system updates
the transaction in the recycling pool with the new info and continues to
recycle.

Additional Configuration Options
The Recycling Engine allows you the additional flexibility of excluding certain transactions from
automatic recycling. You can exclude transactions manually by including the 
element set to None. There are also global controls that allow you to exclude transactions based
upon either submission by a particular presenter, or based upon the transaction type (authorization
or sale). Please consult your Relationship Manager about the global options, since they must be
configured in your Vantiv Merchant Profile.

1.6.2

Account Updater Service

Credit and debit card numbers change for a variety of reasons including card expirations, card
product type upgrades, portfolio conversions, and compromised account numbers among others.
For merchants who offer services that are billed on a recurring or installment basis (for example,
web hosting, gym memberships, specialized social networking, career services, monthly donation
plans, etc.) out-of-date payment information can result in lost revenue, involuntary churn and
decreased customer satisfaction.
Prior to the development of the Account Updater service, the standard method for merchants to
obtain updated account information was to submit a Batch containing existing card information,
requesting that Vantiv check for updates. Typically, merchants request updates for customer
accounts scheduled to be billed in the next billing cycle. This legacy method is a relatively slow
process, requiring several days for Vantiv to accumulate responses from the card networks/issuers
and then to make the response file available to the merchant. Merchants must then update their
billing systems with the new information, requiring IT processing cost. Failure to update their
files can result in multiple requests (and charges) for the update information, as well as delays in
or lost revenue, higher Authorization expenses, and possibly chargebacks when old account
information is used.

14

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Recovery

Introduction

The Account Updater service shifts the workload of obtaining and maintaining updated account
information to Vantiv. Utilizing configurable scheduling algorithms, we initiate account update
requests on your behalf and then stores the updated card information for use in future
transactions. You simply submit billing transactions normally and, if necessary, Vantiv updates
the transaction with the stored card information before submitting it to the networks for
authorization. This fully managed service requires no code update on your systems.
FIGURE 1-3

Account Updater Overview

Merchant

Card Networks
Scheduled
AU Requests

Response
with
updates
from
Network

Process
and
Store
Matches
Vantiv Submits
Auth w/Repaired
Card Info (if info
on file)

Submit
Transaction

Vantiv Adds
Account Info to
Next Scheduled
AU Request
Re-Submit
Transaction

Auth

Auth Decline if updated
info not yet on file

Vantiv Repairs
Card Info and
Submits Auth

(+ 3 days)

Auth Approval

1.6.2.1

Auth
Auth Approval

Match Back

If you decide you wish to have the updated card information returned to you, Vantiv offers the
Match Back option. In this case, you can opt to receive updated information either in a Batch
deposited to the merchant sFTP account, or in the XML transaction response messages. Once you
update your systems, you can resubmit the failed transaction with the new card information. If,
Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

15

cnpAPI Reference Guide
Introduction

Recovery

after receiving an update, you submit a transaction with the old information, systems detect that
you are using the old data and update the transaction for you prior to submitting it to the networks
for authorization.
Please consult your Relationship Manager for additional information and configuration options.
FIGURE 1-4

Match Back Overview

Merchant

Card Networks
Scheduled
AU Requests

Response
with
updates
from
Network

Process
and Store
Matches
Vantiv Submits
Auth w/Repaired
Card Info (if info
on file)

Submit
Transaction

Vantiv Adds
Account Info to
Next Scheduled
AU Request
Re-Submit
Transaction

Vantiv Repairs
Card Info and
Submits Auth

(+ 3 days)

Auth Approval w/New
Card Info

(Next
Payment)
Submit
Transaction
w/New Info

1.6.2.2

Auth

Auth Decline if updated
info not yet on file

Auth
Auth Approval w/New
Card Info

Auth

Submit for Auth

Merchant Requirements

In order to use the Account Updater service, you must first apply for membership to the
following:

16

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Recovery

Introduction

•

MasterCard Automatic Billing Updater

•

Visa Account Updater

•

Discover Account Updater (not required by Discover for Vantiv acquired merchants)

Your Account Updater Welcome Kit includes the required application forms. If you have any
questions about these forms, contact your Relationship Manager, who can walk you through the
application process. Approval from Visa and MasterCard typically takes between 10-15 business
days. Normally, merchants are approved without issue; however, you can be declined for a variety
of reasons. For example, merchants on a risk mitigation program typically are not accepted.
NOTE:

1.6.2.3

Visa does not allow merchants with SIC numbers 5962, 5966, 5967, or
7995 to participate in their Account Updater service. MasterCard has no
restrictions against any specific MCC numbers

Account Updater Features

The Account Updater service can include the following features depending upon the
implementation option you select:
•

Vantiv initiates requests for updated account information to card networks based upon your
billing cycle.

•

Vantiv initiates requests for updated account information following certain failed
Authorization attempts.

•

All updated card information stored (per merchant) in our secure database.

•

Automatic repair/replacement of outdated information with updated information in new
Authorization/Sale transaction submissions.

•

Return of the updated account information in the cnpAPI response message when auto-repair
occurs.

•

Maintenance of card information history, so that the system can repair a card even if multiple
updates have occurred during the card's billing lifecycle.

•

All linked (to an Authorization) transactions will use the updated account information from
the repaired parent transaction, including Captures, Refunds, and Reversals. If a re-Auth is
needed on an attempted capture due to an expired authorization, the system uses the updated
account information.

•

Integration with Vault for merchants utilizing Vantiv’s tokenization solution.

•

Return of Extended Response Codes in the cnpAPI response messages.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

17

cnpAPI Reference Guide
Introduction

1.7

Recurring Engine

Recurring Engine
The Recurring Engine is a managed service that relieves the burden of developing an in-house
billing solution for merchant engaged in installment or recurring transactions. This powerful, but
flexible service allows you to create virtually any payment Plan required by your business model,
whether it is part of a predetermined campaign or a marketing test, and then apply the Plan to
customers as part of the standard Authorization or Sale transaction.
The Recurring Engine provides the following benefits:
•

Reduced Infrastructure Costs - since you do not need to program your own solution, you
save the up-front development cost, as well as ongoing maintenance expenses.

•

Reduced Labor - once you create a Subscription in the Recurring Engine via a standard
Authorization or Sale transaction, no further action is required for the life of the Subscription.

•

Integration with other Vantiv Value Added Services - if you include the Recovery Services
(Account Updater and Recycling Engine) as part of your implementation, you eliminate any
concerns (and reduce expenses) associated with issues such as account number changes and
recycling of declined payments.

•

Flexible Plans - You can define the billing interval (weekly, monthly, quarterly, etc.), number
of payments (including open ended schedules), amount of payments, as well as trial periods
within a Plan. To add flexibility you can override several of these settings and set a specific
start date at the individual Subscription level.

•

Flexible Creation of Discounts - if you wish to offer a discount to selected customers,
simply include the information at the time of the Subscription creation, or add it anytime
afterward by updating the Subscription.

•

Flexible Creation of Add Ons - similar to a discount, you can apply changes for additional
services at the time of the Subscription, or anytime afterward.

•

Integrated Reporting - in addition to the normal revenue reconciliation information
available in the iQ Reporting and Analytics platform, there are a number of recurring specific
reports that allow you to better analyze your revenue stream associated with recurring
payment plans and strategies.

1.7.1

Payment Plans

The first step in setting up recurring billing on the Vantiv eCommerce platform is to establish one
or more payment Plans. To establish a payment Plan you use a Create Plan transaction type,
which allows you to define the payment interval, the number of payments, and the amount. For
example, you could easily define any number of Plans to fulfill your business needs.
For example, suppose you are a SaaS company that sells your product under 1, 2, or 3 year deals,
with either monthly or quarterly payment schedules and reduced rates for longer deals. You could
easily set-up six Plans as shown in the table below.

18

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Recurring Engine

Introduction

TABLE 1-4

Example Pans

Payment
Interval

Plan Code

Amount per
Payment

# of
Payments

Total Subscription

1_Year_Monthly

Monthly

$50.00

12

$600.00

1_Year_Quarterly

Quarterly

$150.00

4

$600.00

2_Year_Monthly

Monthly

$46.66

24

$1119.84

2_Year_Quarterly

Quarterly

$140.00

8

$1120.00

3_Year_Monthly

Monthly

$41.66

36

$1499.76

3_Year_Quarterly

Quarterly

$125.00

12

$1500.00

As part of the Plan, you can also specify trial period. You want to have longer trials for longer
Plans, so for either 1-year Plan, there is a 1 week trial, for either 2-year Plan there is a 2 week
trial, and for the 3-year Plans, a 1 month trial. Below is a cnpAPI example transaction to create
the 3_Year_Monthly Plan.
Example: 3-Year Monthly Plan

3_Year_Monthly
3Year_Monthly
3 Year, monthly Payments, 1 month trial
MONTHLY
4166
36
1
MONTH
true


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  element to
initialize the Subscription using a named Plan and set the start date for the first recurring bill. If
you do not include a start date, the Recurring Engine uses the current date for the first payment.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

19

cnpAPI Reference Guide
Introduction

Recurring Engine

If the recurring bill had an associated set-up or one-time fee use a Sale transaction. The amount of
the Sale transaction would represent that fee, whereas the amount of future recurring payments
are defined in the Plan. If you use an Authorization to create the Subscription, the transaction
would normally be a $0 Auth (or small amount followed by a reversal) and would include the
billing information for Address Verification.
As part of the Subscription creation, you can also override both the number of payments and the
amount, as well as include Add Ons and Discounts (discussed in the next section). The overrides
give you a granular control to modify a standard payments Plan for a particular consumer without
creating additional Plans. For example, if you offered a 1-year Plan with monthly payments as
shown in the previous section, you could allow a consumer to complete their payments in 10
months instead of a year. In this case you would override the number of payments defined in the
Plan (12) with 10 payments, while increasing the amount of each payment from $50 to $60.
Example: Subscription with Overrides

65347567
0
ecommerce

.
.
.


.
.
.



1_Year_Monthly
10
2016-09-21
6000




20

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Recurring Engine

1.7.2.1

Introduction

Add Ons and Discounts

Occasionally, you might wish to modify a Subscription with either a Discount or an Add On
without creating a new Plan that has limited use. A Discount reduces the recurring amount for one
or more payments, while an Add On increases the payments in return for an added service or
item. You can apply either of these payment modifications at the time you initialize the
Subscription or anytime afterward by updating the Subscription. In both cases you define the start
date, end date, and amount of the Discount/Add On.
For example, suppose as part of your standard offering, your customers received 2GB of
cloud-based storage. You also offer additional storage in 2GB blocks for $10 each. One of your
customers wants an additional 4GB of storage for the 8 months remaining on his contract and you
are discounting the first month at 50%, or $10. The example below show the
updateSubscription transaction with the Add On and Discount.
Example: Update Subscription with Discount and Add On

1234

4GBExtraDeal
Half-Off 1st Payment 4GB Extra
1000
2016-09-15
2016-10-14


4GB_Extra
Four_GB_Extra
2000
2016-09-15
2016-04-15



1.7.3

Recurring Reports

In addition to recurring transactions appearing in the normal Vantiv reports (i.e., Payment Detail,
Reconciliation report, etc.), there is an additional report associated specifically with the Recurring
Engine. Available via sFTP, this report is in Batch format and contains cnpAPI saleResponse
messages for all recurring transactions run that day, including all approvals and declines (see the
example, Batch Sales Response with Recurring Info on page 323).

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

21

cnpAPI Reference Guide
Introduction

1.7.4

Recurring Engine

Transaction Types and Uses

The table below provides information about the various Recurring Engine transaction types and
their uses.

TABLE 1-5

Recurring Engine Transaction Types

Use Case/Intent
Create Plan

Parent Element
createPlan

Used to create new Plans.

updatePlan

Used to toggle a Plan between an active
and inactive state. You can not associate
an inactive Plan with a Subscription.
Toggling a Plan to an inactive state does
not affect existing Subscriptions
associated with the Plan.

 or 

Used to initiate a Subscription with an
associated Plan. The Subscription can
include amount and numberOfPayment
overrides to the Plan. Also, the
Subscription can include createAddOn
and createDiscount children.

Update Plan


Create Subscription



updateSubscription

Used to modify Subscription information
including: changing the Plan, changing
the billing name/address, and changing
the method of payment. You can also
use this transaction type to
create/delete/update Add Ons and
Discounts.

cancelSubscription

Used to cancel an existing Subscription.

 or 

Used to create an Add On charge
associated with the Subscription.

Update Subscription

Cancel Subscription

Description/Uses





Create Add On
Or



Update Add On

22




Used to modify one or more of the
parameters associated with the Add On.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Recurring Engine

TABLE 1-5

Introduction

Recurring Engine Transaction Types

Use Case/Intent
Delete Add On

Parent Element


 or 


Description/Uses
Used to delete an Add On charge from
the associated Subscription.
Used to create a Discount charge
associated with the Subscription.


Create Discount


Or




Update Discount

Delete Discount





Used to modify one or more of the
parameters associated with the
Discount.
Used to delete a Discount from the
associated Subscription.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

23

cnpAPI Reference Guide
Introduction

1.8

Issuer Insights

Issuer Insights
Issuer Insights provides you additional card/transaction, performance descriptive data, allowing
you to understand the differences among Issuers and card products, and identify trends that may
impact future transactions. Currently, Vantiv bundles four feature sets into Issuer Insights: the
Issuer Insights Secure Scheduled Report, Real Time Indicators (i.e., Prepaid Indicator, Affluence
Indicator, Issuer Country Indicator, Card Type Indicator), Network Response Data, and the
Insights Analytics Dashboard.

1.8.1

Issuer Insights Secure Scheduled Report

Every merchant wants to maximize their approval rate and with it their customer conversion rate
and sales. Unfortunately, issuing banks do not all use the same criteria and/or algorithms when
approving or declining transactions. Getting an approval on an authorization is not a one size fits
all proposition.
The weekly Issuer Insights report provides a range of data points that breakdown authorization
approvals and declines by card type, BIN (i.e. Issuing Bank), and account ranges (indicating card
product types). It also provides data about the four of the most often seen reasons for declines
(i.e., Non-sufficient Funds, Do Not Honor, Invalid Account, and Lost/Stolen Card), as well as
benchmark data for your MCC(s) across the Vantiv eComm portfolio, and Issuer participation in
AU, as well as account update counts per account range across our portfolio. Using this data, you
can create a wide range of useful analytics, such as approval/decline trending by BIN, account
updates trending by account range, new card issuance/portfolio changes, or customer lifetime
value by card type to name a few.
For additional information about this report please refer to the Vantiv Scheduled Secure Reports
Reference Guide.

1.8.2

Real Time Indicators

The Real Time Indicators provide six data points in the Authorization/Sale transaction response
message. This information includes the Prepaid Indicator, Affluence Indicator, Issuer Country
Indicator, Card Type Indicator, Funding Source Indicator, and Virtual Account Number Indicator.
Each of these pieces of information allows you to make a real time decision about how to proceed
with the transaction. The sections that follow explain each indicator along with possible uses in
your decision making process.

1.8.2.1

Prepaid Indicator

Studies show that branded prepaid cards are growing in popularity with consumers. These cards
are available in the form of non-reloadable Gift cards, Consumer Rebate/Incentive cards, and
Teen cards among others. The Prepaid Indicator feature acts to determine if the submitted card is
a prepaid card. If so, the system returns the type element with a value of Prepaid and the

24

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Issuer Insights

Introduction

availableBalance element stating the outstanding balance remaining on the card (if

available).
Knowing that the card is prepaid at the time of sale, as well as if it is reloadable and the available
balance, is especially useful for merchants engaged in recurring payment, installment payment, or
deferred billing scenarios. Merchants in these situations can use the information made available
by this feature to make intelligent decisions concerning the profitable management of prepaid
card usage by avoiding several factors that may contribute to lost revenue, while taking advantage
of other opportunities that may add to revenue and enhance the customer experience.
For example, one possible situation merchant can avoid is fraudulent deferred/installment
payment purchases made with a prepaid card that does not have enough available balance to
cover the subsequent payments. With the available balance known, merchants can determine if
the card can meet the required payment structure. If the card’s balance does not meet the required
threshold, the merchant can request another payment method, which may result in eliminating
fraudsters, while retaining legitimate customers. If the card is non-reloadable, it is advisable to
not accept the card at all for recurring payments regardless of the available balance.
Another more common situation occurs when the consumer is unaware of the card balance. If the
transaction is rejected due to inadequate balance, perhaps repeatedly, it could result in an
unsatisfied customer and an abandoned purchase. Alternately, the card could have slightly more
that the required balance, which the consumer would spend, if they had the knowledge. If the
available balance is insufficient for the purchase, the merchant can obtain a second or alternate
payment method. If the balance is higher than required for the purchase, the merchant may be
able to encourage additional purchases.
In addition to indicating if the submitted card is a prepaid card and the available balance, this
feature includes information about whether the card is reloadable and the specific type of prepaid
card (e.g., TEEN, GIFT, PAYROLL, etc.). You can use this information to further refine your
sales and marketing strategies.

1.8.2.2

Affluence Indicator

Visa, MasterCard, and Discover provide enhanced credit card products for consumers with high
disposable incomes and high card spending. These cards encourage usage by offering the
cardholders additional benefits usually including reward incentives, no pre-set spending limit,
higher authorization approval rates, faster access to a customer service representatives, and
dedicated chargeback resolution support.
Vantiv analysis of payments data indicates that consumers using these cards types typically spend
more per order than consumers using traditional credit and debit cards. The Affluence Indicator
feature provides the ability for merchants to segment their consumers based on the affluence level
as determined by the issuer. Within the cnpAPI Authorization response, consumers using these
enhanced card products are classified either as Mass Affluent or Affluent. Based upon the specific
card type, high income consumers are classified as Mass Affluent, while high income-high
spending consumers are classified as Affluent.
Having this information at the time of authorization, allows merchants the opportunity to adjust
their sales approach to the needs and spending patterns of the consumer, potentially generating
Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

25

cnpAPI Reference Guide
Introduction

Issuer Insights

additional sales. Having this information on file for later analysis also may provide the
opportunity for targeted marketing campaigns and future sales.

1.8.2.3

Issuer Country Indicator

Knowing the country of the Issuing bank helps you in two respects. From a sales and marketing
standpoint, this knowledge allows you to better analyze the purchasing patterns of your customers
based upon their country of origin. Knowing these customer demographics can allow you to tailor
marketing campaigns to take advantage of this geographic information. Likewise, you can use
this information to analyze the successfulness of tailored campaigns.
The second advantage to having this information readily available is that you can use it to help
determine possible patterns of fraud. With this knowledge in hand, you can use the International
Card Filtering feature to limit your exposure to international fraud originating in particular
geographic locations.

1.8.2.4

Cardholder Type Indicator

The Card Holder Type indicator is an additional data point Vantiv provides as part of Issuer
Insights. This indicator returns an element specifying whether the submitted card is a commercial
or consumer card, providing you with additional data useful when analyzing sales patterns and/or
planning marketing campaigns, such as offering different products/services to a corporate
customer as opposed to a regular consumer.

1.8.3

Extended Network Data

In an effort to provide more data for use in analyzing your transactions and customers, Vantiv
added a number of data elements originating directly from the ISO 8583 network response
messages. If you use V11.0 or above of the Vantiv cnpXML, you can receive up to 17 data
elements as part of the Enhanced Auth Response ( element). These
elements provide more granular data, allowing you to gain a more nuanced understanding of the
approval/decline behavior of particular Issuers. Table 1-6 provides information about the fields
returned.
NOTE:

26

To receive the Extended Network Data elements you must code to Version
V11.0 or above.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Issuer Insights

Introduction

TABLE 1-6

Possible Extended Network Data ISO 8583 Fields

Data
Element

Field Name

Type

4

Transaction Amount

n 12

15

Settlement Date

n4

38

Authorization Identification
Response

an 6

39

Response Code

an 2

44

Additional Response Data

an..25

48

Private Use Additional Data

an...999

50

Settlement Currency Code

n3

51

Cardholder Billing Currency
Code

n3

54

Additional Amounts

an...120

63

Reserved Private

an...999

104

Transaction Description

an...100

116

Reserved for National Use

an...999

123

Reserved for Private Use

an...999

Notes

MMDD format

Defines the currency of the settlement

Example: Extended Network Data

.
.
.

VISA

000000000962





Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

27

cnpAPI Reference Guide
Introduction

Issuer Insights



5





1.8.4

Insights Analytics Dashboard

The Insights Dashboard provides insight into the quality of customers your organization acquires,
based on the number and percentage of authorizations by card type or other indicator, and
contrasts that with the number of customers whose authorizations are successfully converted to
deposits. There are four categories of indicators: Affluence, Prepaid, Corporate Customers, and
Country of Issuing Bank.
Using these values and the related charts, your organization can decide whether the customer mix
you attract yields maximum revenue potential, or if a change in marketing is required. By using
the adjustable date range and reporting groups, you can compare the quality of customers between
different business units and affiliates, or monitor the response to marketing campaigns.
Please refer to the Vantiv eCommerce Reporting and Analytics User Guide.

28

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Fraud Toolkit

1.9

Introduction

Fraud Toolkit
Just because a credit card network/company returns a valid authorization for a purchase does not
always mean that completing the transaction is in your best interest. There are multiple reasons
you may wish to decline a sale on a particular card at a particular time. In many cases there are
indicators that the transaction could be or likely is fraudulent. Acting to stop these transactions at
submission prevents loss, as well as reducing the number fraud related chargebacks in the future.
Vantiv offers a robust fraud solution, the Fraud Toolkit, to assist you in reducing the number of
possibly fraudulent transactions inflicted upon you by bad actors.
The Fraud Toolkit has three tiers or levels of implementation, each providing more rigorous
examination of transaction properties and data points, as well as valuable information and
guidance. The table below provide an overview of the tool provided at each level. The items
highlighted in blue require the inclusion of a small snippet of code on your checkout page.

TABLE 1-7

Fraud Toolkit Implementation Levels
Filter/Feature

Essential

Extended

Premium

AVS Filter

X

X

X

CVV No-Match Filter

X

X

X

International BIN Filter

X

X

X

Prepaid Non-Reloadable Filter

X

X

X

Prior Chargeback Filter

X

X

X

Prior Fraud Advice Filter

X

X

X

Card Velocity Filter

X

X

X

Email Velocity Filter

X

X

X

Phone Velocity Filter

X

X

X

IP Velocity Filter

X

X

X

Device Velocity Filter

X

X

X

IP Address, Geolocation, and Proxy Detection

X

X

Merchant Customizable Rules Template

X

X

ThreatMetrix Cybercrime Dashboard

X

X

(Asynch) Transaction Review Queues

X

X

Rule Management and Portal Training

X

X

Standalone Transaction API Access

X

X

Cybercrime Industry Report (Quarterly)

X

X

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

29

cnpAPI Reference Guide
Introduction

Fraud Toolkit

TABLE 1-7

Fraud Toolkit Implementation Levels
Filter/Feature

Essential

Access to Fraud Consultant

1.9.1

Extended

Premium
X

Essential Tier

The Essential tier includes a suite of eleven Fraud Filters that you can apply individually or in
combination. Nine of the eleven filters, based on card/submitted data, potentially require no
additional integration on your part, assuming you already submit the necessary information. The
remaining two filters require you to add a a small snippet of code on your checkout page.
NOTE:

1.9.1.1

Technically, you can make use of the IP Velocity filter without integrating
the code snippet on your checkout page. Instead you can simply include
the originating IP Address that you detect in your transaction by
submitting it as a customAttribute. Please note that this method will
likely be less effective than making use of the ThreatMetrix functionality,
which includes IP piercing to determine the true IP of the consumer’s
device.

Prepaid Card Filtering

Many merchants engaged in recurring payment, installment payment, or deferred billing
experience some loss due to fraud schemes that make use of prepaid cards. Consider the case of a
consumer using a prepaid card with a balance of $100 to make a purchase that involves an initial
charge of $50 followed by three installments of $50 each. The authorization would be approved
for the initial transaction, and the card might have adequate balance for an additional charge, but
if the consumer was attempting to defraud the merchant or simply used the card for other
purchases, the card may not have sufficient balance for any additional payments. While the
Prepaid Indicator feature provides you with the information necessary to make a decision at the
time of the sale, and to request a secondary or different payment method, instead you may wish to
have Vantiv filter these transactions automatically when you send the Authorization transaction.
If you elect to use the Prepaid Card Filtering Service, you can select one of two methods of
implementation. Using the first filtering method, our system declines all Authorization and Sale
transactions when the consumer uses a prepaid card. Upon a decline, the system returns a
Response Reason Code of 309 - Restricted Card - Prepaid Card Filtering Service. This
method also allows you to disable the filtering logic on a transactional basis by including the
 element set to a value of false, allowing you to accept any prepaid card for these
transactions.
The second method of implementing the Prepaid Card Filtering Service is per transaction. To
enable the filter on a particular transaction, set the  element to a value of true. This
method is useful to a merchant who offers products with both one-time payments and installment

30

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Fraud Toolkit

Introduction

payments. For products involving a single payment, you may want to allow the use of prepaid
cards, while for the product with multiple payments you may want to filter prepaid cards.
NOTE:

1.9.1.2

Within either implementation method, you can elect to filter all prepaid
cards, or only non-reloadable prepaid cards. Please speak to your
Implementation Consultant for additional information about setting these
global parameters.

International BIN Filtering

An examination of your historical fraud data may show a high percentage of fraudulent
transactions originating with certain international cards. You can limit your exposure to this type
of fraud by taking advantage of the International Card Filtering Service. This feature allows you
to filter MasterCard and Visa cards originating in either all foreign countries or selected foreign
countries based upon the country of the card issuer.
If you elect to use this feature, when you submit an Authorization/Sale transaction, the system
determines the country of origin of the card. If the card originates outside the United States and
you have elected to filter all international cards, the system declines the transaction. Likewise, if
you have elected to filter a specific country or countries and the card originates from a designated
country, the system declines the transaction. Upon a decline, the system returns a Response
Reason Code of 312 - Restricted Card - International Card Filtering Service.
You can override your settings on a transactional basis by including the 
element set to false when you submit the Authorization/Sale transaction. In this case, the system
ignores the filtering service and processes the transaction normally.

1.9.1.3

Prior Chargeback Filtering

If you elect to use the Chargeback Filter Service, there are two configuration options. You can
elect to filter all transactions using a card for which you received a chargeback, or you can elect
to filter only the subset of transactions for which you received a fraud related chargeback
(determine by the associated chargeback reason code). In both cases, the system checks your
historical data to see if you received an applicable chargeback from the same account within the
last 90 days. Upon a decline, the system returns a Response Reason Code of 308 - Restricted
Card - Chargeback.

1.9.1.4

Security Code No-Match Filter

The Card brands added the 3- or 4-digit security code to act as a verification that the person
ordering your product in a card-not-present environment has physical possession of the card.
While this validation can be a useful anti-fraud tool, typically, many issuing banks do not decline
the transaction based upon a failure to match the security code. Declining the transaction is left to
the discretion of the merchant.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

31

cnpAPI Reference Guide
Introduction

Fraud Toolkit

NOTE:

Since American Express declines the transaction when the security code
does not match, the Security Code No-Match filter does not apply to
American Express transactions. Transactions declined by American
Express for a failure to match the security code use the Response Reason
Code of 352 - Decline CVV2/CID Fail.
Similarly, if Visa, MasterCard, or Discover decline a transaction based
upon the security code results, Vantiv does not apply the filter and the
transaction response contains the 352 Reason Code.

If you elect to use the Security Code No-Match Filter Service, the system takes action only if the
issuer approves the submitted authorization/sale transaction, but includes a no-match code for the
CVV2/CVC2/CID card validation check. In this case, the Vantiv declines the transaction with a
Response Reason Code of 358 - Restricted by Vantiv due to security code mismatch. The
system also issues an Auth Reversal transaction on your behalf to remove the funds hold on the
account.

1.9.1.5

Card Velocity Filtering

Often, when a person attempts to use a stolen credit card successfully, they will follow the initial
purchase with a number of additional purchases within a short period of time. If you elect to use
the Fraud Velocity Filter, the system filters the transaction based upon the number of previously
approved Auth/Sale transactions plus the number of Auth/Sale transactions declined by another
filter, for the same account within a designated time period. Both the total number of transactions
and the time period are configured in the Vantiv Merchant Profile.
Upon a decline, the system returns a Response Reason Code of 315 - Restricted Card - Auth
Fraud Velocity Filtering Service.

1.9.1.6

Prior Fraud Advice Filtering

Vantiv maintains a database of Fraud Advice information received from the Visa and MasterCard
networks for transactions you processed in the last 200 days. If you use the Prior Fraud Advice
Filter, the system compares the account information from the new transaction against the database
of accounts with prior Fraud Advice and filters the transaction if there is a match.
Upon a decline, the system returns a Response Reason Code of 318 - Restricted Card - Auth
Fraud Advice Filtering Service.

1.9.1.7

AVS Filter

One of the fraud prevention tools provided by all card networks is an Address Verification
System. By submitting the customer’s address information in the billToAddress section of the
cnpAPI message, you can verify that the address/zip code supplied by the consumer matches the
issuer’s records. The card networks, however, do not decline transactions based upon the failure

32

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Fraud Toolkit

Introduction

to match the address or zip code. Using the AVS Filter, you can filter potentially fraudulent
transactions based upon failure to match any of the following:
•

the address

•

the zip/postal code

•

the address + zip/postal code (ANDed)

•

the address or zip/postal code (ORed).

Upon a decline, the system returns a Response Reason Code of 319 - Restricted Card - Fraud
AVS Filtering Service.

1.9.1.8

Email Velocity Filter

Often, card testers or other bad actors submit a number of transaction using multiple cards, but
with a common email address. The only requirement to make use of this filter is that you collect
and include the consumer’s email address with each transaction. We communicate the email
address to our fraud partner, ThreatMetrix, who tracks and analyzes the information. If the filter
detects the same email used in the configured number of transactions within the configured period
of time, the system declines new transactions (using the same email) on your behalf and returns
Response Code 550 - Restricted Device or IP - ThreatMetrix Fraud Score Below Threshold.

1.9.1.9

Phone Velocity Filter

Similar to email, card testers or other bad actors often submit a number of transaction using
multiple cards, but with a common phone number. The only requirement to make use of this filter
is that you collect and include the consumer’s phone number with each transaction. We
communicate the phone number to our fraud partner, ThreatMetrix, who tracks and analyzes the
information. If the filter detects the same phone number used in the configured number of
transactions within the configured period of time, the system declines new transactions (using the
same email) on your behalf and returns Response Code 550 - Restricted Device or IP ThreatMetrix Fraud Score Below Threshold.

1.9.1.10

IP Velocity Filter

The IP Velocity filter is one of the two filter in the Essential tier that requires (see note below) the
addition of a code snippet to your checkout page. This snippet, which you also need to implement
for the higher tiers of Fraud Toolkit, allows our partner, ThreatMetrix, to perform IP
interrogation/piercing t determine the true IP Address of the device originating the order. As with
the other velocity filters, if the filter detects the same IP Address used in the configured number
of transactions within the configured period of time, the system declines new transactions from
the same IP Address on your behalf and returns Response Code 550 - Restricted Device or IP ThreatMetrix Fraud Score Below Threshold.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

33

cnpAPI Reference Guide
Introduction

Fraud Toolkit

NOTE:

1.9.1.11

Technically, you can make use of the IP Velocity filter without integrating
the code snippet on your checkout page. Instead you can simply include
the originating IP Address that you detect in your transaction. Please note
that this method will likely be less effective than making use of the
ThreatMetrix functionality, which includes IP piercing to determine the
true IP of the consumer’s device.

Device Velocity Filter

The Device Velocity filter is the second Essential tier filter in the that requires the addition of a
code snippet to your checkout page. In this case, the snippet allows ThreatMetrix to construct a
device fingerprint of the system originating the order. As with the other velocity filters, if the
filter detects the same device used in the configured number of transactions within the configured
period of time, the system declines new transactions from the same device on your behalf and
returns Response Code 550 - Restricted Device or IP - ThreatMetrix Fraud Score Below
Threshold.

1.9.1.12

Application of Filters - Filtering Rules

NOTE:

Filter Rules are defined as part of your Merchant Profile. Please consult
with your Relationship Manager and/or your Implementation Consultant
concerning the provisioning of Filter Rules.

While you can have all submitted transactions flow through the Fraud toolkit, you likely want to
exercise a finer control over the application of the filters based upon a particular product, service
or other criteria. The system provides you the flexibility of restricting which transactions are
submitted to the filtering service and which filters the system applies to which groups. This is
accomplished by defining Filtering Rules.
For each Filtering Rule you first define a subgroup of transactions by selecting one of the
following Flow Selectors: Report Group, Billing Descriptor, orderSource, or MID (for PayFacs,
flow control by MID or order source only). Only one selector can be applied per rule. After
selecting a particular Flow Selector, you then select which filters to have applied to that subset of
transactions. You can define the Filter Rules so that filters are ORed (transaction filtered when
any one of the filters conditions met), or ANDed (transaction filtered when multiple filter
conditions met). Table 1-8 defines five rules that a merchant might define.

TABLE 1-8

34

Example - Fraud Filtering Service Rules

Filter

Flow Selector

Filters

1

Report Group = "XYZ"

Prepaid

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Fraud Toolkit

Introduction

TABLE 1-8

Example - Fraud Filtering Service Rules

Filter

Flow Selector

Filters

2

Report Group = "XYZ"

International

3

orderSource = "recurring"

Prepaid + Prior Chargeback

4

orderSource = "ecommerce"

Card Velocity + Security Code No-match

5

Billing Descriptor = "GoldMember"

Prepaid + International

Table 1-8 defines five Filter Rules that a merchant might use. These rules would be applied as
follows:
•

Filters 1 and 2 apply to the subset of transactions that are members of Report Group XYZ and
use the Prepaid and International Filters. Since the Filter Rules are defined separately, the
rules are ORed. So, if a transaction uses either a Prepaid card or a card of International origin,
the filtering occurs.

•

Filter 3 applies to the subset of transactions that have an orderSource value set to recurring.
Filtering occurs only if both the criteria for the Prepaid Filter AND the Prior Chargeback
Filter are met.

•

Filter 4 applies to the subset of transactions that have an orderSource value set to ecommerce.
Filtering occurs only if both the criteria for the Card Velocity Filter AND the Security Code
No-Match Filter are met.

•

Filter 5 applies to the subset of transactions that have an Billing Descriptor value set to
GoldMember. Filtering occurs only if both the criteria for the Prepaid Filter AND the
International Filter are met.

1.9.2

Extended Tier

The Extended Tier include all of the Essential Tier filters, but offers an additional levels of fraud
detection made available through Vantiv’s partnership with ThreatMetrix. The addition of the
same code snippet used for the IP and Device Velocity filters to your checkout page allows
ThreatMetrix to gather additional data points, such as the consumer’s device, proxy use, and
location. Unlike the filters in the Essential Tier, which are basic accept/decline filters, the
Extended Tier takes the data and compares the information to a rule list. Vantiv supplies an initial,
Best Practices rules list designed for your business type (i.e., Retail, Digital, Non-profit, etc.),
which you can modify and refine for you particular business model. Each rule, when triggered,
add or subtract a preset value from the transaction score. If the score fall below a set threshold,
the system declines the transaction, unless you prefer to make the final decision yourself. In either
case, Vantiv returns the score and a list of triggered rules in the transaction response message.
In addition to the ThreatMetrix rules engine, you get access to the ThreatMetrix Portal allowing
you to customize your rules list and scoring values. This level also allows you to white list/black
list items, such as email addresses and phone numbers. Other items included in this tier are:
•

ThreatMetrix Cybercrime Dashboard

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

35

cnpAPI Reference Guide
Introduction

Fraud Toolkit

•

Asynchronous Transaction Review Queues

•

Monthly Rules and Portal training

•

API Access to Standalone Fraudcheck transaction.

1.9.3

Premium Tier

The Premium Tier provides all of the tools from the Essential and Extended Tiers, and most
importantly, access to the Vantiv eComm Fraud Consulting service. With the service, the Fraud
Consultant assigned to you helps analyze your transactional data, recommend rule changes to
fine-tune your results, and advises you on fraud detection strategy.

1.9.4

Modifications to Your Web Page

For ThreatMetrix to gather information for analysis, you must add certain profiling tags (see
example below) to selected pages served by you web application. These tags allow ThreatMetrix
to collect information by loading objects used for detection into the consumer’s browser. These
tags are invisible to the consumer and add only a fraction of a second to your page’s rendering
time. Once loaded, these objects require only 3-5 seconds to gather profiling information from the
consumer device.
Place the tags as early as possible on the page, inside the  tags of the page
HTML.
Example: ThreatMetrix Profiling Tags
NOTE:

Replace UNIQUE_SESSION_ID with a uniquely generated handle that
includes the Vantiv supplied prefix.
The value for ORG-ID is a Vantiv supplied value.
The pageid tag is not used at this time. The value for PAGE-ID defaults to
1.
For production, replace h.online-metrix.net with a local URL and configure
your web server to redirect to h.online-metrix.net.






1.9.4.1

cnpAPI Transactions

To subject a transaction to the advanced fraud checks performed by ThreatMetrix and retrieve the
results, you simply submit the  element as part of your cnpAPI
Authorization (or Sale) transaction. This session Id is the same unique value you assigned and
sent to ThreatMetrix when your web page called the application (designated as
UNIQUE_SESSION_ID in the ThreatMetrix Profiling Tags example). When we receive an
Authorization/Sale that includes the , our system automatically
queries the ThreatMetrix platform for the associated results. The cnpAPI response message
includes the  element containing the score and status and
information about any triggered rules. The following two examples show a standard
Authorization transaction, including a  and a pass response.
Example: Authorization including  Element


User Name
password


10102013_sessionId_app
1002
ecommerce

John Doe
15 Main Street
San Jose
CA
95032-1234
USA
9782750000
nobody@vantiv.com


MC
5405102001000003
1115



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

37

cnpAPI Reference Guide
Introduction

Fraud Toolkit

ASDFG-AXXXXAB999




Example: Authorization Response including 
Element


82823534116454639
10102013_sessionId_app
000
2017-10-08T21:36:50
2017-10-08
Approved
000003

00

pass
50

FlashImagesCookiesDisabled





NOTE:

The other possible values for the  element are fail,
review, unavailable, and invalid_session.
The  value can range from -100 to 100. The
resulting pass, fail, or review value depends upon your profile settings.
The  element can occur multiple times, once for each rule
triggered.

38

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Fraud Toolkit

1.9.4.2

Introduction

Information Only Option

If you wish to retain full control of the decision to accept or decline transactions, Vantiv offers the
option of using the Advanced Fraud Tools in an Information Only mode. In this configuration,
you receive the same information in the response as you would with the full implementation;
however, Vantiv will not automatically decline transactions with a failing score.
If the authorization is declined by the network, you can choose to recycle the transaction or do
nothing. If an authorization with a failing score receives approval from the network, it would be
up to you to reverse the authorization should you decide not to proceed with the transaction. This
is similar to the case of an approved transaction that has a status of Review, but you decide not to
proceed. Issuing an authorization reversal allows you to avoid any misuse of Auth fees otherwise
imposed by the card networks.

1.9.4.3

Fraud Check Transactions

If you wish to retrieve the Advanced Fraud results without introducing a Authorization or Sale
transactions, use a Fraud Check transaction (see Fraud Check Transaction on page 288). Fraud
Check transactions are only supported as Online transactions.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

39

cnpAPI Reference Guide
Introduction

Tokenization Feature

1.10 Tokenization Feature
Tokenization is the process by which a reference number, referred to as a token, replaces a credit
card number or eCheck account number. Unlike the card or account number, you can store the
token on your system without concern of a security breach exposing critical customer
information. Instead, Vantiv stores the information in a secure vault and accesses it only when
you submit a transaction using the supplied token.
NOTE:

You must be enabled for card tokenization to use the eCheck tokenization
feature.

In the case of credit cards, since you do not store the customer’s account information, the scope of
PCI requirements to which you must comply may be minimized. This may greatly reduce the cost
of compliance and may limit your liability in the event of a breach. You can reduce the
requirements further, as well as the possibility of exposure from a breach, through the use of the
Vantiv eProtect™. By sending the card information from your checkout page directly to our
systems you eliminate one more facet of handling the card information.
NOTE:

Vantiv recommends you consult your own PCI Compliance and Legal
departments to determine the specific advantages of tokenization for your
company.

This section discusses the following topics:
•

How Tokenization Works

•

Token Formats

•

Obtaining Tokens

•

Supported Token Transactions
NOTE:

40

Please refer to the Vantiv eProtect Integration Guide for additional
information about the use of and integration to the Vantiv eProtect value
added service.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Tokenization Feature

1.10.1

Introduction

How Tokenization Works

In a non-tokenized environment, multiple parties handle and store customer data, including the
card/eCheck account number, for each transaction. From a merchant standpoint, they receive the
information, store it in their own database, and transmit it to their processor with the transaction
request, as shown in Figure 1-5 for card information. While the access and transmission of the
data may occur a single time, as in the case of a Sale transaction, frequently data transmission
occurs multiple times in order to complete a single sale, as in the case of an Auth followed by a
Capture or several partial Captures. The local storage and repeated transmission of the
information creates additional possible breach points, where a malicious third party could
compromise the information.
FIGURE 1-5

Card Information Flow in Non-Token Environment
Card Assn.

Merchant

Account #

Account #

Account #

Account #

Issuing Bank

Cardholder

Account #

Account #

Database

Database

Account #

Database

Account #

Database

In a tokenized environment transmission of customer data ideally occurs a single time and the
merchant never stores it locally, as shown in Figure 1-6 for card data. Once account number
registration occurs, using either a registerTokenRequest or by submitting the account
number (or low value token, when using eProtect) with any supported transaction, Vantiv returns
a (high value) token. You store the token locally and use it for all future transactions concerning
that account. Vantiv takes responsibility for storing and safeguarding the account information.
NOTE:

FIGURE 1-6

The difference between card data flow and eCheck data flow is that the
entities upstream of Vantiv are different. The operation remains the same
from a merchant standpoint.

Card Information Flow in Tokenized Environment

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

41

cnpAPI Reference Guide
Introduction

Tokenization Feature

NOTE:

1.10.2

The use of eProtect allow the account information to come directly to
Vantiv, so the merchant handles the token only.

Token Formats

For credit cards, in an effort to minimize development requirements on the merchant side, Vantiv
elected to use a format-preserving tokenization scheme. In simple terms this means that the length
of the original card number is reflected in the token, so a submitted 16-digit number results in a
16-digit token. Also, all tokens use only numeric characters, so you do not have to change your
systems to accept alpha-numeric characters.
The credit card token numbers themselves have two parts. The last four digits match the last four
digits of the card number. The remaining digits (length can vary based upon original card number
length) are a randomly generated. Unlike credit card numbers, which are Mod 10 compliant,
tokens are Mod 10 + 1 compliant.
FIGURE 1-7

Token Format - Card

Last four digits
of the card

0123456789012345
Randomly generated number
For an eCheck token, since the account number length can vary widely, we elected to make the
tokens a uniform length of 17 digits. Unlike card tokens, the entire eCheck token number is a
randomly generated. The system supplies the last three characters of the account number in a
separate element. As with credit card tokens, eCheck tokens are Mod 10 + 1 compliant.

1.10.3

Obtaining Tokens
NOTE:

You must be token enabled and certified prior to using the Vault feature.
Please consult your Relationship Manager concerning the requirements
and details of this process.

There are three ways for you to obtain tokens for account numbers. First, you can submit an
existing card number/eCheck account information (account number and routing number) using a
Register Token request. When Vantiv receives this transaction type, we generate a token and
return it to you via a Register Token response (see Register Token Transactions on page 307.)

42

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Tokenization Feature

Introduction

Although you can use this method to tokenize an account number at any time, it is most useful
when initially tokenizing your customer database. Vantiv recommends that you collect all distinct
credit card numbers in your database and submit the information in one or more large Batch.
When you receive the response file, parse the returned token information to your database,
replacing the card numbers.
The second method you can use to obtain a token is to submit a supported transaction with the
card information. If you are a tokenized merchant, Vantiv will automatically convert the
submitted card number to a token and return it to you in the transaction response. Typically, you
would use this method when taking and submitting a transaction during the normal course of
business. When you receive the response, you store the token instead of the card information.
NOTE:

Once we convert a card number to a token for a particular merchant,
subsequent submissions of the same card number return the same token.

The third method of obtaining a token applies only to merchants using the Vantiv eProtect feature.
In this case, upon submission of an account number via the eProtect API, Vantiv issues a
Registration Id. You then submit the Registration Id in an Authorization or Sale transaction and
receive the token in the response message.

1.10.3.1

Bulk Token Registration

If you are new to Vantiv, and have utilized tokens with a previous processor, Vantiv can perform a
bulk token registration on all the card numbers that were vaulted with your previous processor.
The following is an example of the process:
1. During your implementation with Vantiv, you contact your previous processor and request an
encrypted mapping file containing the card and token numbers for your customers. A
Implementation Consultant will work with you and your previous processor to facilitate the
secure transfer of this file without impacting your PCI compliance. The file can be
comma-delimited, tab-delimited, or any other common format.
2. Vantiv performs a bulk token registration of all of the card numbers contained in the file.
3. Vantiv returns a mapping file to your organization containing the old tokens and the new
Vantiv-issued tokens, so that you can update your order processing system.
Note that Vantiv supports token-extractor formats of all major token service providers. Contact
your Implementation Consultant for more information or to initiate this process.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

43

cnpAPI Reference Guide
Introduction

1.10.4

Tokenization Feature

Supported Token Transactions

The following transactions support the generation and use of tokens:

44

•

Authorization - You can submit the transaction either with a token or card information. If
you submit card information, Vantiv automatically generates the token and returns it in the
response.

•

Capture Given Auth - You can submit the transaction either with a token or card
information. If you submit card information, Vantiv automatically generates the token and
returns it in the response.

•

Credit - You can submit the transaction either with a token or card information. If you submit
card information, Vantiv automatically generates the token and returns it in the response.

•

Force Capture - You can submit the transaction either with a token or card information. If
you submit card information, Vantiv automatically generates the token and returns it in the
response.

•

Register Token - You use this transaction to convert a card number or eCheck account
number to a Vantiv token without an associated authorization, verification or payment
transaction.

•

Sale - You can submit the transaction either with a token or card information. If you submit
card information, Vantiv automatically generates the token and returns it in the response.

•

eCheck Credit - You can submit the transaction either with a token or account information. If
you submit account information, Vantiv automatically generates the token and returns it in the
response.

•

eCheck Redeposit - You can submit the transaction either with a token or account
information. If you submit account information, Vantiv automatically generates the token and
returns it in the response.

•

eCheck Sale - You can submit the transaction either with a token or account information. If
you submit account information, Vantiv automatically generates the token and returns it in the
response.

•

eCheck Verification - You can submit the transaction either with a token or account
information. If you submit account information, Vantiv automatically generates the token and
returns it in the response.

•

Update Card Validation Number - This is a special transaction type provided to allow the
update of a CVV2/CVC2/CID code supplied at the time of the token registration. You should
only use this transaction type if you had previously submitted the account number and
security code in a registerTokenRequest transaction and now need to change the
CVV2/CVC2/CID value.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Tokenization Feature

1.10.5

Introduction

Compliance with Visa Best Practices for Tokenization

As shown below, the Vault tokenization solution complies with 11 of the 12 items listed in the
Visa Best Practices for Tokenization document. The twelfth item concerns the management of
stored historical data (that may contain card information) within your systems. Tokenizing all
historical card info when implementing the Vantiv solution would satisfy this item, as would
protecting it per PCI DSS requirements.

TABLE 1-9

Visa Best Practices for Tokenization Compliance

Item #

Who

Domain

Best Practice

Complies?

1

Vantiv

Tokenization System

Network Segmentation

Yes

2

Vantiv

Tokenization System

Authentication

Yes

3

Vantiv

Tokenization System

Monitoring

Yes

4

Vantiv

Tokenization System

Token Distinguishability

Yes

5

Vantiv

Token Generation

Token Generation

Yes

6

Vantiv

Token Generation

Single- vs. Multi- use Tokens

Yes

7

Vantiv

Token Mapping

PAN Processing

Yes

8

Vantiv

Card Data Vault

PAN Encrypted in Storage

Yes

9

Vantiv

Card Data Vault

Covered by PCI DSS

Yes

10

Vantiv

Cryptographic Keys

Key Strength

Yes

11

Vantiv

Cryptographic Keys

Covered by PCI DSS

Yes

12

Merchant

Historical Data
Management

Non-tokenized data protected

Merchant
Implementation
Decision

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

45

cnpAPI Reference Guide
Introduction

eCheck Processing

1.11 eCheck Processing
An eCheck is an alternative payment method that directly debits a consumer's account via the
Automatic Clearing House (ACH) network. From a merchant’s standpoint offering eCheck as a
payment method has several advantages, including a large consumer base in excess of 130 million
accounts in the United States and no interchange fees.
This section provides information about several Vantiv eCheck processing features. Please
consult with your Relationship Manager for additional information.
NOTE:

1.11.1

Beginning in March, 2015, Vantiv also supports eCheck processing for our
merchants doing business in Canada. All eCheck transaction types,
except Verification and Prenotification transaction are supported. Please
consult your Relationship Manager for additional information.

Validation Feature

Vantiv performs a validation of the eCheck routing number. This is done both to verify that the
routing number is correctly formatted and that it exists in the Fed database. If the routing number
fails this validation, the transaction is rejected. Vantiv performs this validation on all eCheck
transactions automatically.

1.11.2

Verification Feature

Since there is no authorization process associated with eChecks allowing you to confirm the
availability of funds and hold the purchase amount, there is a higher risk of certain types of fraud.
The optional eCheck Verification feature allows you to submit an eCheck account number for
comparison to a database containing historical information about the account, as well as the
account holder. When you submit an eCheck Verification transaction the information you provide
is compared to a negative database to see if the account is associated with activities, such as
fraud, over drafts, or other items determined to be risk factors.
NOTE:

Vantiv makes use of a third party service, Certegy Check Services Inc., for
all verification operations.
The verification service is not supported for Canadian eChecks.
The verification service is not available for PayFacs.

You can also initiate an account verification operation as part of an eCheck Sale transaction by
setting the  element to true. In this case, the eCheck Sale transaction is conditional
upon the verification passing. If the verification fails, the sale is not processed.

46

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCheck Processing

Introduction

1.11.2.1

Required Contents of Decline Notice

In the event you elect to perform verification on a transaction and also elect not to proceed with
the transaction based upon a verification failure, you must provide your customer with the
following Decline Notice. You can provide the notice orally, electronically, via e-mail, and/or via
U.S Mail, depending upon the type of transaction. The notice must be substantially as the notice
set forth below that contains the disclosures required under the Fair Credit Reporting Act and
instructs your customer how to contact Certegy directly.
NOTE:

If the required language of the Decline Notice changes, Vantiv will notify
you of the change. You must enact the changes within 10 days.

Example: Decline Notice

We're sorry, but we are unable to proceed with your transaction. This determination was
based on information provided by Certegy Check Services, Inc. (“Certegy”). To protect your
privacy, Certegy did not provide any financial information to [Client's Name] during the
authorization process.
The reason your transaction was not authorized was due to [mark one of the following based
on applicable decline code transmitted by Certegy]:
• account closed
• dishonored check or transfer information contained in Certegy's files
• Certegy had insufficient information available
• the identification information you entered did not conform to established guidelines
You have the right under the Fair Credit Reporting Act to know the information Certegy
utilized to make a determination regarding your check. If you find that any information
Certegy utilized in its decision is inaccurate or incomplete, you have a right to dispute it with
Certegy.
You may call Certegy toll free at 800-695-1854, or write to Certegy Check Services, Inc.,
P.O. Box 30046, Tampa, FL 33680-3046.
If you contact Certegy, please provide the following information so they can respond
promptly to your request:

•

First Name

•

Driver’s License Number & State

•

Current Address

•

Home Telephone Number

•

Date Declined

•

Date of Birth

•

Dollar Amount

•

Social Security Number

•

Check/Draft/Transfer Number

•

Merchant Name

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

47

cnpAPI Reference Guide
Introduction

eCheck Processing

•

1.11.3

Checking Account Number

•

Name of Financial Institution

Automatic Notice of Change (NoC) Updates

Similar to an issuing bank providing credit card Account Updater information, RDFIs provide
Notification of Change (NoC) files and deliver them through the ACH network. These NoCs
include updated account information including bank routing numbers, account numbers, and
account names.
Vantiv makes available the NoC information to you for your use in updating your customer files.
Additionally, if you submit a transaction containing information that has changed, we
automatically update the information and forward the corrected transaction to the ACH network.
The cnpAPI response message to you also contains the updated information for your use in
correcting your database.
NOTE:

1.11.4

While we always make the NoC information available to you, Vantiv does
not support automatic updating of account information for PayFacs.

Auto Redeposit Feature

NACHA rules allow merchants to redeposit entries when the initial deposit was returned for
either Insufficient Funds or Uncollected Funds. Two redeposit attempts are allowed within 180
days of the settlement date of the initial deposit. Vantiv offers an optional service that allows you
to preconfigure automatic redeposits of transactions returned for the those reasons. You define the
number of days from the initial return for Vantiv to resubmit the transaction. You also define the
number of days from the return of the first resubmission for the attempt of a second resubmission.
NOTE:

You track the current state of your transactions, returns, and
resubmissions via the iQ User Interface. Please refer to the iQ Reporting
and Analytics User Guide for additional information.

For example, you submitted an eCheck Sale transaction on 29 January that is returned for Return
Reason Code R01 - Insufficient Funds. The return occurs on 1 February. With the Auto Redeposit
feature enabled and a preset period of 5 days for the first redeposit, the system would
automatically generate a resubmission of the deposit on 6 February. If this transaction is also
returned for the same reason code on 7 February and you have a preset time period for the second
redeposit on 7 days, the system generates the second redeposit on 14 February.

48

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCheck Processing

1.11.5

Introduction

eCheck Prenotification

An eCheck Prenotification is a non-monetary transaction used to verify the account information
supplied by the consumer is valid. These transactions are sent to the ACH network to help ensure
subsequent entries are posted appropriately. Since this is a verification of account information,
typically, you would submit a Prenotification transaction in advance of processing the order,
during the customer set-up process. There are two types of Prenotification transaction types:
echeckPreNoteCredit and eCheckPreNoteSale. Per NACHA requirements, you must
submit the Prenotification transaction that corresponds to the intended, subsequent transaction.
For example, if you are planning to submit an echeckSale transaction and want to verify the
account information, you should submit a echeckPreNoteSale.
The possible ACH network responses to a prenotification are as follows:
•

No response - applies when the account is open and the account information is correct.

•

Notification of Change - provides updated account information, including correct routing
number, e.g. C02 Incorrect routing/transit number (visible in the SSR eCheck NOC report).

•

Return code - provides account status, e.g. R02 Account is closed, R03 No account on file,
R04 Invalid account number.
NOTE:

Prenotification transactions are only supported in cnpAPI V9.1 or above
and only in Batch submissions. Prenotification transactions are not
supported for PayFacs or for Canadian eChecks.

When you submit either of the Prenotification transaction types, the system sends an
acknowledgment in the Batch response file. This response file does not provide the results of the
prenotification check, but rather a verification that we received the transaction and it was properly
formatted. You receive the results to the check in the SSR eCheck Notification of Change report.
This report is run daily and you can expect to see the results for submitted prenotification checks
by the second or third business day after the settlement day. The settlement day for a
Prenotification transaction is defined as the next business day after submission to the ACH
network. Remember, if the account you are attempting to verify is open and the account
information is correct, the report will not contain an entry for that transaction. The report only
contains NOCs (update information).
Per NACHA regulations, you can submit the eCheck Sale or eCheck Credit transaction on the
third business day after the settlement day; however, there might still be a forthcoming NOC on
that day. Due to the timing of the responses from NACHA, the generation of the reports, and the
movement of the transactions, you should wait until the fourth day after the settlement day to
submit the live transaction unless you receive a NOC earlier. This timing is illustrated in the
example below.
1. You submit a Prenotification transaction on Monday prior to your cut-off time.
2. Our system forwards the transaction to NACHA on Tuesday. Note, this makes Wednesday the
settlement day.
3. NACHA responds with a NOC/return, if any, by Thursday night.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

49

cnpAPI Reference Guide
Introduction

eCheck Processing

4. On Friday, the information from NACHA is processed by our systems.
5. On Saturday morning, the SSR NOC report containing the information is available to you.
6. You can submit the eCheck Sale or eCheck Credit transaction before your cut-off time on
Saturday night. This is the fourth day after settlement, the fifth day after submission.

50

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
SEPA Direct Debit

Introduction

1.12 SEPA Direct Debit
When building a robust international ecommerce offering, you should always consider regional,
preferred payment methods. Enabling payment methods with which consumers are both familiar
and comfortable may provide a significant bump in your conversion rates and sales. In Europe
there are dozens of regionally popular alternative payment methods. SEPA (Single Euro Payments
Area) Direct Debit is a Pan-European network facilitating direct debit transactions in 34
countries. Currently, SEPA Direct Debit accounts for approximately 10% of all eCommerce sales
in Europe and leads all alternative payment methods in Germany, accounting for more than 35%
of eCommerce spending.
Although similar to eCheck transaction in the US, in that they are both direct debit methods of
collecting funds, there are several differences in the process. Most of the difference concern the
requirement for the presentation of a Mandate to the consumer. A Mandate is basically an
agreement between the consumer and the merchant allowing the merchant to debit the consumer’s
account for the required funds. The agreement can specify either a one-time payment or recurring
payments. The consumer must agree to the Mandate (Usually, by clicking a Confirm button on
the Mandate page.) for the transaction to succeed.
The Vantiv eComm platform allows for two different Mandate scenarios. The first, and
recommended method, involves the redirect from your site to a Vantiv provided Mandate page.
Alternatively, you can provide your own Mandate page. The following sections discuss the
purchase/order flow for each scenario.

1.12.1

SEPA Direct Debit - Vantiv Supplied Mandate

You cannot complete a SEPA Direct Debit transaction without an approved (by the consumer)
Mandate. While you can produce your own Mandate page, Vantiv makes the implementation of
SEPA Direct Debit easier for you by providing Mandates in various languages, for either single
payments or recurring transactions.
Figure 1-8 provides an overview of the order flow, when using a Vantiv supplied Mandate for a
one-time payment, or the first payment in a recurring stream. The steps provide additional
information.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

51

cnpAPI Reference Guide
Introduction

SEPA Direct Debit

FIGURE 1-8

1

Order Flow for Vantiv Supplied Mandate

Consumer selects
iDEAL payment
method on the
Checkout page.

2

Consumer

Merchant
Merchant redirects
consumer to the bank
selection page.

4

5

Consumer redirected back to
Merchant Checkout page. If
the consumer accepted the
agreement, redirectToken
appears as a URL parameter.
If agreement rejected,
redirectToken not included.

Consumer Accepts or
Rejects transaction
using iDEAL/Bank
authentication
process.

Merchant sends Sale
transaction to Vantiv.

Response includes
link to page for bank
selection and
redirectToken.

3

6

.

1. On your checkout page, the consumer selects SEPA Direct Debit as the payment method,
enters their IBAN (International Banking Account Number), selects a preferred language for
the Mandate (optional), and clicks the Submit button.
NOTE:

If you do not specify a preferred language, or you specify an unavailable
language, the Mandate page appears in English.

2. You create a Sale transaction and submit it to the Vantiv eComm platform, using
sepaDirectDebit as the payment method and including its child elements shown below
(preferredLanguage optional). In addition to the required child elements of
sepaDirectDebit you must include the name, email, and country child elements of
billToAddress.
Example: SEPA Direct Debit Sale Request Message - Vantiv Supplied Mandate


SDD
password

52

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
SEPA Direct Debit

Introduction



sddSale
1001
ecommerce

Johann Schmidt
10 Hoch Strasse
Hanover
30159
DE
jschmidt@phoenixprocessing.com
781-270-1111


Vantiv
OneTime
DE79850503003100180568
DE




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


82830949823203015
sddSale
000
2017-01-21T17:07:27
2017-01-21
Approved

http://MandateHostURL/DE
evr0kij413g8r85e32v7deov0c

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

53

cnpAPI Reference Guide
Introduction

SEPA Direct Debit

1ABCA43




4. You redirect the consumer from your checkout page to the redirectUrl.
5. The consumer either accepts or rejects the Mandate.
6. After the consumer either accepts or declines the Mandate, they are redirected back to your
checkout page, or alternate page upon decline. If they accepted the Mandate, the URL
contains a parameter exposing the redirectToken value
(redirectToken=token_value). By comparing this value to the value you received in the
Sale response message you can verify that the consumer accepted the Mandate. If they
declined the Mandate, the URL does not include the parameter.

1.12.2

SEPA Direct Debit - Merchant Supplied Mandate

If you elect to produce and provide your own Mandate to the consumer, the order flow differs
from the Vantiv supplied Mandate flow, as shown in Figure 1-9 and explained in the steps that
follow.
FIGURE 1-9

Order Flow for Merchant Supplied Mandate

Consumer enters their
IBAN and clicks
Submit button on
Checkout page.

1

5

Consumer
Merchant presents
Mandate terms.

3a

Merchant sends Sale
transaction to Vantiv,
including
mandateSignatureDate,
mandateUrl, etc.

Response

Merchant

6

2

3b

Consumer Accepts or
Rejects the Mandate.

Accept/Reject info to
Merchant

Mandate Page

Consumer redirected back to
Merchant Checkout page. If
the consumer accepted the
Mandate, the Merchant
constructs a Sale transaction
to Vantiv.

54

4

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
SEPA Direct Debit

Introduction

1. On your checkout page, the consumer selects SEPA Direct Debit as the payment method,
enters their IBAN (International Banking Account Number), selects a preferred language for
the Mandate (optional), and clicks the Submit button.
2. You redirect the consumer from your checkout page to your Mandate page.
3. The consumer take action on the Mandate page.
a. The consumer either accepts or rejects the Mandate.
b. Your Mandate page provides the Accept or Decline information to your servers.
4. Once the consumer takes action on the Mandate page, you return them to your checkout page.
If the consumer rejected the Mandate, you can ask for a different payment method. If the
consumer accepted the Mandate, you record the signature date and use it to construct a Sale
transaction. Also, if this is the first of a series of recurring payments, you assign a
mandateReference value.
5. You submit the Sale transaction to the Vantiv eComm platform, as shown in the example
below. In addition to the required child elements of sepaDirectDebit you must include the
mandateReference, mandateUrl, and mandateSignatureDate, as well as the name,
email, and country child elements of billToAddress.
Example: SEPA Direct Debit Sale Request Message - Merchant Supplied
Mandate


SDD
password


sddSale
1001
ecommerce

Johann Schmidt
10 Hoch Strasse
Hanover
30159
DE
jschmidt@phoenixprocessing.com
781-270-1111


Merchant
FirstRecurring
ABCD1234

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

55

cnpAPI Reference Guide
Introduction

SEPA Direct Debit

http://MerchantMandateHostURL
2017-01-21
DE79850503003100180568




6. The Vantiv eComm platform returns a Sales response message. This message does not
include the sepaDirectDebitResponse element, since Vantiv does not return any
additional SEPA Direct Debit related information, such as a redirectToken.

56

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
iDEAL, SOFORT, and Giropay

Introduction

1.13 iDEAL, SOFORT, and Giropay
iDEAL, SOFORT, and Giropay are International alternative payment methods. iDEAL services
over 10 million consumers in the Netherlands, Giropay services German consumers, and
SOFORT services consumers in several countries (predominantly Germany and other German
speaking countries). Each of these alternative payment methods initiate a real-time transfer of
funds from the consumer account to the merchant account. This method differs from credit cards
and several other alternate payment methods in that the consumer is not agreeing to pay the
settlement at a future time, rather they communicate directly with their bank and approve the
transfer of fund from their account to yours. After their approval, their bank displays to them a
confirmation of payment and debits their account within a few seconds.
NOTE:

Although the bank debits the consumer’s account immediately, the funds
may not appear in your account for a few days, depending upon your
settlement agreement.

The graphic and steps below illustrate the iDEAL, SOFORT, and Giropay processes.
FIGURE 1-10

1

iDEAL, SOFORT, and Giropay Order Flow

Consumer selects the
payment method on
the Checkout page.

2

Consumer

Merchant
Merchant redirects
consumer to the bank
selection page.

4

5

Consumer Accepts or
Rejects transaction
using the Bank
authentication
process.

Merchant sends Sale
transaction to Vantiv.

Response includes
link to page for bank
selection and
redirectToken.

3

Bank
Consumer redirected back to
Merchant Checkout page. If the
consumer accepted the agreement,
redirectToken appears as a URL
parameter. If agreement rejected,
redirectToken not included.

6

.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

57

cnpAPI Reference Guide
Introduction

iDEAL, SOFORT, and Giropay

1. On your checkout page, the consumer selects iDEAL, SOFORT or Giropay as the payment
method and clicks the Submit button.
2. You create a Sale transaction (iDEAL example below) and submit it to the Vantiv eComm
platform, using ideal as the payment method and including its child elements,
preferredLanguage if specified.
Example: iDEAL Sale Request


user_name
password


p1_idealSale
10011
ecommerce

David Berman
10 Noorderstraat
Amsterdam
1000 AP
NL
dberman@phoenixprocessing.com
020-1234567


NL



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


84568456
p1_idealSale
000
2017-04-03T10:24:31

58

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
iDEAL, SOFORT, and Giropay

Introduction

2017-04-03
Approved

http://ideal.bank.com
1234567890
123456YourCompanyName




4. The consumer selects their bank on the bank selection page.
5. The consumer accepts or rejects the transaction on their bank page. The bank determines the
actual process of authenticating the user and accepting the transaction.
6. The consumer gets redirected back to your checkout page. If they accepted the agreement, the
URL contains a parameter exposing the redirectToken value
(redirectToken=token_value). By comparing this value to the value you received in the
Sale response message you can verify that the consumer accepted the agreement and the bank
transferred the funds. If they declined, the URL does not include the parameter.
NOTE:

Although the consumer does not have chargeback rights when using
these alternate payment methods, Vantiv recommends you maintain a
robust and well documented returns system. European regulations
require that you credit your customer’s account within 30 days of a return.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

59

cnpAPI Reference Guide
Introduction

eCommerce Solution for Apple Pay™

1.14 eCommerce Solution for Apple Pay™
Vantiv supports Apple Pay for in-app and in-store purchases initiated on compatible versions of
iPhone and iPad, as well as purchases from your desktop or mobile website initiated from
compatible versions of iPhone, iPad, Apple Watch, MacBook and iMac (Apple Pay on the Web).
For in-store transactions, a consumer can use the Near Field Communications (NFC) chip in their
device to make a purchase by simply touching the device to an NFC-compliant terminal. Identity
verification is provided by Touch ID, a fingerprint reading application built into the device. If you
wish to allow Apple Pay transactions from your native iOS mobile application, you must build
the capability to make secure purchases using Apple Pay into your mobile application.
If you wish to allow Apple Pay payments on your desktop or mobile website, your website must
be configured to work with Apple to request authorization from the consumers iPhone or iPad via
Touch ID. See Table 1-10, "Apple Pay on the Web Compatible Devices" for more information.
This section provides an overview of the operation of Apple Pay and Apple Pay on the web,
along with the several methods you can use to submit Apple Pay purchases to the Vantiv
eCommerce platform. The topics discussed are:
•

Overview of Apple Pay Operation

•

Vantiv Decryption of Apple Pay PKPaymentToken

•

Merchant Decryption of Apple Pay PKPaymentToken

•

cnpAPI  Structure

•

Vantiv Mobile API for Apple Pay HTTPS POST Components

•

Recurring Payments with Apple Pay

1.14.1

Overview of Apple Pay Operation

The operation of Apple Pay and Apple Pay on the web is relatively simple, but will require either
the development of new native iOS applications or the modification of your existing applications
or website that include the use of the Apple PassKit Framework (or Apple Pay JavaScript for
Apple Pay web) and the handling of the encrypted data returned to your application by Apple Pay.
The basic steps that occur when a consumer initiates an Apple Pay purchase using your mobile
application or website are:
1. When the consumer selects the Apple Pay option from your application, your application
makes use of the Apple PassKit Framework (or Apple Pay JavaScript) to request payment
data from Apple Pay.
2. When Apple Pay receives the call from your application and after the consumer approves the
Payment Sheet (using Touch ID), Apple creates a PKPaymentToken using your public key.
Included in the PKPaymentToken is a network (Visa, MasterCard, Discover, or American
Express) payment token and a cryptogram.

60

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCommerce Solution for Apple Pay™

Introduction

3. Apple Pay returns the Apple PKPaymentToken (defined in Apple documentation; please refer
to
https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSO
N/PaymentTokenJSON.html).
The remainder of this section discusses the various options for handling the PKPaymentToken in
the transaction flow.

1.14.2

Vantiv Decryption of Apple Pay PKPaymentToken

Vantiv recommends using one of the Vantiv Decryption methods. This transaction process
relieves you from the burden of creating and maintaining public and private keys, as well as
decrypting the PKPaymentToken. If you have already implemented eProtect in a mobile
application, you should use eProtect for Apple Pay. A second, similar method, which still allows
you to submit the PKPaymentToken without decryption, involves you sending the
Authorization/Sale transaction with the PKPaymentToken key values in a new cnpAPI element
structure (see applepay), typically from your server. This method can be used even if you are not
tokenized with Vantiv.
In all of these implementations, your Vantiv Implementation Consultant will provide a CSR
(Certificate Signing Request) you use in your registration process with Apple Pay. The CSR
provides Apple Pay with the public key used for encryption, while Vantiv retains the private key
used for decryption.

1.14.2.1

Using the Browser JavaScript API for Apple Pay on the Web

In this scenario, the Vantiv eProtect Customer Browser JavaScript API controls the fields on your
checkout page that hold sensitive card data. When the cardholder clicks the Apple Pay button,
communication is exchanged with Apple Pay via the JavaScript API to obtain the
PKPaymentToken. From this point forward, your handling of the transaction is identical to any
other eProtect transaction. The eProtect server returns a Registration ID (low-value token) and
your server constructs the cnpAPI transaction using that ID. See the Vantiv eProtect Integration
Guide for JavaScript and HTML page examples and more information on using the browser
JavaScript API.
Step 1, Step 2, and Step 3 are the same as those outlined in Overview of Apple Pay Operation on
page 60. The process after Step 3 is detailed below (and shown in Figure 1-11):
4. Your website sends the PKPaymentToken to our secure server via the JavaScript Browser
API and eProtect returns a Registration ID.
5. Your website forwards the transaction data along with the Registration ID to your order
processing server, as it would with any eProtect transaction.
6. Your server constructs/submits a standard cnpAPI Authorization/Sale transaction using the
Registration ID, setting the  element to applepay.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

61

cnpAPI Reference Guide
Introduction

eCommerce Solution for Apple Pay™

7. Using the private key, Vantiv decrypts the PKPaymentToken associated with the Registration
ID and submits the transaction with the appropriate information to the card networks for
approval.
8. Vantiv sends the Approval/Decline message back to your system. This message is the
standard format for an Authorization or Sale response and includes the Vantiv token.
9. You return the Approval/Decline message to your website.
Table 1-10 lists the requirements for your customers’ Apple devices when making purchases via
Apple Pay on the Web.
NOTE:

Table 1-10 represents data available at the time of publication of this
document, and is subject to change. See the latest Apple documentation
for current information.

TABLE 1-10 Apple Pay on the Web Compatible Devices

62

Apple Device

Operating System

iPhone 6 and later
iPhone SE

iOS 10 and later

iPad Pro
iPad Air 2 and later
iPad Mini 3 and later

iOS 10 and later

Apple Watch
Paired with iPhone 6 and later

Watch OS 3 and later

iMac
Paired with any of the above mobile devices
with ID Touch for authentication

macOS Sierra and later

MacBook
Paired with any of the above mobile devices
with ID Touch for authentication

macOS Sierra and later

Browser

Safari only

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCommerce Solution for Apple Pay™

FIGURE 1-11

1.14.2.2

Introduction

Data/Transaction Flow using Browser JavaScript API for Apple Pay on the Web

Using the Vantiv Mobile API for Apple Pay

In this scenario, your native iOS application performs an HTTPS POST of the Apple Pay
PKPaymentToken using the Vantiv Mobile API for Apple Pay. From this point forward, your
handling of the transaction is identical to any other PayPage transaction. The PayPage server
returns a PayPage Registration ID and your Mobile App (or server) constructs the cnpAPI
transaction using that ID.
Step 1, Step 2, and Step 3 are the same as those outlined in Overview of Apple Pay Operation on
page 60. The process after Step 3 is detailed below and in Figure 1-12.
4. Your native iOS application sends the PKPaymentToken to our secure server via an HTTPS
POST and eProtect returns a Registration ID. Please refer to the Vantiv eProtect Integration
Guide for additional information.
5. Your native iOS application forwards the transaction data along with the Registration ID to
your order processing server, as it would with any eProtect transaction.
6. Your server constructs/submits a standard cnpAPI Authorization/Sale transaction using the
Registration ID, setting the  element to applepay.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

63

cnpAPI Reference Guide
Introduction

eCommerce Solution for Apple Pay™

7. Using the private key, Vantiv decrypts the PKPaymentToken associated with the Registration
ID and submits the transaction with the appropriate information to the card networks for
approval.
8. Vantiv sends the Approval/Decline message back to your system. This message is the
standard format for an Authorization or Sale response and includes the Vantiv token.
9. You return the Approval/Decline message to your mobile application.
FIGURE 1-12

1.14.2.3

Data/Transaction Flow using the Vantiv Mobile API for Apple Pay

Submitting the Apple Pay PKPaymentToken in a cnpAPI Message

In this scenario, you submit the Apple Pay PKPaymentToken to the Vantiv eCommerce platform
using a new cnpAPI structure (see applepay), typically from your server. As with the previous
scenario, Vantiv decrypts the PKPaymentToken from Apple Pay using the private key.
Step 1, Step 2, and Step 3 are the same as those outlined in Overview of Apple Pay Operation on
page 60. The process after Step 3 is detailed below and in Figure 1-13.

64

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCommerce Solution for Apple Pay™

Introduction

4. Your mobile application forwards the PKPaymentToken from Apple Pay, along with other
normal information from the transaction (such as Bill To and Ship To Address), to your order
processing server.
5. You do not decrypt the PKPaymentToken, but rather forward the data to Vantiv in the
Authorization/Sale transaction using the cnpAPI  element structure instead of
 (Server-side API submit) and setting the  element to applepay.
6. Using the private key retained by Vantiv, we decrypt the PKPaymentToken and submit the
transaction with the appropriate information to the card networks for approval.
7. Vantiv sends the Approval/Decline message back to your system. This message is the
standard format for an Authorization or Sale response.
8. You return the Approval/Decline message to you mobile application.
FIGURE 1-13

1.14.2.4

Data/Transaction Flow with Direct Submission of PKPaymentToken via cnpAPI

Merchant Decryption of Apple Pay PKPaymentToken

Using this process, the responsibility for the decryption of the PKPaymentToken from Apple Pay
falls to you. After completing the first three steps of the process as detailed in the Overview of

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

65

cnpAPI Reference Guide
Introduction

eCommerce Solution for Apple Pay™

Apple Pay Operation section and depicted by the green and blue arrows in Figure 1-14, the
process continues as follows:
4. Your mobile application forwards the PKPaymentToken from Apple Pay, along with other
normal information from the transaction (such as Bill To and Ship To Address), to your order
processing server.
5. Using your private key, you decrypt the PKPaymentToken, construct the Authorization/Sale
transaction, and submit it to Vantiv. In this case, you would populate the cnpAPI 
element with the device primary account number, the  element with the expiration
date, and the  field with the cryptogram extracted from the
PKPaymentToken. Also, set the  element to applepay (Server-side API
submit).
6. Vantiv detects that this is an Apple Pay transaction and submits the transaction with the
appropriate information to the card networks for approval.
7. Vantiv sends the Approval/Decline message back to your system. This message is the
standard format for an Authorization or Sale response.
8. You return the Approval/Decline message to your mobile application.
FIGURE 1-14

66

Data/Transaction Flow with Merchant Decryption of Apple Pay PKPaymentToken

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCommerce Solution for Apple Pay™

1.14.3

Introduction

Recurring Payments with Apple Pay

When you submit the first transaction in a recurring/installment stream, you must set the
 element to either initialRecurring or initialInstallment, as applicable. If
the transaction involves a Visa or Discover card, the XML response message includes the
 element. You must retain the value returned for use in future
transactions. When you submit the next and all subsequent transactions in the recurring stream,
set the  to recurring or installment as appropriate, and include the
networkTransactionId value in the  element. If it is
a Discover transaction also include the  element. Since the
original payment token was only for a single use and is not available for additional transactions,
this allows Visa/Discover to tie the new transaction to the original approved transaction.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

67

cnpAPI Reference Guide
Introduction

eCommerce Solution for Android Pay™

1.15 eCommerce Solution for Android Pay™
Android Pay is an in-store and in-app (mobile or web) payment method, providing a secure
process for consumers to purchase goods and services. In-store purchases are done by using Near
Field Communication (NFC) technology built into the Android Smart phone with any
NFC-enabled terminal at the retail POS. For in-app purchases, the consumer need only select
Android Pay as the payment method in your application. You will need to modify your
application to use Android Pay as a payment method.
Vantiv supports two methods for merchants to submit Android Pay transactions from Web/Mobile
applications to the eComm platform. The preferred method involves you sending certain Vantiv
specific parameters to Google®. The response from Google includes a Vantiv
paypageRegistrationId, which you use in you payment transaction submission to Vantiv. With the
alternate method, you receive encrypted information from Google, decrypt it on your servers, and
submit the information to Vantiv in a payment transaction.
This section provides an overview of both methods and includes the following sections:
•

Android Pay using eProtect

•

Merchant Decryption Method

1.15.1

Android Pay using eProtect

This is the recommended and typical method of implementing Android Pay for Web and Mobile
Applications on the Vantiv eComm platform. The steps that follow, along with Figure 1-15,
illustrate the high level flow of messages associated with an Android Pay purchase, when
utilizing the Vantiv eProtect service.
NOTE:

This process assumes you have integrated with Google using the method
that returns the Vantiv low-value token (paypageRegistrationId) from
Google following the Full Wallet request.

1. When the consumer clicks the Android Pay button in your application, the action triggers a
MaskedWalletRequest to Google. In the MaskedWalletRequest, you must set a new object
PaymentMethodTokenizationParameters indicating that you are using Vantiv. Use the
following code sample as a guide to setting this field.
Setting the PaymentMethodTokenizationParameters
PaymentMethodTokenizationParameters parameters =
PaymentMethodTokenizationParameters .newBuilder()
.setPaymentMethodTokenizationType(PaymentMethodTokenizationType.PAYMENT_GATEWAY)
.addParameter("gateway","vantiv")

68

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCommerce Solution for Android Pay™

Introduction

.addParameter("vantiv:merchantPayPageId",payPageId)
.addParameter("vantiv:merchantOrderId",orderId)
.addParameter("vantiv:merchantTransactionId",id)
.addParameter("vantiv:merchantReportGroup",reportGroup)
.build();
IMPORTANT: You must use the same orderId value on all calls (i.e., Google, Register
Token, Authorization, Sale, etc.). Failure to use the same orderId can
prevent customers from tracking their orders using the Android Pay
application.

Setting New Object in the MaskedWalletRequest
MaskedWalletRequest request = MaskedWalletRequest.newBuilder()
.setMerchantName(Constants.MERCHANT_NAME)
.setPhoneNumberRequired(true)
.setShippingAddressRequired(true)
.setCurrencyCode(Constants.CURRENCY_CODE_USD)
.setEstimatedTotalPrice(cartTotal)
.setCart(Car.newBuilder()
.setCurrencyCode(Constants.CURRENCY_CODE_USD)
.setTotalPrice(cartTotal)
.setLineItems(lineItems)
.build())
.setPaymentMethodTokenizationParameters(parameters)
.build();

The information returned by Google in the MaskedWallet object may include a masked card
number (last-four digits exposed) and shipping information. The consumer has the option of
changing this information. If any info changes, Android Pay returns an updated
MaskedWallet object.
2. Upon confirmation of the order by the consumer your application initiates a
FullWalletRequest to Google.
3. After receiving the FullWalletRequest from your application, Google submits the card
information to Vantiv eProtect. The eProtect servers return a low-value token
(paypageRegistrationId).
4. Google returns the low-value token to your application along with the Full Wallet
information.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

69

cnpAPI Reference Guide
Introduction

eCommerce Solution for Android Pay™

5. Your applications sends the transaction information to your servers along with the low-value
token. Your servers submit the Auth/Sale transaction to the Vantiv eComm platform. You
must set the orderSource to androidpay in the transaction.
NOTE:

Instead of submitting a Auth/Sale transaction, you can submit a Register
Token transaction to convert the low-value token to a Vantiv high-value
token. You would then use the high-value token in subsequent
transactions submitted to the eComm platform.

6. Vantiv processes your transaction normally and returns the results along with a high-value
token.
FIGURE 1-15

Web App/
Mobil App

High Level Message Flow for Android Pay using eProtect

Merchant
Server

eProtect

eComm

Card
Networks

1

2

3
4

5

6

70

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCommerce Solution for Android Pay™

1.15.2

Introduction

Merchant Decryption Method

Using this process, the responsibility for the decryption of the encrypted payload from Android
Pay falls to you. The steps that follow, along with Figure 1-16, illustrate the high level flow of
messages associated with an Android Pay purchase, when you perform the decryption of the
encrypted payload.
NOTE:

The process assumes you have integrated with Google using the method
that returns the encrypted payload from Google following the Full Wallet
request.

1. When the consumer clicks the Android Pay button in your application, the action triggers a
MaskedWalletRequest to Google. The information returned by Google in the MaskedWallet
object may include a masked card number (last-four digits exposed) and shipping
information. The consumer has the option of changing this information. If any info changes,
Android Pay returns an updated MaskedWallet object.
2. Upon confirmation of the order by the consumer your application initiates a
FullWalletRequest to Google. Google also returns the encrypted payload. The encrypted
payload is a UTF-8 encoded serialized JSON dictionary with the following keys:
• encryptedMessage (string base64) - an encrypted message containing the payment
credentials
• ephemeralPublicKey (string base64) - the ephemeral public key associated with the
private key to encrypt the message
• tag (string base64) - MAC of encryptedMessage
3. Your application sends the encrypted payload along with the transaction information to your
server.
4. Your server decrypts the encrypted payload extracting the payment, which is a UTF-8
encoded, serialized JSON dictionary with the following keys:
• dpan (string (digits only)) - the device-specific personal account number (i.e., device
token)
• expirationMonth (number) - the expiration month of the dpan (1 = January, 2 =
February, etc.)
• expirationYear (number) - The four-digit expiration year of the dpan (e.g., 2015)
• authMethod (string) - the constant 3DS (may change in future releases).
• 3dsCryptogram (string) - the 3DSecure cryptogram
• 3dsEciIndicator ((optional) string) - ECI indicator per 3DSecure specification

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

71

cnpAPI Reference Guide
Introduction

eCommerce Solution for Android Pay™

Example of Decrypted Credentials in JSON
{
“dpan”: “4444444444444444”,
“expirationMonth”: 10,
“expirationYear”: 2015,
“authMethod”: “3DS”,
“3dsCryptogram”: “AAAAAA...”,
“3dsEciIndicator”: “eci indicator”
}

After decryption, submit the Authorization/Sale transaction to Vantiv, setting the
orderSource element to androidpay and populating the following cnpAPI elements with
the decrypted information:
• number - dpan value
• expDate - MMYY derived from the expirationMonth and expirationYear values
• authenticationValue - the 3dsCryptogram value
5. Vantiv processes your transaction normally and returns the results in the response message.

72

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
eCommerce Solution for Android Pay™

FIGURE 1-16

Web App/
Mobil App

Introduction

High Level Message Flow for Android Pay using Merchant Decryption

Merchant
Server

Vantiv
eComm

Card
Networks

1

2

3

4

5

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

73

cnpAPI Reference Guide
Introduction

1.15.3

eCommerce Solution for Android Pay™

Recurring Payments with Android Pay

When you submit the first transaction in a recurring/installment stream, you must set the
 element to either initialRecurring or initialInstallment, as applicable. If
the transaction involves a Visa or Discover card, the XML response message includes the
 element. You must retain the value returned for use in future
transactions. When you submit the next and all subsequent transactions in the recurring stream,
set the  to recurring and include the networkTransactionId value in the
 element. If it is a Discover transaction also include the
 element. Since the original payment token was only for a
single use and is not available for additional transactions, this allows Visa to tie the new
transaction to the original approved transaction.

74

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Supported Transaction Types

Introduction

1.16 Supported Transaction Types
cnpAPI Batch processing supports all transaction types except Voids, eCheck Voids and Private
Label Gift Card reversal transactions, which are handled as Online transactions only. Online
processing handles all transaction types. This section provides a description of each transaction
type, information concerning its use, and any special considerations.
NOTE:

1.16.1

For information about Dynamic Payout Funding Instructions please refer
to Appendix D, "PayFac™ Dynamic Payout".

Authorization Transaction

The Authorization transaction enables you to confirm that a customer has submitted a valid
payment method with their order and has sufficient funds to purchase the goods or services they
ordered. Setting the  element to true in the Authorization request enables
the system to return authorizations for a portion of the order amount for cases where the card does
not have an adequate credit limit or balance available for the full amount.
An approved Authorization reduces the customer's credit limit (or bank balance, in the case of a
debit card) by the amount of the approval by placing the amount on hold. If you have the Prepaid
Indicator feature enabled, the Authorization response also includes an element that indicates if the
card is Prepaid, as well as an element indicating the available balance on the card.
NOTE:

To obtain better interchange rates, you should always perform an AVS
check either as a standalone transaction, or as part of the
Authorization/Sale transaction.
If you settle in a currency other than US or Canada, you cannot use partial
Authorizations.
While most merchants perform Authorizations as Online transactions,
there is no requirement to do so.

The lifespan of an Authorization depends upon the payment method. Table 1-11 provides
information concerning Authorization lifespans for various card types and alternate payment
methods.

TABLE 1-11 Lifespan of Payment Authorizations
Payment Type

Lifespan of Authorization

MasterCard

7 days

Visa

7 days

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

75

cnpAPI Reference Guide
Introduction

Supported Transaction Types

TABLE 1-11 Lifespan of Payment Authorizations
Payment Type

Lifespan of Authorization

American Express

7 days

Discover

10 days

PayPal

29 days total by default; Vantiv recommends capture
submission within three days. For more information, see the
Vantiv PayPal Integration Guide.

As long as the authorization has not expired, or the amount exhausted, you can use it repeatedly
to fulfill an order. This would be the case if the Authorization covered multiple items with
staggered deliveries. In this scenario, you would issue a Partial Capture transaction as each item
shipped until the order was completely fulfilled.
NOTE:

1.16.1.1

If you obtain an Authorization through approved vendors for voice and
terminal authorizations, you would use a Capture Given Auth transaction
to deposit the funds (see Capture Given Auth Transaction on page 79).

AVS Only Transaction

An AVS Only transaction is a variation of an Authorization transaction that uses the Address
Verification System to enable you to verify that a customer supplied address matches the billing
address associated with the card. To submit an AVS Only transaction, submit an Authorization
transaction with the  element set to 000 and the optional billToAddress element
with appropriate child values.
NOTE:

1.16.2

To obtain better interchange rates, you should always perform an AVS
check either as a standalone transaction, or as part of the
Authorization/Sale transaction.

Authorization Reversal Transactions

The primary use of Authorization Reversal transactions is to eliminate any unused amount on an
unexpired Authorization. Issuing an Authorization Reversal has the benefit of freeing any
remaining held amount that reduces the buying power of your customer. Potentially, this both
increases customer satisfaction and can allow them to proceed with additional purchases that may
otherwise be blocked by credit limits. It also helps you avoid any misuse of Auth fees imposed by
the card associations.

76

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Supported Transaction Types

NOTE:

Introduction

For American Express transactions, the reversal amount must match the
authorization amount. American Express does not allow partial reversals
and reversals against remaining amounts after a partial capture. Attempts
to perform these types of reversals result in a Response Code of 336 Reversal amount does not match Authorization amount.

For example, consider the following scenario. A customer with a $6,000 credit limit orders a
$3,000 stereo system, but the stereo is a discontinued item. The merchant notifies the customer,
but does not perform and Authorization Reversal. The customer attempts to submit a new order
for a $3,001 stereo.
•

If the customer uses the same credit card for both orders, the second order could be denied,
since the account’s remaining credit limit is only $3,000.

•

If the customer had used the same debit card for both orders, the second order places the
customer’s bank account in an overdraft situation (assuming a starting balance of $6,000).

Either of these situations can result in the merchant losing a sale, as well as receiving a call from
an angry customer.
Another advantage of Authorization Reversal transactions occurs on Visa transactions. In order
for you to qualify for the best possible interchange rates from Visa, the amount of the Capture
must match the amount of the associated Authorization. In order to take advantage of this
situation for you, if the Capture amount is less than the associated Authorization amount, Vantiv
automatically performs a partial Authorization Reversal for the unused amount (also see Capture
Request on page 232).

1.16.2.1

Notes on the Use of Authorization Reversal Transactions

This section provides additional information concerning the requirements of and exceptions to the
use of Authorization Reversal transactions.
•

Authorization Reversal transactions are supported for the following methods of payment:
PayPal, MasterCard, Visa, Discover, Diners Club, and JC and American Express, but
American Express and PayPal only support reversals of the entire Authorized amount (no
partial reversals).

•

All transactional data, including associated Authorizations, Captures, and Refunds, must use
cnpAPI format.

•

Vantiv recommends that you send the Authorization Reversal transaction using the same
submission method (Batch or Online) as used for the Capture transaction. This is to eliminate
a possible race condition that may occur if you submit an Online Authorization Reversal prior
to the processing of a Batch containing the associate Capture transaction.

•

For Batch transactions, send Authorization Reversal transactions in a session separate from
the both the associated Authorization and the associated Capture transactions.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

77

cnpAPI Reference Guide
Introduction

Supported Transaction Types

•

For Online transactions, when following an Authorization with an Auth Reversal, allow a
minimum of one minute between the transactions.

•

For Visa transactions, Vantiv automatically performs a partial Authorization Reversal, if the
Capture amount is less than the associated Authorization amount.

•

If you do not specify an amount ( element) in the Authorization Reversal, Vantiv
reverses the total amount of the associated Authorization.

•

Do not send an Authorization Reversal against an expired Authorization. This results in a 306
- Auth expired, so amount does not need to be reversed error. When an Authorization expires,
the hold amount is automatically reversed.

•

Do not send an Authorization Reversal against an Authorization that does not exist in our
system. For example, if you sends a reversal against an Authorization that failed or an
Authorization that was declined, the Authorization Reversal returns a 360 - No transaction
found with specified transaction Id error.

•

Do not send an Authorization Reversal against a payment type that does not support
Authorization Reversals. This results in a 335 - This method of payment does not support
reversals error.

•

Do not send an Authorization Reversal for a fully depleted Authorization. This results in a
111 - Authorization amount has already been depleted error.

•

Do not use an Authorization Reversal to reverse an Authorization on a (Closed Loop) Gift
Card. Use a Gift Card Auth Reversal instead (see Gift Card Auth Reversal Transactions on
page 290).

1.16.2.2

Using Authorization Reversal to Halt Recycling Engine

If you are using the Recycling Engine to optimize your authorizations and need to discontinue the
automatic recycling of the transaction, you use an Authorization Reversal transaction to halt the
retries. For example, if a customer cancels an order and the authorization for the order is being
retried by the Recycling Engine, you submit an Authorization Reversal transaction to halt the
automatic recycling of the authorization.
NOTE:

1.16.3

If the initial transaction you submitted is a Sale (conditional deposit)
rather than an Authorization, you use a Void transaction to halt the
recycling.

Activate Transaction

You use an Activate transaction to change the status of a (Closed Loop) Gift Card from an
inactive to an active state with a value as specified by the amount element. You can also use this
transaction type to create a Virtual Gift Card.

78

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Supported Transaction Types

1.16.4

Introduction

Activate Reversal Transaction (Online Only)

You use as Activate Reversal transaction to change the status of a newly activated (Closed Loop)
Gift Card from active to inactive, thus reversing the operation of an Active transaction. The
Activate Reversal references the associated Activate transaction by means of the litleTxnId
element returned in the Activate response.

1.16.5

Balance Inquiry Transaction

You use the Balance Inquiry transaction to determine the balance available for use on a (Closed
Loop) Gift Card.

1.16.6

Cancel Subscription Transaction

If you are using the Recurring Engine, you create Subscriptions as part of an Authorization or
Sale transaction. You use the Cancel Subscription transaction to cancel the specified subscription,
removing the transaction stream managed by the Recurring Engine.

1.16.7

Capture Transaction

You use a Capture transaction to transfer previously authorized funds from the customer to you
after order fulfillment. You can submit a Capture transaction for the full amount of the
Authorization, or for a lesser amount by setting the partial attribute to true.
NOTE:

If you settle in a currency other than US or Canada, you cannot use partial
captures.
For a Visa transaction, if you submit a Capture for an amount less than
the Authorized amount, Vantiv automatically issues a partial Authorization
Reversal for the balance of the Authorized amount.

Do not use a Capture transaction to capture funds on a (Closed Loop) Gift Card transaction; use a
Gift Card Capture instead (see Gift Card Capture Transactions on page 292).

1.16.8

Capture Given Auth Transaction

Similar to a Capture transaction, you use a Capture Given Auth transaction to transfer previously
authorized funds from the customer to you after fulfillment. However, you typically use a Capture
Given Auth transaction if the associated Authorization occurred outside of the system (for
example, if you received a telephone Authorization). Another possible use for a Capture Given
Auth transaction is if the Authorization transaction occurred within the system, but the
litletxnId is unknown by the submitting party (for example, if the Auth was submitted by a
merchant, but a fulfiller submits a Capture Given Auth).
Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

79

cnpAPI Reference Guide
Introduction

Supported Transaction Types

Whenever you submit a Capture Given Auth transaction, Vantiv attempts to match it to an
existing Authorization using COMAAR data (Card Number, Order Id, Merchant Id, Amount,
Approval Code, and (Auth) Response Date) in order to obtain a better Interchange rate for the
transaction. The application uses the following matching logic:
•

If the Order Id was either not submitted (blank, spaces, or null) or does not match any Auth in
the system, it is ignored and the matching attempt proceeds using the remaining COMAAR
data.

•

If the matching operation results in multiple possible matches, the application selects the
Authorization with the lowest amount that is greater than or equal to the Capture Given Auth
amount.
NOTE:

•

In all cases, the Authorization amount must always be greater than or
equal to the Capture Given Auth amount.

If necessary, the application further narrows the match candidates to the one with the most
recent response date.
NOTE:

If Vantiv is able to match the Capture Given Auth to an Authorization and
the following conditions are met: the card type is Visa and the Capture
Given Auth amount is less than the Authorization amount, then Vantiv will
issue an Auth Reversal transaction for the balance of the Authorization.
This is done to obtain the best possible interchange rates from Visa.

1.16.9

Create Plan Transaction

You use the Create Plan transaction to define several attributes of a recurring payment schedule.
Later, as part of an Authorization or sale transaction, you can associate existing, active plans with
Subscriptions. This association establishes a recurring payment schedule managed by the Vantiv
Recurring Engine.

1.16.10 Credit Transaction
You use a Credit transaction to refund money to a customer, even if the original transaction
occurred outside of the system. You can submit refunds against any of the following payment
transactions:

80

•

Capture Transaction

•

Capture Given Auth Transaction

•

Force Capture Transaction

•

Sale Transaction

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Supported Transaction Types

•

Introduction

External Sale or Capture
NOTE:

Vantiv recommends you send all Credit transactions in a Batch separate
from the associated Capture or Sale transactions.

1.16.11 Deactivate Transaction
You use a Deactivate transaction to change the status of a (Closed Loop) Gift Card from an active
to an inactive state.

1.16.12 Deactivate Reversal Transaction (Online Only)
You use a Deactivate Reversal transaction to change the status of a newly deactivated Gift Card
from inactive to active, thus reversing the operation of an Deactivate transaction. The Deactivate
Reversal references the associated Deactivate transaction by means of the litleTxnId element
returned in the Deactivate response.

1.16.13 Deposit Reversal Transaction (Online Only)
Used only for (Closed Loop) Gift Card related transactions, a Deposit Reversal transaction to
reverse the funds capture initiate by either a Capture or Sale transaction. The Deposit Reversal
references the associated Capture/Sale transaction by means of the litleTxnId element returned
in the Capture/Sale response. You should never attempt to use this transaction type to reverse
credit card or eCheck transactions.

1.16.14 eCheck Credit Transaction
Similar to a Credit transaction, you use an eCheck Credit transaction to refund money to a
customer, but only when the method of payment was an eCheck. You can submit an eCheck
Credit transaction regardless of whether the original transaction occurred in or out of the system.

1.16.15 eCheck Prenotification Credit Transaction
You use this non-monetary transaction to verify the consumer’s account information prior to
submitting an eCheck Credit transaction (also see eCheck Prenotification on page 49). This
transaction type is only supported for US transactions.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

81

cnpAPI Reference Guide
Introduction

Supported Transaction Types

1.16.16 eCheck Prenotification Sale Transaction
You use this non-monetary transaction to verify the consumer’s account information prior to
submitting an eCheck Sale transaction (also see eCheck Prenotification on page 49). This
transaction type is only supported for US transactions.

1.16.17 eCheck Redeposit Transaction
You use this transaction type to manually attempt redeposits of eChecks returned for either
Insufficient Funds or Uncollected Funds. You can use this element in either Online or Batch
transactions.
NOTE:

Do not use this transaction type if you are enabled for the Auto Redeposit
feature. If you are enabled for the Auto Redeposit feature, the system will
reject any echeckRedeposit transaction you submit.

1.16.18 eCheck Sales Transaction
You use an eCheck Sales transaction to transfer funds from the customer to you after order
fulfillment. It is the eCheck equivalent of a Capture transaction. Funding usually occurs within
two days. You can also submit this transaction type as a conditional capture, which makes the
processing of the deposit conditional upon a successful verification. If the verification fails, the
deposit is not processed.

1.16.19 eCheck Verification Transaction
You use an eCheck Verification transaction to initiate a comparison to a database containing
information about checking accounts. The database may include information as to whether the
account has been closed, as well as whether there is a history of undesirable behavior associated
with the account/account holder. This transaction type is only supported for US transactions.

1.16.20 eCheck Void Transaction (Online Only)
You use an eCheck Void transaction to either halt automatic redeposit attempts of eChecks
returned for either Insufficient Funds or Uncollected Funds, or cancel an eCheck Sale transaction,
as long as the transaction has not yet settled. This also applies to merchant initiated redeposits.
You can use this element only in Online transactions.

82

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Supported Transaction Types

Introduction

1.16.21 Force Capture Transaction
A Force Capture transaction is a Capture transaction used when you do not have a valid
Authorization for the order, but have fulfilled the order and wish to transfer funds.
CAUTION:

Merchants must be authorized by Vantiv before processing this
transaction. In some instances, using a Force Capture transaction can
lead to chargebacks and fines.

1.16.22 Gift Card Auth Reversal
You use the Gift Card Auth Reversal transaction to reverse an Authorization on a (Closed-loop)
Gift Card. This removes the hold on the previously authorized amount, freeing those funds for
additional purchases by the cardholder.

1.16.23 Gift Card Capture
You use the Gift Card Capture transaction to capture or deposit previously authorized funds on a
(Closed-loop) Gift Card.

1.16.24 Gift Card Credit
You use a Gift Card Credit transaction to refund money to a customer that used a (Closed Loop)
Gift Card for the purchase, even if Vantiv did not process the purchase. You have a choice of two
structures. You use the message type containing a transaction Id to apply a credit for a transaction
processed by Vantiv. You use the message type containing a order Id to apply a credit for a
transaction not processed by Vantiv.

1.16.25 Load Transaction
You use a Load transaction to add funds to an active Gift Card. The load amount cannot exceed
the maximum allowed amount for the Gift Card. If you attempt to load more than the maximum
amount, the transaction will be declined with a response Code of 221 - Over Max Balance.

1.16.26 Load Reversal Transaction (Online Only)
You use a Load Reversal transaction to reverse the operation of a Load transaction, removing the
newly loaded amount from the Gift Card. You cannot perform a partial Load Reversal. This
transaction always reverses the full amount of the referenced Load transaction.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

83

cnpAPI Reference Guide
Introduction

Supported Transaction Types

1.16.27 Refund Reversal Transaction (Online Only)
The Refund Reversal transaction is a (Closed Loop) Gift Card only transaction that reverses the
operation of a Refund transaction on the Gift Card. You cannot perform a partial Refund
Reversal. This transaction always reverses the full amount of the referenced Refund transaction.

1.16.28 Register Token Transaction
You use the Register Token transaction to submit a credit card number, eCheck account number,
or Registration Id to us and receive a token in return. While you can submit Register Token
transactions at any time, typically, you would make use of this transactions when initially
converting to the use of tokens. In this case you would submit large quantities of credit
cards/eCheck account numbers in Batches and replace them in your database with the tokens
returned.

1.16.29 Sale Transaction
The Sale transaction enables you to both authorize fund availability and deposit those funds by
means of a single transaction. The Sale transaction is also known as a conditional deposit,
because the deposit takes place only if the authorization succeeds. If the authorization is declined,
the deposit will not be processed.
NOTE:

If the authorization succeeds, the deposit will be processed automatically,
regardless of the AVS or CVV2 response.
To obtain better interchange rates, you should always perform an AVS
check either as a standalone transaction, or as part of the
Authorization/Sale transaction.

1.16.30 Status Query Transaction
The Status Query Transaction allows you to verify that an Online transaction submitted within the
prior 24 hours exists in the system. The response will be one of the following:
•

A single transaction matching the search criteria

•

Multiple transactions matching the search criteria

•

Empty results, if no transactions matched the criteria

•

A limited response, if a transaction was found, but processing was not complete

As search criteria, you must submit, at a minimum, the id (id attribute) and transaction type (i.e.,
authorization, deposit, void, etc.) of the original transaction, but to narrow the search, you can
also include the transaction id, order id, and the account number (credit, debit, or gift card) from

84

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Supported Transaction Types

Introduction

the original transaction. The response message contains one of four response codes, 150 through
153 (see Payment Transaction Response Codes on page 816), and the results for the search.
NOTE:

Use of this transaction type requires specific permissions. Please speak
to your Vantiv Implementation Consultant for additional information.

1.16.31 Unload Transaction
You use an Unload transaction to remove funds from an active Gift Card. The unload amount
cannot exceed the available balance on the Gift Card. If you attempt to unload more than the
available balance, the transaction will be declined with a response Code of 209 - Invalid Amount.

1.16.32 Unload Reversal Transaction (Online Only)
The Unload Reversal transaction reverses the operation of a Unload transaction, returning the
value removed from the Gift Card by the Unload transaction. You cannot perform a partial
Unload Reversal. This transaction always reverses the full amount of the referenced Unload
transaction.

1.16.33 Update Card Validation Number Transaction
When you submit the CVV2/CVC2/CID in a registerTokenRequest, the platform encrypts
and stores the value on a temporary basis for later use in a tokenized Auth/Sale transaction
submitted without the value. This is done to accommodate merchant systems/workflows where
the security code is available at the time of token registration, but not at the time of the Auth/Sale.
If for some reason you need to change the value of the security code supplied at the time of the
token registration, use an updateCardValidationNumOntoken transaction.

1.16.34 Update Plan Transaction
You use the Update Plan transaction to activate/deactivate Plans associated with recurring
payments. When you deactivate a Plan, by setting the active flag to false, you can no longer
reference that Plan for use with subscriptions. Existing subscriptions already using the deactivated
Plan will continue to use the Plan until the subscription is either modified or completed. You can
also reactivate a deactivated Plan by updating the Plan and setting the active flag to true.

1.16.35 Update Subscription Transaction
You use an Update Subscription transaction to change certain subscription information associated
with a recurring payment. Using this transaction type you can change the plan, card, billing

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

85

cnpAPI Reference Guide
Introduction

Supported Transaction Types

information, and/or billing date. You can also create, update, or delete a Discount and/or an Add
On.

1.16.36 Void Transaction (Online Only)
The Void transaction enables you to cancel any settlement transaction as long as the transaction
has not yet settled and the original transaction occurred within the system (Voids require a
reference to a litleTxnId).
NOTE:

Do not use Void transactions to void an Authorization. To remove an
Authorization use an Authorization reversal transaction (see
Authorization Reversal Transactions on page 76.)

1.16.36.1 Using Void to Halt Recycling Engine
If you use Recovery or the Recycling Engine service and use Sale transactions (conditional
deposits) to authorize and capture the funds, you must use a Void transaction to discontinue the
automatic recycling of the transaction should the need arise. For example, if a customer cancels
an order and the Sale transaction is being retried by the Recycling Engine, you submit a Void
transaction to halt the automatic recycling of the transaction.
NOTE:

If the initial transaction you submitted is an Authorization rather than an
Sale, you use an Authorization Reversal transaction to halt the recycling.

When using a Void transaction to halt recycling, there is a possibility that the recycled transaction
has already been approved and captured. If this condition occurs, depending upon your
configuration, the system takes one of two actions:
•

If you are not configured for the Automatic Refund option (default = disabled), the system
declines the Void transaction. You must issue the Credit transaction to refund the money to
the consumer. The daily Recycling file will include the approved/captured transaction.

•

If you are configured for the Automatic Refund option, the system issues a Credit transaction
on your behalf. The system returns the transaction Id for the Credit transaction in the Void
response message (creditLitleTnxId element). The daily Recycling file will include the
approved/captured transaction only if the file was generated prior to the system receiving the
Void and issuing the automatic refund.

1.16.37 Instruction-Based Dynamic Payout Transactions
If you are a PayFac using the Instruction-Based Dynamic Payout model, there are a number of
Batch only transaction types you use to move funds between various accounts, including funding

86

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Supported Transaction Types

Introduction

Sub-merchants. This section provides information about these transaction types. For additional
information, please refer to the Appendix D, "PayFac™ Dynamic Payout".
•

Funding Instruction Void - You use this transaction type to void a submitted funding
instruction. You must submit the void prior to your daily cutoff time for an instruction not yet
processed.

•

PayFac Credit Transaction - You use this transaction type to move funds from the PayFac
Settlement Account to your Operating Account.

•

PayFac Debit Transaction - You use this transaction type to move funds from your
Operating Account to the PayFac Settlement Account.

•

Physical Check Credit - You use this transaction type to move funds from the PayFac
Settlement Account to the account of a third party that issues physical checks on your behalf.

•

Physical Check Debit - You use this transaction type to move funds from the physical check
issuer’s Account to the PayFac Settlement Account.

•

Reserve Credit Transaction - You use this transaction type to move funds from the PayFac
Settlement Account to the Reserve Account.

•

Reserve Debit Transaction - You use this transaction type to move funds from the Reserve
Account to the PayFac Settlement Account.

•

Sub-merchant Credit Transaction - You use this transaction type to move funds from the
PayFac Settlement Account to the Sub-merchant Account, funding the Sub-merchant.

•

Sub-merchant Debit Transaction - You use this transaction type to move funds from the
Sub-merchant Account to the PayFac Settlement Account.

•

Vendor Credit - You use this transaction type to move funds from the PayFac Settlement
Account to the account of a third party involved in the sale transactions, but are not the
sub-merchant.

•

Vendor Debit - You use this transaction type to move funds from the Vendor Account to the
PayFac Settlement Account.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

87

cnpAPI Reference Guide
Introduction

88

Supported Transaction Types

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

2
TESTING YOUR CNPAPI TRANSACTIONS
The information provided in this chapter enables you to test and verify that your submitted
transaction data conforms to the required cnpAPI schema. This chapter contains the following
topics:
•

Certification and Testing Environments

•

Overview of Testing

•

Transferring Files

•

Performing the Required Certification Tests

•

Performing the Optional Tests
IMPORTANT: Per PCI DSS Requirements and Security Assessment Procedure, Section
6.4.3, "Production data (live PANs) are not used for testing or
development."

NOTE:

This chapter does not include Certification tests for the PayFac
Instruction-Based Dynamic Payout transaction types. Additional
information about these transactions, as well as the Certification tests are
in Appendix D, "PayFac™ Dynamic Payout".

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

89

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.1

Certification and Testing Environments

Certification and Testing Environments
Vantiv has several testing and certification platforms optimized for different uses. These
environments are called: Sandbox, Pre-Live, and Post-Live. This section discusses the various
environments, their uses, and limitations. The certification and testing environments do not have
the full capacity, performance, or availability of the Vantiv Production platform.

2.1.1

Sandbox Environment

The Sandbox environment is a simulator that provides a basic interface for functional level testing
of transaction messages. Typically, merchants using one of the available Software Development
Kits (SDKs) would use the Sandbox to test basic functionality, but it could also be used by any
merchant using cnpAPI. This is a stateless simulator, so it has no historical transactional data, and
does not provide full functionality. This environment is not intended for certification or regression
testing.
NOTE:

At his time, the Sandbox does not support Batch transactions (Online
transactions only).

Use of the Sandbox does not require a password. The environment is available on the public
internet (at www.testvantivcnp.com/sandbox/communicator/online). Supporting documentation,
including test case documentation, is available at vantiv-ecommerce.github.io/sandbox.

2.1.2

Pre-Live Environment

The Pre-Live test environment is the platform used for all merchant Certification testing. This
environment should be used by both newly on-boarding Vantiv merchants (for example, coding a
direct XML integration for the first time), and existing Vantiv merchants seeking to incorporate
additional features or functionalities into their current XML integrations. While the Pre-Live
system provides a working version of the Vantiv production system, it does not have the full
capacity or performance of the production platform and operates using simulators rather than
communicating with the card associations.
The Pre-Live environment provides for the self-provisioning of a basic test account via
www.testvantivcnp.com/sandbox. Using this account, you can submit most standard transaction
types, including those specified in the Certification test sections provided later in this chapter.
You will not be able to test many of the Vantiv eCommerce Value Added Services (VAS) using
this basic account. To add the capability to perform test scenarios for the VAS services, please
contact a Vantiv Implementation Consultant. They will adjust the configuration of your test
account to enable the additional, desired features.

90

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Certification and Testing Environments

2.1.2.1

Testing Your cnpAPI Transactions

Pre-Live Environment Limitations and Maintenance Schedules

When using the Pre-Live environment for testing, please keep in mind the following limitations
and maintenance schedules:
•

The number of merchants configured per organization will be limited to the number necessary
to perform the required certification testing.

•

Data retention is limited to a maximum of 30 days.

NOTE:

Depending upon overall system capacity and/or system maintenance
requirements, data purges may occur frequently. Whenever possible, we will
provide advanced notification.

•

Merchant profile and data deleted after 7 consecutive days with no activity.

•

Maintenance window - each Tuesday and Thursday from 4:00-8:00 AM ET.

•

Maintenance window (Enterprise eProtect) - every other Thursday from 10:00 PM to 6:00
AM ET.

•

Daily limit of 1000 Online transactions.

•

Daily limit of 10000 Batch transactions.

NOTE:

2.1.3

Due to the planned maintenance windows, you should not use this
environment for continuous regression testing.

Post-Live Environment

The Post-Live testing environment is intended for merchants that are already fully certified and
submitting transactions to the Vantiv production platform, but wish to perform regression or other
tests to confirm the operational readiness of modifications to their own systems. Upon completion
of the initial certification and on-boarding process, Vantiv migrates merchants that are
Production-enabled to the Post-Live environment for any on-going testing needs.
In Post-Live, the merchant profile matches your profile from the Vantiv Production environment.
Similar to Pre-Live, the Post-Live system provides a working version of the Vantiv production
system, but it does not have the full capacity or performance of the production platform and
operates using simulators rather than communicating with the card associations. Unlike the
Pre-live platform, all Merchant accounts/IDs are synchronized with the Vantiv production
environment.

2.1.3.1

Post-Live Environment Limitations and Maintenance Schedules

When using the Post-Live environment for testing, please keep in mind the following limitations
and maintenance schedules:

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

91

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Certification and Testing Environments

•

Daily limit of 1000 Online transactions.

•

Daily limit of 10000 Batch transactions.

•

Maintenance window - each Tuesday and Thursday from 4:00-8:00 AM ET.

•

Data retention limited to a maximum of 30 days.

NOTE:

Depending upon overall system capacity and/or system maintenance
requirements, data purges may occur frequently. Whenever possible, Vantiv
will provide advanced notification.
Also, due to the planned maintenance windows, you should not use this
environment for continuous regression testing.

92

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Overview of Testing

2.2

Testing Your cnpAPI Transactions

Overview of Testing
The purpose of the testing and certification process is to verify that your order entry and
supporting systems construct and send XML messages that comply with the cnpAPI
requirements. The testing process involves submitting Vantiv supplied data for specific fields in a
request, and receiving specific data back in a response. The response returned by Vantiv allows
you to verify that you parse the cnpAPI response file correctly.
Various tables in this chapter provide the data you use while testing, including card numbers,
expiration dates, transaction amounts, and other values as required by the testing process. You use
this data as input to your systems resulting in structured requests that conform to the required
cnpAPI schema.
IMPORTANT: The test data supplied does not necessarily account for all data fields/xml
elements in a particular request. Where test data is not supplied, you
should provide appropriate information. You should never override your
own system to enter supplied data. If you are unable to enter the supplied
data without overriding your system, please consult your Implementation
Consultant concerning the test and how to proceed.

Typically, Vantiv assigns an Implementation Consultant to work with you after the completion of
contract negotiations. Before you begin the testing phase, your assigned Implementation
Consultant establishes a test account and supplies you with instruction for accessing the account
along with the username and password. You must supply the IP address from which the data
originates so we can grant access.
NOTE:

Until you complete all required testing, you will only have access to the
test and certification environment.

The testing process involves the following steps:

2.2.1

Planning for Certification Testing

Before you begin testing, determine which transaction types you will use according to your
business needs. Virtually everyone will make use of the following basic transaction types:
Authorization, Capture, Sale, Credit, and Void. There are several other transaction types and most
transaction types offer many options/optional fields that you may wish to utilize and therefore
test. For example, if you decide to offer eChecks as a alternate payment method, there are several
associated certification tested required. Similarly, if you elect to make use of the Insights feature
set, there are additional Authorization tests required for certification.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

93

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

NOTE:

Overview of Testing

For information about certification testing for PayPal, eProtect,
Chargeback API, and the PayFac API, please refer to the following
documents:

– Vantiv PayPal Integration Guide
– Vantiv eProtect Integration Guide
– Vantiv Chargeback API Reference Guide
– Vantiv PayFac API Reference Guide

2.2.2

Required Certification Testing

Certification testing is a required phase of implementing the cnpAPI format. During the
certification testing, a Vantiv Implementation Consultant works with you to verify that your
transaction submissions meet the requirements of the cnpAPI specifications. Each transaction
type has specific test scenarios that use specific data sets simulating real transactions. The Vantiv
Certification environment responds to each submission with an XML response message, allowing
you to verify that you have coded correctly to parse and store the transaction data returned to you.
For more detailed information, see Performing the Required Certification Tests on page 103.

2.2.3

Optional Testing

Vantiv provides you with test data, test scenarios, a test environment, and credentials for using
that test environment so you can perform these tests on your own keeping in mind the limitations
of the certification environment (see Certification and Testing Environments on page 90). During
unattended testing, you use these resources to perform all of the tests that apply to your business
needs.
NOTE:

2.2.4

If you have questions or need assistance while performing unattended
testing, feel free to call your assigned Implementation Consultant or email
implementation@vantiv.com.

System Doctor

The System Doctor is a tool you can use to both verify the operation of the Pre-Live environment
and to verify operation and message structures of individual certification tests. Every 30 minutes
the System Doctor runs each certification test specified in this chapter, except the Recycling and
Recurring tests. You access the System Doctor through the Pre-Live iQ (Operations>System
Doctor).

94

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Overview of Testing

FIGURE 2-1

Testing Your cnpAPI Transactions

System Doctor

As shown in Figure 2-1, the system displays an overall assessment of the system status in the top
panel and the results from each test set in the Test Execution History section (bottom panel). The
center panel has a list of all individual tests by Order Id (pull-down), which you can filter by
clicking on or more of the Search Tag buttons. Selecting one of the Order Ids from the list
displays the XML request and response for that test (see Figure 2-2). You can also display the
XML request and response information by selecting a test run from the Test Execution History
and then selecting an individual test from the expanded list.
NOTE:

The search tags filter the Order Ids shown in the selection pull-down, but
do so in an ORed manner. For example, if you select the Visa Filter and
the Prepaid Filter, the pull-down displays Order Ids for tests that either
use a Visa card OR a Prepaid card, rather than tests for a Prepaid Visa
card.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

95

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

FIGURE 2-2

Overview of Testing

XML Request and Response Messages

If one of your certification tests did not yield the expected results, you can use the System Doctor
to determine if the test is performing as expected in the environment and if there is a discrepancy
between your submitted XML and the XML message used in the automated test. If the test failed
in the last automated run, you will know that there is a system issue and can contact your
Implementation Consultant to determine when it will be resolved. If the test passed in the
automated run, you can compare the automated XML message to your submission to determine
why you are not receiving the expected results.

96

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transferring Files

2.3

Testing Your cnpAPI Transactions

Transferring Files
As discussed in Communications Protocols on page 2, there are several protocols you can use to
submit your transactions to Vantiv for processing. This section provides additional information
concerning the recommended methods for transferring your cnpAPI Batch and Online transaction
files.

2.3.1

Transferring Session Files

This section describes how to FTP your files (not test system specific) and includes the following
topics:
•

Submitting a Session File for Processing

•

Retrieving Processed Session Files
NOTE:

2.3.1.1

Before you begin transferring files via FTP, Vantiv provides the FTP Host
and a username/password for the Vantiv test system.

Submitting a Session File for Processing

CAUTION:

When submitting a file via FTP/sFTP, verify that the file permission is set
to 664.
Also, file naming conventions are crucial to the file submission process.
Incorrect file names will prevent the file from being processed or may
stop processing due to an incomplete file transfer.
Do not append .asc to the end of the filename (Step 3). You must replace
the .prg extension with .asc. If .prg appears in the filename, the system
will not process the file.

1. On your local system, add the extension .prg (lowercase) to the name of the file you want to
submit. For example, you could name the file MerchantName_YYMMDD.prg. Keep in mind
the following rules:
• Spaces are not allowed in the file name
• The .prg extension must be lower case
2. Open your FTP connection to the Vantiv inbound directory and move your file to the Vantiv
directory.
3. After the FTP process completes, change the extension of the transmitted file (in the Vantiv
inbound directory) from .prg to .asc (lowercase). Also, change the file permission to 664. the
The system polls the directory for files with an .asc extension every thirty seconds. When the
system encounters files with the proper extension, it retrieves them for processing.
Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

97

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.3.1.2

Transferring Files

Retrieving Processed Session Files

Depending on the size of your file, your response should be ready within a few minutes. Batches
containing large number of transactions take longer. For example, a batch of 10,000 transactions
may require as long as ten minutes to process.
The initial response represents an acknowledgment that we received the transactions and
notification that we will deliver them upstream to Visa and/or MasterCard for review. Since we
perform validation operations against the credit card number and the expiration date, you may
also receive a decline responses containing the appropriate response code.
To retrieve response files from the outbound directory:
NOTE:

Vantiv removes response files from the outbound directory after 24 hours.
Plan to retrieve your files daily.

1. Open your FTP connection to the Vantiv outbound directory.
2. Locate the response file, which will have the same name as the file you submitted. If the
response file has a .prg extension, it is still transferring. The extension changes to .asc when
the transfer to the outbound directory completes.
3. Retrieve the response file.

2.3.2

Transferring Online Files

The recommended method for submitting Online transactions is via HTTPS POST. The sections
that follow provide examples of ASP and Java programming methods for submitting your data
using HTTPS POST.
•

ASP Programming Example

•

Java Programming Example

•

Helpful Web Sites
NOTE:

98

Before you begin testing, Vantiv provides the test system URL, a
username/password, and any additional information required to test your
XML transactions.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transferring Files

2.3.2.1

Testing Your cnpAPI Transactions

ASP Programming Example

The following code is an example of a cnpAPI Authorization transaction submitted via HTTPS
Post using ASP.
Dim xml
Dim strXML
strXML = strXML & ""
strXML = strXML & ""
strXML = strXML & "USERNAME"
strXML = strXML & "########"
strXML = strXML & ""
strXML = strXML & ""
strXML = strXML & "3235059"
strXML = strXML & "54399"
strXML = strXML & "ecommerce"
strXML = strXML & ""
strXML = strXML & "Todd Wilson"
strXML = strXML & "123 Blue
Street"
strXML = strXML & "Suite 108"
strXML = strXML & "Address Line 3"
strXML = strXML & "Lowell"
strXML = strXML & "MA"
strXML = strXML & "01851"
strXML = strXML & "USA"
strXML = strXML & "twilson@email.com"
strXML = strXML & "323-222-2222"
strXML = strXML & ""
strXML = strXML & ""
strXML = strXML & "VI"
strXML = strXML & "#############"
strXML = strXML & "0521"
strXML = strXML & "###"
strXML = strXML & ""

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

99

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Transferring Files

strXML = strXML & ""
strXML = strXML & ""
set xml = CreateObject("Microsoft.XMLHTTP")
xml.setRequestHeader "Content-type", "text/html; charset=UTF-8"
xml.Open "POST", "https://site.info.com/from_Litle", False
xml.Send strXML
Response.write (xml.responseText)
set xml = Nothing

2.3.2.2

Java Programming Example

The following is an example of Java code used for HTTPS Post.
PostMethod and HttpClient are both part of the Apache HttpClient
library located at http://jakarta.apache.org/commons/httpclient/.

PostMethod post = new PostMethod(url); // url = fully qualified url
of the server to which you are posting
post.setRequestHeader("Content-type", "text/html; charset=UTF-8");
post.setRequestBody(data); //data = request data in XML format

HttpClient client = new HttpClient();
client.setTimeout(10000); //10 second timeout (in milliseconds) is
suggested minimum, 30 second recommended for alternate payment
methods
client.executeMethod(post);

String response = post.getResponseBodyAsString();

//if the server throws an exception you get a null response
//to get around this set it to ""
if (response == null) {
response = "";
}
post.releaseConnection();

100

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transferring Files

2.3.2.3

Testing Your cnpAPI Transactions

Notes on Timeout Settings

While Vantiv optimizes our systems to ensure the return of Authorization responses as quickly as
possible, some portions of the process are beyond our control. The round-trip time of an
Authorization can be broken down into three parts, as follows:
1. Transmission time (across the internet) to Vantiv and back to the merchant
2. Processing time by the card association or authorization provider
3. Processing time Vantiv
Under normal operating circumstances, the transmission time to and from Vantiv does not exceed
0.6 seconds and processing time by Vantiv occurs in 0.1 seconds. Typically, the processing time
by the card association or authorization provider can take between 0.5 and 3 seconds, but some
percentage of transactions may take significantly longer.
Because the total processing time can vary due to a number of factors, Vantiv recommends using
a timeout setting of 10 seconds minimum for card transactions and 30 seconds minimum for
alternate payment methods. These settings should ensure that you do not frequently disconnect
prior to receiving a valid authorization causing dropped orders and/or re-auths and duplicate
auths.
NOTE:

While it is uncommon, under certain circumstances network latency may
cause a duplicate Online Sale transaction to go undetected as a duplicate.
This can occur if you submit a second, duplicate Sale transaction while
the response from the network for the Authorization portion of the first
transaction is sufficiently delayed such that the first Sale has not been
recorded as a valid transaction in the system.
If you elect to submit Online Sale transactions, Vantiv recommends a
timeout setting of not less than 60 seconds to reduce the chances of
undetected duplicate Sale transactions.

2.3.2.4

Notes on Persistent Connections

In order to provide a highly scalable service that meets the needs of high-throughput merchants,
while reducing the number of idle connections that could result in some merchants exceeding
their connection limits, Vantiv systems allow for 10 seconds of idle time before closing a
connection. We selected this value because it is the midpoint between the Apache httpd 2.0
default value of 15 seconds and the Apache 2.2 default value of 5 seconds. Also, HTTP/1.1,
which most modern HTTP client libraries use, employ persistent connections by default. When
using a persistent connection, please keep the 10 second idle time limit in mind, when coding. If
you do not use persistent connections, to avoid connection limit issues, please validate that your
default configuration closes connections after each request.
NOTE:

Proper use of persistent connections is considerably faster than opening
and closing connections with each request.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

101

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.3.2.5

Transferring Files

Helpful Web Sites

The following web sites provide additional information, helpful hints, and examples of different
programming methods used in combination with HTTPS POST.

102

•

http://p2p.wrox.com

•

http://en.allexperts.com/q/Active-Server-Pages-1452/XML-ASP-Parser-2.htm

•

http://www.java-samples.com/java/POST-toHTTPS-url-free-java-sample-program.htm

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

2.4

Testing Your cnpAPI Transactions

Performing the Required Certification Tests
You are required to complete a number of certification tests prior to submitting real transactions
to the Vantiv production system. This testing process allows you to verify that your system not
only submits correctly formatted transaction data, but also correctly parses the data returned to
you in the response messages. To facilitate the certification process, Vantiv has established a
certification environment that simulates the production environment.
IMPORTANT: To determine the final status and response Code of a declined or
duplicate transactions, please refer to the Declined Transaction Report in
Vantiv iQ. Once in the production environment, you can also obtain this
daily report via Secure Scheduled Reports.

During certification testing, a Vantiv Implementation Consultant will guide you through each
required test scenario. For each transaction type specific data is supplied that you must use in
your cnpAPI transactions. Use of this data allows the validation of your transaction
structure/syntax, as well as the return of a response file containing known data.
NOTE:

The test data supplied does not account for all data fields/xml elements in
a particular request. Where data is not supplied, you should provide
appropriate information. You should never override your own system to
enter supplied data. If you are unable to enter the supplied data without
overriding your system, please consult your Implementation Consultant
concerning the test and how to proceed.
Never use the supplied test data in the production environment.

2.4.1

Testing Authorization (including Indicators), AVS Only,
Capture, Credit, Sale, and Void Transactions
NOTE:

To test your handling of 2-series (BIN) number for MasterCard, you can
substitute a 2-series test card number (see Appendix C, "Test Card
Numbers") in any Auth/Sale test and you will receive a 000 - Approved
Response Code in the response message.

Table 2-1 provides 26 data sets you use to test your construction of Authorization, AVS Only,
Sale and Force Capture transactions, as well as your ability to parse the information contained in
the XML response messages. You also use some of the approved authorizations as the basis for
testing Capture and Credit transactions.
You do not necessarily have to perform all Authorization test. The tests you perform depend upon
the Vantiv features you have elected to use. The tests are divided as follows:

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

103

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Required Certification Tests

•

Order Ids 1 through 9 - used to test standard Authorization requests and responses. Also used
for AVS Only test and Sale test. (Capture test use the litleTxnId returned in the response
messages.)

•

Order Ids 10 through 13 - include if you plan to use Partial Authorization

•

Order Ids 14 and 20 - include if you plan to use the Prepaid Indicator feature (see Prepaid
Indicator on page 24)

•

Order Ids 21 through 24 - include if you plan to use the Affluence Indicator feature (see
Affluence Indicator on page 25)

•

Order Id 25 - include if you plan to use the Issuer Country feature (see Issuer Country
Indicator on page 26)

To test Authorization transactions:
1. Verify that your Authorization XML template is coded correctly (refer to Authorization
Transactions on page 208.)
2. Submit authorization transactions using the data shown in the Supplied Data Elements of
Order Ids 1 through 9 of Table 2-1.
3. Verify that your response values match those shown in Key Response Elements for Order Ids
1 through 9 as shown in Table 2-1.
4. If you wish to test AVS only transactions, re-submit Order Ids 1 through 5, 7, 8, and 9 (skip
order 6), but substitute 000 for the amount. The AVS result returned will be the value shown
in the Key Response Elements section.
5. If you plan to use Partial Authorizations, submit authorization transactions using the
data shown in the Supplied Data Elements of Order Ids 10 through 13 of Table 2-1.
6. Verify that your response values match those shown in Key Response Elements for Order Ids
10 through 13 as shown in Table 2-1.
7. If you elected to receive Prepaid Indicators, submit authorization transactions using the
data shown in the Supplied Data Elements of Order Ids 14 through 20 of Table 2-1. Verify
that your response values match those shown in Key Response Elements for Order Ids 14 and
15 as shown in Table 2-1.
8. If you elected to receive Affluence Indicators, submit authorization transactions using
the data shown in the Supplied Data Elements of Order Ids 21through 24 of Table 2-1. Verify
that your response values match those shown in Key Response Elements for Order Ids 16
through 19 as shown in Table 2-1.
9. If you elected to receive Issuer Country information, submit an authorization
transaction using the data shown in the Supplied Data Elements of Order Id 25 of Table 2-1.
Verify that your response values match those shown in Key Response Elements for Order Id
25 as shown in Table 2-1.
NOTE:

104

Some Issuers do not return an Auth Code for $0 Authorizations. You
should code your systems to handle this possibility.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

Testing Your cnpAPI Transactions

To Test Sale transactions:
1. Verify that your Sale XML template is coded correctly (refer to Sale Transactions on page
314.)
2. Submit sale transactions using the data shown in the Supplied Data Elements of Order Ids 1
through 9 of Table 2-1.
3. Verify that your response values match those shown in Key Response Elements for Order Ids
1 through 9 as shown in Table 2-1.
To Test Capture transactions:
1. Verify that your Capture XML template is coded correctly (refer to Capture Transactions on
page 231.).
2. Submit capture transactions for Order Ids 1A through 5A using the litleTnxId value
returned in the response messages for Authorization Order Ids 1 through 5.
3. Verify that your response values match those shown in Key Response Elements for Order Ids
1A through 5A as shown in Table 2-1.
To test Credit transactions:
1. Verify that your Credit XML template is coded correctly (refer to Credit Transactions on page
247.)
2. Submit credit transactions for Order Ids 1B through 5B using the litleTnxId value
returned in the response messages for Capture Order Ids 1A through 5A.
3. Verify that your response values match those shown in Key Response Elements for Order Ids
1B through 5B as shown in Table 2-1.
To test Void transactions (in this test you have the option of voiding either Credit or Sale
transactions):
1. Verify that your Void XML template is coded correctly (refer to Void Transactions (Online
Only) on page 334.)
2. Submit void transactions for Order Ids 1C through 5C (and 6Bif voiding Sale transactions)
using the litleTnxId value returned in either the response messages for Credit Order Ids
1B through 5B, or the response messages for Sale (not Auth) Order Id 1 through 6.
3. Verify that your response values match those shown in Key Response Elements for Order Ids
1C through 5C (include 6B only if you elect to void the Sales transactions) as shown in
Table 2-1.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

105

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-1

Performing the Required Certification Tests

Authorization Test Data
Supplied Data Elements

orderId
1

Element

Key Response Elements

Value

Authorization/Sale/AVS:

Element
Authorization Response:
 000

 10100

 Approved

 John & Mary Smith

 11111

 1 Main St.

 01

 Burlington
 MA

Value

 M

 01803-3747
 US
 VI
 4457010000000009
 0121
 349
1A

Capture Response:

Capture:

 000

 Value returned in
Auth response for
Order Id 1
1B

 Approved
Credit Response:

Credit:

 000

 Value returned in
Capture response
for Order Id 1A
1C

 Approved
Void Response:

Void:

 000

 Use either the value
returned in the
Credit response for
Order Id 1B, or the
value returned in
the Sale response
(not Auth) for Order
Id 1.

106

 Approved

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-1

Testing Your cnpAPI Transactions

Authorization Test Data (Continued)
Supplied Data Elements

orderId
2

Element

Key Response Elements

Value

Authorization/Sale/AVS:

Element
Authorization Response:

 10100

 000

 Mike J. Hammer

 Approved

 2 Main St.

 22222

 Apt. 222

 10

 Riverside
 RI
 02915

Value

 M
 Note: Not returned
for MasterCard

 US
 MC
 5112010000000003
 0221
 261
 BwABBJQ1AgAAA
AAgJDUCAAAAAA
A=
2A

Capture Response:

Capture:

 000

 Value returned in
Auth response for
Order Id 2
2B

 Approved
Credit Response:

Credit:

 000

 Value returned in
Capture response
for Order Id 2A
2C

 Approved
Void Response:

Void:
 Use either the value
returned in the
Credit response for
Order Id 2B, or the
value returned in
the Sale response
(not Auth) for Order
Id 2.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

 000
 Approved

107

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-1

Performing the Required Certification Tests

Authorization Test Data (Continued)
Supplied Data Elements

orderId
3

Element

Key Response Elements

Value

Authorization/Sale/AVS:

Element
Authorization Response:
 000

 10100

 Approved

 Eileen Jones

 33333

 3 Main St.

 10

 Bloomfield
 CT

Value

 M

 06002
 US
 DI
 6011010000000003
 0321
 758
3A

Capture Response:

Capture:

 000

 Value returned in
Auth response for
Order Id 3
3B

 Approved
Credit Response:

Credit:

 000

 Value returned in
Capture response
for Order Id 3A
3C

 Approved
Void Response:

Void:

 000

 Use either the value
returned in the
Credit response for
Order Id 3B, or the
value returned in
the Sale response
(not Auth) for Order
Id 3.

108

 Approved

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-1

Testing Your cnpAPI Transactions

Authorization Test Data (Continued)
Supplied Data Elements

orderId
4

Element

Key Response Elements

Value

Authorization/Sale/AVS:

Element

Value

Authorization Response:
 000

 10100

 Approved

 Bob Black

 44444

 4 Main St.

 13

 Laurel
 MD
 20708
 US
 AX
 375001000000005
 0421
4A

Capture Response:

Capture:

 000

 Value returned in
Auth response for
Order Id 4
4B

 Approved
Credit Response:

Credit:

 000

 Value returned in
Capture response
for Order Id 4A
4C

 Approved
Void Response:

Void:
 Use either the value
returned in the
Credit response for
Order Id 4B, or the
value returned in
the Sale response
(not Auth) for Order
Id 4.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

 000
 Approved

109

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-1

Performing the Required Certification Tests

Authorization Test Data (Continued)
Supplied Data Elements

orderId
5

Element

Key Response Elements

Value

Authorization/Sale/AVS:

Element
Authorization Response:

 10100

 000

 VI

 Approved

 4100200300011001

 55555
 32

 0521
 463

Value

 M

 BwABBJQ1AgAAA
AAgJDUCAAAAAA
A=
5A

Capture Response:

Capture:

 000

 Value returned in
Auth response for
Order Id 5
5B

 Approved
Credit Response:

Credit:

 000

 Value returned in
Capture response
for Order Id 5A
5C

 Approved
Void Response:

Void:

 000

 Use either the value
returned in the
Credit response for
Order Id 5B, or the
value returned in
the Sale response
(not Auth) for Order
Id 5.

110

 Approved

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-1

Testing Your cnpAPI Transactions

Authorization Test Data (Continued)
Supplied Data Elements

orderId
6

Element

Key Response Elements

Value

Element

Value

Authorization Response:

Authorization/Sale:

 110

 10100

 Insufficient Funds

 Joe Green

 34

 6 Main St.
 Derry

 P

 NH
 03038
 US
 VI
 4457010100000008
 0621
 992
6A

Void Response:

Void:

 000

 Use the value
returned in the Sale
response (not Auth)
for Order Id 6.

 Approved
Declined Transaction report
result = 360 - No
transaction found with
specified litleTxnId

7

Authorization/Sale/AVS:

Authorization Response:
 301

 10100

Invalid Account
 Number

 Jane Murray
 7 Main St.

 34

 Amesbury
 MA

 N

 01913
 US
 MC
 5112010100000002
 0721
 251

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

111

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-1

Performing the Required Certification Tests

Authorization Test Data (Continued)
Supplied Data Elements

orderId
8

Element

Key Response Elements

Value

Authorization/Sale/AVS:

Element
Authorization Response:
 123

 10100

 Call Discover

 Mark Johnson

 34

 8 Main St.
 Manchester

Value

 P

 NH
 03101
 US
 DI
 6011010100000002
 0821
 184
9

Authorization/Sale/AVS:

Authorization Response:
 303

 10100

 Pick Up Card

 James Miller

 34

 9 Main St.
 Boston

 P

 MA
 02134
 US
 AX
 375001010000003
 0921
 0421
NOTE:

10

The data sets for orderId 10 through 13 are designed to test Authorization transactions
resulting in partial authorizations. If you are not coding to use partial authorizations, you
may skip these tests.
 010

 40000

 Partially Approved

 VI
 4457010140000141

 32000

 0921
 true

112

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-1

Testing Your cnpAPI Transactions

Authorization Test Data (Continued)
Supplied Data Elements

orderId
11

Element

Key Response Elements

Value

Element
 010

 60000

 Partially Approved

 MC
 5112010140000004

Value

 48000

 1121
 true
12

 010

 50000

 Partially Approved

 AX
 375001014000009

 40000

 0421
 true
13

 010

 15000

 Partially Approved

 DI
 6011010140000004

 12000

 0821
 true
NOTE:

14

The data sets for orderId 14 through 20 are designed to test Authorization transactions
that return Prepaid Indicator information in the response message. If you are not coding
to use the optional Prepaid Indicator feature of the Insights feature set, you may skip
these tests.
 000

 10100

 Approved

 VI

 PREPAID

 4457010200000247
 0821

 2000
 NO
 GIFT

15

 000

 10100

 Approved

 MC

 PREPAID

 5500000254444445
 0321

 2000
 YES
 PAYROLL

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

113

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-1

Performing the Required Certification Tests

Authorization Test Data (Continued)
Supplied Data Elements

orderId
16

Element

Key Response Elements

Value

Element
 000

 10100

 Approved

 MC

 PREPAID

 5592106621450897
 0321

Value

 0
 YES
 PAYROLL

17

 000

 10100

 Approved

 MC

 PREPAID

 5590409551104142
 0321

 6500
 YES
 PAYROLL

18

 000

 10100

 Approved

 MC

 PREPAID

 5587755665222179
 0321

 12200
 YES
 PAYROLL

19

 000

 10100

 Approved

 MC

 PREPAID

 5445840176552850
 0321

 20000
 YES
 PAYROLL

20

 000

 10100

 Approved

 MC

 PREPAID

 5390016478904678
 0321

 10050
 YES
 PAYROLL

114

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-1

Testing Your cnpAPI Transactions

Authorization Test Data (Continued)
Supplied Data Elements

orderId
NOTE:

21

Element

Value

Key Response Elements
Element

Value

The data sets for orderId 21 through 24 are designed to test Authorization transactions
that return Affluence Indicator information in the response message. If you are not
coding to use the optional Affluence Indicator feature of the Insights feature set, you
may skip these tests.
 10100
 VI
 4100200300012009

 000
 Approved
 AFFLUENT

 0921
22

 10100
 VI
 4100200300013007

 000
 Approved
 MASS AFFLUENT

 1121
23

 10100
 MC
 5112010201000109

 000
 Approved
 AFFLUENT

 0421
24

 10100
 MC
 5112010202000108

 000
 Approved
 MASS AFFLUENT

 0821
NOTE:

25

The data set for orderId 25 is designed to test Authorization transactions that return
Issuer Country information in the response message. If you are not coding to use the
optional Issuer Country feature of the Insights feature set, you may skip these tests.
 10100
 VI
 4100200310000002

 000
 Approved
 BRA

 1121

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

115

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.4.2

Performing the Required Certification Tests

Testing Authorization Reversal Transactions

If you plan to use Authorization Reversal Transactions, you must perform this test. If you do not
plan to use Authorization Reversal transactions, skip this test and go to Testing eCheck
Transactions on page 119.
To test Authorization Reversal Transactions:
1. Verify that your Authorization Reversal XML templates are coded correctly (refer to
Authorization Reversal Transactions on page 220).
2. Submit the Authorizations, Captures (if applicable), and Authorization Reversal Transactions
using the orders shown in Table 2-2.
3. Verify that your response values match those shown in Key Response Elements as shown in
Table 2-2.
TABLE 2-2

Authorization Reversal Test Data
Supplied Data Elements

orderId
32

Element

Key Response Elements

Value

Element

Value

Authorization Response:

Authorization:

 000

 10010

 Approved

 John Smith

 11111

 1 Main St.

 01

 Burlington
 MA

 M

 01803-3747
 US
 VI
 4457010000000009
 0121
 349
32A

Capture Response:

Capture:

 000

 5050

 Approved

 Value returned in
Auth response for
Order Id 32

116

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-2

Testing Your cnpAPI Transactions

Authorization Reversal Test Data
Supplied Data Elements

orderId
32B

Element

Key Response Elements

Value

Element

Value

Auth Reversal Response:

Authorization Reversal:

 000

 Value returned in
Auth response for
Order Id 32
 Do Not Submit an
Amount

 Approved
Declined Transaction report
result = 111 - Authorization
amount has already been
depleted
Note: This transaction
returns 111 instead of 000,
because it is unnecessary
to submit an Authorization
Reversal for the Visa
payment card.

33

Authorization:

Authorization Response:
 20020

 000

 Mike J. Hammer

 Approved

 2 Main St.

 22222

 Apt. 222

 10

 Riverside
 RI
 02915

 M
 Note: Not returned
for MasterCard

 US
 MC
 5112010000000003
 0221
 261
 BwABBJQ1AgAAA
AAgJDUCAAAAAA
A=
33A

Auth Reversal Response:

Authorization Reversal:
 Value returned in
Auth response for
Order Id 33

 000
 Approved

 Do Not Submit an
amount

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

117

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-2

Performing the Required Certification Tests

Authorization Reversal Test Data
Supplied Data Elements

orderId
34

Element

Key Response Elements

Value

Element

Value

Authorization Response:

Authorization:

 000

 30030

 Approved

 Eileen Jones

 33333

 3 Main St.

 10

 Bloomfield
 CT

 M

 06002
 US
 DI
 6011010000000003
 0321
 758
34A

Auth Reversal Response:

Authorization Reversal:

 000

 Value returned in
Auth response for
Order Id 34

 Approved

 Do Not Submit an
Amount
35

Authorization Response:

Authorization:

 000

 10100

 Approved

 Bob Black

 44444

 4 Main St.

 13

 Laurel
 MD
 20708
 US
 AX
 375001000000005
 0421

118

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-2

Testing Your cnpAPI Transactions

Authorization Reversal Test Data
Supplied Data Elements

orderId
35A

Element

Key Response Elements

Value

Element
Capture Response:

Capture:

 000

 5050

 Approved

 Value returned in
Auth response for
Order Id 35
35B

Auth Reversal Response:

Authorization Reversal:

 000

 Value returned in
Auth response for
Order Id 35
 5050

36

Value

 Approved
Declined Transaction report
result = 336 - Reversal
amount does not match
Authorization amount
Authorization Response:

Authorization:

 000

 20500

 Approved

 AX
 375000026600004
 0521
36A

Auth Reversal Response:

Authorization Reversal:

 000

 Value returned in
Auth response for
Order Id 36

 Approved

 10000
Declined Transaction report
result = 336 - Reversal
amount does not match
Authorization amount

2.4.3

Testing eCheck Transactions

If you have elected to offer eChecks as an alternate payment method, you are required to
complete the tests in this section. Data sets are provided for you to use to test your construction of
XML request messages, as well as the parsing of the response messages for eCheck transactions.
NOTE:

The eCheck Verification test is required only if you plan to perform
eCheck Verifications.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

119

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Required Certification Tests

To test eCheck Verification transactions:
1. Verify that your eCheck XML template is coded correctly (refer to eCheck Verification
Transactions on page 277.)
2. Submit the eCheck Verification transactions using the data sets supplied in Table 2-3.
NOTE:

In addition to the test data provided in the table, you must also provide
appropriate data for other child elements of the billToAddress element,
such as Address1 (2, 3), city, state, phone, etc.
For Corporate accounts (Order ID 39 and 40) you must include the
firstName, lastName, and companyName in the echeckVerification
request.

3. Verify that your response values match those shown in the Key Response Elements section of
Table 2-3.
4. After you complete this test, go to the next eCheck test.

TABLE 2-3

eCheck Verification Test Data
Supplied Data Elements

orderId
37

Element

Key Response Elements

Value

Element

Value

 301

 3001

 Invalid Account
Number

 telephone
 Tom
 Black
 Checking
 10@BC99999
 053100300
38

 000

 3002

 Approved

 telephone
 John
 Smith
 Checking
 1099999999
 011075150

120

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-3

Testing Your cnpAPI Transactions

eCheck Verification Test Data (Continued)
Supplied Data Elements

orderId

Element

Value

 3003

39

 telephone
 Robert

Key Response Elements
Element

Value

 950
 Declined Negative
Information on File

 Jones
 Good Goods Inc
 Corporate
 3099999999
 053100300
 3004

40

 telephone

 951
 Absolute Decline

 Peter
 Green
 Green Co
 Corporate
 8099999999
 011075150

To test eCheck Prenotification transactions:
NOTE:

The eCheck Prenotification tests are required only if you plan to perform
eCheck Prenotification.
You can only submit eCheck Prenotification transactions in Batches.

1. Verify that your eCheck XML templates are coded correctly (refer to eCheck Prenotification
Credit Transactions (Batch Only) on page 266 and eCheck Prenotification Sale Transactions
(Batch Only) on page 269.)
2. Submit the eCheck Verification transactions using the data sets supplied in Table 2-4.
3. Verify that your response values match those shown in the Key Response Elements section of
Table 2-4.
4. After you complete this test, go to the next eCheck test.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

121

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-4

Performing the Required Certification Tests

eCheck Prenotification Test Data
Supplied Data Elements

orderId
ECPreNoteSa
le

Element

Key Response Elements

Value

Element

Value

 000

 ecommerce

 Approved

 PreNote Sale Corp
 Corporate
 1092969901
 011075150

ECPreNoteCr
edit

 000

 ecommerce

 Approved

 PreNote Credit Corp
 Corporate
 1099339999
 011075150

PreNoteSaleA
ccNumErr

 301

 ecommerce

 Invalid Account
Number

 PreNote Sale Corp
 Corporate
 10@2969901
 011100012

PreNoteCredit
AccNumErr

 301

 ecommerce

 Invalid Account
Number

 PreNote Credit
Personal
 Savings
 10@2969901
 011100012

PreNoteSaleR
outNumErr

 900

 ecommerce

 Invalid Bank
Routing Number

 PreNote Sale
Personal
 Checking
 6099999992
 053133052

122

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-4

Testing Your cnpAPI Transactions

eCheck Prenotification Test Data (Continued)
Supplied Data Elements

orderId

Element

PreNoteCredit
RoutNumErr

Value

 ecommerce
 PreNote Credit
Personal

Key Response Elements
Element

Value

 900
 Invalid Bank
Routing Number

 Checking
 6099999992
 053133052

To test eCheck Sale transactions:
1. Verify that your eCheck XML template is coded correctly (refer to eCheck Sale Transactions
on page 274).
2. Submit the echeckSale transactions using the Supplied Data elements shown in Table 2-5.
NOTE:

In addition to the test data provided in the table, you must also provide
appropriate data for other child elements of the billToAddress element,
such as Address1 (2, 3), city, state, phone, etc.

3. Verify that your response values match those shown in Table 2-5.
4. After you complete this test, go to the next test.
TABLE 2-5

eCheck Sale Test Data
Supplied Data Elements

orderId
41

Element

Value

 2008
 telephone
 Mike

Key Response Elements
Element

Value

 301
 Invalid Account
Number

 J
 Hammer
 Checking
 10@BC99999
 053100300

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

123

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-5

Performing the Required Certification Tests

eCheck Sale Test Data (Continued)
Supplied Data Elements

orderId

Element

Key Response Elements

Value

Element
 000

 2004

42

Value

 Approved

 telephone
 Tom
 Black
 Checking
 4099999992
 011075150

 000

 2007

43

 Approved

 telephone

Note: This
response will
include the
accountUpdater
element (see
accountUpdater on
page 345).

 Peter
 Green
 Green Co
 Corporate
 6099999992
 011075150

 900

 2009

44

 Invalid Bank
Routing Number

 telephone
 Peter
 Green
 Green Co
 Corporate
 9099999992
 053133052

To test eCheck Credit transactions:
1. Verify that your eCheck XML template is coded correctly (refer to eCheck Credit
Transactions on page 263.)
NOTE:

In addition to the test data provided in the table, you must also provide
appropriate data for other child elements of the billToAddress element,
such as Address1 (2, 3), city, state, phone, etc.

2. Submit the echeckCredit transactions using the data in the Supplied Data Elements section
of Table 2-6.

124

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

Testing Your cnpAPI Transactions

3. Verify that your response values match those shown in the Key Response Elements section of
Table 2-6.
4. After you complete this test, go to the next test.
TABLE 2-6

eCheck Credit Test Data
Supplied Data Elements

orderId
45

Element

Value

Key Response Elements
Element

 1001
 telephone
 John

Value

 301
 Invalid Account
Number

 Smith
 Checking
 10@BC99999
 053100300
46

 1003
 telephone

 000
 Approved

 Robert
 Jones
 Widget Inc
 Corporate
 3099999999
 011075150
47

 1007
 telephone
 Peter
 Green
 Green Co
 Corporate
 6099999993

 000
 Approved
Note: This
response will
include the
accountUpdater
element (see
accountUpdater on
page 345.)

 211370545
48

 Value returned in
eCheck Sale
response for Order
Id 43

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

 000
 Approved

125

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-6

Performing the Required Certification Tests

eCheck Credit Test Data (Continued)
Supplied Data Elements

orderId
49

Element

Key Response Elements

Value

Element

Value

 000

 2

 Approved
Declined Transaction
report result = 360 - No
transaction found with
specified litleTxnId

To test eCheck Void transactions:
1. Verify that your eCheck XML template is coded correctly (refer to eCheck Void Transactions
(Online Only) on page 281.)
2. (Re)Submit the echeckSale transaction for Order ID #42 as shown in Table 2-5 with a
different value for the id attribute.
a. Using the litleTxnId returned in the echeckSaleResponse message, submit an
echeckVoid transaction.
b. The system returns an echeckVoidResponse Response Code of “000” and a message of
“Approved”.
3. Using the litleTxnId returned in the echeckCreditResponse message for Order ID
#46, submit an echeckVoid transaction.
a. The system returns an echeckVoidResponse Response Code of “000” and a message of
“Approved”.
4. Submit an echeckVoid request using a value of “2” for the litleTxnId.
a. The system returns an echeckVoidResponse Response Code of “360” and a message of
“No transaction found with specified litleTxnId”.
5. After you complete this test, go to the next test.

2.4.4

Testing Token Transactions

You can obtain tokens in two ways. The first method is explicit registration using the
registerTokenRequest transaction. The second method is implicit registration, which is
achieved by submitting the card or account information (for eChecks) in a normal payment
transaction. This section provides test data sets using both methods for both credit card and
eCheck tokenization.
Perform this test only if you plan to use the Vault feature.

126

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

NOTE:

Testing Your cnpAPI Transactions

The test data does not include values for all elements. You should use
appropriate values for all elements as required to create a properly
structured cnpAPI request.

To test explicit Token Registration transactions:
1. Verify that your cnpAPI template is coded correctly for this transaction type (refer to
registerTokenRequest on page 695.)
2. To test credit card tokenization, submit registerTokenRequest transactions using the data
for Order Ids 50 through 52 from Table 2-7.
3. If you also use eCheck transactions and have elected to tokenize eCheck account numbers,
submit registerTokenRequest transactions using the data for Order Ids 53 and 54 from
Table 2-7; otherwise, skip those two tests.
4. Verify that your registerTokenResponse values match those shown in the Key Response
Elements section of Table 2-7. The complete token values are not defined in the table,
because the system generates the tokens dynamically.
5. After completing this test, proceed to the next set of tests for implicit tokenization.
TABLE 2-7

Register Token Test Data
Supplied Data Elements

orderId
50

Element

Value

 4457119922390123

Key Response Elements
Element

Value

 xxxxxxxxxxxx0123
 445711
 VI
 801
 Account number
was successfully
registered
Note:

51

 4457119999999999

 none returned
 820
 Credit card number
was invalid

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

127

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-7

Performing the Required Certification Tests

Register Token Test Data
Supplied Data Elements

orderId
52

Element

Key Response Elements

Value

Element

Value

 xxxxxxxxxxxx0123

 4457119922390123

 445711
 VI
 802
 Account number
was previously
registered
53

 xxxxxxxxxx

 1099999998

 EC

 011100012

 998
 801
 Account number
was successfully
registered
54

 1022222102

 900

 1145_7895

 Invalid bank
routing number

To test the submission of card data in an tokenized environment using Authorization transactions,
as well as the submission of tokens in transactions, do the following:
1. Verify that your cnpAPI template is coded correctly for this transaction type (refer to
Authorization Transactions on page 208.)
2. Submit three authorization transactions using the Supplied Data Elements from Order Ids
55 through 57 from Table 2-8.
3. Verify that your authorizationResponse values match those shown in the Key Response
Elements section of Table 2-8 for Order Ids 55 through 57.
4. To verify that your cnpAPI template is coded correctly for the submission of tokens in
authorization transactions, submit authorization transactions using the Supplied Data
Elements from Order Ids 58 through 60 from Table 2-8.
To test the submission of eCheck data in an tokenized environment, as well as the submission of
tokens in eCheck transactions, do the following:
1. Verify that your cnpAPI template is coded correctly for these transaction types as applicable
(refer to eCheck Sale Transactions on page 274 and eCheck Credit Transactions on page 263).

128

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

Testing Your cnpAPI Transactions

2. Submit the four transactions, Order Ids 61 through 64, using the Supplied Data Elements
from Table 2-8.
3. Verify that your response values match those shown in the Key Response Elements section
of Table 2-8 for Order Ids 61 through 64.
TABLE 2-8

Implicit Registration Test Data
Supplied Data Elements

orderId
55

Element

Value

Key Response Elements
Element
 000

 15000

 Approved

 MC

 xxxxxxxxxxxx0196

 5435101234510196
 1121
 987

Value

 801
 Account number was
successfully
registered
 MC
 543510

56

< 301

 15000

 Invalid account
number

 MC
 5435109999999999
 1121
 987
57

 000

 15000

 Approved

 MC

 xxxxxxxxxxxx0196

 5435101234510196
 1121
 987

 802
 Account number was
previously registered
 MC
 543510

58

 15000
 xxxxxxxxxxxx0196

 000
 Approved

 1121
 987
Note: Use the token
returned in Order Id
57.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

129

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-8

Performing the Required Certification Tests

Implicit Registration Test Data (Continued)
Supplied Data Elements

orderId
59

Element

Value

Key Response Elements
Element

Value

 822

 15000

 Token was not found

 1111000100092332
 1121

60

 15000

 823

 1112000100000085

 Token was invalid

 1121
61

 xxxxxxxxxxxxxxxxx

eCheck Sale:
 Checking
 1099999003
 011100012

 801
 Account number was
successfully
registered
 EC
 003

62

 xxxxxxxxxxxxxxxxx

eCheck Sale:
 Checking
 1099999999
 011100012

 801
 Account number was
successfully
registered
 EC
 999

63

 xxxxxxxxxxxxxxxxx

eCheck Credit:
 Checking
 1099999999
 011100012

 801
 Account number was
successfully
registered
 EC
 999

130

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

TABLE 2-8

Testing Your cnpAPI Transactions

Implicit Registration Test Data (Continued)
Supplied Data Elements

orderId
64

Element

Value

Key Response Elements
Element

Value



eCheck Sale:

(parent element)

 Checking

 Corporate

 11190000001003001

 6099999993

 211370545

 211370545



(parent element)

 Checking
 11190000001154101
 211370545
 xxxxxxxxxxxxxxxxx
 801
 Account number was
successfully
registered
 EC
 993

NOTE:

2.4.5

Order ID 64 returns accountUpdater information. This test allows you to
test responses you might receive when a NOC exists against the eCheck
account, but you submit the old account information. In this case, the
system provides the old token information, but issues a new token based
upon the new account information and provides it as well.

Testing Query Transactions

You can use the following test scenarios to verify your coding of the queryTransaction, as
well as various responses. To test the query transaction, please do the following:
NOTE:

If you are enabled for the use of the queryTransaction, you will not be able
to test for response code 153 - Query Transaction not enabled.

1. Submit a queryTransaction with the following elements:
• newTransaction (Note: You can use any value never used as an
id attribute.)
• A (Note: You can use any valid action type as
detailed in the enumerations table of origActionType on page 627.)
Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

131

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Required Certification Tests

Verify that you receive a response value of 151 and message of Original transaction not
found.
2. Submit an authorization or sale transaction using a unique id attribute.
3. Submit a queryTransaction using the id attribute value from Step 2 as the value for the
 element and the  element set to the transaction type you
submitted in Step 2.
Verify that you receive a response value of 150 and message of Original transaction
found, a  value of 1, and the response message for the transaction submitted
in Step 2, as a child of the  element.
4. Submit a second authorization or sale transaction (use the same transaction type as Step
2), using the same value for the id attribute. Note: If you use a sale transaction for this test,
you must change the credit card number from the one you used in Step 2 to avoid having the
transaction flagged as a duplicate.
5. Submit a queryTransaction using the id attribute value from Step 2 as the value for the
 element and the  element set to the transaction type you
submitted in Step 2.
Verify that you receive a response value of 150 and message of Original transaction
found, a  value of 2, and the response messages for the transactions
submitted in Steps 2 and 4, as a children of the  element.
6. Submit an authorization or sale transaction using a value of error_id for the id
attribute.
7. Submit a queryTransaction using error_id for the origId value.
Verify that you receive a response value of 152 and message of Original transaction
found but response not yet available, a  value of 1, and the
 element as a child of the
 element.

2.4.6

Testing Online Duplicate Transaction Processing

When you submit certain Online transactions, the system acts to detect if it is a duplicate by
comparing the id attribute and the credit card number against other successful Online
transactions of the same type processed within the previous two days. The system performs this
checking routine for the following transaction types: Capture, Force Capture, Capture Given
Auth, Credit, Sales, eCheck Credit, eCheck Sales, eCheckVoid, and Void, as well as Gift Card
transactions.
If the system determines a transaction to be a duplicate, The transaction appears in the Declined
Transaction report. This report is available in near real-time via Vantiv iQ, and as an Secure
Scheduled Report, which is generated daily for the previous days transactions. Please refer to
Online Duplicate Checking on page 8 for additional information.

132

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Required Certification Tests

Testing Your cnpAPI Transactions

To test your handling of duplicate transactions:
NOTE:

When you submit the duplicate transaction, make sure that all
information, including the id attribute, is identical.

1. Send any of the following Capture transactions more than once within a two day period:
Order numbers 1A, 2A, 3A, 4A, or 5A. The second submission will appear in the Declined
Transaction report with a response Reason Code of 251 - Duplicate Transaction. Note: You
may have to submit the corresponding Authorization transaction prior to submitting the
Capture transaction.
2. Send any of the following Credit transactions more than once within a two day period: Order
numbers 1B, 2B, 3B, 4B, or 5B. The second submission will appear in the Declined
Transaction report with a response Reason Code of 251 - Duplicate Transaction. Note: You
may have to submit the corresponding Capture transaction prior to submitting the Credit
transaction.
3. Send any of the following Void transactions more than once within a two day period: Order
numbers 1C, 2C, 3C, 4C, or 5C. The second submission will appear in the Declined
Transaction report with a response Reason Code of 251 - Duplicate Transaction. Note: You
may have to submit the corresponding Sale transaction prior to submitting the Void
transaction.
4. Send either of the following eCheck Sale transactions more than once within a two day
period: Order numbers 42 or 43. The second submission will appear in the Declined
Transaction report with a response Reason Code of 251 - Duplicate Transaction.
5. Send any of the following eCheck Credit transactions more than once within a two day
period: Order numbers 46, 47, or 48. The second submission will appear in the Declined
Transaction report with a response Reason Code of 251 - Duplicate Transaction.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

133

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.5

Performing the Optional Tests

Performing the Optional Tests
This section describes data that you can use to test different response codes, messages, and AVS
response codes from the Vantiv system for American Express, Visa, MasterCard, Discover, and
Diner’s Club cards. You can perform these tests after completing the certification testing.
This section contains the following topics:

134

•

Testing AVS and Card Validation

•

Testing Address Responses

•

Testing Advanced AVS Response Codes

•

Testing Response Reason Codes and Messages

•

Testing 3DS Responses

•

Testing the Prepaid Filtering Feature

•

Testing the International Card Filter Feature

•

Testing Security Code No-Match Filtering

•

Testing Advanced Fraud Tools

•

Testing Account Updater

•

Testing Tax Billing

•

Testing Convenience Fees

•

Testing the Recycling Engine

•

Testing Recurring Engine Transactions

•

Testing Gift Card Transactions

•

Testing MasterPass Transactions

•

Testing MasterPass Transactions

•

Testing Apple Pay Transaction Processing

•

Testing Android Pay Transaction Processing

•

Testing SEPA Direct Debit Transaction

•

Testing iDEAL Transactions

•

Testing Giropay Transactions

•

Testing SOFORT Transactions

•

Testing Transaction Volume Capacity

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

2.5.1

Testing Your cnpAPI Transactions

Testing AVS and Card Validation

Use the AVS tests to test all of the possible AVS response codes that the system can produce,
including those response codes that cannot be produced by varying the address and ZIP code data.
For these tests the AVS response codes are independent of any address or ZIP code data that you
submit.
To test AVS response codes:
1. Submit transactions using the card data in Table 2-9. If you are using Card Validation, include
the cardValidationNum element. The Card Validation test will return all possible Card
Validation response codes. The response codes that are returned are independent of the card
validation value that you submit.
2. Verify that the AVS tests return the following response:
000
Approved
654321
See Table 2-9
See Table 2-9
NOTE:

For a list of all possible AVS response codes, see AVS Response Codes
on page 842.
For a list of all possible card validation response codes, see Card
Validation Response Codes on page 846.

TABLE 2-9

AVS and Card Validation Test Data
Supplied Data Elements

orderId
65

Element

Value

 01
 M

 VI

 02
 M

 VI

 10

 4457000400000006
69

 U

 VI

 4457003100000003
68

Value

 00

 4457000100000009
67

Element

 VI
 4457000300000007

66

Key Response Elements

 S

 VI

 11

 4457000200000008

 M

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

135

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-9

Performing the Optional Tests

AVS and Card Validation Test Data
Supplied Data Elements

orderId
70

Element

Value

Key Response Elements
Element

 MC
 5112000100000003

71

 12
 M

 MC
 5112002100000009

72

 13
 M

 MC
 5112002200000008

73

 14
 N

 MC
 5112000200000002

74

 20
 N

 MC
 5112000300000001

75

 30
 P

 MC
 5112000400000000

76

 31
 U

 MC
 5112010400000009

78

 32
 S

 MC
 5112000600000008

80

 AX

 34
 P
 N
 352

 374313304211118

 Decline CVV2/CID
Fail

Note: American
Express CID
failures are declined
by American
Express.

2.5.2

Value

Testing Address Responses

Use the address tests to test different AVS responses by varying the address and ZIP code data.
The address tests are intended to return a realistic AVS response code.
To test address responses:
1. Submit Authorization or Sale transactions in Table 2-10. The AVS tests always return an
avsResult of 00 when submitting 95 Main St. and 95022. If you extend the Zip Code to 9
digits, by appending 1111, the system returns an avsResult of 01, as shown in the second
test.

136

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

2. The AVS response code depends on the Address Line 1 and ZIP Code that are passed in with
the transaction. Submit additional transactions using the card data from the table, but varying
the address/zip information to receive other avsResult codes in the response messages as
shown in the tests for orderIds AVS3 and AVS4.
For a detailed list of all possible AVS response codes, see AVS Response Codes on page 842.
TABLE 2-10 AVS and Card Validation Test Data
Supplied Data Elements
orderId
AVS1

Element

Value

Key Response Elements
Element

Value

 00

 VI
 4457000600000004
 95 Main St.
 95022

AVS2

 01

 VI
 4457000600000004
 95 Main St.
 950221111

AVS3

 10

 VI
 4457000600000004
 100 Main St.
 95022

AVS4

 20

 VI
 4457000600000004
 100 Main St.
 02134

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

137

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.5.3

Performing the Optional Tests

Testing Advanced AVS Response Codes

The Advanced AVS (AAVS) feature is an offering from American Express that allows you to
check several parameters not normally covered by a standard AVS check, including name, phone,
and email.
To test AAVS Response Codes:
1. Submit an Authorization transaction using the data supplied in Table 2-12.
2. Verify that you handle the response correctly.
3. Enter additional transaction varying the values for name, phone, and/or email to trigger other
AAVS results (see AAVS Response Codes on page 843 for other result codes). To obtain a
value of 3 in any position, use one of the following values in the appropriate position:
• Jane Doe5555551234badtest@test.com

For example, if you submit a second transaction using the name Jane Doe Instead of John
Doe, the AAVS result would be 311 indicating No Match for name, but Match for phone and
email.
TABLE 2-11 Advanced AVS Test Data
Supplied Data Elements
orderId
81

Element

Value

 12523

Key Response Elements
Element

Value

 111

 John Doe
 95 Main St.
 Palo Alto
 CA
 950221111
 US
 test@test.com
 6178675309
 AX
 341234567890127
 1121

138

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

2.5.4

Testing Your cnpAPI Transactions

Testing Response Reason Codes and Messages

Use the data provided in this section to test Response Reason Codes and Messages.
NOTE:

If you submit account numbers not specified in the tables, you will receive
the following response:
000
Approved
123457
00

To test Response Codes and Messages:
1. Submit transactions using the data in Table 2-12. In each case use the supplied card number
with a prefix of RRC- as the orderId.
2. Verify that you handle the response correctly.
NOTE:

The messages listed are samples of messages that the system can return.
Since the messages are subject to change at any time, you should use
them only for human readability purposes and not for coding purposes.
Always code to the response codes, since these do not change.

• For a list of all possible response reason codes, see Payment Transaction Response Codes
on page 816.
• For a list of all possible AVS response codes, see AVS Response Codes on page 842.
TABLE 2-12

Response Code Test Data
Supplied Data Elements

orderId

Element

Value

Key Response Elements
Element

 VI
 4457000800000002
 VI
 4457000900000001

Value

 000
 Approved
 000
 Approved

RRC-card #
 VI
 4457001000000008
 MC
 5112000900000005

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

 000
 Approved
 000
 Approved

139

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-12

Performing the Optional Tests

Response Code Test Data
Supplied Data Elements

orderId

Element

Value

Key Response Elements
Element

 AX

 120

 375000030000001

 Call Issuer

 DI

 123

 6011000400000000

 Cal Discover

 VI

 120

 4457001200000006

 Call Issuer

 VI

 120

 4457001300000005

 Call Issuer

 VI

 120

 4457001400000004

 Call Issuer

 MC

 101

 5112001000000002

 Issuer Unavailable

 VI

 321

 4457001900000009
RRC-card #

 Invalid Merchant

 VI

 303

 4457002000000006

 Pick Up Card

 VI

 110

 4457002100000005

 Insufficient Funds

 VI

 120

 4457002200000004

 Call Issuer

 AX

 350

 375000050000006

 Generic Decline

 VI

 349

 4457002300000003

 Do Not Honor

 VI

 340

 4457002500000001

 Invalid Amount

 MC

 301

 5112001600000006

140

Value

 Invalid Account
Number

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-12

Testing Your cnpAPI Transactions

Response Code Test Data
Supplied Data Elements

orderId

Element

Value

Key Response Elements
Element

 MC
 5112001700000005
 MC
 5112001800000004
 VI
 4457002700000009
 MC
 5112001900000003
RRC-card #

 VI
 4457002800000008
 VI
 4457002900000007
 VI
 4457003000000004
 MC
 5112002000000000
 VI
 4457000100000000

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

Value

 301
 Invalid Account
Number
 321
 Invalid Merchant
 101
 Issuer Unavailable
 305
 Expired Card
 322
 Invalid Transaction
 350
 Generic Decline
 101
 Issuer Unavailable
 101
 Issuer Unavailable
 301
 Invalid Account
Number

141

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.5.5

Performing the Optional Tests

Testing 3DS Responses

The cardholder authentication value should only be included by merchants who support 3DS (3
Domain Secure) electronic commerce transactions. Your systems must be in compliance with the
Verified by Visa or MasterCard Secure Code implementations of 3DS.
To test 3DS responses:
1. Submit Authorization transactions or Sale transactions using the data in Table 2-13. For all
tests except the last three Discover tests, set the orderSource element to either
3dsAuthenticated or 3dsAttempted and the cardholderAuthentication element to
the following base64 encoded string:
BwABBJQ1AgAAAAAgJDUCAAAAAAA=

The response from a 3DS test will be the same as an Authorization or Sale response, except the
authenticationResult element will be included in the response as a child of the
fraudResult element.

TABLE 2-13 3DS Test Data
Supplied Data Elements
orderId
3DS1

Element

Key Response Elements

Value

 VI

Element

Value

 0

 4100200300000004
3DS2

 VI

 1

 4100200300000012
3DS3

 VI

 2

 4100200300000103
3DS4

 VI

 A

 4100200300001002
3DS5

 VI

 3

 4100200300000020
3DS6

 VI

 4

 4100200300000038
3DS7

 VI

 5

 4100200300000046
3DS8

 VI

 6

 4100200300000053

142

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-13 3DS Test Data
Supplied Data Elements
orderId
3DS9

Element

Key Response Elements

Value

 VI

Element

Value

 7

 4100200300000061
3DS10

 VI

 8

 4100200300000079
3DS11

 VI

 9

 4100200300000087
3DS12

 VI

 B

 4100200300000095
3DS13

 VI

 C

 4100200300000111
3DS14

 VI

 D

 4100200300000129
3DS15

 3dsAttempted

 N/A

 MC
 5112010200000001
3DS16

 3dsAttempted

 N/A

 MC
 5112010200000001
3DS17

 3dsAuthenticated

 0

 MC
 5407102010000018
3DS18

 3dsAuthenticated

 1

 MC
 5167001020236549
3DS19

 3dsAttempted

 0

 MC
 5154605300000121

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

143

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-13 3DS Test Data
Supplied Data Elements
orderId
DI3DS1

Element

Key Response Elements

Value

 3dsAuthenticated

Element

Value

 0

 DI
 6011000400001008
 ERERARERERE=
DI3DS2

 3dsAuthenticated

 1

 DI
 6011000400000018
 ERERARERERE=
DI3DS3

 3dsAuthenticated

 2

 DI
 6011000400000109
 ERERARERERE=

2.5.6

Testing the Prepaid Filtering Feature

Complete this test only if you are planning on using the Prepaid Filtering Feature and are using
schema version 8.3 or above.
To test the Prepaid Filtering feature:
1. Submit authorization transactions using the values provided in Supplied Data Elements of
Table 2-14.
2. Verify that your response values match those shown in the Key Response Elements section of
Table 2-14.
3. After you complete this test, go to the next test.

144

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-14 Prepaid Filtering Test Data
Supplied Data Elements
orderId
filterPrepaidMC

Element

Value

 9100
 recurring
 John Doe
 10 Main St.

Key Response Elements
Element

Value

 309
 Restricted Card Prepaid Card
Filtering Service
 02

 San Jose
 CA
 95032
 US
 jdoe@phoenixProce
ssing.com
 7812701111
 MC
 5500000958501839
 1121
 true
filterPrepaidVI

 9100
 recurring
 John Doe
 10 Main St.
 San Jose

 309
 Restricted Card Prepaid Card
Filtering Service
 none
 34

 CA
 95032
 US
 jdoe@phoenixProce
ssing.com
 7812701111
 VI
 4650002010001478
 1121
 true

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

145

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.5.7

Performing the Optional Tests

Testing the International Card Filter Feature

Complete this test only if you are planning on using the International Card Filtering Feature and
are using schema version 8.3 or above.
To test the International Card Filtering feature:
1. Submit authorization transactions using the values provided in Supplied Data Elements of
Table 2-15.
2. Verify that your response values match those shown in Key Response Elements section of
Table 2-15.
3. After you complete this test, go to the next test.
TABLE 2-15 International Filtering Test Data
Supplied Data Elements
orderId
filterInternational1

Element

Key Response Elements

Value

Element

Value

 312

 9100

 Restricted Card International Card
Filtering Service

 recurring
 John Doe
 10 Main St.

 34

 San Jose
 CA
 95032
 US
 jdoe@phoenixProce
ssing.com
 7812701111
 VI
 4100200309950001
 1121

146

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-15 International Filtering Test Data
Supplied Data Elements
orderId

Element

filterInternational2

Value

 9100
 recurring
 John Doe
 10 Main St.

Key Response Elements
Element

Value

 000
 Approved
 123457
 00

 San Jose
 CA
 95032
 US
 jdoe@phoenixProce
ssing.com
 7812701111
 VI
 4100200309950001
 1121
 false

2.5.8

Testing Security Code No-Match Filtering

Complete this test only if you are planning on using the Security Code No-Match Filtering
Feature.
To test the Security Code No-Match feature:
1. Submit authorization transactions using the values provided in Supplied Data Elements of
Table 2-16.
2. Verify that your response values match those shown in Key Response Elements section of
Table 2-16.
After you complete this test, go to the next test.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

147

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-16 Security Code No-Match Filtering Test Data
Supplied Data Elements
orderId
securityCodeFilte
r1

Element

Key Response Elements

Value

Element
 358

 9100

 Restricted by Litle
due to security
code mismatch.

 ecommerce
 John Doe
 10 Main St.
 San Jose
 CA

Value

 14


 95032
 US
 MC
 5112002200000008
 1121
 123
securityCodeFilte
r2

 358

 9100

 Restricted by Litle
due to security
code mismatch.

 ecommerce
 Jane Doe
 10 Main St.
 San Jose
 CA

 20


 95032
 US
 MC
 5112000200000002
 1121
 123
 false

148

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

2.5.9

Testing Your cnpAPI Transactions

Testing Advanced Fraud Tools

Complete this test only if you are planning on using the Advanced Fraud Tools Feature.
To test the Advanced Fraud Tools feature:
1. Submit authorization transactions using the values provided in Supplied Data Elements of
Table 2-17. For each test, replace "Your Prefix-" with the prefix supplied by your
Implementation Consultant.
2. Verify that your response values match those shown in Key Response Elements section of
Table 2-17.
NOTE:

You can submit these tests as sale transactions using the supplied data,
or as standalone fraudCheck transactions using just the designated
orderId and threatMetrixsessionId. The results for each test type
will be as shown in the Key response elements section.
Also, please note that the third test, orderId = tmx_fail_order_id, has two
possible results depending upon whether you are configured for Info Only
or Auto-Decline.

After you complete this test, go to the next test.

TABLE 2-17 Advanced Fraud Tools Test Data
Supplied Data Elements
orderId
tmx_pass_ord
er_id

Element

Value

Key Response Elements
Element
 000

 150

 Approved

 VI
 4111111111111111
 1230

Value

 pass
 50

 Prefix-A980A93LP2
O3-KNP0050

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

 FlashDisabled

149

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-17 Advanced Fraud Tools Test Data
Supplied Data Elements
orderId
tmx_review_or
der_id

Element

Value

 150

Key Response Elements
Element
Result if Info Only:
 000

 VI

 Approved

 4111111111111111
 1230
 Prefix-A0S9D8F7G
6H5J4-KMR-020

Value

 review
 -20
 PossibleVPNCon
nection
 PossibleCookieWi
pingWeek

tmx_fail_order
_id

 150

Result if Info Only:
 000

 VI

 Approved

 4111111111111111
 1230
 Prefix-Q1W2E3R4T
5Y6U7I8-KHF-100

 fail
 -100
< 5PaymentsOnExa
ctDevice
 ProxyHasNegativ
eReputation


TrueIPProxyIPCity
Mismatch

Result if Auto-decline:
 550
 Restricted
Device or IP ThreatMetrix
Fraud Score
Below Threshold
 fail
 -100
 5PaymentsOnExa
ctDevice
 ProxyHasNegativ
eReputation
 TrueIPProxyIPCity
Mismatch

150

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-17 Advanced Fraud Tools Test Data
Supplied Data Elements
orderId

Element

Value

Key Response Elements
Element
 000

 150

tmx_unavail_o
rder_id

 Approved

 VI
 4111111111111111

Value

 unavailable

 1230
 Prefix-Q1W2E3R4T
5Y6U7I8-XLP0050

2.5.10

Testing Account Updater

To test Account Updater, you submit a normal Authorization transaction. The certification system
returns an Authorization response that includes Account Update information. You should verify
that you correctly parse the update information.
NOTE:

You can also perform the tests in this section using Sale transactions
instead of Authorization transactions.

To test the Account Updater service:
1. Submit authorization transactions using the values provided in Supplied Data Elements of
Table 2-18.
2. Verify that your response values match those shown in Key Response Elements section of
Table 2-18.
3. If you have coded to receive Extended Response Codes, proceed to the next test.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

151

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-18 Account Updater Test Data
Supplied Data Elements
orderId

Element

Value

 10000

100

Key Response Elements
Element

Value



(parent element)

 VI

 VI

 4457000300000007

 4457000300000007

 0115

 0115



(parent element)

 MC
 5112000100000003
 0115
 10000

101



(parent element)

 DI

 DI

 6500102087026221

 6500102087026221

 0115

 0115



(parent element)

 DI
 6011102077026225
 0115

2.5.10.1

Testing Account Updater Extended Response Codes

To test the Account Updater Extended Response Codes feature:
1. Submit authorization transactions using the values provided in Supplied Data Elements
of Table 2-19.
2. Verify that the response values match those shown in Key Response Elements section of
Table 2-19 and that your systems parse the data correctly. The second test case does not
include account repair information only the Extended Response Code.

152

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-19 Account Updater Extended Response Test Data
Supplied Data Elements
orderId

Element

Value

 10000

102

Key Response Elements
Element

Value



(parent element)

 MC

 MC

 5112000101110009

 5112000101110009

 1199

 1199



(parent element)
 VI

 4457000302200001
 1199
 (parent element)
 501
 The account was
closed.
 10000

103

 (parent element)
 504

 VI
 4457000301100004
 1199

2.5.10.2

 Contact the
cardholder for
updated information.

Testing Account Updater for Tokenized Merchants

If you are a tokenized merchant using the Account Updater service, you can test this service using
the card information provided in Table 2-18. In this case you will receive an original and new
token in the  section of the Authorization response message (see
accountUpdater Structure - Credit Cards (tokenized Merchant) on page 347).

2.5.11

Testing Tax Billing

This test applies only to merchants with MCC 9311.
To test Tax Billing and Convenience Fee transactions:
1. Submit authorization transactions using the values provided in Supplied Data Elements
of Table 2-20. Note: The second transactions omits the  element.
2. Verify that the system returns a response code of 000 - Approved for the first transaction and
response code of 851 - MCC 9311 requires taxType element for the second.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

153

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-20

Performing the Optional Tests

Tax Billing Test Data
Supplied Data Elements

orderId

Element

Key Response Elements

Value

Element
 000

 3000

MCC9311Test

Value

 Approved

 VI
 4457010200000247
 1121
 fee
MCC9311Test2

 851

 3000

 MCC 9311 requires
taxType element

 VI
 4457010200000247
 1121

2.5.12

Testing Convenience Fees

You include Convenience Fees through the use of the secondaryAmount element.
To test the use of Convenience Fees submit the transactions detailed below:
1. Submit authorization or sale transactions for the first five transactions of Table 2-21
using the values provided in Supplied Data Elements columns.
2. Verify that the response values match those shown in Key Response Elements section of
Table 2-21 for those transactions and that your systems parse the data correctly.
3. Submit sale transactions for Order Id SaleWOSecondary using the data provided.
4. After receiving an approval for the sale transaction, submit a credit transaction using the
litleTnxId from the sale transaction and including the secondaryAmount element with
the value provided.
5. Verify that the response values match those shown in Key Response Elements section for the
credit transaction using Order Id SaleWOSecondary and that your systems parse the data
correctly.

154

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-21

Testing Your cnpAPI Transactions

Convenience Fee Test Data
Supplied Data Elements

orderId
Visa_secondary
Amount

Element

Value

 10500
 VI

Key Response Elements
Element

Value

 000
 Approved

 4457010200000247
 1121
 10000
SecondaryAmt_
Higher

 2500
 VI
 4111111111111111

 380
 Secondary Amount
cannot exceed the
sale amount

 1230
 3000
MOP_Unsuppor
ted

 6002
 AX
 375001010000003
 0421

 381
 This method of
payment does not
support secondary
amount

 1100
Negative_Secon
dary

 1000
 VI
 4457010200000247

 382
 Secondary Amount
cannot be less
than zero

 1121
 -500
Partial_Not_Allo
wed

 2500
 VI
 4111111111111111
 1230

 383
 Partial transaction
is not supported
when including a
secondary amount

 3000
 true
SaleWOSecond
ary

 1000

(Sale TXN)

 5112010140000004

 MC

 000
 Approved

 1121

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

155

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-21

Performing the Optional Tests

Convenience Fee Test Data
Supplied Data Elements

orderId

Element

Value

Element

Value

 000

 Value from previous
transaction

SaleWOSecond
ary

 Approved

 1000

(Credit Txn)

 400

2.5.13

Key Response Elements

Declined
Transaction report
result = 385 Secondary amount
not allowed on
refund if not
included on deposit

Testing the Recycling Engine

The Certification test cases for the Recycling Engine serve two purposes. First, you use the test
transactions to verify your handling of the responses you receive if you submit additional
Authorization transactions for a declined auth being handled by the engine. Second, you can
verify your process for retrieving and processing recycling completion files via sFTP.
There are three test scenarios you can use to test the Recycling Engine and your ability to parse
the response messages and/or result Batches. The particular data sets and scenarios you use
depends upon the version of cnpAPI you use, as well as your plans for retrieving the response
messages. Use the following to determine which tests you should run:
•

If you plan to retrieve recycling results via the results Batches posted daily to the FTP site,
perform the tests in Scenario 1.

•

If you are using cnpAPI schema version V8.6 or above, perform the tests in Scenario 2.

Scenario 1
To test your handling of the Recycling Results Session file:
1. Submit authorization (or sale) transactions using the values provided in the Supplied
Data Elements column of Table 2-22. Please use the same value for the orderId and if
applicable, the recycleId elements.
NOTE:

If your configuration is set for Vantiv to recycle by default, you can omit
the  element.

2. Wait a minimum of 2 hours after submitting the last transaction. After 2 hours, retrieve the
Results Session file from the FTP site.

156

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-22
orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase1Orde
r1

Testing Your cnpAPI Transactions

Recycling Engine Test Data - Results Session File Pick-up
Supplied Data Elements

Element

Key Response Elements

Value

 10000

Element
Initial Response:
 110

 VI

 Insufficient Funds

 4457012400000027
 1220
 Litle

Value



true

Final Response
(in FTP Session
File):
 000
 Approved
XXXCase1Orde
r2

 10000

Initial Response:
 110

 MC

 Insufficient Funds

 5160124000000029
 1220
 Litle



true

Final Response
(in FTP Session
File):
 000
 Approved
XXXCase1Orde
r3

 10000

Initial Response:
 110

 VI

 Insufficient Funds

 4100200700000059
 1220
 Litle



true

Final Response
(in FTP Session
File):
 110
 Insufficient Funds

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

157

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-22
orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase1Orde
r4

Performing the Optional Tests

Recycling Engine Test Data - Results Session File Pick-up
Supplied Data Elements

Element

Key Response Elements

Value

 10000

Element
Initial Response:
 110

 MC

 Insufficient Funds

 5500010000000052
 1220
 Litle

Value



true

Final Response
(in FTP Session
File):
 110
 Insufficient Funds
XXXCase1Orde
r5

 10000

Initial Response:
 110

 VI

 Insufficient Funds

 4457032800000047
 1220
 Litle



true

Final Response
(in FTP Session
File):
 328
 Cardholder
requests that
recurring or
installment
payment be
stopped
XXXCase1Orde
r6

 10000

Initial Response:
 110

 MC

 Insufficient Funds

 5160328000000042
 1220
 Litle



true

Final Response
(in FTP Session
File):
 120
 Call Issuer

158

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-22

Testing Your cnpAPI Transactions

Recycling Engine Test Data - Results Session File Pick-up
Supplied Data Elements

orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase1Orde
r7

Element

Key Response Elements

Value

 10000

Element
Initial Response:
 302

 VI

 Account Number
Does Not Match
Payment Type

 5160328000000042
 1220
 Litle

Value



false

Final Response
(in FTP Session
File):
None - This type of
decline is not
recycled.

Scenario 2
To test your handling of the Intercept Response Codes/Messages, as well as the Recycling Results
Session file and Normal Batch/Online responses:
1. Submit authorization (or sale) transactions using the values provided in the Supplied
Data Elements column of Table 2-23. Please use the same value for the orderId and if
applicable, the recycleId elements.
NOTE:

If your configuration is set for Vantiv to recycle by default, you can omit
the  element.

2. If you are using schema version V8.6 or above, resubmit any of the first four transactions
within 36 hours to receive a response message containing the intercept Response Reason
Code 372 - Soft Decline - Auto Recycling In Progress. If you are using schema version 8.5 or
below, you will receive a response message with the same Response Reason Code as in the
initial response message.
3. Wait a minimum of 36 hours after submitting the last of the initial transactions. After 36
hours, you can retrieve the Results Session file from the FTP site and/or resubmit the
transaction. The responses will contain the data shown for the Final Response.
Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

159

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-23
orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase3Orde
r1

Performing the Optional Tests

Recycling Engine Test Data - Intercept and Online or Results Session File Pick-up
Supplied Data Elements

Element

Key Response Elements

Value

 20000

Element
Initial Response:
 350

 DI

 Generic Decline

 6223012400000025
 1220
 Litle

Value



true

Intermediate
Attempts (V8.6):
 372
 Soft decline Recycling In
Progress


true

Final Response
(Online/Normal
Batch, or in FTP
Session File):
 000
 Approved

160

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-23
orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase3Orde
r2

Testing Your cnpAPI Transactions

Recycling Engine Test Data - Intercept and Online or Results Session File Pick-up
Supplied Data Elements

Element

Key Response Elements

Value

 20000

Element
Initial Response:
 350

 AX

 Generic Decline

 377201240000025
 1220
 Litle

Value



true

Intermediate
Attempts (V8.6):
 372
 Soft decline Recycling In
Progress


true

Final Response
(Online/Normal
Batch, or in FTP
Session File):
 000
 Approved

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

161

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-23
orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase3Orde
r3

Performing the Optional Tests

Recycling Engine Test Data - Intercept and Online or Results Session File Pick-up
Supplied Data Elements

Element

Key Response Elements

Value

 20000

Element
Initial Response:
 350

 DI

 Generic Decline

 6223012400000033
 1220
 Litle

Value



true

Intermediate
Attempts (V8.6):
 372
 Soft decline Recycling In
Progress


true

Final Response
(Online/Normal
Batch, or in FTP
Session File):
 373
 Hard Decline Auto Recycling
Complete

162

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-23
orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase3Orde
r4

Testing Your cnpAPI Transactions

Recycling Engine Test Data - Intercept and Online or Results Session File Pick-up
Supplied Data Elements

Element

Key Response Elements

Value

 20000

Element
Initial Response:
 101

 DI

 Issuer Unavailable

 6011002078551608
 1220
 Litle

Value



true

Intermediate
Attempts (V8.6):
 372
 Soft decline Recycling In
Progress


true

Final Response
(Online/Normal
Batch, or in FTP
Session File):
 373
 Hard Decline Auto Recycling
Complete
XXXCase3Orde
r5

 20000

Initial Response:
 302

 VI

 Account Number
Does Not Match
Payment Type

 377203280000048
 1220
 Litle



false

All Responses:
None - This type of
decline is not
recycled.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

163

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.5.13.1

Performing the Optional Tests

Testing Recycling Engine Cancellation

You use an authReversal transaction to halt the automatic recycling of an authorization. For a
sale transaction, use a void transaction to halt recycling.
NOTE:

You can perform this test either after completing the Recycling Engine
test or prior to starting that test.

To test recycling cancellation:
1. Submit a sale transaction using the values provided for Case1Order1a and an authorization
transaction using the values provided for Case1Order2a in the Supplied Data Elements of
Table 2-24.
2. Two (2) hours after receiving the decline message, submit a void transaction using the
litleTxnId returned in the response message for Case1Order1a. If you are not enabled for
Auto-refunding an approved Sales on Void, the Declined transaction report will contain a
response code of 362 - Transaction not Voided - Already Settled.
NOTE:

If you submit the Void transaction (Step 2) within 2 hours of the initial
transaction submission, you will receive a voidResponse with a response
code of 000 - Approved.

3. After receiving the decline messages, submit an authReversal transaction using the
litleTxnId returned in the response message for Case1Order2a. This will halt the recycling
of the order.

164

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-24
orderId or
recycleId
(replace XXX
with your
merchantId)
XXXCase1Orde
r1a

Testing Your cnpAPI Transactions

Recycling Engine Cancellation Test Data
Supplied Data Elements

Element

Key Response Elements

Value

 11000

Element
Initial Response:
 110

 VI

 Insufficient Funds

 4457012400000027
 1220
 Litle
Submit Void using
litleTxnId from
Initial Response

Value



true

Void Response (if
enabled for
Auto-Refund):
 000
 Approved
 (Random Value)
Void Response (if
not enabled for
Auto-Refund:

000
 Approved


Declined
Transaction report
result = 362 Transaction Not
Voided - Already
Settled

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

165

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-24

Performing the Optional Tests

Recycling Engine Cancellation Test Data
Supplied Data Elements

orderId or
recycleId
(replace XXX
with your
merchantId)

Element

XXXCase1Orde
r2a

Key Response Elements

Value

 11000

Element
Initial Response:
 110

 MC

 Insufficient Funds

 5160124000000029
 1220
 Litle
Submit
authReversal
using litleTxnId
from Initial
Response

2.5.14

Value



true

authReversalResp
onse:
 000
 Approved

Testing Recurring Engine Transactions

Use the following Certification tests to verify transactions associated with the Recurring Engine
functionality. For testing purposes, the Certification environment will process the first recurring
transaction within 2 hours. The system cancels subsequent recurring transactions in the payment
stream. For example, if you submitted an Authorization at 9:00 AM that set-up a subscription for
twelve monthly payments, the Cert Recurring Engine would process the first payment by 11:00
AM and cancel the remaining eleven payments.
IMPORTANT: The test data supplied does not necessarily account for all data fields/xml
elements in a particular request. Where test data is not supplied, you
should provide appropriate information.
You should never override your own system to enter supplied data. If you
are unable to enter the supplied data without overriding your system,
please consult your Implementation Consultant concerning the test and
how to proceed.

To test the Recurring Engine functionality using the data supplied in Table 2-25:
1. Submit createPlan transactions for Order Ids R1.1, R1.2, R1.3, R1.4, R1.5, and R1.6.
These transactions establish Plans used in the remaining tests, as well as verify your cnpAPI
messages used to create Plans. You can use whatever values you wish for the 

166

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

and  elements. Verify that each transaction receives an approval code in the response
message.
2. Submit createPlan transactions for Order Id R1.7 using the same  value you
used in R1.3. This transaction is declined, because the Plan Code already exists. Verify that
the transaction receives a response code of 487 - Plan code already exists.
3. Submit a sale transaction for Order Id R2.1. This transaction creates a subscription using the
plan established in Order R1.1. The amount in the sale transaction represents a set-up fee and
not the initial payment. Verify that the transaction receives an approval code in the response
message.
4. Submit an authorization transaction for Order Id R2.2. This transaction creates a
subscription using the plan established in Order R1.1. Because the Authorization did not
specify a start date, the Recurring Engine schedules the first payment for the current date.
Verify that the transaction receives an approval code in the response message.
NOTE:

The transaction specified in Order 2.2 is a $0 Auth. If you include an
amount when using an Auth to establish a subscription, you should plan
on reversing the Auth to avoid a Misuse of Auth fee. The Recurring
Engine obtains its own Auth for the first payment.

5. Submit an updateSubscription transaction for Order Id R2.3. This transaction updates
the subscription initiated with Order Id 2.1, changing the Plan to the plan you created in R1.2.
6. Submit a sale transaction for Order Id R3.1. This transaction utilizes a Sale transaction to
initialize a subscription based upon the plan created in R1.3, but overrides both the number of
payments and the amount specified in the Plan. Verify that the transaction receives an
approval code in the response message.
7. Submit an authorization transaction for Order Id R3.2. This transaction utilizes an
Authorization transaction to initialize a subscription based upon the plan created in R1.3, but
overrides both the number of payments and the amount specified in the Plan. Verify that the
transaction receives an approval code in the response message.
8. Submit an updateSubscription transaction for Order Id R3.3. This transaction updates an
existing subscription, changing the billing date.
9. Submit an authorization transaction for Order Id R4.1. This transaction utilizes an
Authorization transaction to initialize a subscription that overrides the default amount in the
Plan and has a trial period. Verify that the transaction receives an approval code in the
response message.
10. Submit an updateSubscription transaction for Order Id R4.2. This transaction updates an
existing subscription with a new credit card number.
11. Submit an authorization transaction for Order Id R5.1. This transaction utilizes an
Authorization transaction to initialize a subscription based upon the SEMIANNUAL_PLAN,
but overrides the number of payments. Verify that the transaction receives an approval code
in the response message.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

167

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

12. Submit an updateSubscription transaction for Order Id R5.2. This transaction updates an
existing subscription with new billing information.
13. Submit an updateSubscription transaction for Order Id R5.3. Since the transaction does
not include any updated information, the Declined Transaction report will contain a response
code of 484 - Insufficient data to update subscription. Verify the response code by accessing
the Declined Transaction report in Vantiv iQ.
14. Submit an updateSubscription transaction for Order Id R5.4. Since the transaction
specifies a new billing date in the past, the Declined Transaction report will contain a
response code of 485 - Invalid billing date. Verify the response code by accessing the
Declined Transaction report in Vantiv iQ.
15. Submit an authorization transaction for Order Id R6.1. The system declines this
transaction, since it uses an invalid Plan Code. Verify that the transaction receives a response
code of 472 - Invalid plan code.
16. Submit an updateSubscription transaction for Order Id R6.2. Since this order uses an
invalid subscription Id, The system declines this transaction, the Declined Transaction report
will contain a response code of 482 - Invalid start date. Verify the response code by accessing
the Declined Transaction report in Vantiv iQ.
17. Submit an authorization transaction for Order Id R6.3. The system declines this
transaction, since it uses a start date in the past. Verify that the transaction receives a response
code of 475 - Invalid Subscription Id.
18. Submit an authorization transaction for Order Id R7.1. This transaction utilizes an
Authorization transaction to initialize a subscription based upon the
PLAN_WITH_PROMOTIONS Plan with an add On and a Discount applied. Verify that the
transaction receives an approval code in the response message.
19. Submit an updateSubscription transaction for Order Id R7.2. This transaction attempts to
update an existing subscription with a new Add On, but is declined because the Add On
already exists. Verify that the Declined Transaction report contains a response code of 476 Add On already exists.
20. Submit an updateSubscription transaction for Order Id R7.3. This transaction attempts to
update an Add On for an existing subscription, but is declined because the specified Add On
is not associated with the Subscription. Verify that the Declined Transaction report contains a
response code of 478 - No matching Add On code for the subscription.
21. Submit an updateSubscription transaction for Order Id R7.4. This transaction attempts to
update an Add On for an existing subscription, but is declined because the specified Add On
is not associated with the Subscription. Verify that the Declined Transaction report contains a
response code of 478 - No matching Add On code for the subscription.
22. Submit an updateSubscription transaction for Order Id R7.5. This transaction attempts to
update a Discount for an existing subscription, but is declined because the specified Discount
is not associated with the Subscription. Verify that the Declined Transaction report contains a
response code of 480 - No matching Discount code for the subscription.
23. Submit an authorization transaction for Order Id R8.1. This transaction utilizes an
Authorization transaction to initialize a subscription, but includes duplicate Add Ons. Verify
that the transaction receives a response code of 477 - Duplicate add-on codes in request.
168

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

24. Submit an authorization transaction for Order Id R8.2. This transaction utilizes an
Authorization transaction to initialize a subscription, but includes duplicate Discounts. Verify
that the transaction receives a response code of 481 - Duplicate discount codes in request.
25. Submit an authorization transaction for Order Id R9.1. In this case the parent
Authorization transaction is declined with a response code of 301 - Invalid Account Number.
The response code associated with the recurring request is 471 - Parent transaction declined Recurring subscription not created.PREMIUM_MONTHLY
26. Submit an cancelSubscription transaction for Order Id R10.1. Verify that the transaction
receives an approval code in the response message.
27. Submit an updatePlan transaction for Order Id R11.1. This transaction changes the Plan to
an inactive state. Verify that the transaction receives an approval code in the response
message.
TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R1.1

Element

Value

Key Response Elements
Element

 (parent element)
 Your Value
 Your Value

Value

 000
 Approved
 Your Value

 Basic monthly plan
 MONTHLY
 5000
 12
R1.2

 (parent element)
 Your Value
 Your Value

 000
 Approved
 Your Value

 Premium monthly
plan
 MONTHLY
 7000
 12
R1.3

 (parent element)
 Your Value
 Your Value

 000
 Approved
 Your Value

 An annual plan
 ANNUAL
 14000

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

169

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R1.4

Element

Value

Key Response Elements
Element

Value

 000

 (parent element)

 Approved

 Your Value

 Your Value

 Your Value
 A monthly plan with
trial period
 MONTHLY
 5000
 MONTH
 2
R1.5

 000

 (parent element)

 Approved

 Your Value

 Your Value

 Your Value
 A semi-annual plan
 SEMIANNUAL
 7000
R1.6

 000

 (parent element)

 Approved

 Your Value

 Your Value

 Your Value
 A plan with Add Ons
and Discounts
 MONTHLY
 5000
R1.7

 487

 (parent element)

 Plan code already
exists

 Value from R1.3
 Value from R1.3

 Value from R1.3

 An annual plan
 ANNUAL
 5000

170

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R2.1

Element

Value
 (parent element)

 1000
 (parent element)
 (parent element)

Key Response Elements
Element

Value

 (parent element)
 470
 Approved - Recurring
subscription created

 Value from R1.1
 Use any date
R2.2

 (parent element)
 000
 (parent element)
 (parent element)

 (parent element)
 470
 Approved - Recurring
subscription created

 Value from R1.1
R2.3

 (parent element)

 (parent element)
 000

 Value returned in
R2.1 response

 Approved

 Value from R1.2
R3.1

 (parent element)
 (parent element)
 (parent element)
 Value from R1.3

 (parent element)
 470
 Approved - Recurring
subscription created

 Use any valid date in
the future.
 6
 4000
R3.2

 (parent element)
 (parent element)
 (parent element)
 Value from R1.3

 (parent element)
 470
 Approved - Recurring
subscription created

 Use any valid date in
the future.
 6
 4000

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

171

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R3.3

Element

Value

Key Response Elements
Element

Value

 000

 (parent element)

 Approved

 Value returned in
R3.1 response
 Use any valid date in
the future and
different from date
used in R3.1.

R4.1

 (parent element)
 (parent element)
 (parent element)
 Value from R1.4

 (parent element)
 470
 Approved - Recurring
subscription created

 Use any valid date in
the future.
 4000
R4.2

 000

 (parent element)

 Approved

 Value returned in
R4.1 response
 (parent element)
 VI
 4457010000000009
 1221
R5.1

 (parent element)
 (parent element)
 (parent element)
 Value from R1.5

 (parent element)
 470
 Approved - Recurring
subscription created

Use any valid date in
 the future.
6


172

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R5.2

Element

Value

 (parent element)
 Value returned in
R5.1 response

Key Response Elements
Element

Value

 Value returned in
R5.1 response
 000
 Approved

 (parent element)
 John
 900 Chelmsford St.
 Lowell
 MA
 01781
 US
 john@gmail.com
 8559658965
R5.3

 000

 (parent element)

 Approved

 Value returned in
R5.1 response

Declined Transaction
report result = 484 Insufficient data to
update subscription
R5.4

 000

 (parent element)

 Approved

 Value returned in
R5.1 response
 2000-10-01

R6.1

 (parent element)
 (parent element)

Declined Transaction
report result = 485 Invalid billing date
 472
 Invalid plan code

 (parent element)
 INVALID_PLAN

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

173

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R6.2

Element

Value

Key Response Elements
Element

Value

 000

 (parent element)

 Approved

 1111111111
 (parent element)
 John
 900 Chelmsford St.

Declined Transaction
report result = 475 Invalid Subscription Id

 Lowell
 MA
 01781
 US
 john@gmail.com
 8559658965
R6.3

 (parent element)
 (parent element)
 (parent element)

 (parent element)
 482
 Invalid start date

 Value from R1.1
 2000-04-04

174

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R7.1

Element

Value

 (parent element)
 (parent element)
 (parent element)
 Value from R1.6

Key Response Elements
Element

Value

 (parent element)
 470
 Approved - Recurring
Subscription Created

(parent element)
 SSL_ADDON
 Additional Service
 1000
 2013-08-30
 2050-08-30
 (parent element)
 PROMO_DISCOUN
 T
Special Offer


1000
 2013-08-30
 2050-08-30

R7.2

 (parent element)

 (parent element)
 000

 Value returned in
R7.1 response

 Approved

 (parent element)
 SSL_ADDON
 Additional Service
 1000

Declined Transaction
report result = 476 Add-on code already
exists

 2013-08-30
 2050-08-30

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

175

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R7.3

Element

Value

Key Response Elements
Element
 000

 (parent element)

 Approved

 Value returned in
R7.1 response
 (parent element)
 PROMO_DISCOUN
T
 Special Offer

Value

Declined Transaction
report result = 486 Discount code already
exists

 1000
 2013-08-30
 2050-08-30
R7.4

 478

 (parent element)

 No matching Add-on
code for the
subscription
 (parent element)
Declined Transaction
 INVALID_ADDON_C report result = 478 No matching Add-on
ODE
code for the
 Extra Features
subscription
 1000
 Value returned in
R7.1 response

R7.5

 480

 (parent element)
 Value returned in
R7.1 response
 (parent element)
 INVALID_DISCOUN
T_CODE
 Special Offer
 1000

 No matching
Discount code for the
subscription
Declined Transaction
report result = 480 No matching Discount
code for the
subscription

 2013-08-30
 2050-08-30

176

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R8.1

Element

Value

 (parent element)

Key Response Elements
Element

Value

 (parent element)

 (parent element)
 (parent element)
 Value from R1.6

 477
 Duplicate Add-on
codes in request

(parent element)
 SSL_ADDON
 Additional Service
 1000
 2013-08-30
 2050-08-30
 (parent element)
 SSL_ADDON
 Additional Service
 1000
 2013-08-30
 2050-08-30


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

177

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId
R8.2

Element

Value

 (parent element)
 (parent element)
 (parent element)
 Value from R1.6

Key Response Elements
Element

Value

 (parent element)
 481
 Duplicate discount
codes in request

(parent element)
 PROMO_DISCOUN
 T
Discount


1000
 2013-08-30
 2050-08-30


(parent element)
 PROMO_DISCOUN
 T
Discount


1000
 2013-08-30
 2050-08-30

R9.1

 (parent element)
 (parent element)
 MC
 5112010100000002
 0721

 (parent element)
 471
 Parent transaction
declined - Recurring
subscription not
created

 (parent element)
 (parent element)
 Value from R1.6
R10.1

 (parent element)

 (parent element)

 Value returned in
R7.1 response

 Submitted value
 000
 Approved

178

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

TABLE 2-25 Recurring Engine Test Data
Supplied Data Elements
orderId

Element

Value

Key Response Elements
Element

 (parent element)

R11.1

 Value from R1.2

Value

 000
 Approved

 false

2.5.15

Testing Gift Card Transactions

Use the following Certification tests to verify transactions associated with the Private Label Gift
Card functionality. The tests are designed so that you can verify your XML structure for each
transaction type, as well as your ability to parse the response data.
To test the Gift Card functionality using the data supplied in Table 2-26:
NOTE:

When processing gift cards, many transactions response messages
include the refCode, sequenceNumber, systemTraceId, and txnTime
elements. You should always store these values for possible use in
subsequent transactions. For example, to perform the giftCardCapture
in test GC2A, you must include the values returned for these elements in
the associated authorization transaction, GC2.

1. Submit an activate transaction for Order Id GC1. Verify that the data in the response
message matches the Key Response Elements specified in the table.
2. Submit an activate transaction for Order Id GC1A. This transaction activates a Virtual Gift
Card. Verify that the data in the response message matches the Key Response Elements
specified in the table.
3. Submit an authorization transaction for Order Id GC2. Verify that the data in the response
message matches the Key Response Elements specified in the table.
4. Submit a giftCardCapture transaction for Order Id GC2A. Verify that the data in the
response message matches the Key Response Elements specified in the table.
5. Submit a giftCardCredit transaction for Order Id GC2B. Verify that the data in the
response message matches the Key Response Elements specified in the table.
6. Submit a deactivate transaction for Order Id GC3. Verify that the data in the response
message matches the Key Response Elements specified in the table.
7. Submit a load transaction for Order Id GC4. Verify that the data in the response message
matches the Key Response Elements specified in the table.
8. Submit a unload transaction for Order Id GC5. Verify that the data in the response message
matches the Key Response Elements specified in the table.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

179

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

9. Submit a balanceInquiry transaction for Order Id GC6. Verify that the data in the
response message matches the Key Response Elements specified in the table.
10. Submit an activate transaction for Order Id GC7. Verify that the data in the response
message matches the Key Response Elements specified in the table.
11. Submit an activateReversal transaction for Order Id GC7A. Verify that the data in the
response message matches the Key Response Elements specified in the table.
12. Submit an activateReversal transaction for Order Id GC1A. Verify that the data in the
response message matches the Key Response Elements specified in the table.
13. Submit an authorization transaction for Order Id GC8. Verify that the data in the response
message matches the Key Response Elements specified in the table.
14. Submit an authorizationReversal transaction for Order Id GC8A. Verify that the data in
the response message matches the Key Response Elements specified in the table.
15. Submit a sale transaction for Order Id GC9. Verify that the data in the response message
matches the Key Response Elements specified in the table.
16. Submit a depositReversal transaction for Order Id GC9A. Verify that the data in the
response message matches the Key Response Elements specified in the table.
17. Submit a sale transaction for Order Id GC10. Verify that the data in the response message
matches the Key Response Elements specified in the table.
18. Submit a giftCardCredit transaction for Order Id GC10A. Verify that the data in the
response message matches the Key Response Elements specified in the table.
19. Submit a refundReversal transaction for Order Id GC10B. Verify that the data in the
response message matches the Key Response Elements specified in the table.
20. Submit a deactivate transaction for Order Id GC11. Verify that the data in the response
message matches the Key Response Elements specified in the table.
21. Submit a loadReversal transaction for Order Id GC12. Verify that the data in the response
message matches the Key Response Elements specified in the table.
22. Submit an unload transaction for Order Id GC13. Verify that the data in the response
message matches the Key Response Elements specified in the table.
23. Submit an unloadReversal transaction for Order Id GC13A. Verify that the data in the
response message matches the Key Response Elements specified in the table.
24. Submit an activate transaction for Order Id GC14. This transaction is declined with a
response code of 301 - Invalid Account Number. Verify that the data in the response message
matches the Key Response Elements specified in the table.
25. Submit an activate transaction for Order Id GC15. This transaction is declined with a
response code of 217 - Already active, because it attempts to activate the same card already
activated in Order Id GC1. Verify that the data in the response message matches the Key
Response Elements specified in the table.
26. Submit an authorization transaction for Order Id GC16. This transaction is declined with
a response code of 110 - Insufficient Funds. Verify that the data in the response message
matches the Key Response Elements specified in the table.

180

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

27. Submit an authorization transaction for Order Id GC17. This transaction is declined with
a response code of 281 - Card not active. Verify that the data in the response message matches
the Key Response Elements specified in the table.
28. Submit a sale transaction for Order Id GC19. Verify that the data in the response message
matches the Key Response Elements specified in the table.
29. Submit a giftCardCredit transaction for Order Id GC19A. For this transaction the
Declined Transaction report will contain response code of 304 - Lost/Stolen Card.
30. Submit a balanceInquiry transaction for Order Id GC20. This transaction is declined with
a response code of 352 - Invalid CVV2. Verify that the data in the response message matches
the Key Response Elements specified in the table.
TABLE 2-26

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC1

Element

Key Response Elements

Value

Element

Value

Activate Response:

Activate:

 000

 15000

 Approved

 GC
 Supplied by
Implementation
Consultant


 15000

 1220
 123
GC1A

Activate Response:

Virtual Activate:

 000

 8000

 Supplied by
Implementation
Consultant
GC2

Authorization:
 1500

 Approved
 8000
 603571xxxxxxxx
xx
Authorization
Response:
 000

 GC

 Approved

 Number from GC1

 11111

 1220
 123


 13500

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

181

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-26

Performing the Optional Tests

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC2A

Element

Key Response Elements

Value

Element

Value

Capture Response:

Gift Card Capture:

 000

 Value from GC2 resp.

 Approved

 1500
 GC
 Number from GC2
 1220
 123
 refCode from GC2
 amount from GC2
 txnTime from GC2
GC2B

Credit Response:

Gift Card Credit:

 000

 Value from GC2A resp.

 Approved

 500
 GC
 Number from GC2
 1220
CG3

Deactivate:
 GC

Deactivate
Response:
 000

 Supplied by
Implementation
Consultant

 Approved
 0

GC4

Load Response:

Load:

 000

 5000

 Approved

 GC
 Supplied by
Implementation
Consultant


 5000

 0121
 123

182

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-26

Testing Your cnpAPI Transactions

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC5

Element

Key Response Elements

Value

Element
Unload Response:

Unload:

 000

 2500

 Approved

 GC
 Number from GC4
 0121
 123
GC6

Value

Balance Inquiry:
 GC


 2500
Balance Inquiry
Response:
 000

 Number from GC1

 Approved

 0121
 123


 2500

GC7

Activate Response:

Activate:

 000

 8000

 Approved

 GC
 Supplied by
Implementation
Consultant


 8000

 1215
 123
GC7A

Activate Reversal:
 Value from GC7 resp.

Activate Reversal
Response:

 from GC7
 from GC7

 000
 Approved

 from GC7
 refCode from GC7
 amount from GC7
 systemTraceId from GC7
 GC7

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

183

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-26

Performing the Optional Tests

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC7B

Element

Key Response Elements

Value

Activate Reversal:
 Value from GC1A resp.

Element

Value

Activate Reversal
Response:
 000

 from GC1

 Approved

 from GC1
 from GC1
 refCode from GC1A
 amount from GC1A
 systemTraceId from
GC1A

GC8

sequenceNumber from
GC1A

Authorization:
 2000

Authorization
Response:
 000

 GC

 Approved

 Supplied by
Implementation
Consultant
 1220
 123
GC8A

 11111

 4000
Auth Reversal
Response:

Gift Card Auth
Reversal:
 Value from GC8 resp.

 000

 from GC8

 Approved

 from GC8
 from GC8
 refCode from GC8
 amount from GC8
 systemTraceId from GC8


184

sequenceNumber from
GC8

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-26

Testing Your cnpAPI Transactions

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC9

Element

Key Response Elements

Value

Element

Value

Sale Response:

Sale:

 000

 2000

 Approved

 GC
 Supplied by
Implementation
Consultant
 1220

 11111

 8000

 123
GC9A

Deposit Reversal:
 Value from GC9 resp.

Deposit Reversal
Response:
 000

 from GC9

 Approved

 from GC9
 from GC9
 refCode from GC9
 amount from GC9
 systemTraceId from GC9

GC10

sequenceNumber from
GC9
Sale Response:

Sale:

 000

 2000

 Approved

 GC

 11111

 Number from GC9
 1220
 123


 8000

GC10A

Credit Response:

Gift Card Credit:
 Value from GC10 resp.
 2000

 000
 Approved

 GC
 Number from GC9
 1220

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

185

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-26

Performing the Optional Tests

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC10B

Element

Key Response Elements

Value

Refund Reversal:
 Value from GC10A resp.

Element

Value

Refund Reversal
Response:
 000

 from GC10

 Approved

 form GC10
 from GC10
 refCode from GC10A
 amount from GC10A
 systemTraceId from
GC10A

GC11

sequenceNumber from
GC10A

Deactivate Reversal:
 Value from GC3 resp.

Deactivate
Reversal
Response:

 from GC3
 000

 from GC3

 Approved

 from GC3
 refCode from GC3 resp.
 amount from GC3 resp.
 systemTraceId from GC3

GC12

sequenceNumber from
GC3 resp.

Load Reversal:
 Value from GC4 resp.

Load Reversal
Response:
 000

 from GC4

 Approved

 from GC4
 form GC4

 0

 refCode from GC4 resp.
 amount from GC4 resp.
 systemTraceId from GC4


186

sequenceNumber from
GC4 resp.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-26

Testing Your cnpAPI Transactions

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC13

Element

Key Response Elements

Value

Element

Value

Unload Response:

Unload:

 000

 2500

 Approved

 GC
 Supplied by
Implementation
Consultant


 1500

 0121
 123
GC13A

Unload Reversal:
 Value from GC13 resp.

Unload Reversal
Response:
 000

 from GC13

 Approved

 from GC13
 from GC13
 refCode from GC13 resp.
 amount from GC13 resp.
 systemTraceId from
GC13 resp.

GC14

sequenceNumber from
GC13 resp.
Activate Response:

Activate:

 301

 15000

 Invalid Account
Number

 GC
 Supplied by
Implementation
Consultant
 1221
 123
GC15

Activate Response:

Activate:

 217

 10000

 Already active

 GC
 Number from GC1

 14000

 1221
 123

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

187

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

TABLE 2-26

Performing the Optional Tests

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC16

Element

Key Response Elements

Value

Authorization:
 1500000

Element
Authorization
Response:
 352

 GC

 Decline
CVV/CID Fail

 Number from GC1
 1221
 123

GC17

Authorization:
 15000

Value


 14000
Authorization
Response:
 218

 GC

 Card not active

 Supplied by
Implementation
Consultant
 1221
 123
GC19

Sale Response:

Sale:

 000

 1000

 Approved

 GC
 Supplied by
Implementation
Consultant
 1220

 11111

 1500

 123
GC19A

Credit Response:

Gift Card Credit:

 000

 Value from GC19 resp.

 Approved

 10000
 GC
 Value from GC19
 1220

188

Declined Transaction
report result = 304 Lost/Stolen Card

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

TABLE 2-26

Testing Your cnpAPI Transactions

Private Label Gift Card Test Data
Supplied Data Elements

orderId
GC20

Element

Key Response Elements

Value

Element

Value

Balance Inquiry
Response:

Balance Inquiry:
 GC
 Number from GC4

 352
 Invalid CVV2

 0121
 476

2.5.16

Testing MasterPass Transactions

If you are planning to support MasterPass transaction, in addition to other required certification
testing, you should submit the following transactions to test the use of the additional cnpAPI
elements required for a MasterPass transaction.
To test the MasterPass functionality using the data supplied in Table 2-27:
1. Submit an Authorization transaction using the data supplied for Order Id MCWalletAuth.
Verify that the response data matches the values for the Key Response Elements for that
orderId.
2. Submit a Sale transaction using the data supplied for Order Id MCWalletSale. Verify that the
response data matches the values for the Key Response Elements for that orderId.
TABLE 2-27 MasterPass Test Data
Supplied Data Elements
orderId
MCWalletAut
h

Element

Value

 (parent element)
 MasterPass

Key Response Elements
Element

Value

 000
 Approved

 102
MCWalletSal
e

 (parent element)
 MasterPass

 000
 Approved

 102

2.5.17

Testing Apple Pay Transaction Processing

The following Apple Pay tests allow you to verify your submission of valid XML for two Apple
Pay scenarios. The first test scenario applies to the case where you decrypt the Apple Pay

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

189

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

PKPaymentToken, while the second scenario applies to the Vantiv decryption PKPaymentToken
components submitted in a cnpAPI transaction.
NOTE:

2.5.17.1

For information about testing the submission of the PKPaymentToken
using the Mobile eProtect, please refer to the Vantiv eProtect Integration
Guide.

Testing the Submission of the Decrypted PKPaymentToken in
cnpAPI

To test the submission of an Apple Pay transaction in cnpAPI when you decrypt the
PKPaymentToken, you must include the information listed in the table below in an Authorization
or Sale transaction. Assuming you submit valid XML with appropriate values, the test
environment will return an approved response message.

TABLE 2-28 cnpAPI Elements for Merchant Decrypted PKPaymentToken
cnpAPI Element

Value

number

Use any valid (Mod-10 compliant) card number.
You can find test numbers in Chapter 2 of the
Vantiv cnpAPI Reference Guide.

expDate

Use any valid expiration date (i.e., a date in the
future).

authenticationValue

Any Base-64 encoded value between 40 and 56
characters in length. This value simulates the
cryptogram extracted from the PKPaymentToken.

orderSource

Set to applepay

2.5.17.2

Testing the Submission of PKPaymentToken in cnpAPI

When you receive a PKPaymentToken, you must parse (not decrypt) the component parts and use
the data to populate the cnpAPI  child elements. This test is designed to allow you
to verify your ability to parse the PKPaymentToken data and construct well formed cnpAPI
messages. The test uses the data from the example PKPaymentToken shown below (data element
names in bold red type) to construct an Authorization or Sale transaction (see applepay). The
system returns a Response Code of 000 - Approved.
Example: PKPaymentToken
{"version":"EC_v1","data":"Ww9EI+10VVpyZrAb3nxu9c8PG4JEnIh4oTkDhZi4axj5QqC5WIir6
TJcFmk/3wkrNL/KaRXz3aan4WRO6cPL+cUTRpQUO9ECqTBItmQbJxGbN42713TyI+y97k3msl7bd5rJO
MIOpkCtfp2ua+3lnBhjGFnUzdCxq+/K6eoIEwYlAEfX9Sdpjm+plVfvSK7vj0BQCcXo1dXGkNUKwKWA4

190

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

GYPUE3qwbuiQWcZwLxAEF43274pACV4LBmdv0HYgYpcgCY0+U6/YSVKdpPrhHLDeLOlO7T4WwuimHojs
KA/BknpPY1uJfP+YJxj1fYghaAOAR0tA5cYJftlWLXaV9lZu113Ns1rxColh4PR8wsuw81CdOruvoURG
NaNyX+hG1suQoHeE8ECzKIE6DlHEeVMcdxXySwFPY7hxEY1QKSSXw==","signature":"MIAGCSqGSI
b3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIICvzCCAmWgAwIBAg
IIQpCV6UIIb4owCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYX
Rpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBA
oMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwODAxMjMzOVoXDTE5MDUwNzAxMjMzOVowXz
ElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbX
MxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQg
AEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0ko
mJPnwPE6OB7zCB7DBFBggrBgEFBQcBAQQ5MDcwNQYIKwYBBQUHMAGGKWh0dHA6Ly9vY3NwLmFwcGxlLm
NvbS9vY3NwMDQtYXBwbGVhaWNhMzAxMB0GA1UdDgQWBBSUV9tv1XSBhomJdi9+V4UH55tYJDAMBgNVHR
MBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMDQGA1UdHwQtMCswKaAnoCWGI2
h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92
NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIQCFGdtAk+7wXrBV7jTwzCBLE+OcrVL15hjif0reLJiPGg
IgXGHYYeXwrn02Zwcl5TT1W8rIqK0QuIvOnO1THCbkhVowggLuMIICdaADAgECAghJbS+/OpjalzAKBg
gqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcn
RpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xND
A1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludG
VncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQ
YDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEY
QZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VE
WjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2
NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/w
QFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaH
R0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSI
b3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXk
K3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiS
FhBpkPCZIdAAAxggFfMIIBWwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3
JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1
UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCEKQlelCCG+KMA0GCWCGSAFlAwQCAQUAoGkwGAYJKo
ZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTQxMDAzMjE1NjQzWjAvBgkqhkiG9w
0BCQQxIgQgg8i4X6yRAU7AXS1lamCf02UIQlpUvNPToXUaamsFUT8wCgYIKoZIzj0EAwIERzBFAiBe17
NGTuuk+W901k3Oac4Z90PoMhN1qRqnij9KNEb/XAIhALELZyDWw0fQM8t0pXO86gg9xXFz424rEMlJ01
TM1VxhAAAAAAAA","header":{"applicationData":"496461ea64b50527d2d792df7c38f301300
085dd463e347453ae72debf6f4d14","transactionId":"f9b0d3cfbb64cd155249c691aca3c521
de03725720616b810d90341f97f347b7","ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZI
zj0DAQcDQgAEarp8xOhLX9QliUPS9c54i3cqEfrJD37NG75ieNxncOeFLkjCk","publicKeyHash":"
jAMRQqg4nffHrXvfwRfbaEc11bk3QD3rv5K9xLqLgu0="}}

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

191

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.5.18

Performing the Optional Tests

Testing Android Pay Transaction Processing

The certification testing you need to perform depends upon the integration method you
implement. This section provides information about the required tests for the eProtect integration
method.

2.5.18.1

Testing Android Pay using eProtect

In this integration method, your application submits information to the Google test environment,
receives a low-value token, and then submits the low value token to Vantiv in a normal payment
transaction.
The table below provides key data values you provide in the submitted transaction.
1. Perform an implicit token registration by submitting a Sale or Authorization transaction using
the data shown for the androidpay_1 (orderId) transaction in Table 1.
2. Verify the response message includes the key Response values shown.
3. Perform an explicit token registration by submitting a Register Token Request using the data
shown for the androidpay_2 (orderId) transaction in Table 1.
4. Verify the response message includes the key Response values shown.
TABLE 2-29 Android Pay using eProtect Test Data
Supplied Data Elements
orderId
androidpay_1

androidpay_2

Element

Key Response Elements

Value

Element

Value

 000

 androidpay
 Value returned from
Google

 Approved

 Value returned from
Google

 801
 Account number
was successfully
registered
Note: Under
certain
circumstances this
test could return
820 - Account
number was
previously
registered.

192

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

Testing Your cnpAPI Transactions

Example: Implicit Token Registration via Authorization Transaction


User Name
Password


androidpay_1
40000
androidpay

Low-Value Token




Example: Explicit Token Registration Transaction


User Name
Password


androidpay_2
Low-Value Token



2.5.19

Testing checkoutId

The checkoutId element is a low value token issued by eProtect in replacement for the CVV
value. You only need to perform these test if you use eProtect and plan to the checkoutId in
place of the CVV.
To test the use of the checkoutId element, do the following:
The first test provides a response of a matching CVV, while the second and third test return
checkoutId failure messages allowing you to verity your handling of these conditions. All tests

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

193

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

return as Approved, because the CVV check does not necessarily impact the approval/decline of a
transaction.
1. Using your (test) Web site, the token value returned for orderId 1 (Table 2-1) and the CVV
value shown for orderId 1 to initiate an eProtect transaction. Use the checkoutId value you
receive for CVV to construct an Authorization transaction within 24 hours. Verify the
response data matches the information shown for orderId chkoutId_1 in Table 2-30.
2. Submit an Authorization using the same token value from Step 1 and the checkoutId value
from the Supplied Data Elements for orderId chkoutId_2. Verify that the response data
matches the Key response Elements for orderId chkoutId_2 in Table 2-30.
3. Submit an Authorization using the same token value from Step 1 and the checkoutId value
from the Supplied Data Elements for orderId chkoutId_3. Verify that the response data
matches the Key response Elements for orderId chkoutId_3 in Table 2-30.
TABLE 2-30 checkoutId Test Data
Supplied Data Elements
orderId
chkoutId_1

Element

Value

Key Response Elements
Element

Value

 000

 value from orderId_1

 Approved

 value from eProtect

 M

chkoutId_2

 000

 value from orderId_1

 Approved

 A90999999999999999

 826
 Checkout Id was
invalid
chkoutId_3

 000

 value from orderId_1

 Approved

 201234567891234567

 827
 Checkout Id was
not found

194

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

2.5.20

Testing Your cnpAPI Transactions

Testing SEPA Direct Debit Transaction

Currently, the SEPA Direct Debit certification tests cover the Vantiv supplied Mandate scenario
only. End-to-end testing involves simulating a consumer on your test site, who selects SEPA
Direct Debit as the payment method and approves the Mandate.
To test the SEPA Direct Debit alternate payment method, do the following:
1. Construct a Sale transaction using the information provided for orderId 1_sddSale, and
submit it to the Pre-Live environment. Ideally, you should do this using a test checkout page
as a simulated consumer. Make sure you include all required fields, as well as the name,
email, and country child elements of billToAddress.
2. Redirect the customer browser to the redirectUrl from the response message. Also, record
the redirectToken and the mandateReference values.
3. As the customer, accept the Mandate. After redirecting the browser back to your checkout
page, verify that the redirectToken parameter from the URL matches the
redirectToken value from the response message.
4. To simulate a recurring (subsequent) payment, construct a Sale transaction using the
information provided for orderId 1a_sddSale, including the mandateReference value
returned in the 1_ssdSale response message.
5. Verify the approval of the transaction.
6. Construct a Sale transaction using the information provided for orderId 15_sddSale, and
submit it to the Pre-Live environment.
7. Verify you receive a 904 response code and that you handle it appropriately. In a production
environment you should prompt the consumer to reenter their IBAN.
8. Construct a Sale transaction using the information provided for orderId 24_sddSale, and
submit it to the Pre-Live environment.
9. Verify you receive a 379 response code and that you handle it appropriately. In a production
environment you should prompt the consumer to select a different payment method.
10. Construct a Sale transaction using the information provided for orderId 2_sddSale, and
submit it to the Pre-Live environment.
11. Verify you receive a 386 response code and that you handle it appropriately. In a production
environment you should retry submitting the transaction.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

195

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-31 SEPA Direct Debit Test Data
Supplied Data Elements
orderId
1_sddSale

Element

Value

Key Response Elements
Element
 000

 David Berman

 Approved

 Vantiv

 Cert Mandate page

 FirstRecurring
 DE7985050300310
0180568

Value

 Dynamically
Generated
 Dynamically
Generated

1a_sddSale

 000

 David Berman

 Approved

 Vantiv
 SubsequentRecurri
ng
 Value from
1_sddSale
 DE7985050300310
0180568
15_sddSale

 904

 David Berman

 Invalid IBAN

 Vantiv
 OneTime
 DE79850503A0310
0180568
24_sddSale

 379

 girogateDecline

 Transaction
declined by the
processing network

 Vantiv
 OneTime
 DE79850503A0310
0180568
2_sddSale

 386

 unknownError

 Processing
Network Error

 Vantiv
 OneTime
 DE7985050300310
0180568

196

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

2.5.21

Testing Your cnpAPI Transactions

Testing iDEAL Transactions

iDEAL (Real-time Bank Transfers) is an international alternate payment method used in the
Netherlands.
To test the iDEAL alternate payment method, do the following:
1. Construct a Sale transaction using the information provided for orderId p1_idealSale and
submit it to the Pre-Live environment. Ideally, you should do this using a test checkout page
as a simulated consumer. Make sure you include all required fields and set the (billing)
country to NL.
2. Redirect the customer browser to the redirectUrl from the response message. Also, record
the redirectToken.
3. As the customer, accept the agreement. After redirecting the browser back to your checkout
page, verify that the redirectToken parameter from the URL matches the
redirectToken value from the response message.
NOTE:

The agreement page presented by the Pre-Live simulator differs from the
bank page that a consumer uses and may vary by bank. Although the
mechanics of the consumer accepting the agreement may differ, any
difference does not change the operations from the merchants standpoint.

4. Verify the approval of the agreement by comparing the redirectToken value to the
token_value parameter returned in the URL.
5. Construct a Sale transaction using the information provided for orderId n10_idealSale and
submit it to the Pre-Live environment.
6. Verify that the transaction fails with a Response Code of 917 - Invalid Country and that your
system handles the response correctly. All iDeal transaction must use NL as the (Billing)
country.
TABLE 2-32 iDEAL Test Data
Supplied Data Elements
orderId
p1_idealSale

Element

Value

Key Response Elements
Element

Value

 000

 10011

 Approved

 David Berman

 Cert bank page

 NL

 Dynamically
Generated
n10_idealSal
e

 20100
 David Berman
 USA

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

 917
 Invalid Billing
Country

197

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

2.5.22

Performing the Optional Tests

Testing Giropay Transactions

Giropay (Real-time Bank Transfers) is an international alternate payment method used in
Germany.
To test the Giropay alternate payment method, do the following:
1. Construct a Sale transaction using the information provided for orderId p1_giropaySale and
submit it to the Pre-Live environment. Ideally, you should do this using a test checkout page
as a simulated consumer. Make sure you include all required fields and set the (billing)
country to NL.
2. Redirect the customer browser to the redirectUrl from the response message. Also, record
the redirectToken.
3. As the customer, accept the agreement. After redirecting the browser back to your checkout
page, verify that the redirectToken parameter from the URL matches the
redirectToken value from the response message.
NOTE:

The agreement page presented by the Pre-Live simulator differs from the
bank page that a consumer uses and may vary by bank. Although the
mechanics of the consumer accepting the agreement may differ, any
difference does not change the operations from the merchants standpoint.

4. Verify the approval of the agreement by comparing the redirectToken value to the
token_value parameter returned in the URL.
5. Construct a Sale transaction using the information provided for orderId n10_giropaySale and
submit it to the Pre-Live environment.
6. Verify that the transaction fails with a Response Code of 917 - Invalid Country and that your
system handles the response correctly. All Giropay transaction must use DE as the (Billing)
country.
TABLE 2-33 Giropay Test Data
Supplied Data Elements
orderId
p1_giropayS
ale

Element

Value

Key Response Elements
Element

Value

 000

 10011

 Approved

 David Berman

 Cert bank page

 NL

 Dynamically
Generated
n10_giropay
Sale

 917

 20100

 Invalid Billing
Country

 David Berman
 USA

198

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Performing the Optional Tests

2.5.23

Testing Your cnpAPI Transactions

Testing SOFORT Transactions

SOFORT (Real-time Bank Transfers) is an international alternate payment method used in several
European countries.
To test the SOFORT alternate payment method, do the following:
1. Construct a Sale transaction using the information provided for orderId p1_sofortSale and
submit it to the Pre-Live environment. Ideally, you should do this using a test checkout page
as a simulated consumer. Make sure you include all required fields and set the (billing)
country to NL.
2. Redirect the customer browser to the redirectUrl from the response message. Also, record
the redirectToken.
3. As the customer, accept the agreement. After redirecting the browser back to your checkout
page, verify that the redirectToken parameter from the URL matches the
redirectToken value from the response message.
NOTE:

The agreement page presented by the Pre-Live simulator differs from the
bank page that a consumer uses and may vary by bank. Although the
mechanics of the consumer accepting the agreement may differ, any
difference does not change the operations from the merchants standpoint.

4. Verify the approval of the agreement by comparing the redirectToken value to the
token_value parameter returned in the URL.
5. Construct a Sale transaction using the information provided for orderId n10_sofortSale and
submit it to the Pre-Live environment.
6. Verify that the transaction fails with a Response Code of 917 - Invalid Country and that your
system handles the response correctly. All SOFORT transaction must use one of the following
as the (Billing) country: DE (Germany), AT (Austria), CH (Switzerland), BE (Belgium), FR
(France), NL (the Netherlands), (the UK), IT (Italy), ES (Spain), PL (Poland), HU (Hungary),
SK (Slovakia), CZ (Czech Republic)
NOTE:

The list of countries (above) where SOFORT is available is accurate at the
time of printing, but may change over time.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

199

cnpAPI Reference Guide
Testing Your cnpAPI Transactions

Performing the Optional Tests

TABLE 2-34 SOFORT Test Data
Supplied Data Elements
orderId
p1_sofortSal
e

Element

Value

Key Response Elements
Element

Value

 000

 10011

 Approved

 David Berman

 Cert bank page

 NL

 Dynamically
Generated
n10_sofortS
ale

 20100

 917

 David Berman

 Invalid Billing
Country

 USA

2.5.24

Testing Transaction Volume Capacity

Volume testing is useful if you plan to send large files. This is an optional test you can perform
during certification testing. Volume testing enables you to verify how many transactions (the
number of requests and responses) you can process within a specific time frame.
Vantiv recommends you submit transactions for a 15-minute time interval. Submit the
approximate number of transactions that you anticipate to be normal volume for any 15-minute
period. You can send in any valid transaction data; the actual data you send will not be verified.

200

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

3
CNPAPI

TRANSACTION EXAMPLES

This chapter contains information and examples concerning the structure of cnpAPI transaction
messages. Where differences exist between the structure of Batch and Online transactions, the
sections present examples of both structures.
NOTE:

In the cnpAPI, the order of the elements is enforced. Failure to adhere to
the element order as defined in the schema will result in XML validation
errors.

This chapter discusses the following topics:
•

Overview of Online and Batch Processing Formats

•

Transaction Types and Examples
NOTE:

This chapter does not include examples of the PayFac Instruction-Based
Dynamic Payout transaction types. For additional information about these
transactions, please refer to Appendix D, "PayFac™ Dynamic Payout".

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

201

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.1

Overview of Online and Batch Processing Formats

Overview of Online and Batch Processing Formats
There are two methods of submitting payment transactions using the cnpAPI format: Online (one
transaction at a time), or Batch. This section provides a high level overview of the request and
response structures used for each submission type.

3.1.1

Batch Process Format

We treat each Batch transmission you send to us as a single request. You can think of the entire
Batch request as a session composed of one or more individual batches, each containing one or
more transactions. You can also use a Batch as a retrieval request for the response to a previously
processed session. We return a response transmission for each request.
Batch processing supports the following transaction types:

•

Activate Transactions

•

eCheck Verification Transactions

•

Authorization Transactions

•

Force Capture Transactions

•

Authorization Reversal

•

Fraud Check Transaction

•

Balance Inquiry Transactions

•

Gift Card Auth Reversal Transaction

•

Cancel Subscription Transactions

•

Gift Card Capture Transaction

•

Capture Transactions

•

Gift Card Credit Transaction

•

Capture Given Auth Transactions

•

Load Transactions

•

Create Plan Transactions

•

Register Token Transactions

•

Credit Transactions

•

RFR Batch Transactions (Batch Only)

•

Deactivate Transactions

•

Sale Transactions

•

eCheck Credit Transactions

•

Unload Transactions

•

eCheck Prenotification Credit

•

Update Card Validation Number
Transactions

•

eCheck Prenotification Sale

•

Update Plan Transactions

•

eCheck Redeposit Transactions

•

Update Subscription Transactions

•

eCheck Sale Transactions

•

All PayFac Dynamic Payout Transactions

NOTE:

202

For information and examples of Dynamic Payout Funding Instructions,
please refer to Appendix D, "PayFac™ Dynamic Payout".

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Overview of Online and Batch Processing Formats

cnpAPI Transaction Examples

For more information about Batch processing, see Batch Transaction Processing on page 5.

3.1.1.1

Supported Communication Protocols

We supports the following communication protocols for Batch processing:
•

Encrypted FTP (PGP or GPG key encryption)

•

sFTP

For additional information concerning the recommended transmission methods, see Transferring
Session Files on page 97.

3.1.1.2

Batch Processing Request Format

The Batch processing request is made up of the following elements:
•

Header information - one  element

•

Merchant authentication information - one  element

•

Batch information - one or more  elements

•

Payment transactions (for example, an Authorization, Capture, Credit, etc.) - at least one per
 element
NOTE:

3.1.1.3

Each of the num and amount attributes used in a batchRequest defaults to
0 (zero) if not specified in the request. In any of the amount fields
(authAmount, captureAmount, etc.), the value is an implied decimal (for
example 500=5.00).

Batch Processing Response Format

The Batch processing response is composed of the following elements:
•

Header information - one  element

•

One or more  elements - contains payment transactions response.

•

At least one payment transaction response (for example, an Authorization response, Capture
response, Credit response, etc.).

NOTE:

For information on the XML Validation response and message attributes,
please refer to XML Validation Error Messages on page 864.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

203

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.2

Online Processing Format

Online Processing Format
Each Online request you send to us is a single transaction. We process Online transactions upon
receipt and return a response file.
Online processing supports the following transaction types:

204

•

Activate Transactions

•

Activate Reversal Transactions (Online Only)

•

Authorization Transactions

•

Authorization Reversal

•

Balance Inquiry Transactions

•

Cancel Subscription Transactions

•

Capture Transactions

•

Capture Given Auth Transactions

•

Create Plan Transactions

•

Credit Transactions

•

Deactivate Transactions

•

Deactivate Reversal Transactions (Online Only)

•

Deposit Reversal Transactions (Online Only)

•

Force Capture Transactions

•

Load Transactions

•

Load Reversal Transactions (Online Only)

•

eCheck Sale Transactions

•

eCheck Credit Transactions

•

eCheck Redeposit Transactions

•

eCheck Verification Transactions

•

eCheck Void Transactions (Online Only)

•

Refund Reversal Transactions (Online Only)

•

Sale Transactions

•

Status Query Transaction (Online Only)

•

Unload Transactions

•

Unload Reversal Transactions (Online Only)

•

Update Card Validation Number Transactions

•

Update Plan Transactions

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Online Processing Format

cnpAPI Transaction Examples

•

Update Subscription Transactions

•

Void Transactions (Online Only)

3.2.1

Supported Communication Protocols

Vantiv supports the HTTPS POST communication protocol for Online processing.
For additional information concerning the recommended transmissions methods, see Transferring
Online Files on page 98.

3.2.2

Online Processing Request Format

The Online processing request is made up of the following elements:
•

Header information - one  element

•

Merchant authentication information - one  element

•

Payment transaction - one payment transaction

3.2.3

Online Processing Response Format

An Online processing response is composed of the following elements:
•

Header information - one 

•

Payment transaction - one payment transaction
NOTE:

For information on the XML Validation response and message attributes,
please refer to XML Validation Error Messages on page 864.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

205

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.3

Transaction Types and Examples

Transaction Types and Examples
This section presents structural information of each transaction type for both Online and Batch
submission methods. The structural information is followed by one or more examples of the
cnpAPI transaction. Each structural example shows the parent and all child elements, but does not
show grandchildren. The cnpAPI examples do show child elements to multiple levels.
The element names in the structural examples provide links to the element definitions in Chapter
4.
NOTE:

The XML examples in this section are intended to present typical cnpAPI
transactions. The examples may not include every possible element for a
particular transaction type. When coding your XML, always consult the
cnpAPI schema files for information concerning all available elements.

This section contains examples of the following transaction types:
NOTE:

206

In the cnpAPI, the order of the elements is enforced. Failure to adhere to
the element order as defined in the schema will result in XML validation
errors.

•

Authorization Transactions

•

Authorization Reversal Transactions

•

Activate Transactions (Private Label Gift Card transaction)

•

Activate Reversal Transactions (Online Only) (Private Label Gift Card transaction)

•

Balance Inquiry Transactions (Private Label Gift Card transaction)

•

Cancel Subscription Transactions (Recurring Engine transaction)

•

Capture Transactions

•

Capture Given Auth Transactions

•

Create Plan Transactions (Recurring Engine transaction)

•

Credit Transactions

•

Deactivate Transactions (Private Label Gift Card transaction)

•

Deactivate Reversal Transactions (Online Only) (Private Label Gift Card transaction)

•

Deposit Reversal Transactions (Online Only) (Private Label Gift Card transaction)

•

eCheck Credit Transactions

•

eCheck Prenotification Credit Transactions (Batch Only)

•

eCheck Prenotification Sale Transactions (Batch Only)

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

•

eCheck Redeposit Transactions

•

eCheck Sale Transactions

•

eCheck Verification Transactions

•

eCheck Void Transactions (Online Only)

•

Force Capture Transactions

•

Fraud Check Transaction

•

Gift Card Auth Reversal Transactions (Private Label Gift Card transaction)

•

Gift Card Capture Transactions (Private Label Gift Card transaction)

•

Gift Card Credit Transactions (Private Label Gift Card transaction)

•

Load Transactions (Private Label Gift Card transaction)

•

Load Reversal Transactions (Online Only) (Private Label Gift Card transaction)

•

Status Query Transactions (Online Only)

•

Refund Reversal Transactions (Online Only) (Private Label Gift Card transaction)

•

Register Token Transactions

•

RFR Transactions (Batch Only)

•

Sale Transactions

•

Unload Transactions (Private Label Gift Card transaction)

•

Unload Reversal Transactions (Online Only) (Private Label Gift Card transaction)

•

Update Plan Transactions (Recurring Engine transaction)

•

Update Subscription Transactions (Recurring Engine transaction)

•

Update Card Validation Number Transactions

•

Void Transactions (Online Only)

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

207

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.3.1

Transaction Types and Examples

Authorization Transactions

The Authorization transaction enables you to confirm that a customer has submitted a valid
payment method with their order and has sufficient funds to purchase the goods or services they
ordered.
The lifespan of an authorization varies according to the payment type being used, as shown in
Table 3-1. During the lifespan, you can use a valid authorization multiple times as needed.
NOTE:

To submit an AVS Only request, submit an Authorization request with the
 element set to 000. The response is identical to an
Authorization response message.

TABLE 3-1

Lifespan of a Payment Authorization

Payment Type

Lifespan of Authorization

American Express

7 days

Discover

10 days

MasterCard

7 days

PayPal

29 days total; Vantiv recommends three days. For more information
about PayPal authorizations, see the Vantiv PayPal Integration
Guide.

Visa

7 days

This section describes the format you must use for an Authorization request, as well as the format
of the Authorization Response you receive from us.

3.3.1.1

Authorization Request Structure

You must structure an Authorization request as shown in the following examples. The structure of
an Authorization request is identical for either an Online or a Batch submission.

Order Id
Authorization Amount
Secondary Amount
Order Entry Source



208

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples


[  |  |  |  |  | ]





payment or fee






 (for Recovery merchants using Recycling)

 (for Recurring Engine merchants)
true or false


processingType Enum
Network Txn Value
Amount from Orig Txn

Example: Batch Authorization Request - Card Not Present

The example below shows a batch request with a single card-not-present Authorization request. If
the batch included additional Authorization requests, each would have it’s own
 element with all applicable attributes and child elements. Also, the
numAuths attribute of the  element would increment for each additional
 element and the authAmount attribute would increase by the new amounts
from each authorization.


userName
password

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

209

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples




visa_test1
2500
telephone

John Doe
15 Main Street
San Jose
CA
95032-1234
USA
9782750000
jdoe@vantiv.com


Jane Doe
15 Main Street
San Jose
CA
95032-1234
USA
9782750000
jdoe@vantiv.com


VI
4005550000081019
1110


8009990001
bdi*001

true




210

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Batch Authorization Request - Card Present

The following example contains two Authorization requests, each defined in its own
 element. The first is a card present transaction, which uses the 
child of the  element.


userName
password



12z58743y1
12522
retail

95032


%B40000001^Doe/JohnP^06041...?;40001=0604101064200?


magstripe
completeread
signature



12z58743y7
55814
retail

01854


VI
4005550000081019
0911


keyedonly

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

211

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

keyed
directmarket

true




Example: Online Authorization Request
NOTE:

The example below uses 3dsAuthenticated as the 
value. If you submit the wrong  value, we return the
response code 370 - Internal System Error - Contact Litle.
Also, the values for the  and
 elements in the example below have
been truncated.



User Name
Password


65347567
40000
3dsAuthenticated

John Smith
100 Main St
Boston
MA
12345
jsmith@someaddress.com
555-123-4567


VI
4000000000000002
1209
555

212

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples



BwABBJQ1gJDUCAAAAAAA=
gMV75TmjAgk=




Example: Authorization Request using token Element

The example below uses the following token related elements (click name to jump to element
definition): token and litleToken.
NOTE:

When you submit the CVV2/CVC2/CID in a registerTokenRequest, the
platform encrypts and stores the value on a temporary basis for later use
in a tokenized Auth/Sale transaction submitted without the value. To use
the store value when submitting an Auth/Sale transaction, set the
cardValidationNum value to 000.


F12345
15000
telephone

John Doe
15 Main Street
San Jose
CA
95032-1234
USA
9782750000
jdoe@vantiv.com


Jane Doe
15 Main Street
San Jose
CA
95032-1234
USA
9782750000
jdoe@vantiv.com

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

213

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples



1111000101039449
1112
987



Example: Authorization Request with Recurring Request


User Name
Password


65347567
40000
3dsAuthenticated

John Smith
100 Main St
Boston
MA
12345
jsmith@someaddress.com
555-123-4567


VI
4000000000000002
1209
555


BwABBJQ1gJDUCAAAAAAA=
gMV75TmjAgk=



Gold_Monthly_1
12

214

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

2016-07-21
1500

New_Customer_Discount_1
New_Customer
750
2016-07-21
2016-07-22


Extra_Feature_1
Extra_1
900
2016-08-21
2016-07-21






3.3.1.2

Authorization Response Structure

An Authorization response has the following structure. The response message is identical for
Online and Batch transactions except Online includes the  element.

Transaction Id
Order Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message
Approval Code
Approved amount for partial Auth




Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

215

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples


 (for Tokenized merchants submitting card data)

 (included for declined Auths if feature is enabled)
 (for Recurring Engine merchants)
 (included if Gift Card is Method of Payment)

Card Last 4 (included for ApplePay using VI or MC)

Txn ID returned from network

Example: Batch Authorization Response

The example below shows a batch Authorization response that contains two transactions.



84568456
12z58743y1
000
2011-03-01T10:24:31
Approved
123456

00



84568457
12z58743y7
000
2011-03-01T10:24:31
Approved
123456

00
2



216

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples


PREPAID
5000
NO
GIFT






Example: Online Authorization Response including Advanced Fraud Results
NOTE:

The online response format contains a  element, which
indicates the date the financial transaction will post.



969506
65347567
000
2011-07-25T15:13:43
2011-07-25
Approved
123457

00
N
2

pass
70
FlashImagesCookiesDisabled




PREPAID
0
YES
TEEN

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

217

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples






Example: Authorization Response for Tokenized Merchant Sending Card Data

If a tokenized merchant submits card data in the Authorization request, the response includes the
tokenResponse element. The example below is a response for an Online request
(litleOnlineresponse element not shown); therefore, it includes the postDate element.

21200000001108
F12345
000
2011-10-08T21:38:32
2011-10-08
Approved
270005

11
P


1111100100240005
801
Account number was successfully registered
VI
402410



Example: Online Authorization Response with Account Updater Token Info

In this example. the  contains both original and new card information as
well as the  element. This signifies that the card number changed
from the original to the new and (from the extended response code) that the issuer reported the
new account as closed. Although the Authorization was approved, this information allows you to
make an informed decision about how to proceed with the sale.


969506

218

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

65347567
000
2011-07-25T15:13:43
2011-07-25
Approved
123457


1111100100240005
VI
1112
400555


1111100100250017
VI
1114
400555


501
The account was closed



00
N
2




Example: Online Authorization Response with Recurring Response


969506
65347567
000
2016-07-25T15:13:43
2016-07-25
Approved

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

219

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

123457

00
N
2


1234567890
000
Approved




3.3.2

Authorization Reversal Transactions

The Authorization Reversal transaction enables you to remove the hold on any funds being held
by an Authorization. The original Authorization transaction must have been processed within the
system. For information on how to use the Authorization Reversal transaction, see Notes on the
Use of Authorization Reversal Transactions on page 77. Also, if you use our Recycling Engine,
you can use the authReversal transaction to halt the recycling of an authorization
transaction.
NOTE:

3.3.2.1

To reverse an Authorization on a Closed-loop Gift Card, submit a Gift Card
Auth Reversal transaction, not an Authorization Reversal transaction. See
Gift Card Auth Reversal Transactions on page 290 for additional
information.

Authorization Reversal Requests

You must structure an Authorization Reversal request as shown in the following examples. The
structure of the request is identical for either an Online or a Batch submission.

Transaction Id
Authorization Amount to Reverse
SUSPECT_FRAUD


220

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Batch Authorization Reversal Request

The following example contains three Authorization Reversal Requests.


userName
password



12345678
1002


81234567
1003


78123456
1000




Example: Online Authorization Reversal Request


User Name
Password


12345678
2999



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

221

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.3.2.2

Transaction Types and Examples

Authorization Reversal Responses

The basic structure of an Authorization Reversal response is identical for Batch and Online
responses.

Transaction Id
Response Code
Date and Time in GMT
Response Message

Example: Batch Authorization Reversal Response

This example shows a Batch Response containing three Authorization Reversal responses.



21200000002700
000
2011-10-14T13:15:43
Approved


21200000002809
001
2011-10-14T13:15:43
Transaction received


21200000002908
001
2011-10-14T13:15:43
Transaction received




222

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Online Authorization Reversal Response


12345678
000
2017-04-30T13:15:43
Approved



3.3.3

Activate Transactions

The Activate transaction changes the status of a (Closed Loop) Gift Card from inactive to active
with a value as specified by the amount element. You can also use this transaction type to create
a Virtual Gift Card.
NOTE:

3.3.3.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Activate Request

You must structure an Activate request as shown in the following examples. The structure of the
request is identical for either an Online or a Batch submission.

Order Id
Activation Amount
Order Entry Source
[  |  ]

Example: Activate Request - Gift Card


User Name
Password

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

223

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples



65347567
40000
ecommerce

GC
9000000000000001




Example: Activate Request - Virtual Gift Card


User Name
Password


65347567
40000
ecommerce

16
900000




3.3.3.2

Activate Response

An Activate response has the following structure. The response message is identical for Online
and Batch transactions except Online includes the  element.

Transaction Id
Response Code
Date and Time in GMT

224

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Date transaction posted (Online Only)
Response Message




Example: Activate Response - Gift Card


9695064321
000
2017-01-25T15:13:43
2017-01-25
Approved

2016-11-25T15:13:38
123456
123456
123456
5000




Example: Activate Response - Virtual Gift Card


9695064321
000
2017-01-25T15:13:43
2017-01-25
Approved

2017-01-25T15:13:38
123456
123456
123456
5000

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

225

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples



9000000000000001
978
1234




3.3.4

Activate Reversal Transactions (Online Only)

The Activate Reversal transaction changes the status of a newly activated Gift Card from active to
inactive, thus reversing the operation of an Active transaction. The Activate Reversal references
the associated Activate transaction by means of the litleTxnId element returned in the Activate
response. This transaction type is available only for Online transactions.
NOTE:

3.3.4.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Activate Reversal Request

You must structure an Activate Reversal request as shown in the following examples.

Transaction Id from Activate Response


Reference Code from Activate Response
Amount from Activate Transaction
Transaction Time from Activate Response
Trace Id from Activate Response
Seq Num from Activate Rsp


226

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Activate Reversal Request


User Name
Password


1234567890123456789

GC
1234102000003558
888
1234

123456
1900
2017-03-21T10:02:46
678901
123456



3.3.4.2

Activate Reversal Response

An Activate Reversal response has the following structure.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

227

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Example: Activate Reversal Response


9695064321
000
2017-03-22T15:13:43
2017-03-22
Approved

2017-03-22T12:00:00
003558
834528
123456
0




3.3.5

Balance Inquiry Transactions

A Balance Inquiry transaction returns the available balance of a Gift Card.
NOTE:

3.3.5.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Balance Inquiry Request

You must structure an Balance Inquiry request as shown in the following examples. The structure
of the request is identical for either an Online or a Batch submission.

Order Id
Order Entry Source



228

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Balance Inquiry Request


User Name
Password


65347567
ecommerce

GC
9000000000000001
1234




3.3.5.2

Balance Inquiry Response

An Balance Inquiry response has the following structure. The response message is identical for
Online and Batch transactions except Online includes the  element.

Transaction Id
Order Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message



Example: Balance Inquiry Response


9695064321

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

229

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

65347567
000
2017-03-21T15:13:43
2017-03-21
Approved

N


2000


3.3.6

Cancel Subscription Transactions

The Cancel Subscription transaction cancels the specified subscription, removing the transaction
stream managed by the Recurring Engine.

3.3.6.1

Cancel Subscription Request

You must structure an Cancel Subscription request as shown in the following examples. The
structure of the request is identical for either an Online or a Batch submission.

ID of Subscription to Cancel

Example: Cancel Subscription Request


User Name
password


1234



230

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

3.3.6.2

cnpAPI Transaction Examples

Cancel Subscription Response

A Cancel Subscription response has the following structure. The response message is identical for
Online and Batch transactions except Online includes the  element.

Transaction Id
Response Code
Response Message
Date and Time in GMT
ID of Subscription Canceled

Example: Cancel Subscription Response


1100030055
000
Approved
2017-04-11T14:48:46
123457



3.3.7

Capture Transactions

The Capture transaction transfers funds from the customer to the merchant. The Capture
references the associated Authorization by means of the litleTxnId element returned in the
Authorization response.
NOTE:

To perform a capture on a Closed-loop Gift Card, submit a Gift Card
Capture transaction, not an Capture transaction. See Gift Card Capture
Transactions on page 292 for additional information.

You send a Capture after the order has been fulfilled. In some cases, it is not possible to fulfill a
customer’s entire order in one shipment (for example, if some items are backordered, or some
shipped from an off-site DCS). In this situation, you can send a Partial Capture transaction by
setting the partial attribute to true. A Partial Capture contains only the data relevant to the
items that were actually shipped, enabling you to settle the funds related to those items.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

231

cnpAPI Reference Guide
cnpAPI Transaction Examples

NOTE:

3.3.7.1

Transaction Types and Examples

If you settle in a currency other than US or Canada, you cannot use partial
captures.

Capture Request

You must structure a Capture request as shown in the following examples. The structure of the
request is identical for either an Online or a Batch submission.

Transaction Id
Authorization Amount
Surcharge Amount


Set to true for final Capture
Gift Card Pin Number
Example: Batch Capture Request - Full Capture

The following Capture example is for a full capture. Although the  element includes
an  child, it is not required for a full Capture. If you omit the  child element,
the capture amount defaults to the full amount from the associated Authorization.


userName
password



84568457
55814

PO12346
1500
false
0

232

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

3714
0
01851
01851
USA
123456
2011-09-14

true
500
0.01667
00
011234567


1
table
TB123
1
EACH
1500
30000
31500
0
301
300.00

true
500
0.01667
03
011234567



2
chair
CH123
1
EACH
20000
0
301

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

233

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

200.00






Example: Batch Capture Request - Partial Capture

A partial Capture has the partial attribute set to true and must include an amount child
element.


userName
password



84568457
45814

PO12346
2100
false
0
3714
0
01851
01851
USA
123456
2016-09-14

true
500
0.01667
00
011234567



234

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

1
table
TB123
1
EACH
1500
30000
31500
0
301
300.00

true
500
0.01667
03
011234567



2
chair
CH123
1
EACH
20000
0
301
200.00






Example: Online Capture Request - Full Capture

The following Capture example is for a full capture. Although the  element includes
an  child, it is not required for a full Capture. If you omit the  child element,
the capture amount defaults to the full amount from the associated Authorization.


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

235

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples


User Name
password


13254123434

PO12345
125
false
0
495
0
01851
01851
USA
123456
2011-08-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80

true
55
0.0059
03

236

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

011234567



2
table
TB123
1
EACH
30000
0
300
300.00





Example: Online Capture Request - Partial Capture

A partial Capture has the partial attribute set to true and must include an  child
element.


User Name
password


13254123434
100

PO12345
125
false
0
495
0
01851
01851
USA

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

237

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

123456
2011-08-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80

true
55
0.0059
03
011234567



2
table
TB123
1
EACH
30000
0
300
300.00





238

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

3.3.7.2

cnpAPI Transaction Examples

Capture Response

A Capture response has the following structure. The response message is identical for Online and
Batch transactions except Batch always includes the  element, while Online includes
the  element.

Transaction Id
Response Code
Date and Time in GMT
Date Of Posting (Online Only)
Response Message


Example: Batch Capture Response




84568456
000
2017-04-01T10:24:31
Approved


84568457
000
2017-04-01T10:24:31
message




Example: Online Capture Response



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

239

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

1100030204
000
2017-04-11T14:48:48
2016-07-11
Approved



3.3.8

Capture Given Auth Transactions

You typically use a Capture Given Auth transaction when the associated Authorization occurred
outside of the system (for example, if you received a telephone Authorization). Another possible
use for a Capture Given Auth transaction is if the Authorization transaction occurred within the
system, but the  is unknown by the submitting party (for example, if the Auth was
submitted by a merchant, but a fulfiller submits a Capture Given Auth).

3.3.8.1

Capture Given Auth Request

You must specify the Capture Given Auth request as follows. The structure of the request is
identical for either an Online or a Batch submission.

Order Id

Authorization Amount
Secondary Amount
Order Entry Source


[  |  |  | ]

payment or fee






240

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples


true or false
processingType Enum
Network Txn Value
Amount from Orig Txn

Example: Batch Capture Given Auth Request

The following example shows a single Capture Given Auth request. The example uses the
 child element, but a tokenized merchant could use the  child element in its
place.


User Name
password



orderId

2016-09-21
123456

10000
ecommerce

VI
4005550000081019
0910


PO12345
125
false
0
495
0
01851
01851

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

241

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

USA
123456
2016-09-21

true
55
0.0055
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80






Example: Online Capture Given Auth Request


userName
password


orderId

2016-08-24
123456

10000

242

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

ecommerce

VI
4005550000081019
0910


PO12345
125
TBD
false
0
495
0
01851
01851
USA
123456
2016-08-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80





Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

243

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Example: Capture Given Auth Request using token Element

The example below uses the following token related elements (click name to jump to element
definition): token and litleToken.

F12345

2011-10-25
500005

15000
ecommerce

John Doe
10 Main Street
San Jose
CA
95032-1234
USA


1112000100010085
1112
987



3.3.8.2

Capture Given Auth Response

A Capture Given Auth response has the following structure. The response message is identical for
Online and Batch transactions except Online includes the  element.

Transaction Id
Response Code
Date and Time in GMT
Date of Posting (Online Only)
Response Message
 (for Tokenized merchants submitting card data)


244

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Batch Capture Given Auth Response



84568457
000
2017-04-01T10:24:31
Approved




Example: Online Capture Given Auth Response


1100030204
000
2017-04-11T14:48:48
2017-04-11
Approved



Example: Capture Given Auth Response for Tokenized Merchant Sending Card
Data

21200000022005
000
2017-04-25T04:00:00
2017-04-26
Approved

1111000100409510
801
Account number was successfully registered
VI
432610


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

245

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples



3.3.9

Create Plan Transactions

The Create Plan transaction allows you to define several attributes of a recurring payment
schedule. Later, you can associate existing, active plans with subscriptions, which establishes a
recurring payment schedule managed by the Recurring Engine.

3.3.9.1

Create Plan Request

You must specify the Create Plan transaction as follows. The structure of the request is identical
for either an Online or a Batch submission.

Plan Reference Code
Name of Plan
Description of Plan
The Type of Interval
Amount of Recurring Payment
1 to 99
Number of Trial Intervals
Type of Trial Period Interval
true or false

Example: Online Create Plan Request


User Name
password


Gold12
Gold_Monthly
Gold Level with Monthly Payments
MONTHLY
5000
4

246

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

1
MONTH
true



3.3.9.2

Create Plan Response

The Create Plan response message is identical for Online and Batch transactions.

Transaction Id
Response Code
Response Message
Date and Time in GMT
Plan Reference Code

Example: Online Create Plan Response


1100030055
000
Approved
2016-07-11T14:48:46
Gold12



3.3.10

Credit Transactions

The Credit transaction enables you to refund money to a customer, even if the original transaction
occurred outside of our system. You can submit refunds against any of the following payment
transactions:

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

247

cnpAPI Reference Guide
cnpAPI Transaction Examples

NOTE:

Transaction Types and Examples

To perform a credit on a Closed-loop Gift Card, submit a Gift Card Credit
transaction, not an Credit transaction. See Gift Card Credit Transactions
on page 294 for additional information.

•

Capture Transactions

•

Capture Given Auth Transactions

•

Force Capture Transactions

•

Sale Transactions

•

External Sale or Capture Transactions
NOTE:

3.3.10.1

Although there are two different scenarios for Credit requests, there is
only one scenario for the Credit response.

Credit Request for a Vantiv Processed Transaction

You must specify the Credit request for a Vantiv processed transaction as follows. The structure
of the request is identical for either an Online or a Batch submission.

Transaction Id
Authorization Amount
Secondary Amount



SUSPECT_FRAUD

Example: Batch Credit Request for a Vantiv Processed Transaction

To request a Credit against a sale settled by us, you only need to specify the 
element. The application uses the  to look-up the Capture referenced and obtain
all the necessary information including the amount.
NOTE:

248

Although it is not required, if you choose to include  elements in
your Credit transaction, you must include the total amount in the
creditAmount attribute of the . If you do not specify
amounts, set the creditAmount attribute to 0.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples



userName
password



84568456
10000

PO12345
125
false
0
3017
0
01851
01851
USA
123456
2016-09-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

249

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples


true
55
0.0059
03
011234567







Example: Online Credit Request for a Vantiv Processed Transaction

To request a Credit against a sale settled by us, you need only specify the 
element. The application uses the  to look up the Capture referenced and obtain
all the necessary information including the amount. The example below includes the optional
 and  elements.


User Name
password


13254123434

8888888888
descriptor


PO12345
125
false
0
495
0
01851
01851
USA
123456

250

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

2016-07-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80

true
55
0.0059
03
011234567



2
table
TB123
1
EACH
30000
0
300
300.00





Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

251

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.3.10.2

Transaction Types and Examples

Credit Request for a Non-Vantiv Processed Transaction

You must specify the Credit request for a Non-Vantiv processed transaction as follows. The
structure of the request is identical for either an Online or a Batch submission.
NOTE:

Although the schema shows  as an optional element for a Credit
against a non-Vantiv processed transaction, refunds of this type are not
supported for PayPal. If you need to refund non-Vantiv processed
transactions and have not maintained a temporary relationship with your
former processor for this purpose, please ask your Relationship Manager
for alternative options.


Order Id
Authorization Amount
Order Entry Source

[  |  |  |  ]

payment or fee






SUSPECT_FRAUD

Example: Batch Credit Request for a Non-Vantiv Processed Transaction

If the sale occurred outside of our system, you must specify the following elements in your Credit
request: , , and , or  ( not supported for
this transaction type).


userName
password


252

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples



12z58743y1
10000
ecommerce

John Doe
123 4th street
Apt. 20
second floor
San Jose
CA
95032
USA
jdoe@isp.com
408-555-1212


MC
5186005800001012
1110


PO12345
125
false
0
495
0
01851
01851
USA
123456
2016-09-14

true
55
0.0059
00
011234567



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

253

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80






Example: Online Credit Request for a Non-Vantiv Processed Transaction

If the sale occurred outside of our system, you must specify the following elements in your Credit
request: , , and , or  ( not supported for
this transaction type).


User Name
password


56789
10000
ecommerce

Mike J. Hammer
Two Main Street
Apartment 222

Riverside
RI
02915
US
mike@sample.com

254

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

5555555555


VI
4005550000081019
0907


5555555555
descriptor


PO12345
125
false
0
495
0
01851
01851
USA
123456
2011-08-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

255

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples


2
table
TB123
1
EACH
30000
0
300
300.00





3.3.10.3

Credit Response

The Credit response message is identical for Online and Batch transactions except Online
includes the postDate element.

Transaction Id
Response Code
Date and Time in GMT
Date of Posting (Online Only)
Response Message
 (for Tokenized merchants submitting card data)

Example: Credit Response

The example below illustrates a Batch Credit response. A response for an Online transaction uses
a litleOnlineResponse element as the parent.



84568457
000
2017-04-01T10:24:31

256

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Approved




Example: Credit Response for a Tokenized Merchant Sending Card Data

When a tokenized merchant submits card data in the Credit request, the response includes the
tokenResponse element. The example below is a response for an Online request
( element not shown), so it includes the  element.

21200000473208
000
2017-04-19T19:29:45
2017-04-19
Approved

1111102200202001
801
Account number was successfully registered
VI
402410



3.3.11

Deactivate Transactions

The Deactivate transaction changes the status of a (Closed Loop) Gift Card from active to
inactive.
NOTE:

3.3.11.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Deactivate Request

You must structure a Deactivate request as shown in the following examples. The structure of the
request is identical for either an Online or a Batch submission.


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

257

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Order Id
Order Entry Source


Example: Online Deactivate Request


User Name
Password


65347567
ecommerce

GC
9000000000000001
1234




3.3.11.2

Deactivate Response

A Deactivate response has the following structure. The response message is identical for Online
and Batch transactions except Online includes the  element.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message

5000



258

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Online Deactivate Response


9695064321
000
2016-07-25T15:13:43
2016-07-25
Approved
5000

0
5000
0




3.3.12

Deactivate Reversal Transactions (Online Only)

The Deactivate Reversal transaction changes the status of a newly deactivated Gift Card from
inactive to active, thus reversing the operation of an Deactivate transaction. The Deactivate
Reversal references the associated Deactivate transaction by means of the litleTxnId element
returned in the Deactivate response. This transaction type is available only for Online
transactions.
NOTE:

3.3.12.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Deactivate Reversal Request

You must structure an Deactivate Reversal request as shown in the following examples.

Transaction Id from Load Response

Reference Code from Deactivate Response
Amount from Deactivate Transaction

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

259

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Transaction Time from Deactivate Response
Trace Id from Deactivate Resp
Seq Num from Deactivate Resp

Example: Deactivate Reversal Request


User Name
Password


1234567890123456789

GC
1234102000003558
888
1234

123456
1900
2017-03-21T10:02:46
678901
123456



3.3.12.2

Deactivate Reversal Response

An Deactivate Reversal response has the following structure.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted
Response Message

260

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples



Example: Online Deactivate Reversal Response


9695064321
000
2017-03-22T15:13:43
2017-03-22
Approved

2017-03-22T12:00:00
003558
834528
123456
5000




3.3.13

Deposit Reversal Transactions (Online Only)

The Deposit Reversal transaction is a Gift Card transaction that reverses the deposit initiated by
either a Capture or Sale transaction. The Deposit Reversal references the associated Capture/Sale
transaction by means of the litleTxnId element returned in the Capture/Sale response. This
transaction type is available only for Online transactions.
NOTE:

3.3.13.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Deposit Reversal Request

You must structure an Deposit Reversal request as shown in the following examples.

Transaction Id from Load Response


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

261

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Reference Code from Gift Card Capture Resp
Amount from Gift Card Capture Resp
Transaction Time from GC Capture Response
Trace Id from GC Capture Resp
Seq Num from GC Capture Resp

Example: Deposit Reversal Request


User Name
Password


1234567890123456789

GC
1234102000003558
888

123456
1900
2017-03-21T10:02:46
678901
123456



3.3.13.2

Deposit Reversal Response

An Deposit Reversal response has the following structure.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted

262

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Response Message


Example: Online Deposit Reversal Response


9695064321
000
2017-03-22T15:13:43
2017-03-22
Approved

2017-03-22T12:00:00
003558
834528
123456
5000




3.3.14

eCheck Credit Transactions

The eCheck Credit transaction enables you to refund a previous eCheck Sale. Merchants can
submit an eCheck Credit transaction for a sale regardless or whether the original transaction was
settled by our system, although the requests are structured differently. This section contains the
following:
•

eCheck Credit Request Against a Vantiv Transaction

•

eCheck Credit Request for a Non-Vantiv Processed Sale

•

eCheck Credit Response
NOTE:

3.3.14.1

Although there are two different scenarios for eCheck Credit requests, the
response message uses the same structure.

eCheck Credit Request Against a Vantiv Transaction

To request an eCheck Credit against an eCheck Sale that had been settled by us, you only need to
specify the  element. When you specify this element, the application uses the

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

263

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

 to look up the referenced echeckSale transaction and obtain the necessary
information. In this case, the  element is optional, but should be included if the credit
amount is less than the captured amount. If you do not include the  element, the system

assumes the credit to be for the total amount of the referenced transaction.
When requesting a echeckCredit against an echeckSale that occurred within our system, specify
the Credit request as follows:

Transaction Id
Credit Amount
Secondary Amount
 (Do not use)


Example: eCheck Credit Request

The eCheck Credit batch request shown below contains three  elements. The
first two use a Transaction Id as a reference. The third, which you would use for a sale occurring
outside of our system, uses the , , , and 
elements to provide the required information.


userName
password



4455667788
1000


4455667789
1100


12z58743y1
10000
ecommerce


264

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

John Doe
123 4th street
Apt. 20
second floor
San Jose
CA
95032
USA
jdoe@isp.com
408-555-1212


Checking
5186005800001012
000010101
1104





3.3.14.2

eCheck Credit Request for a Non-Vantiv Processed Sale

If the original eCheck Sale transaction was not processed via our system, or the if the
 for the original eCheck Sale transaction is not available, specify eCheck Credit
request as follows:

Order Id
Credit Amount
Secondary Amount
Order Entry Source

 or 
 (Do not use)



The third transaction shown in the eCheck Credit Request example on page 264 shows an
example of a Credit request against a non-Vantiv processed transaction.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

265

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.3.14.3

Transaction Types and Examples

eCheck Credit Response

The eCheck Credit message is identical for either type of eCheck Credit request. The
 element is included only if you submit account information in the request
transaction for which a NOC exists. In this case the system automatically updates the information
sent to the ACH network and includes the change information in the response.
The eCheck Credit response has the following structure:

Transaction Id
Response Code
Date and Time in GMT
Response Message
Date of Posting (Online Only)
Account Change Info
 (for Tokenized merchants submitting account data)

Example: eCheck Credit Response



84568456
000
2017-04-01T10:24:31
Approved




3.3.15

eCheck Prenotification Credit Transactions (Batch Only)

You use this non-monetary transaction to verify the consumer’s account information prior to
submitting an eCheck Credit transaction (also see eCheck Prenotification on page 49). This
transaction type is only supported for US transactions.

266

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

3.3.15.1

cnpAPI Transaction Examples

eCheck Prenotification Credit Request

You must specify the eCheck Prenotification Credit request using the following format:

Order Id
Order Entry Source




Example: eCheck Prenotification Credit Request


userName
password



12z58743y1
telephone

John
Doe
123 4th street
Apt. 20
second floor
San Jose
CA
95032
USA
jdoe@isp.com
408-555-1212


Checking
5186005800001012
000010101
1104

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

267

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples






3.3.15.2

eCheck Prenotification Credit Response

The eCheck Prenotification Credit response has the following structure:

Transaction Id
Order Id
Response Code
Date and Time in GMT
Response Message

Example: eCheck Prenotification Credit Response



84568456
12z58743y1
000
2017-03-01T10:24:31
Approved


84568457
12z58743y7
000
2017-03-01T10:24:31
Approved




268

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

3.3.16

cnpAPI Transaction Examples

eCheck Prenotification Sale Transactions (Batch Only)

You use this non-monetary transaction to verify the consumer’s account information prior to
submitting an eCheck Sale transaction (also see eCheck Prenotification on page 49). This
transaction type is only supported for US transactions.

3.3.16.1

eCheck Prenotification Sale Request

You must specify the eCheck Prenotification Credit request using the following format:

Order Id
Order Entry Source




Example: eCheck Prenotification Sale Request


userName
password



12z58743y1
telephone

John
Doe
123 4th street
Apt. 20
second floor
San Jose
CA
95032
USA
jdoe@isp.com
408-555-1212

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

269

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples



Checking
5186005800001012
000010101
1104





3.3.16.2

eCheck Prenotification Sale Response

The eCheck Prenotification Sale response has the following structure:

Transaction Id
Order Id
Response Code
Date and Time in GMT
Response Message

Example: eCheck Prenotification Sale Response



84568456
12z58743y1
000
2017-03-01T10:24:31
Approved


84568457
12z58743y7
000
2017-03-01T10:24:31

270

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Approved




3.3.17

eCheck Redeposit Transactions

You use this transaction type to manually attempt redeposits of eChecks returned for either
Insufficient Funds or Uncollected Funds. You can use this element in either Batch or Online
transactions.
NOTE:

3.3.17.1

Do not use this transaction type if you are enabled for the Auto Redeposit
feature. If you are enabled for the Auto Redeposit feature, the system will
reject any echeckRedeposit transaction you submit.

eCheck Redeposit Request

You must specify the eCheck Redeposit request using the following format:

Transaction Id
 or 



NOTE:

If you include the echeck element, the values submitted for accType,
accNum, and routingNum children must match those submitted in the
original echeckSale transaction.

Example: Online eCheck Redeposit Request


User Name
password



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

271

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

345454444

Checking
1099999903
114567895


New Marketing Campaign




Example: Batch eCheck Redeposit Request


User Name
Password



3456456444

ABC Marketing



3456456449

Checking
1099999903
114567895


ABC Marketing



3456557123

Savings
10999999444

272

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

114567895


ABC Marketing



123456789




3.3.17.2

eCheck Redeposit Response

The eCheck Redeposit response indicates that we have received your eCheck Redeposit request.
This does not indicate when funds will be transferred. The  element is
included only if the account information submitted in the request transaction has changed (NOC
exists). In this case the system automatically updates the information sent to the ACH network
and includes the change information in the response.
The eCheck Sale response has the following structure:

Transaction Id
Response Code
Date and Time in GMT
Response Message
Date of Posting (Online Only)
Account Change Info

Example: Batch eCheck Redeposit Response



84568456
000
2017-06-01T10:24:31
Approved

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

273

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples



84568457
000
2017-06-01T10:24:31
Approved


Checking
5186005800001012
000010101


Checking
5499576040500006
000010102






3.3.18

eCheck Sale Transactions

You use the eCheck Sale transaction to capture funds from a customer paying via electronic
checks. It is the eCheck equivalent of a Capture transaction. Setting the  element to
true triggers an eCheck Verification operation prior to the capture. If the verification fails, the
system does not process the capture operation.
NOTE:

To perform a verification you must include the following optional children
of the billToAddress element in your request: firstName, lastName,
companyName (if accType = Corporate or Corp Savings), address1
(address 2 and 3 if needed), city, state, zip, and phone.
The value for the orderSource element must be one of the following:
telephone, ecommerce, or recurringtel.

3.3.18.1

eCheck Sale Request

You must specify the eCheck Sale request using the following format:


274

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Order Id
true or false
Authorization Amount
Secondary Amount
Order Entry Source


 or 
 (Do not use)



Example: Batch eCheck Sale Request


userName
password



12z58743y1
true
10000
telephone

John
Doe
123 4th street
Apt. 20
second floor
San Jose
CA
95032
USA
jdoe@isp.com
408-555-1212


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

275

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples


Checking
5186005800001012
000010101
1104





3.3.18.2

eCheck Sale Response

The eCheck Sale response indicates that we have received your eCheck Sale request. This does
not indicate when funds will be transferred. The  element is included only if
the account information submitted in the request transaction has changed (NOC exists). In this
case the system automatically updates the information sent to the ACH network and includes the
change information in the response.
NOTE:

The schema for echeckSalesResponse includes a verificationCode
child element. This element is not used at this time.

The eCheck Sale response has the following structure:

Transaction Id
Response Code
Date and Time in GMT
Response Message
Date of Posting (Online Only)
Account Change Info
 (for Tokenized merchants submitting account data)

Example: Batch eCheck Sale Response

The response example below includes the accountUpdater element, which indicates that there
is a NOC against the account and provides the new account information. If the request used a
token, the accountUpdater element would have children providing the original and new token
information.

276

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples




84568456
000
2016-09-01T10:24:31
Approved


84568457
000
2016-09-01T10:24:31
Approved


Checking
5186005800001012
000010101


Checking
5499576040500006
000010102






3.3.19

eCheck Verification Transactions

You use an eCheck Verification transaction to initiate a comparison to a database containing
information about checking accounts. The database may include information as to whether the
account has been closed, as well as whether there is a history of undesirable behavior associated
with the account/account holder. This transaction type is only supported for US transactions.
NOTE:

While eCheck Verification is a valuable tool that you can use to reduce
possible fraud and loss, unlike a credit card authorization, it does not
check for the availability of funds, nor does it place a hold on any funds.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

277

cnpAPI Reference Guide
cnpAPI Transaction Examples

3.3.19.1

Transaction Types and Examples

eCheck Verification Request

You must specify the eCheck Verification request using the following format:
IMPORTANT: For an eCheckVerification transaction, you must submit the
firstName and lastName elements instead of the name element
(middleInitial is optional). For a corporate account you must include
the companyName element in addition to the firstName and lastName
elements. In both cases, you also must include the address, city,
state, zip and phone information.
For a corporate account, if you do not have the name of the check issuer,
you can use a value of “unavailable” for the firstName and lastName
elements.


Order Id
Authorization Amount
Order Entry Source

 or 


Example: eCheck Verification Request - Personal Checking


userName
password



12z58743y1
10000
telephone

John
Doe
123 4th street
Apt. 20

278

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

second floor
San Jose
CA
95032
USA
jdoe@isp.com
408-555-1212


Checking
5186005800001012
000010101
1104


New Campaign





Example: eCheck Verification Request - Corporate Account
NOTE:

If you do not have the name of the check issuer, you can use a value of
“unavailable” for the firstName and lastName elements.



userName
password



12z58743y1
10000
telephone

Paul
Jones
Widget Company

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

279

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

123 4th street
Apt. 20
second floor
San Jose
CA
95032
USA
pjones@isp.com
408-555-1212


Corporate
5186005800001012
000010101
1104



8.6

3.3.19.2

eCheck Verification Response

The  element is included only if the account information submitted in the
request transaction has changed (NOC exists). In this case the system automatically updates the
information sent to the ACH network and includes the change information in the response.
The eCheck Verification response has the following structure:

Transaction Id
Response Code
Date and Time in GMT
Response Message
Date of Posting (Online Only)
 (for Tokenized merchants submitting account data)
Account Change Info

Example: eCheck Verification Response



84568456
000
2016-09-01T10:24:31
Approved


84568457
000
2016-09-01T10:24:31
Approved


Checking
5186005800001012
000010101


Checking
5499576040500006
000010102






3.3.20

eCheck Void Transactions (Online Only)

You use an eCheck Void transaction to either halt automatic redeposit attempts of eChecks
returned for either Insufficient Funds or Uncollected Funds, or cancel an eCheck Sale transaction,
as long as the transaction has not yet settled. This also applies to merchant initiated redeposits.
You can use this element only in Online transactions.

3.3.20.1

eCheck Void Request

The eCheck Void request references the  of the previously approved transaction.
You must structure an eCheck Void request as follows.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

281

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples


Transaction Id

Example: eCheck Void Request


User Name
Password


345454444



3.3.20.2

eCheck Void Response

The eCheck Void response has the following structure.
"1"
Transaction Id
Response Code
Date and Time in GMT
Date of Posting
Response Message

Example: Online eCheck Void Response


21200000026600
000
2017-06-17T21:20:50
Approved
2017-06-17



282

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

3.3.21

cnpAPI Transaction Examples

Force Capture Transactions

A Force Capture transaction is a Capture transaction used when you do not have a valid
Authorization for the order, but have fulfilled the order and wish to transfer funds.
CAUTION:

3.3.21.1

Merchants must be authorized by Vantiv before submitting transactions of
this type. In some instances, using a Force Capture transaction can lead
to chargebacks and fines.

Force Capture Request

You must specify the Force Capture request as follows. The structure of the request is identical
for either an Online or a Batch submission.

Order Id
Force Capture Amount
Secondary Amount
Order Entry Source

[  |  | ]

payment or fee





true or false
processingType Enum

Example: Batch Force Capture Request



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

283

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

userName
password



orderId
10000
ecommerce

VI
4005550000081019
0910


PO12345
125
false
0
495
0
01851
01851
USA
123456
2016-09-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0

284

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

300
93.80

true
55
0.0059
03
011234567







Example: Online Force Capture Request


userName
password


orderId
10000
ecommerce

VI
4005550000081019
0907


PO12345
125
false
0
495
0
01851
01851
USA
123456

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

285

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

2016-08-14

true
55
0.0059
00
011234567


1
chair
CH123
1
EACH
125
9380
9505
0
300
93.80





3.3.21.2

Force Capture Response

The Force Capture response message is identical for Online and Batch transactions, except Online
includes the  element. The Force Capture response has the following structure:

Transaction Id
Response Code
Date and Time in GMT
Date of Posting (Online Only)
Response Message
 (for Tokenized merchants submitting card data)



286

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Batch Force Capture Response


id="123"



84568457
000
2016-09-01T10:24:31
Approved




Example: Online Force Capture Response


1100030204
000
2016-07-11T14:48:48
2016-07-11
Approved



Example: Force Capture Response for Tokenized Merchant Sending Card Data

A tokenized merchant that includes card information in the request receives a response message
that includes the token element. The example below is an Online response.

21200000039504
000
2016-10-20T18:25:38
2016-10-20
Approved

111310880008000
801
Account number was successfully registered
AX

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

287

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples





3.3.22

Fraud Check Transaction

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.

3.3.22.1

Fraud Check Request

You must specify the Fraud Check request as follows.





Example: Fraud Check Request


User Name
password



ASDFG-AXXXXAB999
Attribute passed to ThreatMetrix
Attribute passed to ThreatMetrix
Attribute passed to ThreatMetrix
Attribute passed to ThreatMetrix
Attribute passed to ThreatMetrix


John Doe
15 Main Street
San Jose

288

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

CA
95032-1234
USA
9782750000
jdoe@vantiv.com


Jane Doe
15 Main Street
San Jose
CA
95032-1234
USA
9782750000
jdoe@vantiv.com




3.3.22.2

Fraud Check Response

A Fraud Check response has the following structure.

Transaction Id
Response Code
Response Message
Date and Time in GMT


Example: Fraud Check Response


82823534116454639
000
Approved
2016-11-08T21:36:50

pass

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

289

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

50
FlashImagesCookiesDisabled




3.3.23

Gift Card Auth Reversal Transactions

The Gift Card Auth Reversal transaction allows you to reverse an authorization against a
closed-loop gift card; thereby, removing the funds hold established by the authorization.

3.3.23.1

Gift Card Auth Reversal Request

You must specify the Gift Card Auth Reversal request as follows. The structure of the request is
identical for either an Online or a Batch submission.

Transaction Id from Auth Response

Auth Code from Auth Response
Amount from Auth Response
txnTime from Auth Response
systemTraceId from Auth Rsp
sequenceNumber from Auth Rsp

Example: Online Gift Card Auth Reversal


User Name
Password


82823534116454002

GC
9000000000000001

290

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

1234

123456
40000
2016-07-25T15:13:43
654321
456789



3.3.23.2

Gift Card Auth Reversal Response

A Gift Card Auth Reversal response has the following structure. The response message is
identical for Online and Batch transactions except Online includes the  element.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message


Example:


9695064321
000
2017-03-25T15:13:43
2017-03-25
Approved

2017-03-25T15:13:38
123456
123456
123456
5000


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

291

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples




3.3.24

Gift Card Capture Transactions

The Gift Card Capture transaction allows you to capture (settle) funds previously authorized on a
Closed-loop gift card. Unlike the Capture transaction used for a credit card transaction, a Gift
Card Capture requires you to provide both the capture amount and the original (authorized)
amount. If the transaction is a partial capture, the capture amount will be less than the original
amount, with the remainder available for future capture.

3.3.24.1

Gift Card Capture Request

You must specify the Gift Card Capture request as follows. The structure of the request is
identical for either an Online or a Batch submission.

Transaction Id from Auth Response
Amt of Capture

Auth Code from Auth Response
Amount from Auth Request
txnTime from Auth Response

Example: Gift Card Capture Request


User Name
Password


82823534116454002
40000

GC
9000000000000001


292

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

123456
40000
2016-07-25T15:13:43



3.3.24.2

Gift Card Capture Response

A Gift Card Capture response has the following structure. The response message is identical for
Online and Batch transactions except Online includes the  element.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message




Example: Gift Card Capture Response


9695064321
000
2017-03-25T15:13:43
2017-03-25
Approved

2017-03-25T15:13:38
123456
123456
123456
5000



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

293

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples



3.3.25

Gift Card Credit Transactions

The Gift Card Credit transaction allows you to refund funds previously captured on a Closed-loop
gift card.

3.3.25.1

Gift Card Credit Request

You must specify the Gift Card Credit request as follows. There are two possible structures for
this transaction type. You use the structure containing the litleTxnId element, when the Vantiv
processed the capture transaction. You use the structure containing the orderId, when the
processor of the capture transaction was not Vantiv. Typically, this occurs when you first migrate
your processing to Vantiv. The structures of the requests are identical for either an Online or a
Batch submission.

Transaction Id from Auth Response
Amt of Credit



or

Order Id from Capture
Amt of Credit



Example: Online Gift Card Credit Transaction (Vantiv Processed Capture)


User Name
Password


82823534116454002

294

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

40000

GC
9000000000000001




Example: Online Gift Card Credit Transaction (Non-Vantiv Processed Capture)


User Name
Password


116454002
4000
ecommerce

GC
9000000000000001




3.3.25.2

Gift Card Credit Response

A Gift Card Credit response has the following structure. The response message is identical for
either request structure, as well as Online and Batch transactions except Online includes the
 element.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

295

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples




Example: Gift Card Credit Response


9695064321
000
2017-03-22T15:13:43
2017-03-22
Approved

2017-03-22T12:00:00
003558
834528
123456
0




3.3.26

Load Transactions

The Load transaction adds funds to an active Gift Card. The load amount cannot exceed the
maximum allowed amount for the Gift Card. If you attempt to load more than the maximum
amount, the transaction will be declined with a response Code of 221 - Over Max Balance.
NOTE:

3.3.26.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Load Request

You must specify the Load request as follows. The structure of the request is identical for either
an Online or a Batch submission.

Order Id

296

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Amount to Load
Order Entry Source


Example: Online Load Request


User Name
Password


65347567
40000
ecommerce

GC
9000000000000001
888
1234




3.3.26.2

Load Response

A Load response has the following structure. The response message is identical for Online and
Batch transactions except Online includes the  element.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted (Online Only)
Response Message



Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

297

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples


Example: Load Response


9695064321
000
2017-03-22T15:13:43
2017-03-22
Approved

2017-03-22T15:13:38
123456
123456
123456
5000




3.3.27

Load Reversal Transactions (Online Only)

The Load Reversal transaction reverses the operation of a Load transaction, removing the newly
loaded amount from the Gift Card. The Load Reversal references the associated Load transaction
by means of the litleTxnId element returned in the Load response. You cannot perform a
partial Load Reversal. This transaction always reverses the full amount of the referenced Load
transaction. This transaction type is available only for Online transactions.
NOTE:

3.3.27.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Load Reversal Request

You must structure a Load Reversal request as shown in the following examples.

Transaction Id from Load Response

298

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples


Reference Code from Load Response
Amount from Load Transaction
Transaction Time from Load Response
Trace Id from Load Response
Seq Num from Load Rsp

Example: Online Load Reversal Request


User Name
Password


1234567890123456789

GC
1234102000003558
888
1234

123456
1900
2017-03-21T10:02:46
678901
123456



3.3.27.2

Load Reversal Response

An Load Reversal response has the following structure.

Transaction Id
Response Code

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

299

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Date and Time in GMT
Date transaction posted
Response Message


Example: Online Load Reversal Response


9695064321
000
2017-03-22T15:13:43
2017-03-22
Approved

2017-03-22T12:00:00
003558
834528
123456
0




3.3.28

Status Query Transactions (Online Only)

You use a Status Query Transaction to verify the status of an Online transaction submitted within
the prior 24 hours. As search criteria, you must submit, at a minimum, the id (the id attribute)
and transaction type (i.e., authorization, deposit, void, etc.) of the original transaction, but to
narrow the search, you can also include the transaction id from the original transaction. This
transaction type is available only for Online transactions.
NOTE:

300

You must be specifically enabled to use this transaction type. Please
speak to your Implementation Consultant or Relationship Manager for
additional information.

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

3.3.28.1

cnpAPI Transaction Examples

Query Transaction Request

You must structure your Query request as shown below. The origId and origActionType
elements are required.
NOTE:

If submitting a query for an eCheck transaction, do not include the
account number. Use the origAccountNumber element for
Credit/Debit/Gift cards only.


id Attribute for Original Transaction
Code for type of Original Transaction
litleTxnId from Original Transaction

Example: Query Transaction Request


User Name
Password


834262
A
9695061110103040608



3.3.28.2

Query Transaction Response

The structure of the Query Transaction response message can vary according to the results of the
query. The results can include a single or multiple transactions that meet the query criteria, no
results, if nothing was found, or a limited response, if a transaction was found, but processing was
not complete. The structure of the response message will be as follows:

Response Code
Date and Time in GMT
Response Message

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

301

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Number of Matches Found


or
One or more (10 max) found transaction responses of type specified in the
queryTransaction


Example: Query Transaction Response with One Found Transaction


150
2017-04-06T16:40:24
Original transaction found
1


82827170811986124
150330_GCAuth
000
2017-04-06T16:40:04
2017-04-06
Approved
111115

30
M


125






302

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

Example: Query Transaction Response with Multiple Found Transactions
NOTE:

This response only occurs if you fail to use unique values for the id
attribute, when submitting transactions.



150
2017-04-06T16:40:24
Original transaction found
2


82827170811986215
150331_DupeAuth2
000
2017-04-06T16:40:12
2017-04-06
Approved
055858

32
M



82827170811986207
150331_DupeAuth1
000
2017-04-06T16:40:11
2017-04-06
Approved
111111

00
M






Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

303

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

Example: Query Transaction Response with No Found Transaction


151
2017-04-06T16:40:30
Original transaction not found
0




Example: Query Transaction Response with Transaction Found, but not
Complete


152
2016-04-06T16:40:30
Original transaction found but response not yet
available
1


82827170811986124
152
Original transaction found but response not yet
available





3.3.29

Refund Reversal Transactions (Online Only)

The Refund Reversal transaction is a Gift Card only transaction that reverses the operation of a
Refund transaction on the Gift Card. The Refund Reversal references the associated Credit
transaction by means of the litleTxnId element returned in the Credit response. You cannot

304

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

cnpAPI Transaction Examples

perform a partial Refund Reversal. This transaction always reverses the full amount of the
referenced Refund transaction. This transaction type is available only for Online transactions.
NOTE:

3.3.29.1

You must be enabled for (Closed Loop) Gift Card transactions to use this
transaction type. Please consult your Relationship Manager for additional
information about Gift Card transactions.

Refund Reversal Request

You must structure a Refund Reversal request as shown in the following examples.

Transaction Id from CGCredit Response

Reference Code from CGCredit Response
Amount from CGCredit Transaction
Transaction Time from CGCredit Response
Trace Id from CGCredit Response
Seq Num from CGCredit Rsp


Example: Online Refund Reversal Request


User Name
Password


1234567890123456789

GC
1234102000003558
888
1234

123456

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

305

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

1900
2017-03-21T10:02:46
678901
123456



3.3.29.2

Refund Reversal Response

An Refund Reversal response has the following structure.

Transaction Id
Response Code
Date and Time in GMT
Date transaction posted
Response Message



Example: Online Refund Reversal Response


9695064321
000
2017-03-22T15:13:43
2017-03-22
Approved

2017-03-22T12:00:00
003558
834528
123456
0



306

Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

cnpAPI Reference Guide
Transaction Types and Examples

3.3.30

cnpAPI Transaction Examples

Register Token Transactions

The Register Token transaction enables you to submit a credit card number, eCheck account
number, or Registration Id to us and receive a token in return. While you can submit Register
Token transactions at any time, typically, you would make use of this transactions when initially
converting to the use of tokens. In this case you would submit large quantities of credit
cards/eCheck account numbers in Batches and replace them in your database with the tokens
returned.
NOTE:

3.3.30.1

When initially tokenizing your customer database, Vantiv recommends
that you collect all distinct credit card numbers and submit the
information in one or more large Session files. When you receive the
response file, parse the returned token information to your database,
replacing the card numbers.

Register Token Request

You must specify the Register Token request as follows. The structure of the request is identical
for either an Online or a Batch submission. The child elements used differ depending upon
whether you are registering a credit card account, an eCheck account, or submitting a Registration
Id.
When you submit the CVV2/CVC2/CID in a registerTokenRequest, the platform encrypts
and stores the value on a temporary basis for later use in a tokenized Auth/Sale transaction
submitted without the value. This is done to accommodate merchant systems/workflows where
the security code is available at the time of token registration, but not at the time of the Auth/Sale.
If for some reason you need to change the value of the security code supplied at the time of the
token registration, use an updateCardValidationNumOnToken transaction. To use the store
value when submitting an Auth/Sale transaction, set the cardValidationNum value to 000.
NOTE:

The use of the cardValidationNum element in the
registertokenRequest only applies when you submit an
accountNumber element.

For credit cards:

Order Id
Card Account Number
CVV2/CVC2/CID


Document Version: 1.8 — cnpAPI Release: 11.3

© 2017 Vantiv, LLC - All Rights Reserved.

307

cnpAPI Reference Guide
cnpAPI Transaction Examples

Transaction Types and Examples

For eCheck accounts:

Order Id

Account Number
Routing Number



For Registration Ids:

Order Id



For Mobile POS transactions:

Order Id

Key Serial Number
Format of Encrypted Track
Encrypted Track Data
Track Read Status - 0 or 1
Track Read Status - 0 or 1



For Apple Pay transactions:

Order Id

Encrypted Payment Data
Hash of Application Data Property Ephemeral Public Key Merchant Cert Encoded Public Key 308 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples Transaction Id from Device
Signature of Payment and Header Data Payment Token Version
Example: Batch Register Token Request - Credit Card userName password F12345 4005101001000002 999 Example: Batch Register Token Request - eCheck userName password F12345 12345678901234567 000010101 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 309 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples Example: Batch Register Token Request - paypageRegistationId userName password F12345 12345678901234567 3.3.30.2 Register Token Response There is no structural difference an Online and Batch response; however, some child elements change depending upon whether the token is for a credit card account or an eCheck account. The response will have one of the following structures. Register Token response for Credit Cards: Transaction Id Token BIN Method of Payment Response Code Response Message Response Time Register Token response for eChecks: Transaction Id Token Method of Payment 310 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples Last 3 of Acct Number Response Code Response Time Response Message Register Token response for ApplePay: Transaction Id Token Method of Payment Response Code Response Time Response Message App PAN Exp Date Currency Code Amount of Transaction Name of cardholder Device Mfr Id Type of Payment Data Payment Cryptogram eCommerece Indicator Example: Batch Register Token Response - Credit Card 21122700 1111000100360002 400510 VI 801 2016-10-26T17:21:51 Account number was successfully registered Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 311 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples Example: Batch Register Token Request - eCheck 21122700 1111000100360002 VI 511 801 2016-10-26T17:21:51 Account number was successfully registered 3.3.31 RFR Transactions (Batch Only) An RFR (Request For Response) transaction enables you to request a response file for a previously submitted Batch. You make the request by submitting either the litleSessionId of the Batch, or in the case of a request for an Account Updater file, the accountUpdateFileRequestData element. NOTE: 3.3.31.1 The use of RFR transactions for Account Updater files apply only to the legacy Account Updater solution. RFR Request You must specify the RFR request as follows. 312 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples Example: RFR Request for Payment Transaction Batch The following example shows an RFR request for the response, with 7766554321 as the value of the element. userName password 7766554321 Example: RFR Request for an Account Updater File userName password 100 2017-01-15 3.3.31.2 RFR Response When using an RFR request to obtain the response file for a payment transaction Batch, the RFR response is exactly the same as the original session response associated with the you submitted in the RFR request. The session ID returned in the response will be the session ID of the original session. When using an RFR request in an Account Updater scenario, you will receive either an Account Updater Completion response, if the file is ready, or an Account Updater RFR “not ready” response, as shown in the example below. Example: Account Updater RFR “not ready” Response 3.3.32 Sale Transactions The Sale transaction enables you to both authorize fund availability and deposit those funds by means of a single transaction. The Sale transaction is also known as a conditional deposit, because the deposit takes place only if the authorization succeeds. If the authorization is declined, the deposit will not be processed. NOTE: 3.3.32.1 If the authorization succeeds, the deposit is processed automatically, regardless of the AVS, CVV2, CVC2, or CID response, except for American Express transactions. For American Express, a failure to match the security code (CID) results in a declined transaction with the Response Reason Code of 352 - Decline CVV2/CID Fail. Sale Request You must specify the Sale request as follows. The structure of the request is identical for either an Online or a Batch submission. NOTE: When you submit the CVV2/CVC2/CID in a registerTokenRequest, the platform encrypts and stores the value on a temporary basis for later use in a tokenized Auth/Sale transaction submitted without the value. To use the store value when submitting an Auth/Sale transaction, set the cardValidationNum value to 000. Order Id Authorization Amount Secondary Amount Order Entry Source [|||||| |||giropay>] (Choice) 314 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples payment or fee Send true in the final Sale (for Recycling Engine merchants) (for Recurring Engine merchants) true or false processingType Enum Network Txn Value Amount from Orig Txn Example: Batch Sale Request userName password 12z58743y1 12522 ecommerce John Doe Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 315 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples 123 4th street Apt. 20 second floor San Jose CA 95032 USA jdoe@isp.com 408-555-1212 MC 5186005800001012 1110 Example: Online Sale Request NOTE: The example below includes an value of 3dsAuthenticated and includes the information. Use this value only if you are a 3DS merchant and authenticated the cardholder. Also, the values for the and elements in the example below have been truncated. User Name password 5234234 40000 3dsAuthenticated John Smith 100 Main St 316 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples 100 Main St 100 Main St Boston MA 12345 US jsmith@someaddress.com 555-123-4567 VI 4005550000081019 1210 555 BwABBJQ1AgJDUCAAAAAAA= gMV75TAgk= 8888888888 bdi*Vantiv Test PO12345 125 false 0 495 0 01851 01851 USA 123456 2016-08-14 true 55 0.0059 00 011234567 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 317 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples 1 chair CH123 1 EACH 125 9380 9505 0 300 93.80 true 55 0.0059 03 011234567 2 table TB123 1 EACH 30000 0 300 300.00 Example: Online Sale Request - SEPA Direct Debit User Name password 318 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples 5234234 40000 3dsAuthenticated John Smith 100 Main St 100 Main St 100 Main St Boston MA 12345 US jsmith@someaddress.com 555-123-4567 Vantiv OneTime DE89370400440532013000 DE 3.3.32.2 Sale Response The Sale response message is identical for Online and Batch transactions except Online includes the postDate element. The Sale response has the following structure: Transaction Id Response Code Order Id Date and Time in GMT Date of Posting (Online Only) Response Message Approval Code Approved amount for partial Auth Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 319 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples (for Tokenized merchants submitting card data) (included for declined Auths if featrure is enabled) (for Recurring Engine merchants) (included if Gift Card is Method of Payment) (included if an ApplePay transaction) Card Last 4 (included for ApplePay using VI or MC) Txn ID returned from network Example: Batch Sale Response 84568456 000 12z58743y1 2016-09-01T10:24:31 Approved 123456 00 84568457 000 12z58743y7 2016-09-01T10:24:31 Approved 123456 00 2 320 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples Example: Online Sale Response 1100030055 000 23423434 2016-07-11T14:48:46 2011-07-11 Approved 123457 01 U 2 Example: Online Sale Response for Tokenized Merchant Sending Card Data A tokenized merchant that includes card information in the request receives a response message that includes the token element. The example below is an Online response. 21200000028606 000 F12345 2016-10-26T17:30:00 2011-10-26 Approved 089510 11 P Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 321 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples 1111000100329510 801 Account number was successfully registered VI 432610 Example: Online Sale Response with Account Updater Info 1100030055 000 23423434 2017-07-11T14:48:46 2011-07-11 Approved 123457 VI 4234823492346234 1112 VI 4234823490005777 1114 01 U 2 322 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples Example: Batch Sales Response with Recurring Info The following is an example of the Recurring Response file produced daily to provide information about the transactions submitted by the Recurring Engine. This file is delivered via sFTP. 82912082263409610 000 recurring_appr1 2017-01-30T20:15:51 Approved 11111 01 82912081866997773 473 Scheduled recurring payment processed 211014241510 82912082263410311 000 recurring_appr2 2017-01-30T20:15:55 Approved 123457 00 82912081866997799 473 Scheduled recurring payment processed 211014245016 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 323 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples 82912082263410337 110 recurring_decline1 2017-01-30T20:15:56 Insufficient Funds 34 true 82912081866997807 473 Scheduled recurring payment processed 211014245115 82912082263410378 110 recurring_decline3 2017-01-30T20:15:56 Insufficient Funds 34 true 82912081866997807 473 Scheduled recurring payment processed 211014245313 324 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples 3.3.33 cnpAPI Transaction Examples Unload Transactions The Unload transaction removes funds from an active Gift Card. The unload amount cannot exceed the available balance on the Gift Card. If you attempt to unload more than the available balance, the transaction will be declined with a response Code of 209 - Invalid Amount. NOTE: 3.3.33.1 You must be enabled for (Closed Loop) Gift Card transactions to use this transaction type. Please consult your Relationship Manager for additional information about Gift Card transactions. Unload Request You must specify the Unload request as follows. The structure of the request is identical for either an Online or a Batch submission. Order Id Amount to Load Order Entry Source Example: Online Unload Request User Name Password 65347567 40000 ecommerce GC 9000000000000001 1234
Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 325 cnpAPI Reference Guide cnpAPI Transaction Examples 3.3.33.2 Transaction Types and Examples Unload Response An Unload response has the following structure. The response message is identical for Online and Batch transactions except Online includes the element. Transaction Id Response Code Date and Time in GMT Date transaction posted (Online Only) Response Message Example: Unload Response 9695064321 000 2017-03-22T15:13:43 2017-03-22 Approved 2017-03-22T12:00:00 003558 834528 123456 0 3.3.34 Unload Reversal Transactions (Online Only) The Unload Reversal transaction reverses the operation of a Unload transaction, returning the value removed from the Gift Card by the Unload transaction. The Unload Reversal references the associated Unload transaction by means of the litleTxnId element returned in the Unload response. You cannot perform a partial Unload Reversal. This transaction always reverses the full 326 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples amount of the referenced Unload transaction. This transaction type is available only for Online transactions. NOTE: 3.3.34.1 You must be enabled for (Closed Loop) Gift Card transactions to use this transaction type. Please consult your Relationship Manager for additional information about Gift Card transactions. Unload Reversal Request You must structure a Unload Reversal request as shown in the following examples. Transaction Id from CGCredit Response Reference Code from Unload Response Amount from Unload Transaction Transaction Time from Unload Response Trace Id from Unload Response Seq Num from Unload Rsp Example: Online Unload Reversal Request User Name Password 1234567890123456789 GC 1234102000003558 888 1234 123456 1900 2017-03-21T10:02:46 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 327 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples 678901 123456 3.3.34.2 Unload Reversal Response An Unload Reversal response has the following structure. Transaction Id Response Code Date and Time in GMT Date transaction posted Response Message Example: Online Unload Reversal Response 9695064321 000 2017-03-22T15:13:43 2017-03-22 Approved 2017-03-22T12:00:00 003558 834528 123456 0 328 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples 3.3.35 cnpAPI Transaction Examples Update Plan Transactions You use the Update Plan transaction to activate/deactivate Plans associated with recurring payments. When you deactivate a Plan, by setting the active flag to false, you can no longer reference that Plan for use with subscriptions. Existing subscriptions already using the deactivated Plan will continue to use the Plan until the subscription is either modified or completed. You can also reactivate a deactivated Plan by updating the Plan and setting the active flag to true. 3.3.35.1 Update Plan Request You must structure an Update Plan request as shown in the following examples. The structure of the request is identical for either an Online or a Batch submission. Plan Reference Code true or false Example: Online Update Plan Request User Name password Reference_Code false 3.3.35.2 Update Plan Response An Update Plan response has the following structure. The response message is identical for Online and Batch transactions. Transaction Id Response Code Response Message Date and Time in GMT Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 329 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples Plan Reference Code
Example: Online Update Plan Response 1100030055 000 Approved 2017-07-11T14:48:46 Reference_Code 3.3.36 Update Subscription Transactions The Update Subscription transaction allows you to change certain subscription information associated with a recurring payment. Using this transaction type you can change the plan, card, billing information, and/or billing date. You can also create, update, or delete a Discount and/or an Add On. NOTE: 3.3.36.1 You can include multiple create, update, and delete Discounts and Add On operations in a single updateSubscription transaction. Update Subscription Request You must structure an Update Subscription request as shown in the following examples. The structure of the request is identical for either an Online or a Batch submission. Subscription Id Plan Reference Code
[ | | ] New Billing Date 330 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples cnpAPI Transaction Examples
User Name password 1234 Gold_Monthly John Smith 100 Main St Boston MA 12345 US jsmith@someaddress.com 555-123-4567 VI 4005550000081019 1210 555 1GBExtra 1WF One_GB_Extra 500 2017-07-15 2017-07-22 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 331 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples 3.3.36.2 Update Subscription Response An Update Subscription response has the following structure. The response message is identical for Online and Batch transactions. Transaction Id Response Code Response Message Date and Time in GMT ID of Subscription Canceled (For Tokenized Merchants submitting Card/Paypage) Example: Online Update Subscription Response 1100030055 000 Approved 2017-06-11T14:48:46 123457 3.3.37 Update Card Validation Number Transactions When you submit the CVV2/CVC2/CID in a registerTokenRequest, the platform encrypts and stores the value on a temporary basis for later use in a tokenized Auth/Sale transaction submitted without the value. This is done to accommodate merchant systems/workflows where the security code is available at the time of token registration, but not at the time of the Auth/Sale. If for some reason you need to change the value of the security code supplied at the time of the token registration, use an updateCardValidationNumOntoken transaction. 332 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples NOTE: 3.3.37.1 cnpAPI Transaction Examples You should only use this transaction type if you had previously submitted the account number and security code in a registerTokenRequest transaction and now need to change the CVV2/CVC2/CID value. Update Card Validation Number Request The updateCardValidationNumOnToken transaction has the following structure: Order Id Token CVV2/CVC2/CID Value Example: Online Update Card Validation Number Request F12345 1111000101039449 987 3.3.37.2 Update Card Validation Number Response The updateCardValidationNumOnTokenResponse transaction has the following structure: Transaction Id Response Code Response Message Date and Time in GMT Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 333 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples Example: Online Update Card Validation Number Response 21122700 803 Card Validation Number Updated 2017-06-09T17:21:51 3.3.38 Void Transactions (Online Only) You use a Void transaction to cancel a transaction that occurred during the same business day. You can void Capture, Credit, and Sale transactions. Also, if you use Recycling Engine, you can use the void transaction to halt the recycling of a sale transaction. In this case the response may include the recycling element. (see Using Void to Halt Recycling Engine on page 86). NOTE: Do not use Void transactions to void an Authorization. To remove an Authorization use an Authorization Reversal transaction (see Authorization Reversal Transactions on page 220.) If you attempt to void a transaction after the cutoff time, the system returns a response code of 362 and the message, Transaction Not Voided - Already Settled. In this situation, you can cancel the original transaction by using its reverse transaction, as shown in Table 3-2. TABLE 3-2 334 Cancelling a Transaction That Cannot Be Voided If you had originally sent this transaction... Cancel it by using this transaction... Capture Transactions Credit Transactions Sale Transactions Credit Transactions Credit Transactions Sale Transactions Force Capture Transactions Credit Transactions Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide Transaction Types and Examples 3.3.38.1 cnpAPI Transaction Examples Void Request The Void request references the of the previously approved transaction. You must structure a Void request as follows. Transaction Id Example: Online Void Request User Name Password 345454444 3.3.38.2 Void Response The Void response has the following structure. Transaction Id Response Code Date and Time in GMT Date of Posting Response Message (May be included if halting recycling.) Example: Online Void Response 1100026202 000 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 335 cnpAPI Reference Guide cnpAPI Transaction Examples Transaction Types and Examples 2017-06-16T19:43:38 2017-06-16 Approved Example: Online Void Response with Recycling Element When you use a Void transaction to halt recycling, the response may include the recycling element. (see Using Void to Halt Recycling Engine on page 86). 1100026202333456789 000 2017-06-16T19:43:38 2017-06-16 Approved 1234567890123456789
336 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 4 CNPAPI ELEMENTS This chapter provides definitions for the elements and attributes used by the cnpAPI. This information is intended to be used in combination with the various cnpAPI schema files to assist you as you build the code necessary to submit transactions to our transaction processing systems. Each section defines a particular element, its relationship to other elements (parents and children), as well as any attributes associated with the element. For additional information on the structure of cnpAPI requests and responses using these elements, as well as XML examples, please refer to Chapter 3, "cnpAPI Transaction Examples". The XML elements defined in this chapter are listed alphabetically. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 337 cnpAPI Reference Guide cnpAPI Elements 4.1 accNum accNum The accNum element is a required child of the echeck, originalAccountInfo, and newAccountInfo elements defining the account number of the eCheck account. Type = String; minLength = 4; maxLength = 17 NOTE: Although the schema does not specify a minimum length for the accNum element, the number must be greater than or equal to 4 characters for the transaction to succeed. Parent Elements: echeck, newAccountInfo, originalAccountInfo, accountInfo Attributes: None Child Elements: None 338 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide accountInfo 4.2 cnpAPI Elements accountInfo The accountInfo element is a required child of the submerchantCredit, and submerchantDebit transactions. It contains child elements used to provide details concerning the Sub-merchant account. Parent Elements: submerchantCredit, submerchantDebit, vendorCredit, vendorDebit Attributes: None Child Elements: Required: accType, accNum, routingNum Optional: ccdPaymentInformation NOTE: Although shown as an optional element in the schema, the checkNum element should not be used as a child of acccountInfo. Example: accountInfo Structure Account Type Abbreviation Account Number Routing Number Payment Description Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 339 cnpAPI Reference Guide cnpAPI Elements 4.3 accountInformation accountInformation The accountInformation element is an optional child of the authorizationResponse and saleResponse elements. It contains two children that define the card type and account number. Parent Elements: authorizationResponse, saleResponse Attributes: None Child Elements: Required: type Optional: number 340 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide accountNumber 4.4 cnpAPI Elements accountNumber The accountNumber element is a required child of the registerTokenRequest element defining the account number for which you are requesting a token. It is also an optional child of the virtualGiftCardResponse element, where it defines the account number of the requested Virtual Gift Card. Type = String; minLength = 13; maxLength = 25 Parent Elements: registerTokenRequest, virtualGiftCardResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 341 cnpAPI Reference Guide cnpAPI Elements 4.5 accountNumberLength accountNumberLength The accountNumberLength element is a required child of the virtualGiftCard element defining the requested length of the virtual Gift Card number you are requesting. NOTE: In an early iteration of schema V8.22 issued in September of 2013 this element was defined as an optional child of the virtualGiftCard element. If you coded to the earlier version, be aware that this element is now required. If you do not include this element, the transaction will fail XML validation. Type = Integer; Allowed Values between 13 and 25 inclusive. IMPORTANT: Although the schema defines the allowed values as any integer between 13 and 25 inclusive, it this time you can only use a value of either 16 or 19. Parent Elements: virtualGiftCard Attributes: None Child Elements: None 342 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide accountUpdate 4.6 cnpAPI Elements accountUpdate The accountUpdate element is the parent element for all Account Updater request transactions. You can use this only with Batch transactions. Parent Elements: batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (all Required) orderId, cardOrToken (allows the substitution of either the card or token elements) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 343 cnpAPI Reference Guide cnpAPI Elements 4.7 accountUpdateFileRequestData accountUpdateFileRequestData The accountUpdateFileRequestData element is a child of the RFRRequest element, required when requesting the response file for an (legacy) Account Updater submission. Parent Elements: RFRRequest Attributes: None Child Elements: Required: merchantId Optional: postDay Example: accountUpdateFileRequestData Structure Merchant ID Post Date 344 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide accountUpdater 4.8 cnpAPI Elements accountUpdater The accountUpdater element is an optional child of the authorizationResponse, captureResponse, echeckSalesResponse, echeckcreditResponse, echeckVerificationResponse, forceCaptureResponse, and saleResponse elements. This element is included in the response messages when the submitted account information has changed. In the case of eCheck accounts, the system automatically updates the information sent to the ACH network and includes the original and updated information in the response. Similarly, if you use the Account Updater service (for credit cards), the system automatically repairs the card information sent to the card networks and depending upon the option you select, can return the info to you. Parent Elements: authorizationResponse, captureResponse, forceCaptureResponse, echeckCreditResponse, echeckRedepositResponse, echeckSalesResponse, saleResponse Attributes: None Child Elements: Required:extendedCardResponse, newAccountInfo, newCardInfo, newCardTokenInfo, newTokenInfo, originalAccountInfo, originalCardInfo, originalCardTokenInfo, originalTokenInfo IMPORTANT: When using Account Updater (any variation), you must always code to receive the extendedCardResponse element and its children. Vantiv always returns this information whenever applicable regardless of whether you receive other account updater information in the transaction response message. Example: accountUpdater Structure - Credit Cards without extendedCardResponse Card Type Old Account Number Old Expiration Date Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 345 cnpAPI Reference Guide cnpAPI Elements accountUpdater Card Type New Account Number New Expiration Date Example: accountUpdater Structure - Credit Cards with extendedCardResponse Card Type Old Account Number Old Expiration Date Card Type New Account Number New Expiration Date Code Description Either 501 or 504 Example: accountUpdater Structure - Credit Cards only extendedCardResponse Code Description Either 501 or 504 346 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide accountUpdater cnpAPI Elements Example: accountUpdater Structure - Credit Cards (tokenized Merchant) NOTE: This structure can also include the element. Old Token Card Type Old Expiration Date Old Card BIN New Token Card Type New Expiration Date New Card BIN Example: accountUpdater Structure - eCheck (for non-Tokenized Merchant) Original Account Type Original Account Number Original Routing Number New Account Type New Account Number New Routing Number Example: accountUpdater Structure - eCheck (for Tokenized Merchant) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 347 cnpAPI Reference Guide cnpAPI Elements accountUpdater Original Account Type Original Token Original Routing Number New Account Type New Token New Routing Number 348 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide accountUpdateResponse 4.9 cnpAPI Elements accountUpdateResponse The accountUpdaterResponse element is the parent element for all Account Update responses transactions. You can use this only with Batch transactions. Parent Elements: batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the accountUpdate transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the accountUpdate transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the accountUpdate transaction. minLength = 1 maxLength = 25 Child Elements: (Required) litleTxnId, orderId, response, responseTime, message Child Elements: (Optional) updatedCard, originalCard, originalToken, updatedToken Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 349 cnpAPI Reference Guide cnpAPI Elements accType 4.10 accType The accType element is a required child of the echeck, originalAccountInfo, and newAccountInfo elements defining the type of eCheck account used in the transaction. Type = Choice (Enum); Enumerations = Checking, Savings, Corporate, or Corp Savings NOTE: Use Corporate for Corporate Checking accounts. Parent Elements: echeck, newAccountInfo, originalAccountInfo, originalTokenInfo, newTokenInfo, accountInfo Attributes: None Child Elements: None 350 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide actionReason cnpAPI Elements 4.11 actionReason The actionReason element is an optional child of the authReversal element defining if the reversal is due to suspected fraud. Type = String (Enum); Enumerations = SUSPECT_FRAUD NOTE: When you include this optional element in an authReversal transaction, the information will be forwarded to MasterCard as part of the MasterCard eCommerce Fraud Alert program. When you include this optional element in an credit transaction, the system uses the information to track potentially fraudulent transactions for future analysis. Parent Elements: authReversal, credit Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 351 cnpAPI Reference Guide cnpAPI Elements activate 4.12 activate The activate element is the parent element for the transaction type that activates a Gift Card. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) orderId, amount, orderSource, card, virtualGiftCard 352 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide activateResponse cnpAPI Elements 4.13 activateResponse The activateResponse element is the parent element for information returned to you in response to an activate transaction.You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Activate transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Activate transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Activate transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message, giftCardResponse Optional: postDate, fraudResult, giftCardResponse, virtualGiftCardResponse Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 353 cnpAPI Reference Guide cnpAPI Elements activateReversal 4.14 activateReversal The activateReversal element is the parent element for the transaction type that reverses the activation of a Gift Card. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) card, originalRefCode, originalAmount, originalTxnTime, originalSystemTraceId, originalSequenceNumber Child Elements: (Optional) litleTxnId, virtualGiftCardBin 354 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide activateReversalResponse cnpAPI Elements 4.15 activateReversalResponse The activateReversalResponse element is the parent element for information returned to you in response to an activateReversal transaction. You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Activate Reversal transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Activate Reversal transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Activate Reversal transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message, giftCardResponse Optional: postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 355 cnpAPI Reference Guide cnpAPI Elements active 4.16 active The active element is an optional child of both the createPlan and updatePlan elements. You use this flag to activate/deactivate a Plan. When you deactivate a Plan, you can no longer reference that Plan for use with subscriptions. Existing subscriptions making use of the deactivated Plan will continue to use the Plan until either modified or completed. You can also reactivate a deactivated Plan by updating the Plan and setting the active flag to true. Type = Boolean; Valid Values = true or false Parent Elements: createPlan, updatePlan Attributes: None Child Elements: None 356 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide addOnCode cnpAPI Elements 4.17 addOnCode The addOnCode element is the identifier of a defined add on charge to a subscription. You use this element when creating, updating, and deleting an Add On applied to a subscription. Type = String; minLength = N/A; maxLength = 25 Parent Elements: createAddOn, updateAddOn, deleteAddOn Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 357 cnpAPI Reference Guide cnpAPI Elements addressIndicator 4.18 addressIndicator The addressIndicator element is an optional child of the billMeLaterResponseData element and indicates whether the shipping address is a commercial (c) or residential (r) shipping address. Type = String; minLength = N/A; maxLength = 1 Parent Elements: billMeLaterResponseData Attributes: None Child Elements: None 358 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide addressLine1, addressLine2, addressLine3 cnpAPI Elements 4.19 addressLine1, addressLine2, addressLine3 The elements addressLine1, addressLine2, and addressLine3 define the address information in both the billToAddress and shipToAddress elements. Type = String; minLength = N/A; maxLength = 35 Parent Elements: billToAddress, shipToAddress Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 359 cnpAPI Reference Guide cnpAPI Elements advancedAVSResult 4.20 advancedAVSResult The advancedAVSResult element is an optional child element of the fraudResult element. It defines the American Express Advanced AVS response codes that can be returned as verification of information supplied in the and/or child elements of the element. For a list of possible values, please refer to AAVS Response Codes on page 843. NOTE: You must be specifically enabled to use the Advanced AVS feature. Please consult your Relationship Manager for additional information. Type = String; minLength = N/A; maxLength = 3 Parent Elements: fraudResult Attributes: None Child Elements: None 360 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide advancedFraudChecks cnpAPI Elements 4.21 advancedFraudChecks The advancedFraudChecks element is an optional child of both the authorization and sale elements and a required child of the fraudCheck element. Parent Elements: authorization, sale, fraudCheck Attributes: None Child Elements: threatMetrixSessionId, customAttribute1 through customAttribute5 Example: advancedFraudChecks Structure Session Id from Threat Metrix Some attribute passed to ThreatMetrix Some attribute passed to ThreatMetrix Some attribute passed to ThreatMetrix Some attribute passed to ThreatMetrix Some attribute passed to ThreatMetrix Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 361 cnpAPI Reference Guide cnpAPI Elements advancedFraudResults 4.22 advancedFraudResults The advancedFraudResults element is an optional child of both the fraudResult and the fraudCheckResponse elements. Child elements return the results of advanced fraud checks performed by Threat Metrix, as well as a list of the rules triggered from the ThreatMetrix (merchant) Policy. Parent Elements: fraudResult, fraudCheckResponse Attributes: None Child Elements: (Required) deviceReviewStatus, deviceReputationScore, triggeredRule Example: advancedFraudChecks Structure pass, fail, review, or unavailable Score Returned from ThreatMetix Triggered Rule #1 . . . Triggered Rule #N 362 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide affiliate cnpAPI Elements 4.23 affiliate The affiliate element is an optional child element of the merchantData element. You can use it to track transactions associated with various affiliate organizations. Type = String; minLength = N/A; maxLength = 25 Parent Elements: merchantData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 363 cnpAPI Reference Guide cnpAPI Elements affluence 4.24 affluence The affluence element is an optional child of the enhancedAuthResponse element and defines whether the card used falls into one of the two defined affluent categories. If the card does not meet the definition of either category, the system does not return the affluence element. NOTE: Please consult your Relationship Manager for additional information concerning this feature. Type = String (enum); minLength = N/A; maxLength = N/A Parent Elements: enhancedAuthResponse Attributes: None Child Elements: None Enumerations: Enumeration Description MASS AFFLUENT Returned for certain Visa and MasterCard cards indicating high income customers (>100K annual income). AFFLUENT Returned for certain Visa and MasterCard cards indicating high income customers with high spending patterns (>100K annual income and >40K in card usage). NOTE: 364 The Affluence indicator applies only to certain Visa and MasterCard cards. This indicator does not apply to American Express or Discover cards. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide allowPartialAuth cnpAPI Elements 4.25 allowPartialAuth The allowPartialAuth element is an optional child of both Authorization and Sale transactions, which allows you to specify whether to authorize a partial amount if the entire requested authorization amount exceeds available credit/balance. NOTE: If you settle in a currency other than US or Canada, you cannot use partial authorizations. When submitting transactions for private label gift cards (card type of GC), the use of partial authorizations is determined by a setting in the Merchant Profile (on or off globally). This flag has no effect. Type = Boolean; Valid Values = true or false Parent Elements: authorization, sale Attributes: None Child Elements: None NOTE: For a Sale transaction, the deposit will be for the partial amount. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 365 cnpAPI Reference Guide cnpAPI Elements amexAggregatorData 4.26 amexAggregatorData The amexAggregatorData element defines Amex Aggregator specific information in the cnpAPI. The system does not use the information unless you are designated as an Aggregator by American Express. Parent Elements: authorization, captureGivenAuth, credit, forceCapture, sale Attributes: None Child Elements: (Required) sellerId, sellerMerchantCategoryCode Example: amexAggregatorData Structure Seller Id MerchantCategoryCode 366 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide amount cnpAPI Elements 4.27 amount The amount element is a child of several elements. When used in a payment transaction this element defines the amount of the transaction. When amount is a child of the subscription element, it defines the amount of the recurring payment. As a child of the activate, load, or unload transactions, amount defines the initial value of a newly activated gift Card, the amount loaded onto a reloadable Gift Card, or the amount unloaded from a Gift Card, respectively. When used in an Instruction-Based Dynamic Payout transaction type, it specifies the amount of funds to transfer. Supply the value in cents without a decimal point. For example, a value of 1995 signifies $19.95. NOTE: For the following currencies, the value you submit is the amount without implied decimal: Burundian Franc, Chilean Peso, Comoro Franc, Djibouti Franc, Guinea Franc, Iceland Krona, Japanese Yen, South Korean Won, Vanuatu Vatu, Paraguayan Guarani, Rawanda Franc, Vietnamese Dong, Uganda Shilling, CFA Franc BEAC, CFA Franc BCEAO, and CFP Franc. For example, if the currency is Japanese Yen, entering 2000 means 2000 Yen, NOT 20.00 Yen. Type = Integer; totalDigits = 12 Parent Elements: The amount element is a required child of each of the following Parent Elements: activate, authorization, credit (required if original transaction was not processed by Vantiv), captureGivenAuth, echeckCredit (required if original transaction was not processed by Vantiv), echeckSale, echeckVerification, forceCapture,fraudCheck, load, sale, unload This element is also a required child of the following Instruction-Based Dynamic Payout transaction types: payFacCredit, payFacDebit, physicalCheckCredit, physicalCheckDebit, reserveCredit, reserveDebit, submerchantCredit, submerchantDebit, vendorCredit, vendorDebit, fastAccessFunding The amount element is an optional child of each of the following Parent Elements: authReversal, capture, credit, echeckCredit, subscription NOTE: For all cases where the amount element is optional, except when a child of the subscription element, if you do not specify a value, the system uses the entire amount from the referenced (by litleTxnId) transaction. When amount is a child of the subscription element, if you do not specify a value, the amount defaults to the value defined in the referenced recurring plan (planCode element). Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 367 cnpAPI Reference Guide cnpAPI Elements amount Attributes: None Child Elements: None 368 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide androidpayResponse cnpAPI Elements 4.28 androidpayResponse The androidpayResponse element is an optional child of several transaction types and is returned in response messages, when the orderSource in the request is androidpay. Parent Elements: authorizationResponse, registerTokenResponse, saleResponse Attributes: None Child Elements (all optional): cryptogram, expMonth, expYear, eciIndicator Example: androidpayResponse Structure Payment Cryptogram Expiration Month Expiration Year eCommerece Indicator Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 369 cnpAPI Reference Guide cnpAPI Elements applepay 4.29 applepay The applepay element is an optional child of several transaction types and takes the place of the card element in Apple Pay transaction where the merchant does not decrypt the (Apple Pay) PKPaymentToken prior to submitting the transaction. It contains child elements for the component parts of the PKPaymentToken. Parent Elements: authorization, registerTokenRequest, sale Attributes: None Child Elements (all required): data, header, signature, version Example: applepay Structure User Name
Base64 Hash of App Data Property Base64 Encoded Ephemeral Public Key Base64 Hash of Public Merchant Key Cert Hex Transaction Id
Signature of Payment and Header Data Payment Token Version Info
370 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide applepayResponse cnpAPI Elements 4.30 applepayResponse The applepayResponse element is an optional child of several transaction types and is returned in response messages, when the request includes the applepay element. Parent Elements: authorizationResponse, registerTokenResponse, saleResponse Attributes: None Child Elements: applicationPrimaryAccountNumber, applicationExpirationDate, currencyCode, transactionAmount, cardholderName, deviceManufacturerIdentifier, paymentDataType, onlinePaymentCryptogram, eciIndicator Example: applepayResponse Structure App PAN App PAN Exp Date Currency Code Amount of Transaction Name of cardholder Id of Device Mfr Type of Payment Data Payment Cryptogram eCommerece Indicator IMPORTANT: The system never returns the applicationPrimaryAccountNumber element in a registerTokenresponse message, since this transaction type includes a token replacing the application PAN. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 371 cnpAPI Reference Guide cnpAPI Elements applicationData 4.31 applicationData The applicationData element is an optional child of the header element and provides the SHA-256 hash, hex encoded string of the original PKPaymentRequest of the Apple Pay transaction. Type = Hex Encoded String; minLength = N/A; maxLength = 10000 Parent Elements: header Attributes: None Child Elements: None 372 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide applicationExpirationDate cnpAPI Elements 4.32 applicationExpirationDate The applicationExpirationDate element is an optional child of the applepayResponse element and defines expiration date of the application primary account number. Type = String; minLength = N/A; maxLength = 20 Parent Elements: applepayResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 373 cnpAPI Reference Guide cnpAPI Elements applicationPrimaryAccountNumber 4.33 applicationPrimaryAccountNumber The applicationPrimaryAccountNumber element is an optional child of the applepayResponse element and defines the primary account number associated with the application. Type = String; minLength = N/A; maxLength = 20 Parent Elements: applepayResponse Attributes: None Child Elements: None IMPORTANT: The system never returns the applicationPrimaryAccountNumber element (child of the applepayResponse element) in a registerTokenresponse message, since this transaction type includes a token replacing the application PAN. 374 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide approvedAmount cnpAPI Elements 4.34 approvedAmount The approvedAmount element defines the dollar amount of the approval. It appears in an authorization or sale response only if the allowPartialAuth element is set to true in the request transaction. It can also appear as the child of a deactivateResponse message where it specifies the value of the Gift Card prior to deactivation. Type = Integer; totalDigits = 8 Parent Elements: authorizationResponse, saleResponse, deactivateResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 375 cnpAPI Reference Guide cnpAPI Elements authAmount 4.35 authAmount The authAmount element is an optional child of the authInformation element and is used to define the dollar amount of the authorization for Capture Given Auth transactions. Type = Integer; totalDigits = 8 Parent Elements: authInformation Attributes: None Child Elements: None 376 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide authCode cnpAPI Elements 4.36 authCode The authCode element is an optional child of both the authorizationResponse and saleResponse elements. It is also a required child of the authInformation element (used in captureGivenAuth transactions), where it specifies the authorization code from the associated Authorization or Sale transaction. Type = String; minLength = N/A; maxLength = 6 Parent Elements: authInformation, authorizationResponse, saleResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 377 cnpAPI Reference Guide cnpAPI Elements authDate 4.37 authDate The authDate element is a required child of the authInformation element and defines the date of the associated Authorization transaction. Type = Date; Format = YYYY-MM-DD Parent Elements: authInformation Attributes: None Child Elements: None 378 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide authenticatedByMerchant cnpAPI Elements 4.38 authenticatedByMerchant The authenticatedByMerchant element is an optional child element of the cardholderAuthentication element. This element indicates whether or not the customer has logged in to a secure web site or has been authenticated by the call center ANI. Type = Boolean; Valid Values = true or false Parent Elements: cardholderAuthentication Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 379 cnpAPI Reference Guide cnpAPI Elements authentication 4.39 authentication The authentication element is a required element of both the litleOnlineRequest and the batchRequest elements. It contains child elements used to authenticate that the XML message is from a valid user. NOTE: The authentication element and its child elements, user and password, are used to identify the merchant submitting transactions. They do not provide other access to platform or to the iQ reporting system. Parent Elements: litleOnlineRequest, litleRequest Attributes: None Child Elements: Required: user, password Example: authentication Structure User Name Password 380 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide authenticationResult cnpAPI Elements 4.40 authenticationResult The authenticationResult element is an optional child element of the fraudResult element. It defines the 3DS results from either Verified by Visa, MasterCard SecureCode, or Discover ProtectBuy. For a list of possible values, please refer to 3DS Authentication Result Codes on page 840. Type = String; minLength = N/A; maxLength = 1 Parent Elements: fraudResult Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 381 cnpAPI Reference Guide cnpAPI Elements authenticationTransactionId 4.41 authenticationTransactionId The authenticationTransactionId element is an optional child of the cardholderAuthentication element. This element defines the Verified by Visa Transaction Id or the Visa TAVV (Token Authentication Verification Value). This element is not used for Discover ProtectBuy transactions. You must include this element for Visa transactions, when the orderSource element is set to 3dsAuthenticated. Type = Base 64 Encoded String; minLength = N/A; maxLength = 28 Parent Elements: cardholderAuthentication Attributes: None Child Elements: None 382 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide authenticationValue cnpAPI Elements 4.42 authenticationValue The authenticationValue element is an optional child of the cardholderAuthentication element. This element defines either the Visa CAVV value (fixed length 28 characters) or the MasterCard UCAF value (variable length up to 32 characters). You must include this element for Visa and MasterCard transactions, when the orderSource element is set to 3dsAuthenticated, as well as MasterCard transactions if the orderSource element is set to 3dsAttempted. Type = Base 64 Encoded String; minLength = N/A; maxLength = 56 Parent Elements: cardholderAuthentication Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 383 cnpAPI Reference Guide cnpAPI Elements authInformation 4.43 authInformation The authInformation element is a required child of the captureGivenAuth element. It contains child elements used to provide details concerning the external (to the systems) Authorization. Parent Elements: captureGivenAuth Attributes: None Child Elements: Required: authDate, authCode Optional: fraudResult, authAmount Example: authInformation Structure Auth Date Approval Code AVS Verification Result Code Validation Result Code Verified by Visa Result Code Amount of Authorization 384 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide authorization cnpAPI Elements 4.44 authorization The authorization element is the parent element for all Authorization transactions. You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, amount, orderSource, (choice of) card, paypal, paypage, mpos, token, or applepay, cardholderAuthentication NOTE: The cardholderAuthentication child element is required only for 3-D Secure transactions. Optional: customerInfo, billToAddress, shipToAddress, billMeLaterRequest, processingInstructions, pos, customBilling, taxType, enhancedData, amexAggregatorData, allowPartialAuth, healthcareIIAS, merchantData, recyclingRequest, fraudFilterOverride, surchargeAmount, debtRepayment, recurringRequest, advancedFraudChecks, secondaryAmount, wallet, processingType, origOrderId, password, originalNetworkTransactionId, originalTransactionAmount Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 385 cnpAPI Reference Guide cnpAPI Elements authorizationResponse 4.45 authorizationResponse The authorizationResponse element is the parent element for information returned to you in response to an Authorization transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Authorization transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Authorization transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Authorization transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, orderId, response, responseTime, message Optional: postDate, cardProductId (see Note below), authCode, authorizationResponseSubCode (see Note below), approvedAmount, accountInformation, fraudResult, billMeLaterResponseData, tokenResponse, enhancedAuthResponse, accountUpdater, recycling, recurringResponse, giftCardResponse, applepayResponse, cardSuffix, androidpayResponse, networkTransactionId NOTE: The postDate child element is returned only in responses to Online transactions. The cardProductId element returns a raw code referencing the card type. Please consult your Relationship Manager for additional information. The authorizationResponseSubCode element is not used at this time. 386 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide authorizationSourcePlatform cnpAPI Elements 4.46 authorizationSourcePlatform The authorizationSourcePlatform element is an optional child element of the billMeLaterRequest element. This element defines the physical platform that was used for submitting the authorization request (not the order). Specify as needed for auditing and re-authorization management purposes. Type = String; minLength = N/A; maxLength = 1 (valid values below) Value Description A application processing B batch capture, recurring or mail order C call center F fulfillment/order management K kiosk M mobile device gateway P processor or gateway reauthorization R retail POS Parent Elements: billMeLaterRequest Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 387 cnpAPI Reference Guide cnpAPI Elements authReversal 4.47 authReversal The authReversal element is the parent element for all Authorization Reversal transactions. You can use this element in either Online or Batch transactions. Also see Notes on the Use of Authorization Reversal Transactions on page 77. Also, if you use the Recycling Engine, you can use the authReversal transaction to halt the recycling of an authorization transaction. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId Optional: amount, actionReason, payPalNotes, surchargeAmount NOTE: 388 If you do not specify an amount child element, the system reverses the full amount from the associated Authorization transaction. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide authReversalResponse cnpAPI Elements 4.48 authReversalResponse The authReversalResponse element is the parent element for information returned to you in response to an Auth Reversal transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Authorization Reversal transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Authorization Reversal transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Authorization Reversal transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate NOTE: The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 389 cnpAPI Reference Guide cnpAPI Elements availableBalance 4.49 availableBalance The availableBalance element is a required child element of the fundingSource element and an optional child of the giftCardResponse element. It defines the outstanding available balance on the submitted prepaid or Gift Card. If the balance can not be determined, the element returns, “Not Available.” Type = String; minLength = N/A; maxLength = 20 Parent Elements: fundingSource, giftCardResponse Attributes: None Child Elements: None NOTE: The fundingSource element and its child elements, type and availableBalance are associated with the Insights features (see Issuer Insights on page 24.) Please consult your Relationship Manager for additional information. 390 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide avsResult cnpAPI Elements 4.50 avsResult The avsResult element is an optional child element of the fraudResult element. It defines the Address Verification response code returned by the networks. For a list of possible values, please refer to AVS Response Codes on page 842. Type = String; minLength = N/A; maxLength = 2 Parent Elements: fraudResult Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 391 cnpAPI Reference Guide cnpAPI Elements balanceInquiry 4.51 balanceInquiry The balanceInquiry element is the parent element for the transaction type that queries the available balance of a Gift Card. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (all Required) orderId, orderSource, card 392 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide balanceInquiryResponse cnpAPI Elements 4.52 balanceInquiryResponse The balanceInquiryResponse element is the parent element for information returned to you in response to a balanceInquiry transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Balance Inquiry transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Balance Inquiry transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Balance Inquiry transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, orderId, response, responseTime, message Optional: postDate, fraudResult, giftCardResponse Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 393 cnpAPI Reference Guide cnpAPI Elements batchRequest 4.53 batchRequest This is the root element for all cnpAPI Batch requests. Parent Elements: litleRequest Attributes: NOTE: Include the count and amount attributes for all transaction types included in the Batch. For example if you submit one Sale transaction of $10, include numSales="1" and saleAmount="1000". You must always include an amount, if you include a count. Do not include corresponding attributes, if the Batch does not include the transaction type. Attribute Name Type Required? Description id String No A unique string to identify this batchRequest within the system. minLength = N/A maxLength = 50 numAuths Integer No Defines the total count of Authorization transactions in the batchRequest. minLength = N/A maxLength = N/A authAmount Integer No Defines the total dollar amount of Authorization transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numAuthReversals Integer No Defines the total count of AuthReversal transactions in the batchRequest. minLength = N/A maxLength = N/A authReversalAmount Integer No Defines the total dollar amount of AuthReversal transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numGiftCardAuthReversa ls Integer No Defines the total count of giftCardAuthReversal transactions in the batchRequest. minLength = N/A maxLength = N/A 394 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide batchRequest cnpAPI Elements Attribute Name Type Required? Description giftCardAuthReversalOrig inalAmount Integer No Defines the total dollar amount of giftCardAuthReversal transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numCaptures Integer No Defines the total count of Capture transactions in the batchRequest. minLength = N/A maxLength = N/A captureAmount Integer No Defines the total dollar amount of Capture transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numGiftCardCaptures Integer No Defines the total count of giftCardCapture transactions in the batchRequest. minLength = N/A maxLength = N/A giftCardCaptureAmount Integer No Defines the total dollar amount of giftCardCapture transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numCredits Integer No Defines the total count of Credit transactions in the batchRequest. minLength = N/A maxLength = N/A creditAmount Integer No Defines the total dollar amount of Credit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numGiftCardCredits Integer No Defines the total count of giftCardCredit transactions in the batchRequest. minLength = N/A maxLength = N/A giftCardCreditAmount Integer No Defines the total dollar amount of giftCardCredit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 395 cnpAPI Reference Guide cnpAPI Elements batchRequest Attribute Name Type Required? Description numForceCaptures Integer No Defines the total count of Force Capture transactions in the batchRequest. minLength = N/A maxLength = N/A forceCaptureAmount Integer No Defines the total dollar amount of Force Capture transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numSales Integer No Defines the total count of Sale transactions in the batchRequest. minLength = N/A maxLength = N/A saleAmount Integer No Defines the total dollar amount of Sale transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numCaptureGivenAuths Integer No Defines the total count of Capture Given Auth transactions in the batchRequest. minLength = N/A maxLength = N/A captureGivenAuthAmount Integer No Defines the total dollar amount of Capture Given Auth transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numEcheckSales Integer No Defines the total count of eCheck Sale transactions in the batchRequest. minLength = N/A maxLength = N/A echeckSalesAmount Integer No Defines the total dollar amount of eCheck Sale transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numEcheckCredit Integer No Defines the total count of eCheck Credit transactions in the batchRequest. minLength = N/A maxLength = N/A 396 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide batchRequest cnpAPI Elements Attribute Name Type Required? Description echeckCreditAmount Integer No Defines the total dollar amount of eCheck Credit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numEcheckVerification Integer No Defines the total count of eCheck Verification transactions in the batchRequest. minLength = N/A maxLength = N/A echeckVerificationAmount Integer No Defines the total dollar amount of eCheck Verification transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numEcheckRedeposit Integer No Defines the total count of eCheck Redeposit transactions in the batchRequest. minLength = N/A maxLength = N/A numEcheckPreNoteSale Integer No Defines the total count of eCheck Prenotification Sale transactions in the batchRequest. minLength = N/A maxLength = N/A numEcheckPreNoteCredi t Integer No Defines the total count of eCheck Prenotification Credit transactions in the batchRequest. minLength = N/A maxLength = N/A numAccountUpdates Integer No Defines the total count of Account Update transactions in the batchRequest. minLength = N/A maxLength = N/A numTokenRegistrations Integer No Defines the total count of Token Registration transactions in the batchRequest. minLength = N/A maxLength = N/A numUpdateCardValidatio nNumOnTokens Integer No Defines the total count of Update Card Validation Number request transactions in the batchRequest. minLength = N/A maxLength = N/A numCancelSubscriptions Integer No Defines the total count of Cancel Subscription transactions in the batchRequest. minLength = N/A maxLength = N/A numUpdateSubscriptions Integer No Defines the total count of Update Subscription transactions in the batchRequest. minLength = N/A maxLength = N/A Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 397 cnpAPI Reference Guide cnpAPI Elements batchRequest Attribute Name Type Required? Description numCreatePlans Integer No Defines the total count of Create Plan transactions in the batchRequest. minLength = N/A maxLength = N/A numUpdatePlans Integer No Defines the total count of Update Plan transactions in the batchRequest. minLength = N/A maxLength = N/A numActivates Integer No Defines the total count of (Gift Card) Activate transactions in the batchRequest. minLength = N/A maxLength = N/A numDeactivates Integer No Defines the total count of (Gift Card) Deactivate transactions in the batchRequest. minLength = N/A maxLength = N/A activateAmount Integer No Defines the total dollar amount of (Gift Card) Activate transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numLoads Integer No Defines the total count of (Gift Card) Load transactions in the batchRequest. minLength = N/A maxLength = N/A loadAmount Integer No Defines the total dollar amount of (Gift Card) Load transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numUnloads Integer No Defines the total count of (Gift Card) Unload transactions in the batchRequest. minLength = N/A maxLength = N/A unloadAmount Integer No Defines the total dollar amount of (Gift Card) Unload transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 numBalanceInquirys Integer No Defines the total count of (Gift Card) Balance Inquiry transactions in the batchRequest. minLength = N/A maxLength = N/A 398 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide batchRequest cnpAPI Elements Attribute Name Type Required? Description numPayFacCredit Integer No Defines the total count of PayFac Credit transactions in the batchRequest. minLength = N/A maxLength = N/A numPayFacDebit Integer No Defines the total count of PayFac Debit transactions in the batchRequest. minLength = N/A maxLength = N/A numSubmerchantCredit Integer No Defines the total count of Submerchant Credit transactions in the batchRequest. minLength = N/A maxLength = N/A numSubmerchantDebit Integer No Defines the total count of Submerchant Debit transactions in the batchRequest. minLength = N/A maxLength = N/A numReserveCredit Integer No Defines the total count of Reserve Credit transactions in the batchRequest. minLength = N/A maxLength = N/A numReserveDebit Integer No Defines the total count of Reserve Debit transactions in the batchRequest. minLength = N/A maxLength = N/A numVendorCredit Integer No Defines the total count of Vendor Credit transactions in the batchRequest. minLength = N/A maxLength = N/A numVendorDebit Integer No Defines the total count of Vendor Debit transactions in the batchRequest. minLength = N/A maxLength = N/A numPhysicalCheckCredit Integer No Defines the total count of Physical Check Credit transactions in the batchRequest. minLength = N/A maxLength = N/A numPhysicalCheckDebit Integer No Defines the total count of Physical Check Debit transactions in the batchRequest. minLength = N/A maxLength = N/A numFundingInstructionVo id Integer No Defines the total count of Funding Instruction Void transactions in the batchRequest. minLength = N/A maxLength = N/A Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 399 cnpAPI Reference Guide cnpAPI Elements batchRequest Attribute Name Type Required? Description payFacCreditAmount Integer No Defines the total dollar amount of PayFac Credit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 payFacDebitAmount Integer No Defines the total dollar amount of PayFac Debit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 submerchantCreditAmou nt Integer No Defines the total dollar amount of Sub-merchant Credit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 submerchantDebitAmoun t Integer No Defines the total dollar amount of Sub-merchant Debit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 reserveCreditAmount Integer No Defines the total dollar amount of Reserve Credit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 reserveDebitAmount Integer No Defines the total dollar amount of Reserve Debit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 vendorCreditAmount Integer No Defines the total dollar amount of Vendor Credit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 vendorDebitAmount Integer No Defines the total dollar amount of Vendor Debit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 400 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide batchRequest cnpAPI Elements Attribute Name Type Required? Description physicalCheckCreditAmo unt Integer No Defines the total dollar amount of Physical Check Credit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 physicalCheckDebitAmou nt Integer No Defines the total dollar amount of Physical Check Debit transactions in the batchRequest. The decimal point is implied. For example, you enter $25.00 as 2500. totalDigits = 10 merchantId String Yes A unique string to identify the merchant within the system. minLength = N/A maxLength = 50 Note: International currencies are supported on a per merchantId basis. sameDayFunding Boolean No Used for Dynamic Payout Funding Instructions only. Set to true to mark this Batch of Funding Instructions for same day funding. Also, see Same Day Funding on page 888. Child Elements: At least one of the following required: activate, authorization, authReversal, balanceInquiry, cancelSubscription, capture, captureGivenAuth, createPlan, credit, deactivate, echeckCredit, echeckPreNoteSale, echeckRedeposit, echeckSale, echeckVerification, forceCapture, giftCardAuthReversal, giftCardCapture, giftCardCredit, load, registerTokenRequest, sale, unload, updateCardValidationNumOnToken, updatePlan, updateSubscription, payFacCredit, payFacDebit, reserveCredit, reserveDebit, submerchantCredit, submerchantDebit, vendorCredit, vendorDebit Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 401 cnpAPI Reference Guide cnpAPI Elements batchResponse 4.54 batchResponse The batchResponse element is the parent element for information returned to you in response to a batch you submitted for processing. It is a child of a litleResponse element. Parent Elements: litleResponse Attributes: Attribute Name Type Required? Description id String No The response returns the same value submitted in the Batch Request. minLength = N/A maxLength = 25 litleBatchId Long Yes A unique value assigned by Vantiv to identify the batch. minLength = N/A maxLength = 19 merchantId String Yes The response returns the same value submitted in the Batch Request. minLength = 1 maxLength = 50 Child Elements: Required:accountUpdateResponse, activateResponse, authorizationResponse, authReversalResponse, captureResponse, captureGivenAuthResponse, createPlanResponse, creditResponse, deactivateResponse, echeckCreditResponse, echeckPreNoteCreditResponse, echeckPreNoteSaleResponse, echeckRedepositResponse, echeckSalesResponse, echeckVerificationResponse, forceCaptureResponse, giftCardAuthReversalResponse, giftCardCaptureResponse, giftCardCreditResponse, loadResponse, registerTokenResponse, saleResponse, unloadResponse, updateCardValidationNumOnTokenResponse, cancelSubscriptionResponse, updatePlanResponse, updateSubscriptionResponse, payFacCreditResponse, payFacDebitResponse, physicalCheckCreditResponse, physicalCheckDebitResponse, reserveCreditResponse, reserveDebitResponse, submerchantCreditResponse, submerchantDebitResponse, vendorCreditResponse, vendorDebitResponse NOTE: 402 The batchResponse contains child elements corresponding to the requests submitted in the batchRequest. For example, if the batchRequest contained 10 authorization and 8 capture transactions, the batchResponse would contain 10 authorizationResponse and 8 captureResponse transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide beginningBalance cnpAPI Elements 4.55 beginningBalance The beginningBalance element is an optional child of the giftCardResponse element. It defines the available balance on the submitted Gift Card prior to the requested operation. NOTE: Although included in the schema, the beginningBalance, endingBalance, and cashBackAmount elements are not currently supported. Type = String; minLength = N/A; maxLength = 20 Parent Elements: giftCardResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 403 cnpAPI Reference Guide cnpAPI Elements billingDate 4.56 billingDate The billingDate element is an optional child of the updateSubscription element that defines the new date for the recurring billing when the scheduled date need to be changed. Type = Date; Format = YYYY-MM-DD Parent Elements: updateSubscription Attributes: None Child Elements: None 404 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide billMeLaterRequest cnpAPI Elements 4.57 billMeLaterRequest The billMeLaterRequest element is the parent of several child elements used to define merchant, product type, terms and conditions, and other items for PayPal Credit authorization transactions, or where you must reference an external (to Vantiv) BML transaction. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Parent Elements: authorization, captureGivenAuth, credit, sale Attributes: None Child Elements: (all optional) bmlMerchantId, bmlProductType, itemCategoryCode, termsAndConditions, preapprovalNumber, virtualAuthenticationKeyPresenceIndicator, virtualAuthenticationKeyData, authorizationSourcePlatform NOTE: The following elements appear in the schema as children of the billMeLaterRequest element, but are not used at this time: • authorizationSourcePlatform • customerBillingAddressChanged • customerEmailChanged • customerPasswordChanged • customerPhoneChanged • merchantPromotionalCode • secretQuestionAnswer • secretQuestionCode Example: billMeLaterRequest bmlMerchantId bmlProductType termsAndConditions Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 405 cnpAPI Reference Guide cnpAPI Elements billMeLaterRequest preapprovalNumber Indicator virtualAuthenticationKeyData itemCategoryCode platformType 406 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide billMeLaterResponseData cnpAPI Elements 4.58 billMeLaterResponseData The billMeLaterResponseData element is the parent of several child elements used in the response XML for PayPal Credit authorization transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Parent Elements: authorizationResponse, saleResponse Attributes: None Child Elements: bmlMerchantId, creditLine, addressIndicator NOTE: The following elements appear in the schema as children of the billMeLaterResponseData element, but are not used at this time: • approvedTermsCode • loanToValueEstimator • promotionalCodeOffer • riskEstimator • riskQueueAssignment Example: billMeLaterResponseData Structure bmlMerchantId creditLine addressIndicator Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 407 cnpAPI Reference Guide cnpAPI Elements billToAddress 4.59 billToAddress The billToAddress element contains several child elements that define the postal mailing address (and telephone number) used for billing purposes. It also contains several elements used for the eCheck verification process. Parent Elements: authorization, captureGivenAuth, credit, echeckCredit (required if original transaction was not processed by Vantiv), echeckPreNoteCredit, echeckPreNoteSale, echeckSale, echeckVerification, forceCapture,fraudCheck, sale, updateSubscription Attributes: None Child Elements: (all optional) name, firstName, middleInitial, lastName, companyName, addressLine1, addressLine2, addressLine3, city, state, zip, country, email, phone NOTE: You must submit the name element for echeckSale and echeckCredit transactions. If you do not submit the customer name in these eCheck transactions, we return the response 709 - Invalid Data. You must submit the name, country, and email elements in sale transactions using the sepaDirectDebit method of payment. Failure to include the these elements results in a 901 - Missing Name Response Code, 903 - Missing Billing Country Code, or 905 - Missing Email Address respectively. For an eCheckVerification transaction, you must submit the firstName and lastName elements instead of the name element (middleInitial is optional). For a corporate account you must include the companyName element in addition to the firstName and lastName elements. In both cases, you also must include the address, city, state, zip and phone information. For a corporate account, if you do not have the name of the check issuer, you can use a value of “unavailable” for the firstName and lastName elements. Example: billToAddress Structure Customer’s Full Name Customer’s First Name Customer’s Middle Initial Customer’s Last Name 408 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide billToAddress cnpAPI Elements Company’s Name (include for echeckVerification of corporate account) Address Line 1 Address Line 2 Address Line 3 City State Abbreviation Postal Code Country Code Email Address Telephone Number Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 409 cnpAPI Reference Guide cnpAPI Elements bin 4.60 bin The bin element provides the 6-digit Bank (or Issuer) Identification Number of the Issuing Bank. The system returns this value in XML responses when issuing new tokens to replace Visa or MasterCard account numbers. For Discover and American Express cards, this element is empty in a registerTokenResponse. For Discover, when included with Account Updater information in a payment transaction response, the bin element will have a value of discov. Type = String; minLength = 0; maxLength = 6 Parent Elements: The bin element is an optional child of each listed parent element. registerTokenResponse, tokenResponse, newCardTokenInfo, originalCardTokenInfo, originalToken, updatedToken Attributes: None Child Elements: None 410 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide bmlMerchantId cnpAPI Elements 4.61 bmlMerchantId The bmlMerchantId element is a value assigned by PayPal Credit to identify the merchant within the PayPal Credit system. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = Long; minLength = N/A; maxLength = 19 Parent Elements: The bmlMerchantId element is an optional child of each listed parent element. billMeLaterRequest, billMeLaterResponseData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 411 cnpAPI Reference Guide cnpAPI Elements bmlProductType 4.62 bmlProductType The bmlProductType element is a value assigned by PayPal Credit to identify the merchant account type within the PayPal Credit system. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = String; minLength = 2; maxLength = 2 Parent Elements: The bmlProductType element is an optional child of each listed parent element. billMeLaterRequest, billMeLaterResponseData NOTE: At this time, the only valid value for this element is BL. Attributes: None Child Elements: None 412 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide bypassVelocityCheck cnpAPI Elements 4.63 bypassVelocityCheck The bypassVelocityCheck element is an optional child of the processingInstructions element, which allows you to specify whether or not the system performs velocity checking on the transaction. NOTE: Velocity Checking is not currently supported. Type = Boolean; Valid Values = true or false Parent Elements: processingInstructions Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 413 cnpAPI Reference Guide cnpAPI Elements campaign 4.64 campaign The campaign element is an optional child element of the merchantData element. You can use it to track transactions associated with various marketing campaigns. Type = String; minLength = N/A; maxLength = 25 Parent Elements: merchantData Attributes: None Child Elements: None 414 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide cancelSubscription cnpAPI Elements 4.65 cancelSubscription The cancelSubscription element is the parent element for the transaction that cancels a subscription. You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineRequest, batchRequest Attributes: None Child Elements: Required: subscriptionId Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 415 cnpAPI Reference Guide cnpAPI Elements cancelSubscriptionResponse 4.66 cancelSubscriptionResponse The cancelSubscriptionresponse element is the parent element for the response to a cancelSubscription transaction. Parent Elements: litleOnlineResponse, batchResponse Attributes: None Child Elements: Required: subscriptionId, litleTxnId, response, message, responseTime 416 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide capability cnpAPI Elements 4.67 capability The capability element is a required child of the pos element, which describes the capability of the point of sale terminal. Type = String (Enum); minLength = N/A; maxLength = N/A Parent Elements: pos Attributes: None Child Elements: None Enumerations: Enumeration Description notused terminal not used magstripe magnetic stripe reader capability keyedonly keyed entry only capability NOTE: For CAT (Cardholder Activated Terminal) transactions, the capability element must be set to magstripe, the cardholderId element must be set to nopin, and the catLevel element must be set to self service. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 417 cnpAPI Reference Guide cnpAPI Elements capture 4.68 capture The capture element is the parent element for all Capture (deposit) transactions. You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 partial Boolean No maxLength = 25 If there is more than one capture that references the same , set this attribute to “true” for each of those partial captures. The default value is false. Valid Values = true or false Note: If you settle in a currency other than US or Canada, you cannot use partial captures. Child Elements: Required: litleTxnId, payPalOrderComplete (required only if closing a PayPal order) Optional: amount, enhancedData, payPalNotes, pin, processingInstructions, secondaryAmount, surchargeAmount NOTE: 418 If you do not specify an amount, the system uses the full amount from the associated Authorization transaction. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide captureAmount cnpAPI Elements 4.69 captureAmount The captureAmount element is a required child of the giftCardCapture element and defines the amount of the capture (deposit). This value must be less than or equal to the value of the originalAmount element. Setting this element to a value less than the originalAmount implies that this is a partial capture. Type = Integer; totalDigits = 12 Parent Elements: giftCardCapture Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 419 cnpAPI Reference Guide cnpAPI Elements captureGivenAuth 4.70 captureGivenAuth The captureGivenAuth element is the parent element for all Capture Given Auth transactions. These are specialized Capture transactions used when the litleTxnId for the associated Authorization is unknown or when the Authorization occurred outside our system. You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, authInformation, amount, orderSource, choice of card, token, mpos, or paypage Optional: billToAddress, shipToAddress, customBilling, taxType, enhancedData, processingInstructions, pos, amexAggregatorData, merchantData, secondaryAmount, surchargeAmount, debtRepayment, processingType, originalNetworkTransactionId, originalTransactionAmount NOTE: 420 If you do not specify an amount child element, the system uses the full amount from the associated Authorization transaction. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide captureGivenAuthResponse cnpAPI Elements 4.71 captureGivenAuthResponse The captureGivenAuthResponse element is the parent element for information returned to you in response to a Capture Given Auth transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Capture Given Auth transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Capture Given Auth transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Capture Given Auth transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, tokenResponse, giftCardResponse NOTE: The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 421 cnpAPI Reference Guide cnpAPI Elements captureResponse 4.72 captureResponse The captureResponse element is the parent element for information returned to you in response to a Capture transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the capture transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, accountUpdater, giftCardResponse NOTE: 422 The system returns the postDate child element in all Online transactions responses. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide card cnpAPI Elements 4.73 card The card element defines payment card information. It is a required element for most transaction types unless the transaction uses an alternate payment method such as PayPal. It contains one or more child elements depending upon whether the transaction is a card-not-present or a card-present (face-to-face) transaction. Parent Elements: activate, activateReversal, accountUpdate, authorization, balanceInquiry, captureGivenAuth, credit, deactivate, deactivateReversal, depositReversal, forceCapture, giftCardAuthReversal, giftCardCapture, giftCardCredit, load, loadReversal, refundReversal, sale, unload, unloadReversal, updateSubscription, fastAccessFunding Attributes: None Child Elements: For card-not-present transactions (Required): type, number, expDate For card-present transactions (Required): track For both transactions types (Optional): cardValidationNum For Gift Card transactions (Optional): pin Example: card Structure - Card-Not-Present Card Type Abbreviation Account Number Expiration Date Card Validation Number Example: card Structure - Card-Present Magnetic Stripe Read Example: card Structure - Gift Card (Card-Not-Present) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 423 cnpAPI Reference Guide cnpAPI Elements card GC Account Number Expiration Date Card Validation Number Pin Number 424 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide cardAcceptorTaxId cnpAPI Elements 4.74 cardAcceptorTaxId The cardAcceptorTaxId element is an optional child of the detailTax element and defines the merchant's Tax Id. This ID is nine digits long if the merchant is domiciled in the U.S. If the card acceptor tax ID is unknown, do not include this element. Type = String; minLength = 1; maxLength = 20 Parent Elements: detailTax Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 425 cnpAPI Reference Guide cnpAPI Elements cardholderAuthentication 4.75 cardholderAuthentication The cardholderAuthentication element is an optional child element of the Authorization and Sale transactions. The children of this element have two purposes. The first is to define Verified by Visa or MasterCard SecureCode data in the Authorization or Sale transactions (authenticationValue, authenticationTransactionId, and authenticatedByMerchant elements). The remaining child element, customerIpAddress, as well as the authenticationTransactionId, are used in PayPal Credit transactions. The customerIpAddress element can also be used to supply the customer IP Address by merchants enabled for American Express Advanced AVS services. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Parent Elements: authorization, sale Attributes: None Child Elements: authenticationValue, authenticationTransactionId, customerIpAddress, authenticatedByMerchant Example: cardholderAuthentication Structure BwABBJQ1AgAAAAAgJDUCAAAAAAA= EaOMucALHQqLAEGAgk= Customer Ip Boolean NOTE: 426 The values for the and elements in the example above have been truncated. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide cardholderId cnpAPI Elements 4.76 cardholderId The cardholderId element is a required child of the pos element, which describes the method used for cardholder identification at the point of sale. Type = String (Enum); minLength = N/A; maxLength = N/A Parent Elements: pos Attributes: None Child Elements: None Enumerations: Enumeration Description signature customer signature obtained pin PIN number nopin unattended terminal - no PIN pad directmarket mail, telephone, or online NOTE: For CAT (Cardholder Activated Terminal) transactions, the capability element must be set to magstripe, the cardholderId element must be set to nopin, and the catLevel element must be set to self service. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 427 cnpAPI Reference Guide cnpAPI Elements cardholderName 4.77 cardholderName The cardholderName element is an optional child of the applepayResponse element and provides the name of the cardholder whose card initiated the Apple Pay transaction. Type = String; minLength = N/A; maxLength = 512 Parent Elements: applepayResponse Child Elements: None 428 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide cardOrToken cnpAPI Elements 4.78 cardOrToken The cardOrToken element is an abstract that allows the substitution of either the card or token element. You must specify one of the two substitution elements as a child of the accountUpdate element. Parent Elements: accountUpdate Substitution Options: card, token Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 429 cnpAPI Reference Guide cnpAPI Elements cardProductType 4.79 cardProductType The cardProductType element is an optional child of the enhancedAuthResponse element and whether the card used is commercial or consumer. Type = String (enum); minLength = N/A; maxLength = N/A Parent Elements: enhancedAuthResponse Attributes: None Child Elements: None Enumerations: 430 Enumeration Description COMMERCIAL The card is a commercial card. CONSUMER The card is a consumer card. UNKNOWN The type of card is not known. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide cardSuffix cnpAPI Elements 4.80 cardSuffix The cardSuffix element is an optional child of both the authorizationResponse and saleResponse elements. It provides the last four digits of the actual PAN for Apple Pay transactions, when the underlying card is either Visa or MasterCard. Type = String; minLength = 3; maxLength = 6 Parent Elements: authorizationResponse, saleResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 431 cnpAPI Reference Guide cnpAPI Elements cardValidationNum 4.81 cardValidationNum The cardValidationNum element is an optional child of the card element, which you use to submit either the CVV2 (Visa), CVC2 (MasterCard), or CID (American Express and Discover) value.5 NOTE: Some American Express cards may have a 4-digit CID on the front of the card and/or a 3-digit CID on the back of the card. You can use either of the numbers for card validation, but not both. When you submit the CVV2/CVC2/CID in a registerTokenRequest, the platform encrypts and stores the value on a temporary basis for later use in a tokenized Auth/Sale transaction submitted without the value. This is done to accommodate merchant systems/workflows where the security code is available at the time of token registration, but not at the time of the Auth/Sale. If for some reason you need to change the value of the security code supplied at the time of the token registration, use an updateCardValidationNumOnToken transaction. To use the store value when submitting an Auth/Sale transaction, set the cardValidationNum value to 000. The cardValidationNum element is an optional child of the virtualGiftCardResponse element, where it defines the value of the validation Number associated with the Virtual Gift Card requested. NOTE: The use of the cardValidationNum element in the registertokenRequest only applies when you submit an accountNumber element. Type = String; minLength = N/A; maxLength = 4 Parent Elements: card, paypage, token, registerTokenRequest, updateCardValidationNumOnToken, virtualGiftCardResponse Attributes: None Child Elements: None 432 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide cardValidationResult cnpAPI Elements 4.82 cardValidationResult The cardValidationResult element is an optional child element of the fraudResult element. It defines the Card Validation response code returned by the networks. For a list of possible values, please refer to Card Validation Response Codes on page 846. Type = String; minLength = N/A; maxLength = 2 Parent Elements: fraudResult Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 433 cnpAPI Reference Guide cnpAPI Elements cashBackAmount 4.83 cashBackAmount The cashBackAmount element is an optional child of the giftCardResponse element. It defines the Cash Back amount provided to the Gift Card holder. NOTE: Although included in the schema, the beginningBalance, endingBalance, and cashBackAmount elements are not currently supported. Type = String; minLength = N/A; maxLength = 20 Parent Elements: giftCardResponse Attributes: None Child Elements: None 434 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide catLevel cnpAPI Elements 4.84 catLevel The catLevel element is an optional child of the pos element, which describes the capability of the Cardholder Activated Terminal. Although optional in the schema, it is required for all CAT transactions. Type = String (Enum); minLength = N/A; maxLength = N/A Parent Elements: pos Attributes: None Child Elements: None Enumerations: Enumeration Description self service Cardholder Activated Terminal level Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 435 cnpAPI Reference Guide cnpAPI Elements ccdPaymentInformation 4.85 ccdPaymentInformation The ccdPaymentInformation element is an optional child of the echeck element. This element is intended for use by PayFacs using Instruction Based Dynamic Payout to submit a description of the transaction. The description will appear in the extended detail section of the receiver’s bank statement, if that section is supported by the receiver’s bank. Type = String; minLength = N/A; maxLength = 80 Parent Elements: accountInfo, echeck Attributes: None Child Elements: None 436 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide chargeback cnpAPI Elements 4.86 chargeback The chargeback element is an optional child of the filtering element. To disable the chargeback filtering operation for a selected transaction include the chargeback element with a setting of false. Type = Boolean; Valid Value = false NOTE: Although included in the schema, the element is not supported. To override the chargeback filter for a selected transaction, use the fraudFilterOverride flag (see fraudFilterOverride on page 540). Please consult your Relationship Manager for additional information. Parent Elements: filtering Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 437 cnpAPI Reference Guide cnpAPI Elements checkNum 4.87 checkNum The checkNum element is an optional child of the echeck element defining the check number of used in the transaction. Type = String; minLength = N/A; maxLength = 15 Parent Elements: echeck Attributes: None Child Elements: None 438 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide checkoutId cnpAPI Elements 4.88 checkoutId The checkoutId element is an optional child of the token element specifying the low value token replacing the CVV value. You use this feature when you already have the consumer’s card (i.e., token) on file, but wish the consumer to supply the CVV value for a new transaction. This LVT remains valid for 24 hours from the time of issue. NOTE: For additional information about this element, please refer to the Vantiv Enterprise eProtect Integration Guide. Type = String; minLength = 18; maxLength = 18 Parent Elements: token Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 439 cnpAPI Reference Guide cnpAPI Elements city 4.89 city The city element defines the customer’s city name in the billToAddress and shipToAddress elements. In the customBilling element, city defines the location of the merchant for card-present transactions. Type = String; minLength = N/A; maxLength = 35 Parent Elements: billToAddress, shipFromPostalCode, customBilling Attributes: None Child Elements: None 440 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide clinicOtherAmount cnpAPI Elements 4.90 clinicOtherAmount The clinicAmount element is an optional child of the healthcareAmounts element and defines the healthcare amount used for the clinic/office visits. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: Optional: healthcareAmounts Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 441 cnpAPI Reference Guide cnpAPI Elements code 4.91 code The code element is a required child of the extendedCardResponse element. The code/message combination can be either 501- The account was closed, or 504 - Contact the cardholder for updated information. Type = String; minLength = N/A; maxLength = 3 Parent Elements: extendedCardResponse Attributes: None Child Elements: None 442 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide commodityCode cnpAPI Elements 4.92 commodityCode The commodityCode element is an optional child of the lineItemData element, which specifies the Identifier assigned by the card acceptor that categorizes the purchased item. Although the schema defines it as an optional child of the enhancedData element, it is required by Visa for Level III interchange rates. Type = String; minLength = 1; maxLength = 12 Parent Elements: lineItemData Attributes: None Child Elements: None NOTE: A commodity code is a numeric code representing a particular product or service. The code can be 3, 5, 7, or 11 digits in length. The longer the code the more granular the description of the product/service. For example, code 045 is used for Appliances and Equipment, Household Type, while code 04506 represents the sub-set of Appliances, Small Electric. The codes are issued by the NIGP (National Institute of Governmental Purchasing. Their site, www.nigp.com, offers a subscription based code search engine, as well as downloadable lists for purchase. You can also find many lists published online by performing a simple search on “Commodity Codes”. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 443 cnpAPI Reference Guide cnpAPI Elements companyName 4.93 companyName The companyName element is an optional child of the billToAddress element, which specifies the name of the company associated with the corporate checking account. This element is required when performing an eCheck Verification of a check from a corporate account, as defined by the child of the element. Type = String; minLength = N/A; maxLength = 40 Parent Elements: billToAddress Attributes: None Child Elements: None 444 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide country cnpAPI Elements 4.94 country The country element defines the country portion of the postal mailing address in both the billToAddress and shipToAddress elements. Type = String (Enum); minLength = N/A; maxLength = 3 NOTE: The enumerations for this element are listed under in the cnpAPI Common XSD. The country names corresponding to the abbreviations can be found in the ISO 3166-1 standard. All Country Codes are 2-character except for the United States, which accepts both US and USA. The country element is required for sale transactions using the sepaDirectDebit method of payment. Failure to include the name element results in a 903 - Missing Billing Country Code Response Code. Parent Elements: billToAddress, shipFromPostalCode Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 445 cnpAPI Reference Guide cnpAPI Elements createAddOn 4.95 createAddOn The createAddOn element is the parent of several child elements used to define an additional charge added to a new or existing subscription. Parent Elements: subscription, updateSubscription Attributes: None Child Elements (all Required): addOnCode, name, amount, startDate, endDate Example: customerInfo Structure Add On Reference Code Name of Add On Amount of Add On Start Date of Add On Charge End Date of Add On Charge 446 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide createDiscount cnpAPI Elements 4.96 createDiscount The createDiscount element is the parent of several child elements used to define a discount to be applied to a new or existing subscription. Parent Elements: subscription, updateSubscription Attributes: None Child Elements (all Required): discountCode, name, amount, startDate, endDate Example: customerInfo Structure Discount Reference Code Name of Discount Amount of Discount Start Date of Discount End Date of Discount Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 447 cnpAPI Reference Guide cnpAPI Elements createPlan 4.97 createPlan The createPlan element is the parent of several child element that define the attributes of a recurring payment plan. You associate Plans with subscriptions to define the billing behavior for the recurring payment. Parent Elements: litleOnlineRequest, batchRequest Attributes: None Child Elements: planCode, name, description, intervalType, amount, numberOfPayments, trialNumberOfIntervals, trialIntervalType, active Example: createPlan Structure Plan Reference Code Name of Plan Description of Plan The Type of Interval Amount of Recurring Payment 1 to 99 Number of Trial Period Intervals Type of Trial Period Interval true or false 448 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide createPlanResponse cnpAPI Elements 4.98 createPlanResponse The createPlanResponse element is the parent element for the response to a createPlan transaction. Parent Elements: litleOnlineResponse, batchResponse Attributes: None Child Elements: planCode, litleTxnId, response, message, responseTime Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 449 cnpAPI Reference Guide cnpAPI Elements credit 4.99 credit The credit element is the parent element for all Credit transactions. You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: For credits to transactions processed by Vantiv (Required): litleTxnId For credits to transactions processed by Vantiv (Optional): amount, payPalNotes, pin, secondaryAmount, surchargeAmount NOTE: If you do not specify an amount, the system uses the full amount from the associated settlement transaction. You must include the amount element for credits to transactions not processed by Vantiv For credits to transactions not processed by Vantiv (Required): orderId, amount, orderSource, choice of card, token, paypage, mpos, paypal, or applepay For credits to transactions not processed by Vantiv (Optional): billToAddress, billMeLaterRequest, amexAggregatorData For both transaction types (Optional): customBilling, taxType, enhancedData, processingInstructions, merchantData, actionReason, pos 450 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide creditAmount cnpAPI Elements 4.100 creditAmount The creditAmount element is a required child of the giftCardCredit transaction, where it specifies the amount of the refund. Supply the value in cents without a decimal point. For example, a value of 1995 signifies $19.95. Type = Integer; totalDigits = 12 Parent Elements: giftCardCredit Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 451 cnpAPI Reference Guide cnpAPI Elements creditLine 4.101 creditLine The creditLine element is an optional child of the billMeLaterResponseData element and indicates the credit line of the customer. The amount is specified using a two-digit implied decimal. Type = Integer; totalDigits = 8 Parent Elements: billMeLaterResponseData Attributes: None Child Elements: None 452 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide creditLitleTxnId cnpAPI Elements 4.102 creditLitleTxnId The creditLitleTxnId element is the Transaction Id (litleTxnId) of a Credit transaction automatically submitted under the following conditions: • You submitted a Void transaction to halt the recycling of a declined Sale transaction by the Recovery/Recycling Engine. • The Sale transaction has already been approved and captured. • Your Recovery/Recycling Engine configuration enables automatic refunds. • The system has successfully submitted a Credit transaction on your behalf. Type = Long; minLength = N/A; maxLength = 19 Parent Elements: recycling Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 453 cnpAPI Reference Guide cnpAPI Elements creditResponse 4.103 creditResponse The creditResponse element is the parent element for information returned to you in response to a Credit transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the credit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the credit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the credit transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, tokenResponse, giftCardResponse, applepayResponse NOTE: 454 The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide cryptogram cnpAPI Elements 4.104 cryptogram The cryptogram element is an optional child of the androidResponse element and provides the BASE64 Encoded signature cryptogram associated with the Android Pay transaction. Type = Base 64 Encoded String; minLength = N/A; maxLength = 56 Parent Elements: androidpayResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 455 cnpAPI Reference Guide cnpAPI Elements currencyCode 4.105 currencyCode The currencyCode element is an optional child of the applepayResponse element and provides the 3-character code for the currency used in the transaction. Type = String; minLength = N/A; maxLength = 3 Parent Elements: applepayResponse Attributes: None Child Elements: None 456 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide customAttribute1 cnpAPI Elements 4.106 customAttribute1 The customAttribute1 through customAttribute5 elements are an optional children of the advancedFraudChecks element. These elements allow users of Advanced Fraud Tools with self-serve rules to submit additional custom data to ThreatMetrix for inclusion in the fraud evaluation process. For example, if you assigned a certain attribute to your customers for segmentation purposes, you might wish to submit the assigned value and also establish a ThreatMetrix rule so the value was included in the evaluation. NOTE: Once you decide to use a particular custom attribute for a particular value set and establish a rule for its evaluation, you Type = String; minLength = 1; maxLength = 200 Parent Elements: advancedFraudChecks Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 457 cnpAPI Reference Guide cnpAPI Elements customBilling 4.107 customBilling The customBilling element allows you to specify custom billing descriptor information for the transaction. This billing descriptor is used instead of the descriptor defined as the default billing descriptor. If you do not define this element, the system uses the default. NOTE: If you submit a captureGivenAuth transaction with a customBilling element and Vantiv finds a matching Authorization (see Capture Given Auth Transaction on page 79), the system uses the customBilling information from the Authorization and discards the information from the captureGivenAuth. Parent Elements: authorization, captureGivenAuth, credit, echeckCredit, echeckSale, forceCapture, sale IMPORTANT: Although the schema includes the customBilling element as a child of echeckCredit and echeckSale, Vantiv does not support its use in these instances. Attributes: None Child Elements: Please consult your Relationship Manager prior to using the element. The contents of this element are discarded unless Vantiv specifically enables to use it in your cnpAPI submissions.Required for card-not-present transactions: phone, or url NOTE: Please consult your Relationship Manager prior to using the element. The contents of this element are discarded unless Vantiv specifically enables the use it in your cnpAPI submissions. Required for card present transactions: city Optional for either: descriptor Example: customBilling Structure - Card-Not-Present (using phone child) Telephone Number Billing Descriptor 458 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide customBilling cnpAPI Elements Example: customBilling Structure - Card-Not-Present (using url child) retail.url www.retail.com Example: customBilling Structure - Card-Present City Billing Descriptor Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 459 cnpAPI Reference Guide cnpAPI Elements customIdentifier 4.108 customIdentifier The customIdentifier element is an optional child of Sub-merchant funding instruction request transaction types, as well as eCheck Sale/Credit/Redeposit requests. PayFacs/Merchants can use this element to specify a Billing Descriptor to appear on the bank statements of the parties involved in the funds transfer or eCheck transaction. NOTE: The information you provide in this element populates the Individual ID field of the ACH Record. The use of this field and its appearance on bank statements is at the discretion of the bank producing the statement. Type = String; minLength = N/A; maxLength = 15 Parent Elements: echeckCredit, echeckRedeposit, echeckSale, submerchantCredit, submerchantDebit Attributes: None Child Elements: None 460 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide customerInfo cnpAPI Elements 4.109 customerInfo The customerInfo element is the parent of several child elements use to define customer information for PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Parent Elements: authorization, sale Attributes: None Child Elements: ssn, dob, customerRegistrationDate, customerType, incomeAmount, employerName, customerWorkTelephone, residenceStatus, yearsAtResidence, yearsAtEmployer NOTE: Under certain conditions PayPal Credit requires you to include ssn, dob, customerType and customerRegistrationDate. Example: customerInfo Structure ssn dob customerRegistrationDate customerType incomeAmount incomeCurrency employerName customerWorkTelephone residenceStatus yearsAtResidence yearsAtEmployer Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 461 cnpAPI Reference Guide cnpAPI Elements customerIpAddress 4.110 customerIpAddress The customerIpAddress element is an optional child element of the cardholderAuthentication element. This element defines the IP Address of the customer's system. This element is used either for PayPal Credit transactions or to supply the customer IP Address by merchants enabled for American Express Advanced AVS services. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = Ip Address; Format = nnn.nnn.nnn.nnn NOTE: This element is required for BML ecommerce transactions to succeed. Parent Elements: cardholderAuthentication Attributes: None Child Elements: None 462 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide customerReference cnpAPI Elements 4.111 customerReference The customerReference element defines a reference string used by the customer for the purchase (for example, a Purchase Order Number). Although the schema defines it as an optional child of the enhancedData element, Vantiv recommends you include the element if a value is available/supplied and omit this element if it is blank. Type = String; minLength = 1; maxLength = 17 Parent Elements: enhancedData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 463 cnpAPI Reference Guide cnpAPI Elements customerRegistrationDate 4.112 customerRegistrationDate The customerRegistrationDate element is an optional child of the customerInfo element defining the earliest date on file with this customer. The latest allowable date is the current date. It is used in combination with several other elements to provide required information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = Date; Format = YYYY-MM-DD NOTE: In order for a BML transaction to succeed, you must include this element if the customer does not have a BML account. Parent Elements: customerInfo Attributes: None Child Elements: None 464 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide customerType cnpAPI Elements 4.113 customerType The customerType element is an optional child of the customerInfo element defining whether the customer is a new or existing customer. An existing customer is a customer in good standing that has been registered with the merchant for a minimum of 30 days and has made at least one purchase in the last 30 days. It is used in combination with several other elements to provide required information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = Choice (Enum); Enumerations = New or Existing NOTE: In order for a PayPal Credit transaction to succeed, you must include this element if the customer does not have a PayPal Credit account. Parent Elements: customerInfo Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 465 cnpAPI Reference Guide cnpAPI Elements customerWorkTelephone 4.114 customerWorkTelephone The customerWorkTelephone element is an optional child of the customerInfo element and defines the customer’s work telephone number. It is used in combination with several other elements to provide information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = String; minLength = N/A; maxLength = 20 Parent Elements: customerInfo Attributes: None Child Elements: None 466 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide data cnpAPI Elements 4.115 data The data element is a required child of the applepay element. It is the payment data dictionary, BASE64 encoded string from the PKPaymentToken. Type = String; minLength = N/A; maxLength = 2000 Parent Elements: applepay Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 467 cnpAPI Reference Guide cnpAPI Elements deactivate 4.116 deactivate The deactivate element is the parent element for the transaction type that deactivate a Gift Card. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (all Required) orderId, orderSource, card 468 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide deactivateResponse cnpAPI Elements 4.117 deactivateResponse The deactivateResponse element is the parent element for information returned to you in response to a deactivate transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Deactivate transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Deactivate transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Deactivate transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, fraudResult, giftCardResponse Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 469 cnpAPI Reference Guide cnpAPI Elements deactivateReversal 4.118 deactivateReversal The deactivateReversal element is the parent element for the transaction type that reverses the deactivation of a Gift Card. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) card, originalRefCode, originalAmount, originalTxnTime, originalSystemTraceId, originalSequenceNumber Child Elements: (Optional) litleTxnId 470 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide deactivateReversalResponse cnpAPI Elements 4.119 deactivateReversalResponse The deactivateReversalResponse element is the parent element for information returned to you in response to an deactivateReversal transaction. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Deactivate Reversal transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Deactivate Reversal transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Deactivate Reversal transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, giftCardResponse Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 471 cnpAPI Reference Guide cnpAPI Elements debtRepayment 4.120 debtRepayment The debtRepayment element is an optional child of authorization, captureGivenAuth, forceCapture, and sale transactions. You use this flag only if the method of payment is Visa and the transaction is a for a debt repayment. Also, your MCC must be either 6012 or 6051. If you set this flag to true and you are not one of the allowed MCCs, the system declines the transaction with a Response Reason Code of 852 - Debt Repayment only allowed for VI transactions on MCCs 6012 and 6051. Type = Boolean; Valid Values = true or false (default) Parent Elements: authorization, captureGivenAuth, forceCapture, sale Attributes: None Child Elements: None 472 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide deleteAddOn cnpAPI Elements 4.121 deleteAddOn The deleteAddOn element is the parent element used to define an Add On to be removed from an existing subscription. Parent Elements: updateSubscription Attributes: None Child Elements (all Required): addOnCode Example: deleteAddOn Structure Add On Reference Code Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 473 cnpAPI Reference Guide cnpAPI Elements deleteDiscount 4.122 deleteDiscount The deleteDiscount element is the parent element used to define a discount to be removed from an existing subscription. Parent Elements: updateSubscription Attributes: None Child Elements (all Required): discountCode Example: deleteDiscount Structure Discount Reference Code 474 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide deliveryType cnpAPI Elements 4.123 deliveryType The deliveryType element is an optional child of the enhancedData element and defines the shipping method used for delivery of the product. Type = String (enum); minLength = N/A; maxLength = N/A Parent Elements: enhancedData Attributes: None Child Elements: None Enumerations: Enumeration Description CNC Cash and Carry DIG Digital Delivery PHY Physical Delivery SVC Service Delivery TBD (default) To be determined. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 475 cnpAPI Reference Guide cnpAPI Elements dentalAmount 4.124 dentalAmount The dentalAmount element is an optional child of the healthcareAmounts element and defines the healthcare amount used for dental related purchases. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: Optional: healthcareAmounts Attributes: None Child Elements: None 476 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide depositReversal cnpAPI Elements 4.125 depositReversal The depositReversal element is the parent element for a Gift Card specific transaction type that reverses a giftCardCapture or sale transaction. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) card, originalRefCode, originalAmount, originalTxnTime, originalSystemTraceId, originalSequenceNumber Child Elements: (Optional) litleTxnId Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 477 cnpAPI Reference Guide cnpAPI Elements depositReversalResponse 4.126 depositReversalResponse The depositReversalResponse element is the parent element for information returned to you in response to an depositReversal transaction. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Deposit Reversal transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Deposit Reversal transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Deposit Reversal transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message, giftCardResponse Optional: postDate 478 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide description cnpAPI Elements 4.127 description The description element is an optional child of the createPlan element and provides a text description of the Plan. Type = String; minLength = N/A; maxLength = 100 Parent Elements: createPlan Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 479 cnpAPI Reference Guide cnpAPI Elements descriptor 4.128 descriptor The descriptor element is an optional child of the customBilling element. This element defines the text you wish to display on the customer bill, enabling the customer to better recognize the charge. Type = String; minLength = 4; maxLength = 25 NOTE: If you include a prefix: • the prefix must be either 3, 7, or 12 characters in length. • you must use an asterisk (*) after the prefix as a separator, in one of the following positions: 4th, 8th, or 13th. Do not use an asterisk in more than one position. • Use only the following valid characters: – Numbers – Letters – Special characters as follows: ampersand, asterisk (Required; see note above), comma, dash, period, or pound sign. Parent Elements: customBilling Attributes: None Child Elements: None NOTE: 480 When using a descriptor with eChecks, Vantiv maps the first 16 characters to the Company Name field of the ACH message and the last nine characters as the company phone number. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide destinationCountryCode cnpAPI Elements 4.129 destinationCountryCode The destinationCountryCode element defines the country portion of the postal mailing address in the enhancedData element. Type = String (Enum); minLength = N/A; maxLength = 3 NOTE: The enumerations for this element are listed under in the cnpAPI Common XSD. The country names corresponding to the abbreviations can be found in the ISO 3166-1 standard. Parent Elements: enhancedData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 481 cnpAPI Reference Guide cnpAPI Elements destinationPostalCode 4.130 destinationPostalCode The destinationPostalCode element defines the postal code of the destination in the enhancedData element. Type = String; minLength = N/A; maxLength = 20 NOTE: Although the schema specifies the maxLength of the element as 20 characters, in practice you should never exceed 10 characters in your submissions. Parent Elements: enhancedData Attributes: None Child Elements: None 482 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide detailTax cnpAPI Elements 4.131 detailTax The detailTax element is an optional child of both the enhancedData and lineItemData elements, which you use to specify detailed tax information (for example, city or local tax). The total sum of the detailTax values should match either the salesTax value, if detailTax is a child of enhancedData, or the taxAmount element if detailTax is a child of lineItemData. Parent Elements: enhancedData, lineItemData NOTE: The detailTax element can appear a maximum of six times as a child of either parent. Attributes: None Child Elements: Required: taxAmount Optional: taxIncludedInTotal, taxRate, taxTypeIdentifier, cardAcceptorTaxId Example: detailTax Structure true or false Additional Tax Amount Tax Rate of This Tax Amount Tax Type Enum Tax ID of Card Acceptor Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 483 cnpAPI Reference Guide cnpAPI Elements deviceManufacturerIdentifier 4.132 deviceManufacturerIdentifier The deviceManufacturerIdentifier element is an optional child of the applepayResponse element and defines the manufacturer of the device originating the transaction. Type = String; minLength = N/A; maxLength = 20 Parent Elements: applepayResponse Attributes: None Child Elements: None 484 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide deviceReputationScore cnpAPI Elements 4.133 deviceReputationScore The deviceReputationScore element is an optional child of the advancedFraudResults element and specifies score resulting from the ThreatMetrix analysis of the customer device. Type = Integer; totalDigits = 8 Parent Elements: advancedFraudResults Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 485 cnpAPI Reference Guide cnpAPI Elements deviceReviewStatus 4.134 deviceReviewStatus The deviceReviewStatus element is a required child of the advancedFraudResults element and specifies the results of the comparison of the deviceReputationScore against the threshold levels configured for the merchant. Typical values are: pass, fail, review, unavailable, and invalid_session. NOTE: The system returns invalid_session if you submitted a session Id using an invalid prefix. Type = String; minLength = N/A; maxLength = Parent Elements: advancedFraudResults Attributes: None Child Elements: None 486 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide discountAmount cnpAPI Elements 4.135 discountAmount The discountAmount element defines the amount of the discount for the order. Although the schema defines it as an optional child of the enhancedData element, it is required by Visa for Level III interchange rates. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: enhancedData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 487 cnpAPI Reference Guide cnpAPI Elements discountCode 4.136 discountCode The discountCode element is the identifier of a defined discount. You use this element when creating, updating, and deleting a discount applied to a subscription. Type = String; minLength = N/A; maxLength = 25 Parent Elements: createDiscount, updateDiscount, deleteDiscount Attributes: None Child Elements: None 488 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide dob cnpAPI Elements 4.137 dob The dob element is an optional child of the customerInfo element. It is used in combination with several other elements to provide required information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = Date; Format = YYYY-MM-DD NOTE: In order for a PayPal Credit transaction to succeed, you must include this element if: • the customer does not have a PayPal Credit account or • the customer has a PayPal Credit account, but the account has not been authenticated. You do not need to include this element if the PayPal Credit account has been authenticated. Parent Elements: customerInfo Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 489 cnpAPI Reference Guide cnpAPI Elements dutyAmount 4.138 dutyAmount The dutyAmount element defines duty on the total purchased amount for the order. Although the schema defines it as an optional child of the enhancedData element, it is required by Visa for Level III interchange rates. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: enhancedData Attributes: None Child Elements: None 490 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeck cnpAPI Elements 4.139 echeck The echeck element is a required child of the echeckSale, echeckVerification, and echeckCredit (when the credit is against a transaction not originally processed through our system) elements. It contains child elements used to provide details concerning the eCheck account. Parent Elements: echeckCredit, echeckPreNoteCredit, echeckPreNoteSale, echeckSale, echeckVerification Attributes: None Child Elements: Required: accType, accNum, routingNum Optional: checkNum, ccdPaymentInformation Example: echeck Structure Account Type Abbreviation Account Number Routing Number Check Number Payment Description Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 491 cnpAPI Reference Guide cnpAPI Elements eCheckAccountSuffix 4.140 eCheckAccountSuffix The eCheckAccountSuffix element is an optional child of the tokenResponse element that provides the last three characters of the eCheck account number. Type = String; minLength = 3; maxLength = 3 Parent Elements: registerTokenResponse, tokenResponse Attributes: None Child Elements: None 492 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckCredit cnpAPI Elements 4.141 echeckCredit The echeckCredit element is the parent element for all eCheck Credit transactions. You can use this element in either Batch or Online transactions. IMPORTANT: Although the schema includes the customBilling element as a child of echeckCredit and echeckSale, Vantiv does not support its use in these instances. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type id String Yes Required? Description A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: For credits to transactions processed by Vantiv (Required): litleTxnId For credits to transactions processed by Vantiv (Optional): amount NOTE: Omit the amount child element, to use the full amount from the echeckSale. For credits to transactions not processed by Vantiv (Required): orderId, amount, orderSource, billToAddress, echeckOrEcheckToken (allows the substitution of either the echeck or echeckToken elements) For credits to transactions not processed by Vantiv (Optional): merchantData For both (Optional): customBilling, secondaryAmount, customIdentifier Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 493 cnpAPI Reference Guide cnpAPI Elements echeckCreditResponse 4.142 echeckCreditResponse The echeckCreditResponse element is the parent element for information returned to you in response to an echeckCredit transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the echeckCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the echeckCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the echeckCredit transaction. minLength = 1 maxLength = 25 Child Elements: (all Required) litleTxnId, response, responseTime, message Optional: postDate, accountUpdater NOTE: 494 The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckForToken cnpAPI Elements 4.143 echeckForToken The echeckForToken element is a child of the registerTokenRequest element. It contains the routing and account number of the eCheck account which the system uses to generate a token. Parent Elements: registerTokenRequest Attributes: None Child Elements: Required: accNum, routingNum Example: echeck Structure Account Number Routing Number Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 495 cnpAPI Reference Guide cnpAPI Elements echeckOrEcheckToken 4.144 echeckOrEcheckToken The echeckOrEcheckToken element is an abstract that allows the substitution of either the echeck or echeckToken element. In eCheck transactions, except echeckVoid, you must specify one of the two substitution elements as a child. Parent Elements: echeckCredit, echeckRedeposit, echeckSale, echeckVerification Substitution Options: echeck, echeckToken 496 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckPreNoteCredit cnpAPI Elements 4.145 echeckPreNoteCredit The echeckPreNoteCredit element is the parent element for all eCheck Prenotification Credit transactions. You use this transaction type to perform an eCheck Prenotification, when the subsequent eCheck transaction will be an eCheck Credit transaction. You can use this element only in Batch transactions. This transaction type is only supported for US transactions. Parent Elements: batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, orderSource, billToAddress, echeck Optional: merchantData Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 497 cnpAPI Reference Guide cnpAPI Elements echeckPreNoteCreditResponse 4.146 echeckPreNoteCreditResponse The echeckPreNoteCreditResponse element is the parent element for information returned to you in response to an echeckPreNoteCredit transaction. Parent Elements: batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the echeckCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the echeckCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the echeckCredit transaction. minLength = 1 maxLength = 25 Child Elements: (all Required) litleTxnId, response, responseTime, message 498 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckPreNoteSale cnpAPI Elements 4.147 echeckPreNoteSale The echeckPreNoteSale element is the parent element for all eCheck Prenotification Sale transactions. You use this transaction type to perform an eCheck Prenotification, when the subsequent eCheck transaction will be an eCheck Sale transaction. You can use this element only in Batch transactions. This transaction type is only supported for US transactions. Parent Elements: batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, orderSource, billToAddress, echeck Optional: merchantData Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 499 cnpAPI Reference Guide cnpAPI Elements echeckPreNoteSaleResponse 4.148 echeckPreNoteSaleResponse The echeckPreNoteSaleResponse element is the parent element for information returned to you in response to an echeckPreNoteSale transaction. Parent Elements: batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the echeckCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the echeckCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the echeckCredit transaction. minLength = 1 maxLength = 25 Child Elements: (all Required) litleTxnId, response, responseTime, message 500 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckRedeposit cnpAPI Elements 4.149 echeckRedeposit The echeckRedeposit element is the parent element for all eCheck Redeposit transactions. You use this transaction type to manually attempt redeposits of eChecks returned for either Insufficient Funds or Uncollected Funds. You can use this element in either Batch or Online transactions. NOTE: Do not use this transaction type if you are enabled for the Auto Redeposit feature. If you are enabled for the Auto Redeposit feature, the system will reject any echeckRedeposit transaction you submit. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId Optional: echeckOrEcheckToken (allows the substitution of either the echeck or echeckToken elements), merchantData, customIdentifier Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 501 cnpAPI Reference Guide cnpAPI Elements echeckRedepositResponse 4.150 echeckRedepositResponse The echeckRedepositResponse element is the parent element for information returned to you in response to an echeckRedeposit transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the echeckSale transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the echeckSale transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the echeckSale transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, accountUpdater NOTE: 502 The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckSale cnpAPI Elements 4.151 echeckSale The echeckSale element is the parent element for all eCheck Sale transactions. You can use this element in either Batch or Online transactions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, amount, orderSource, billToAddress, echeckOrEcheckToken (allows the substitution of either the echeck or echeckToken elements) NOTE: You must use one of the following values for the orderSource element: telephone, ecommerce, recurringtel, or echeckppd. Optional: shipToAddress, verify, customBilling, merchantData, secondaryAmount, customIdentifier IMPORTANT: Although the schema includes the customBilling element as a child of echeckCredit and echeckSale, Vantiv does not support its use in these instances. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 503 cnpAPI Reference Guide cnpAPI Elements echeckSalesResponse 4.152 echeckSalesResponse The echeckSalesResponse element is the parent element for information returned to you in response to an echeckSale transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the echeckSale transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the echeckSale transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the echeckSale transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, accountUpdater, tokenResponse NOTE: 504 The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckToken cnpAPI Elements 4.153 echeckToken The echeckToken element replaces the echeck element in tokenized eCheck transactions and defines the tokenized account information. Parent Elements: echeckCredit, echeckRedeposit, echeckSale, echeckVerification Attributes: None Child Elements: Required: litleToken, routingNum, accType Optional: checkNum Example: echeck Structure Token Routing Number Account Type Abbreviation Check Number Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 505 cnpAPI Reference Guide cnpAPI Elements echeckVerification 4.154 echeckVerification The echeckVerification element is the parent element for all eCheck Verification transactions. You use this transaction type to initiate a comparison of the consumer’s account information against positive/negative databases. You can use this element in either Batch or Online transactions. This transaction type is only supported for US transactions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, amount, orderSource, billToAddress, echeckOrEcheckToken (allows the substitution of either the echeck or echeckToken elements) Optional: merchantData 506 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckVerificationResponse cnpAPI Elements 4.155 echeckVerificationResponse The echeckVerificationResponse element is the parent element for information returned to you in response to a eCheck Verification transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the capture transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate NOTE: The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 507 cnpAPI Reference Guide cnpAPI Elements echeckVoid 4.156 echeckVoid The echeckVoid element is the parent element for all eCheck Void transactions. You use this transaction type to either cancel an eCheck Sale transaction, as long as the transaction has not yet settled, or halt automatic redeposit attempts of eChecks returned for either Insufficient Funds or Uncollected Funds. You can use this element only in Online transactions. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId 508 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide echeckVoidResponse cnpAPI Elements 4.157 echeckVoidResponse The echeckVoidResponse element is the parent element for information returned to you in response to an eCheck Void transaction. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the void transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the void transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the void transaction. minLength = 1 maxLength = 25 Child Elements: (all Required) litleTxnId, response, responseTime, message, postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 509 cnpAPI Reference Guide cnpAPI Elements eciIndicator 4.158 eciIndicator The eciIndicator element is an optional child of the applepayResponse and androidpayResponse elements and specifies electronic commerce indicator associated with an Apple Pay/Android Pay transaction. Type = String; minLength = N/A; maxLength = 2 Parent Elements: applepayResponse, androidpayResponse Attributes: None Child Elements: None 510 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide email cnpAPI Elements 4.159 email The email element defines the email address of the customer in both the billToAddress and shipToAddress elements. NOTE: The email element is required for sale transactions using the sepaDirectDebit method of payment. Failure to include the name element results in a 905 - Missing Email Address Response Code. Type = String; minLength = N/A; maxLength = 100 Parent Elements: billToAddress, shipToAddress Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 511 cnpAPI Reference Guide cnpAPI Elements employerName 4.160 employerName The employerName element is an optional child of the customerInfo element and defines the name of the customer’s place of employment. It is used in combination with several other elements to provide information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = String; minLength = N/A; maxLength = 20 Parent Elements: customerInfo Attributes: None Child Elements: 512 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide encryptedTrack cnpAPI Elements 4.161 encryptedTrack The encryptedTrack element is a required child of the mpos element. This element provides the encrypted track data resulting from a card swipe using a ROAM device. Type = String; minLength = 1; maxLength = 1028 Parent Elements: mpos Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 513 cnpAPI Reference Guide cnpAPI Elements endDate 4.162 endDate The endDate element is a optional child of both the createAddOn and createDiscount element, where it specifies either the ending date of the Add On charge or the ending date of the discount. Type = Date; Format = YYYY-MM-DD Parent Elements: createAddOn, createDiscount Attributes: None Child Elements: None 514 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide endingBalance cnpAPI Elements 4.163 endingBalance The endingBalance element is an optional child of the giftCardResponse element. It defines the available balance on the submitted Gift Card after the requested operation. NOTE: Although included in the schema, the beginningBalance, endingBalance, and cashBackAmount elements are not currently supported. Type = String; minLength = N/A; maxLength = 20 Parent Elements: giftCardResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 515 cnpAPI Reference Guide cnpAPI Elements endpoint 4.164 endpoint The endpoint element is a required child of the networkResponse element. It defines the card network (i.e., Visa, MasterCard, Discover, or American Express) acting as an endpoint for the submitted transaction. Type = String; minLength = N/A; maxLength = 256 Parent Elements: networkResponse Attributes: None Child Elements: None 516 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide enhancedAuthResponse cnpAPI Elements 4.165 enhancedAuthResponse The enhancedAuthResponse element is an optional child of both the authorizationResponse and saleResponse elements. Through its child elements, it can provide information concerning whether the card used for the transaction is Prepaid and if so, the available balance. Depending upon the card used, other elements can indicate affluence, card product type, prepaid card type, reloadability and whether or not it is a virtual account number. Parent Elements: authorizationResponse, saleResponse Attributes: None Child Elements: (all Optional) fundingSource, affluence, issuerCountry, cardProductType, virtualAccountNumber, networkResponse Example: enhancedAuthResponse - with fundingSource PREPAID 0 YES|NO|UNKNOWN GIFT Example: enhancedAuthResponse - with affluence AFFLUENT Example: enhancedAuthResponse - with issuerCountry MEX Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 517 cnpAPI Reference Guide cnpAPI Elements enhancedAuthResponse Example: enhancedAuthResponse - with cardProductType CONSUMER Example: enhancedAuthResponse - with virtualAccountNumber true or false Example: enhancedAuthResponse - with networkResponse VISA 000000000962 5 518 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide enhancedData cnpAPI Elements 4.166 enhancedData The enhancedData element allows you to specify extra information concerning a transaction in order to qualify for certain purchasing interchange rates. The following tables provide information about required elements you must submit to achieve Level 2 or Level 3 Interchange rates for Visa and MasterCard. • For MasterCard: – The transaction must be taxable. – The tax charged must be between 0.1% and 30% of the transaction amount, except as noted bellow. – For Level 3, the transaction must use a corporate, business, or purchasing card. NOTE: You can qualify for MasterCard Level 2 rates without submitting the total tax amount (submit 0) if your MCC is one of the following: 4111, 4131, 4215, 4784, 8211, 8220, 8398, 8661, 9211, 9222, 9311, 9399, 9402. This also applies to Level 3, regardless of your MCC (i.e., submission of 0 allowed). – You must include at least one line item with amount, description, and quantity defined. TABLE 4-1 MasterCard Level 2/Level 3 Data Requirements MasterCard Level 2 Data MasterCard Level 3 Data cnpAPI Element (child of enhancedData unless noted) Customer Code (if supplied by customer) Customer Code (if supplied by customer) customerReference Card Acceptor Tax ID Card Acceptor Tax ID cardAcceptorTaxId (child of detailTax) Total Tax Amount Total Tax Amount salesTax Product Code productCode (child of lineItemData) Item Description itemDescription (child of lineItemData) Item Quantity quantity (child of lineItemData) Item Unit of Measure unitOfMeasure (child of lineItemData) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 519 cnpAPI Reference Guide cnpAPI Elements enhancedData TABLE 4-1 MasterCard Level 2/Level 3 Data Requirements MasterCard Level 2 Data MasterCard Level 3 Data cnpAPI Element (child of enhancedData unless noted) Extended Item Amount lineItemTotal (child of lineItemData) or lineItemTotalWithTax (child of lineItemData) In addition to the requirements below, please be aware of the following: • For Visa: – The transaction must be taxable. – The tax charged must be between 0.1% and 22% of the transaction amount, except as noted. – For Level 3, the transaction must use a a corporate or purchasing card. 520 NOTE: Sales Tax is no longer required for Level 3. In this case omit the element entirely. TABLE 4-2 Visa Level 2/Level 3 Data Requirements Visa Level 2 Data Visa Level 3 Data cnpAPI Element (child of enhancedData unless noted) Sales Tax Sales Tax* salesTax Discount Amount discountAmount Freight/Shipping Amount shippingAmount Duty Amount dutyAmount Item Sequence Number itemSequenceNumber (child of lineItemData) Item Commodity Code commodityCode (child of lineItemData) Item Description itemDescription (child of lineItemData) Product Code productCode (child of lineItemData) Quantity quantity (child of lineItemData) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide enhancedData cnpAPI Elements TABLE 4-2 Visa Level 2/Level 3 Data Requirements Visa Level 2 Data Visa Level 3 Data cnpAPI Element (child of enhancedData unless noted) Unit of Measure unitOfMeasure (child of lineItemData) unit Cost unitCost (child of lineItemData) Discount per Line Item itemDiscountAmount (child of lineItemData) Line Item Total lineItemTotal (child of lineItemData) * Sales Tax is no longer required for Level 3. In this case omit the element entirely. NOTE: We always attempts to qualify your transactions for the optimal Interchange Rate. Although in some instances your transaction may qualify for either Level 2 or Level 3 rates without submitting all recommended fields, for the most consistent results, Vantiv strongly recommends that you adhere to the guidelines detailed above. For Discover transactions, the interchange rate is not impacted by the presence of Level 2 or Level 3 data. Parent Elements: authorization, capture, captureGivenAuth, credit, forceCapture, sale Child Elements: (all Optional) customerReference, salesTax, deliveryType, taxExempt, discountAmount, shippingAmount, dutyAmount, shipFromPostalCode, destinationPostalCode, destinationCountryCode, invoiceReferenceNumber, orderDate, detailTax, lineItemData Example: enhancedData Structure Customer Reference Amount of Sales Tax Included in Transaction TBD true or false Discount Amount Applied to Order Amount to Transport Order Duty on Total Purchase Amount Ship From Postal Code Ship To Postal Code Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 521 cnpAPI Reference Guide cnpAPI Elements enhancedData Ship To ISO Country Code Merchant Invoice Number Date Order Placed true or false Additional Tax Amount Tax Rate of This Tax Amount Tax Type Enum Tax ID of Card Acceptor Line Item Number within Order Description of Item Product Code of Item Quantity of Item Unit of Measurement Code Sales Tax or VAT of Item Total Amount of Line Item taxAmount + lineItemTotal Discount Amount Card Acceptor Commodity Code for Item Price for One Unit of Item 522 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide entryMode cnpAPI Elements 4.167 entryMode The entryMode element is a required child of the pos element, which describes the method used for card data entry at the point of sale. Type = String (Enum); minLength = N/A; maxLength = N/A Parent Elements: pos Attributes: None Child Elements: None Enumerations: Enumeration Description notused terminal not used keyed card number manually entered track1 track 1 read track2 magnetic stripe read (track 2 when known or when the terminal makes no distinction between tracks 1 and 2.) completeread complete magnetic stripe read and transmitted Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 523 cnpAPI Reference Guide cnpAPI Elements ephemeralPublicKey 4.168 ephemeralPublicKey The ephemeralPublicKey element is a required child of the header element and provides the BASE64 Encoded string of the ephemeral public key bytes from the Apple Pay transaction. Type = Base 64 Encoded String; minLength = N/A; maxLength = 400 Parent Elements: header Attributes: None Child Elements: None 524 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide expDate cnpAPI Elements 4.169 expDate The expDate element is a child of the card, token, paypage elements, which specifies the expiration date of the card (format: mmyy) and is required for card-not-present transactions. NOTE: Although the schema defines the expDate element as an optional child of the card, token and paypage elements, you must submit a value for card-not-present transactions. Type = String; minLength = 4; maxLength = 4 Parent Elements: card, newCardInfo, newCardTokenInfo, originalCard, originalCardInfo, originalCardTokenInfo, originalToken, paypage, token, updatedCard, updatedToken Attributes: None Child Elements: None NOTE: You should submit whatever expiration date you have on file, regardless of whether or not it is expired/stale. We recommend all merchant with recurring and/or installment payments participate in the Account Updater program. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 525 cnpAPI Reference Guide cnpAPI Elements expMonth 4.170 expMonth The expMonth element is an optional child of the androidpayResponse element, which specifies the month of expiration of the network token (format: mm). Type = String; minLength = 2; maxLength = 2 Parent Elements: androidpayResponse Attributes: None Child Elements: None 526 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide expYear cnpAPI Elements 4.171 expYear The expYear element is an optional child of the androidpayResponse element, which specifies the year of expiration of the network token (format: yyyy). Type = String; minLength = 4; maxLength = 4 Parent Elements: androidpayResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 527 cnpAPI Reference Guide cnpAPI Elements extendedCardResponse 4.172 extendedCardResponse The extendedCardResponse element is an optional child of the accountUpdater element, which contains two child elements, code and message. The codes/messages can be either “501 The Account Was Closed.” or “504 - Contact the cardholder for updated information.” IMPORTANT: When using Account Updater (any variation), you must always code to receive the extendedCardResponse element and its children. We always return this information whenever applicable regardless of whether you receive other account updater information in the transaction response message. Parent Elements: accountUpdater Attributes: None Child Elements: code, message Example: newCardInfo Structure Message for Code Either 501 or 504 528 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide fastAccessFunding cnpAPI Elements 4.173 fastAccessFunding The fastAccessFunding element is the parent element for the transaction type that a PayFac uses to move funds to a sub-merchant held debit card. The transfer of funds occurs within 30 minutes. NOTE: For additional information about PayFac Instruction-Based Dynamic Payout and the use of this transaction type, please refer to the PayFac Instruction-Based Dynamic Payout document. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 maxLength = 25 Child Elements: Required: amount, fundingSubmerchantId, fundsTransferId, submerchantName, (choice of) card, paypage, or token Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 529 cnpAPI Reference Guide cnpAPI Elements fastAccessFundingResponse 4.174 fastAccessFundingResponse The fastAccessFundingResponse element is the parent element for information returned to you in response to a fastAccessFunding transaction. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the payFacCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the payFacCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the submerchantCredit transaction. minLength = 1 duplicate boolean No maxLength = 25 If the request is a duplicate, the response includes the duplicate flag set to true and the entire original response. Note: This attribute applies only to Online Dynamic Payout Funding Instruction responses. Child Elements: Required: litleTxnId, fundsTransferId, response, responseTime, message, postDate 530 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide fieldValue cnpAPI Elements 4.175 fieldValue The fieldValue element is a child of both the networkField and networkSubField elements. The fieldValue element is required when a child of the networkField element and no subfield exists. This element is always required when used as a child of the networkSubField element. It provides the raw data for the designated field, extracted from the network ISO 8583 response message. Type = String; minLength = N/A; maxLength = 9999 Parent Elements: networkField, networkSubField Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 531 cnpAPI Reference Guide cnpAPI Elements filtering 4.176 filtering The filtering element is an optional child of either the Authorization or Sale request transaction. You use its child elements to selectively enable/disable the various Basic Fraud toolkit features. Setting either the or child element to false disables that filtering feature for the transaction. The child can be set to true to enable the feature selectively, or set to false to disable the feature for the transaction, if you elected to use the filter all prepaid configuration option. Parent Elements: authorization, sale Attributes: None Child Elements: Optional: prepaid, international, chargeback NOTE: Although included in the schema and shown in the example below, the element is not supported. To override the chargeback filter for a selected transaction, use the fraudFilterOverride flag (see fraudFilterOverride on page 540). Please consult your Relationship Manager for additional information. Example: filtering Structure true or false false false 532 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide finalPayment cnpAPI Elements 4.177 finalPayment The fianlPayment element is a required child of the litleInternalRecurringRequestType. A value of true indicates that this is the final payment of the subscription. Since this element is used only in internally generated transaction, you do not need to code for its use. Type = Boolean; Valid Values = true or false Parent Elements: litleInternalRecurringRequest Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 533 cnpAPI Reference Guide cnpAPI Elements firstName 4.178 firstName The firstName element is a child of the billtoAddress element, which specifies the first name of the account holder and is required for echeckVerification transactions. NOTE: When performing an eCheck Verification for a corporate account, you must include values for the firstName and lastName elements. If you do not have the name of the check issuer, you can use a value of “unavailable” for both elements. Type = String; minLength = N/A; maxLength = 25 Parent Elements: billToAddress Attributes: None Child Elements: None 534 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide forceCapture cnpAPI Elements 4.179 forceCapture The forceCapture element is the parent element for all Force Capture transactions. These are specialized Capture transactions used when you do not have a valid Authorization for the order, but have fulfilled the order and wish to transfer funds. You can use this element in either Online or Batch transactions. CAUTION: You must be authorized by Vantiv before processing this transaction type. In some instances, using a Force Capture transaction can lead to chargebacks and fines. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, amount, orderSource, choice of card, token, mpos, paypage, or applepay Optional: billToAddress, customBilling, taxType, enhancedData, processingInstructions, pos, amexAggregatorData, merchantData, productCode, secondaryAmount, surchargeAmount, debtRepayment, processingType Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 535 cnpAPI Reference Guide cnpAPI Elements forceCaptureResponse 4.180 forceCaptureResponse The forceCaptureResponse element is the parent element for information returned to you in response to a Force Capture transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Force Capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, tokenResponse, accountUpdater, giftCardResponse, applepayResponse NOTE: 536 The postDate child element is returned only in responses to Online transactions. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide formatId cnpAPI Elements 4.181 formatId The formatId element is a required child of the mpos element. This element identifies the format of the encrypted track submitted from the device. Type = String; minLength = 1; maxLength = 1028 Parent Elements: mpos Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 537 cnpAPI Reference Guide cnpAPI Elements fraudCheck 4.182 fraudCheck The fraudCheck element is the parent element for the standalone Advanced Fraud Check transaction. You use this transaction type to retrieve the results of the Advanced Fraud Check tool without submitting an Authorization or Sale transaction. You can use this element only in Online transactions. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: advancedFraudChecks Optional: billToAddress, shipToAddress, amount 538 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide fraudCheckResponse cnpAPI Elements 4.183 fraudCheckResponse The fraudCheckResponse element is the parent element for information returned to you in response to a standalone Fraud Check transaction. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Force Capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: advancedFraudResults Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 539 cnpAPI Reference Guide cnpAPI Elements fraudFilterOverride 4.184 fraudFilterOverride The fraudFilterOverride element is an optional child of both the authorization and the sale elements. A setting of true will override (disable) all fraud filters for the submitted transaction. Type = Boolean; Valid Values = true or false Parent Elements: authorization, sale Attributes: None Child Elements: None 540 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide fraudResult cnpAPI Elements 4.185 fraudResult The fraudResult element is an optional child of the authorizationResponse, the saleResponse and the authInformation elements. It contains child elements defining any fraud checking results. Parent Elements: activateResponse, authorizationResponse, deactivateResponse, loadResponse, saleResponse, unloadResponse, authInformation Attributes: None Child Elements: (All Optional) authenticationResult, avsResult, cardValidationResult, advancedAVSResult, advancedFraudResults Example: fraudResult Structure 00 N 2 011 pass, fail, review, or unavailable Score from ThreatMetix Triggered Rule_may occur multiple times NOTE: The element applies only to American Express transactions. Also, you must be enabled specifically to use the Advanced AVS feature. Please consult your Relationship Manager for additional information. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 541 cnpAPI Reference Guide cnpAPI Elements fundingInstructionVoid 4.186 fundingInstructionVoid The fundingInstructionVoid element is the parent element for the transaction type that a PayFac uses to void a submitted, but not yet processed funding instruction. You must submit the fundingInstructionVoid transaction prior to your cutoff time on the same day you submitted the instruction to be voided. This rule also applies to funding instructions submitted on weekends. Parent Elements: batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId 542 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide fundingInstructionVoidResponse cnpAPI Elements 4.187 fundingInstructionVoidResponse The fundingInstructionVoidResponse element is the parent element for information returned to you in response to a fundingInstructionVoid transaction. Parent Elements: batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the credit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the credit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the credit transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 543 cnpAPI Reference Guide cnpAPI Elements fundingSource 4.188 fundingSource The fundingSource element is an optional child of the enhancedAuthResponse element. Through its child elements, it provides information concerning whether the card used for the transaction is Prepaid, Credit, Debit, or FSA and if Prepaid, the available balance, the type of prepaid card, and whether it is reloadable. Parent Elements: enhancedAuthResponse Attributes: None Child Elements: Required: type, availableBalance, reloadable, prepaidCardType Example: fundingSource Structure PREPAID 0 YES|NO|UNKNOWN GIFT NOTE: The fundingSource element and its child elements, type and availableBalance are associated with the Insights features (see Issuer Insights on page 24.) Please consult your Relationship Manager for additional information. 544 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide fundingSubmerchantId cnpAPI Elements 4.189 fundingSubmerchantId The fundingSubmerchantId element is a required child of each funding instruction request transaction type, where it specifies the identifier of the sub-merchant whose funds the instruction moves. NOTE: If you process transactions solely on the Vantiv platform or on both the Vantiv and Vantiv eCommerce platforms, use the Vantiv-supplied Sub-merchant Merchant Id as the value of the fundingSubmerchantId element. If you process solely on the Vantiv eCommerce platform, use the eCommerce-supplied value obtained, after creating the Sub-merchant, by submitting a Sub-Merchant Retrieval Request via the Merchant Provisioner API as the value of the fundingSubmerchantId element. Please refer to the Vantiv PayFac API Reference Guide for additional information. Type = String; minLength = N/A; maxLength = 50 Parent Elements: payFacCredit, payFacDebit, physicalCheckCredit, physicalCheckDebit, reserveCredit, reserveDebit, submerchantCredit, submerchantDebit, vendorCredit, vendorDebit, fastAccessFunding, fastAccessFundingResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 545 cnpAPI Reference Guide cnpAPI Elements fundsTransferId 4.190 fundsTransferId The fundingTransferId element is a required child of each funding instruction request/response transaction type, where it specifies the PayFac assigned identifier for the transaction. You must use unique values for each transaction across you entire organization. The system mirrors this identifier back in the response messages. Type = String; minLength = N/A; maxLength = 36 (for all except fastAccessFunding and fastAccessFundingResponse) Type = String; minLength = N/A; maxLength = 16 (for fastAccessFunding and fastAccessFundingResponse) Parent Elements: payFacCredit, payFacCreditResponse, payFacDebit, payFacDebitResponse, physicalCheckCredit, physicalCheckCreditResponse, physicalCheckDebit, physicalCheckDebitResponse, reserveCredit, reserveCreditResponse, reserveDebit, reserveDebitResponse, submerchantCredit, submerchantCreditResponse, submerchantDebit, submerchantDebitResponse, vendorCredit, vendorCreditResponse, vendorDebit, vendorDebitResponse, fastAccessFunding, fastAccessFundingResponse Attributes: None Child Elements: None 546 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide giftCardAuthReversal cnpAPI Elements 4.191 giftCardAuthReversal The giftCradAuthReversal element is the parent element for the transaction type that reverses an authorization on a Gift Card. Parent Elements: litleOnlineRequest, litleRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) card, originalRefCode, originalAmount, originalTxnTime, originalSystemTraceId, originalSequenceNumber Child Elements: (Optional) litleTxnId Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 547 cnpAPI Reference Guide cnpAPI Elements giftCardAuthReversalResponse 4.192 giftCardAuthReversalResponse The giftCardAuthReversalResponse element is the parent element for information returned to you in response to a Gift Card Auth Reversal transaction. Parent Elements: litleOnlineResponse, litleResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Force Capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message, giftCardResponse Optional: postDate (returned for online transactions only) 548 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide giftCardBin cnpAPI Elements 4.193 giftCardBin The giftCardBin element is a required child of the virtualGiftCard element defining the requested BIN of the virtual Gift Card number requested. NOTE: In an early iteration of schema V8.22 issued in September of 2013 this element was defined as an optional child of the virtualGiftCard element. If you coded to the earlier version, be aware that this element is now required. If you do not include this element, the transaction will fail XML validation. Type = String; minLength = N/A; maxLength = 10 Parent Elements: virtualGiftCard Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 549 cnpAPI Reference Guide cnpAPI Elements giftCardCapture 4.194 giftCardCapture The giftCardCapture element is the parent element for the transaction type that captures funds previously authorized on a Gift Card. Parent Elements: litleOnlineRequest, litleRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) card, captureAmount, originalRefCode, originalAmount, originalTxnTime, Child Elements: (Optional) litleTxnId 550 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide giftCardCaptureResponse cnpAPI Elements 4.195 giftCardCaptureResponse The giftCardCaptureResponse element is the parent element for information returned to you in response to a Gift Card Capture transaction. Parent Elements: litleOnlineResponse, litleResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Force Capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message, giftCardResponse Optional: fraudResult, postDate (returned for online transactions only) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 551 cnpAPI Reference Guide cnpAPI Elements giftCardCredit 4.196 giftCardCredit The giftCardCredit element is the parent element for all Gift Card Credit transactions. There are two possible structures for this message type. You use the first structure for credit transactions against captures/sales processed by Vantiv. The alternate structure applies to credits against captures/sales not processed by Vantiv. You can use this transaction type in either Online or Batch submissions. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: For credits to transactions processed by Vantiv (Required): creditAmount, card For credits to transactions processed by Vantiv (Optional): litleTxnId For credits to transactions not processed by Vantiv (Required): orderId, creditAmount, orderSource, card 552 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide giftCardCreditResponse cnpAPI Elements 4.197 giftCardCreditResponse The giftCardCreditResponse element is the parent element for information returned to you in response to a Gift Card Credit transaction. Parent Elements: litleOnlineResponse, litleResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Force Capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Force Capture transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message, giftCardResponse Optional: fraudResult, postDate (returned for online transactions only) Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 553 cnpAPI Reference Guide cnpAPI Elements giftCardResponse 4.198 giftCardResponse The giftCardResponse element is a required child of several transaction types and optional for several others. Through its child elements, it provides details about the available balance on a Gift Card, as well as additional reference items used in subsequent, related transactions. For example, in a giftCardAuthReversal transaction, you must include values of the refCode, systemTraceId, and sequenceNumber from the authorizationResponse in the originalRefCode, originalSystemTraceId, and originalSequenceNumber elements respectively. Parent Elements: Required:activateResponse, activateReversalResponse, giftCardAuthReversalResponse, balanceInquiryResponse, giftCardCaptureResponse, giftCardCreditResponse, deactivateResponse, deactivateReversalResponse, depositReversalResponse, loadResponse, loadReversalResponse, refundReversalResponse, unloadResponse, unloadReversalResponse Optional (per schema, but always returned for Gift Card Transactions): authorizationResponse, captureGivenAuthResponse, forceCaptureResponse, saleResponse Attributes: None Child Elements (All Optional, but must contain at least one child): Optional: txnTime, refCode, systemTraceId, sequenceNumber, availableBalance, beginningBalance, endingBalance, cashBackAmount NOTE: Although included in the schema, the beginningBalance, endingBalance, and cashBackAmount elements are not currently supported. Example: giftCardResponse Structure 2016-11-15T12:00:00 abc123 123456 123456 Balance Available on Gift Card 554 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide giropay cnpAPI Elements 4.199 giropay The giropay element is a child of the sale transaction that, through its child elements, defines information needed to process an Giropay (Real-time Bank Transfer) transaction. At this time, you can use the iDeal method of payment in Online transactions only. Parent Elements: sale Attributes: None Child Elements: Optional: preferredLanguage Example: giropay Structure Country Code of Language Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 555 cnpAPI Reference Guide cnpAPI Elements giropayResponse 4.200 giropayResponse The giropayResponse element is a child of the saleResponse transaction when the method of payment in the request is giropay. It contains child elements that you should store for future use/reference. Parent Elements: saleResponse Attributes: None Child Elements (all Optional): paymentPurpose, redirectUrl, redirectToken Example: giropayResponse Structure URL of Vantiv Supplied Mandate Map Mandate to litleTxnId Reference Number + Billing Descsriptor 556 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide header cnpAPI Elements 4.201 header The header element is a required child of the applepay element. Its child elements provides information required to process the Apple Pay transaction. Type = String; minLength = N/A; maxLength = 10000 Parent Elements: applepay Attributes: None Child Elements (All Optional, but must contain at least one child): Optional: applicationData, ephemeralPublicKey, publicKeyHash, transactionId Example: header Structure
Password
SHA-256 Hash Hex Encoded of App Data Property Base64 Encoded Ephemeral Public Key Base64 Hash of Public Key Bytes from Merchant Certtificate Hex Transaction Id Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 557 cnpAPI Reference Guide cnpAPI Elements healthcareAmounts 4.202 healthcareAmounts The healthcareAmount element is a required child of the healthcareIIAS element. Through its child elements, it provides details about the dollar amount and type of IIAS qualified items purchased using Healthcare Prepaid cards. The value used for the totalHealthcareAmount child must be the sum of the values applied to the following elements: RxAmount, visionAmount, clinicOtherAmount, and dentalAmount. Parent Elements: healthcareIIAS Attributes: None Child Elements: Required: totalHealthcareAmount Optional: RxAmount, visionAmount, clinicOtherAmount, dentalAmount Example: fundingSource Structure Total of Healthcare Items Amount for Medications Amount for Vision Items Amount for Clinic Charges Amount for Dental Charges 558 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide healthcareIIAS cnpAPI Elements 4.203 healthcareIIAS The healthcareIIAS element is an optional child of Authorization and Sale transactions. Through its child elements, it provides information about IIAS qualified items purchased using Healthcare Prepaid cards. Parent Elements: authorization, sale Attributes: None Child Elements: Required: healthcareAmounts, IIASFlag Example: fundingSource Structure Total of Healthcare Items Amount for Medications Amount for Vision Items Amount for Clinic Charges Amount for Dental Charges Y Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 559 cnpAPI Reference Guide cnpAPI Elements iban 4.204 iban The iban element is a required child of the sepaDirectDebit element. It defines the International Bank Account Number of the customer. Type = String; minLength = 15; maxLength = 34 Parent Elements: sepaDirectDebit Attributes: None Child Elements: None 560 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide ideal cnpAPI Elements 4.205 ideal The ideal element is a child of the sale transaction that, through its child elements, defines information needed to process an iDEAL (Real-time Bank Transfers) transaction. At this time, you can use the iDEAL method of payment in Online transactions only. Parent Elements: sale Attributes: None Child Elements: Optional: preferredLanguage Example: ideal Structure Country Code of Language Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 561 cnpAPI Reference Guide cnpAPI Elements idealResponse 4.206 idealResponse The idealResponse element is a child of the saleResponse transaction when the method of payment in the request is ideal. It contains child elements that you should store for future use/reference. Parent Elements: saleResponse Attributes: None Child Elements (all Optional): paymentPurpose, redirectUrl, redirectToken Example: idealResponse Structure URL of Vantiv Supplied Mandate Map Mandate to litleTxnId Reference Number + Billing Descsriptor 562 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide IIASFlag cnpAPI Elements 4.207 IIASFlag The IIASFlag element is a required child of the healthcareIIAS element. This element only supports a value of Y. Type = String (enum); minLength = N/A; maxLength = 1; Valid Value = Y Parent Elements: healthcareIIAS Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 563 cnpAPI Reference Guide cnpAPI Elements incomeAmount 4.208 incomeAmount The incomeAmount element is an optional child of the customerInfo element and defines the yearly income of the customer. It is used in combination with several other elements to provide information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = Long; minLength = N/A; maxLength = N/A Parent Elements: customerInfo Attributes: None Child Elements: None 564 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide incomeCurrency cnpAPI Elements 4.209 incomeCurrency The incomeCurrency element is an optional child of the customerInfo element and defines the currency of the incomeAmount element. The default value is USD (United States Dollars). It is used in combination with several other elements to provide information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = String (Enum); minLength = N/A; maxLength = N/A Parent Elements: customerInfo Attributes: None Child Elements: None Enumerations: Enumeration Description AUD Australian Dollar CAD Canadian Dollar CHF Swiss Francs DKK Denmark Kroner EUR Euro GBP United Kingdom Pound HKD Hong Kong Dollar JPY Japanese Yen NOK Norwegian Krone NZD New Zealand Dollar Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 565 cnpAPI Reference Guide cnpAPI Elements 566 incomeCurrency Enumeration Description SEK Swedish Kronor SGD Singapore Dollar USD (default) United States Dollar Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide international cnpAPI Elements 4.210 international The international element is an optional child of the filtering element. To disable the filtering operation for a selected transaction include the international element with a setting of false. Type = Boolean; Valid Value = false Parent Elements: filtering Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 567 cnpAPI Reference Guide cnpAPI Elements intervalType 4.211 intervalType The intervalType element is a required child of the createPlan element and defines the billing period associated with the Plan. Type = String (enum); minLength = N/A; maxLength = N/A Parent Elements: createPlan Attributes: None Child Elements: None Enumerations: Enumeration Description ANNUAL The billing period is once per year. SEMIANNUAL The billing period is twice per year. QUARTERLY The billing period is every three months. MONTHLY The billing period is every month. WEEKLY The billing period is every week. 568 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide invoiceReferenceNumber cnpAPI Elements 4.212 invoiceReferenceNumber The invoiceReferenceNumber element is an optional child of the enhancedData element, which specifies the merchant’s invoice number. If you do not know the invoice number, do not include this element. Type = String; minLength = 1; maxLength = 15 Parent Elements: enhancedData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 569 cnpAPI Reference Guide cnpAPI Elements issuerCountry 4.213 issuerCountry The issuerCountry element is an optional child of the enhancedAuthResponse element, which defines the country of the bank that issued the card submitted in the Authorization or Sale transaction. Type = String; minLength = N/A; maxLength = 3 Parent Elements: enhancedAuthResponse Attributes: None Child Elements: None 570 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide itemCategoryCode cnpAPI Elements 4.214 itemCategoryCode The itemCategoryCode element is an optional child of the billMeLaterRequest element and defines the PayPal Credit item category for the type of product sold. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = Integer; totalDigits = 4 Parent Elements: billMeLaterRequest Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 571 cnpAPI Reference Guide cnpAPI Elements itemDescription 4.215 itemDescription The itemDescription element is a required child of the lineItemData element, which provides a brief text description of the item purchased. Type = String; minLength = N/A; maxLength = 26 Parent Elements: lineItemData Attributes: None Child Elements: None 572 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide itemDiscountAmount cnpAPI Elements 4.216 itemDiscountAmount The itemDiscountAmount element is an optional child of the lineItemData element, which specifies the item discount amount. Although an optional element, it is required by Visa for Level III Interchange rates. The value must be greater than or equal to 0. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: lineItemData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 573 cnpAPI Reference Guide cnpAPI Elements itemSequenceNumber 4.217 itemSequenceNumber The itemSequenceNumber element is an optional child of the lineItemData element (required for Visa transactions). When providing line item data, you must number each item sequentially starting with 1. Type = Integer; minInclusive value = 1, maxInclusive value = 99 Parent Elements: lineItemData Attributes: None Child Elements: None 574 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide ksn cnpAPI Elements 4.218 ksn The ksn element is a required child of the mpos element. This element defines the Key serial Number returned from the encrypting device. It is created automatically from the unique identifier of the device and an internal transaction counter. Type = String; minLength = 1; maxLength = 1028 Parent Elements: mpos Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 575 cnpAPI Reference Guide cnpAPI Elements lastName 4.219 lastName The lastName element is a child of the billtoAddress element, which specifies the last name of the account holder and is required for echeckVerification transactions. NOTE: When performing an eCheck Verification for a corporate account, you must include values for the firstName and lastName element. If you do not have the name of the check issuer, you can use a value of “unavailable” for both elements. Type = String; minLength = N/A; maxLength = 25 Parent Elements: billToAddress Attributes: None Child Elements: None 576 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide lineItemData cnpAPI Elements 4.220 lineItemData The lineItemData element contains several child elements used to define information concerning individual items in the order. Although the schema defines it as an optional child of the enhancedData element, it is required for Level III interchange rates. NOTE: MasterCard and Visa allow up to 99 instances of this element in a transaction. American Express allows a maximum of 4 instances of this element in a transaction. Parent Elements: enhancedData Attributes: None Child Elements: Required: itemDescription Optional: itemSequenceNumber, productCode, quantity, unitOfMeasure, taxAmount, lineItemTotal, lineItemTotalWithTax, itemDiscountAmount, commodityCode, unitCost, detailTax NOTE: When including the lineItemData element, please be aware of the following rules for its child elements: • itemSequenceNumber is required by Visa • productCode, quantity, unitOfMeasure, and lineItemTotal are required by Visa and MasterCard • itemDiscountAmount, commodityCode, and unitCost are required by Visa for Level III Interchange rates Example: lineItemData Structure Line Item Number within Order Description of Item Product Code of Item Quantity of Item Unit of Measurement Code Sales Tax or VAT of Item Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 577 cnpAPI Reference Guide cnpAPI Elements lineItemData Total Amount of Line Item taxAmount + lineItemTotal Discount Amount Card Acceptor Commodity Code for Item Price for One Unit of Item true or false Additional Tax Amount Tax Rate of This Tax Amount Tax Type Enum Tax ID of Card Acceptor 578 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide lineItemTotal cnpAPI Elements 4.221 lineItemTotal The lineItemTotal element is an optional child of the lineItemData element, which specifies the total cost of the line items purchased, not including tax. For example, if the order was for 500 pencils at $1.00 each, the lineItemTotal would be $500. Although an optional element, it is required by Visa and MasterCard when specifying line item data. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: lineItemData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 579 cnpAPI Reference Guide cnpAPI Elements lineItemTotalWithTax 4.222 lineItemTotalWithTax The lineItemTotalWithTax element is an optional child of the lineItemData element, which specifies the total cost of the line items purchased including tax. If the tax is not known, do not include this element. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: lineItemData Attributes: None Child Elements: None 580 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide litleInternalRecurringRequest cnpAPI Elements 4.223 litleInternalRecurringRequest The litleInternalRecurringRequest element and its children is an element structure that exists solely for internally (to system) generated transactions associated with recurring payments managed by the Recurring engine. You do not need to code for this structure. Parent Elements: sale Attributes: None Child Elements: subscriptionId, recurringTxnId, finalPayment Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 581 cnpAPI Reference Guide cnpAPI Elements litleOnlineRequest 4.224 litleOnlineRequest This is the root element for all cnpAPI Online requests. Parent Elements: None Attributes: Attribute Name Type Required? Description version String Yes Defines the cnpAPI schema version against which the XML is validated. minLength = N/A maxLength = 10 xmlns String Yes Defines the URI of the schema definition. This is a fixed location and must be specified as: http://www.litle.com/schema. minLength = N/A maxLength = 38 merchantId String Yes A unique string used to identify the merchant within the system. minLength = N/A maxLength = 50 Note: International currencies are supported on a per merchantId basis. loggedInUser String No Internal Use Only sameDayFunding Boolean No Used for Dynamic Payout Funding Instructions only. Set to true to mark this Funding Instructions for same day funding. Also, see Same Day Funding on page 888. Child Elements: Required: authentication One of the following required: activate, activateReversal, authorization, authReversal, balanceInquiry, cancelSubscription, capture, captureGivenAuth, createPlan, credit, deactivate, deactivateReversal, depositReversal, echeckCredit, echeckRedeposit, echeckSale, echeckVerification, echeckVoid, forceCapture, fraudCheck, giftCardAuthReversal, giftCardCapture, giftCardCredit, load, loadReversal, registerTokenRequest, refundReversal, sale, unload, updateCardValidationNumOnToken, updatePlan, updateSubscription, unloadReversal, void, fastAccessFunding, payFacCredit, payFacDebit, physicalCheckCredit, physicalCheckDebit, reserveCredit, reserveDebit, submerchantCredit, submerchantDebit, vendorCredit, vendorDebit 582 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide litleOnlineResponse cnpAPI Elements 4.225 litleOnlineResponse This is the root element for all cnpAPI Online responses. Parent Elements: None Attributes: Attribute Name Type Required? Description version String Yes Defines the cnpAPI schema version against which the XML is validated. minLength = N/A maxLength = 10 xmlns String Yes Defines the URI of the schema definition. This is a fixed location and must be specified as: http://www.litle.com/schema. minLength = N/A maxLength = 38 response String Yes Indicates whether your XML syntax passed validation. Expected values are as follows: 0 - XML validation succeeded. 1 - XML validation failed. See the message attribute for more details. 2 - Indicates that the submitted content was either improperly formatted XML or non-XML content. 3 - Indicates that the submission contains empty or invalid credentials (user and password). 4 - Indicates that the merchant has reached the maximum number of concurrent connections. 5 - Indicates that systems may have detected message content that violates certain restrictions. minLength = N/A maxLength = 3 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 583 cnpAPI Reference Guide cnpAPI Elements litleOnlineResponse Attribute Name Type Required? Description message String Yes XML validation error message. Expected values are as follows: • If the response attribute returns 0, the message attribute returns the text “Valid Format.” • If the response attribute returns 1, the message attribute returns an error message that helps you to identify and troubleshoot the syntax problem. See XML Validation Error Messages on page 864 for example messages. • If the response attribute returns 2, the message attribute is "System Error - Call Litle & Co." • If the response attribute returns a value of 3, 4, or 5, the message attribute is "There is a problem with the system. Contact eCommerceSupport@vantiv.com." minLength = N/A maxLength = 512 Child Elements: One of the following required: activateResponse, activateReversalResponse, authorizationResponse, authReversalResponse, balanceInquiryResponse, cancelSubscriptionResponse, captureGivenAuthResponse, captureResponse, createPlanResponse, deactivateResponse, deactivateReversalResponse, depositReversalResponse, creditResponse, echeckCreditResponse, echeckRedepositResponse, echeckSalesResponse, echeckVerificationResponse, forceCaptureResponse, giftCardAuthReversalResponse, giftCardCaptureResponse, giftCardCreditResponse, loadResponse, loadReversalResponse, refundReversalResponse, registerTokenResponse, saleResponse, unloadResponse, unloadReversalResponse, updateCardValidationNumOnTokenResponse, voidResponse, updatePlanResponse, updateSubscriptionResponse, fastAccessFundingResponse, payFacCreditResponse, payFacDebitResponse, physicalCheckCreditResponse, physicalCheckDebitResponse, reserveCreditResponse, reserveDebitResponse, submerchantCreditResponse, submerchantDebitResponse, vendorCreditResponse, vendorDebitResponse 584 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide litleRequest cnpAPI Elements 4.226 litleRequest This is the root element for all cnpAPI Batch requests. Parent Elements: None Attributes: Attribute Name Type Required? Description version String Yes Defines the cnpAPI schema version against which the XML is validated. minLength = N/A maxLength = 10 xmlns String Yes Defines the URI of the schema definition. This is a fixed location and must be specified as: http://www.litle.com/schema. minLength = N/A maxLength = 38 id String No A unique string to identify the session within the system. minLength = N/A maxLength = 25 numBatchRequests Integer Yes Defines the total number of batchRequest children included in the litleRequest. If the litleRequest contains only an RFRRequest, then set this attribute to “0”. Child Elements: Required: authentication One of the following required: batchRequest, RFRRequest Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 585 cnpAPI Reference Guide cnpAPI Elements litleResponse 4.227 litleResponse This is the root element for all cnpAPI Batch responses. Parent Elements: None Attributes: Attribute Name Type Required? Description version String Yes Defines the cnpAPI schema version against which the XML is validated. minLength = N/A maxLength = 10 xmlns String Yes Defines the URI of the schema definition. This is a fixed location and must be specified as: http://www.litle.com/schema. minLength = N/A maxLength = 38 id String No The response returns the same value submitted in the Litle Request. minLength = N/A maxLength = 25 response String Yes Indicates whether your XML syntax passed validation. Expected values are as follows: 0 - XML validation succeeded. 1 - XML validation failed. See the message attribute for more details. 2 - Indicates that the submitted content was either improperly formatted XML or non-XML content. 3 - Indicates that the submission contains empty or invalid credentials (user and password). 4 - Indicates that the merchant has reached the maximum number of concurrent connections. 5 - Indicates that systems may have detected message content that violates certain restrictions. minLength = N/A maxLength = 3 586 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide litleResponse cnpAPI Elements Attribute Name Type Required? Description message String Yes XML validation error message. Expected values are as follows: • If the response attribute returns 0, the message attribute returns the text “Valid Format.” • If the response attribute returns 1, the message attribute returns an error message that helps you to identify and troubleshoot the syntax problem. See XML Validation Error Messages on page 864 for example messages. • If the response attribute returns 2, the message attribute is "System Error - Call Litle & Co." • If the response attribute returns a value of 3, 4, or 5, the message attribute is "There is a problem with the system. Contact eCommerceSupport@vantiv.com." minLength = N/A maxLength = 512 litleSessionId Long Yes A unique value assigned by Vantiv to identify the session. minLength = N/A maxLength = 19 Child Elements: One of the following required: batchResponse, RFRResponse Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 587 cnpAPI Reference Guide cnpAPI Elements litleSessionId 4.228 litleSessionId The litleSessionId element is a child of the RFRRequest element used to request the response from a previously submitted Batch. The value of the litleSessionId must be the same at the value returned in the corresponding attribute of the litleResponse. Type = Long; minLength = N/A; maxLength = 19 Parent Elements: RFRRequest Attributes: None Child Elements: None 588 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide litleToken cnpAPI Elements 4.229 litleToken The litleToken element defines the value of the token. The system returns this value in XML responses when issuing new tokens to replace account numbers. The length of the token is the same as the length of the submitted account number for credit card tokens or a fixed length of seventeen (17) characters for eCheck account tokens. Type = String; minLength = 13; maxLength = 25 Parent Elements: The litleToken element is an optional child of each listed parent element. registerTokenResponse, tokenResponse, newCardTokenInfo, originalCardTokenInfo, originalToken, originalTokenInfo, newTokenInfo, updatedToken, token, echeckToken Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 589 cnpAPI Reference Guide cnpAPI Elements litleTxnId 4.230 litleTxnId The litleTxnId element is used to identify transactions in the system. The system returns this element in XML responses. You use it in various requests to reference the original transaction. For example, when you submit a Capture transaction, you include the litleTxnId for the associated Authorization. Type = Long; minLength = N/A; maxLength = 19 Parent Elements: This element is a required child of the following: accountUpdateResponse, activateResponse, activateReversalResponse, authorizationResponse, authReversalResponse, capture, captureResponse, credit, creditResponse, captureGivenAuthResponse, deactivateResponse, deactivateReversalResponse, depositReversalResponse, echeckCredit, echeckCreditResponse, echeckPreNoteCreditResponse, echeckPreNoteSaleResponse, echeckRedeposit, echeckRedepositResponse, echeckSalesResponse, echeckVerificationResponse, echeckVoid, echeckVoidResponse, fastAccessFundingResponse, forceCapture, forceCaptureResponse, fraudCheckResponse, fundingInstructionVoid, fundingInstructionVoidResponse, giftCardAuthReversalResponse, giftCardCaptureResponse, giftCardCreditResponse, loadResponse, loadReversalResponse, payFacCreditResponse, payFacDebitResponse, physicalCheckCreditResponse, physicalCheckDebitResponse, refundReversalResponse, saleResponse, unloadResponse, void, voidResponse, cancelSubscriptionResponse, updatePlanResponse, updateSubscriptionResponse, unloadReversalResponse, submerchantCreditResponse, submerchantDebitResponse, vendorCreditResponse, vendorDebitResponse NOTE: While the litleTxnId is optional in the transaction types listed below, Vantiv recommends you include it whenever possible. Failure to include the litleTxnId results in missing information in the Associated Transaction Stream section of the Transaction Detail screen in iQ. This element is an optional child of the following: activateReversal, deactivateReversal, depositReversal, giftCardAuthReversal, giftCardCapture, giftCardCredit, loadReversal, refundReversal, unloadReversal NOTE: Although the schema shows the litleTxnId element as an optional child of the authorization, echeckSale, and sale transactions, under normal circumstances, merchants would never use this option. Attributes: None 590 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide litleTxnId cnpAPI Elements Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 591 cnpAPI Reference Guide cnpAPI Elements load 4.231 load The load element is the parent element for the transaction type that adds funds to a reloadable Gift Card. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (all Required) orderId, amount, orderSource, card 592 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide loadResponse cnpAPI Elements 4.232 loadResponse The loadResponse element is the parent element for information returned to you in response to a load transaction. It can be a child of either a litleOnlineResponse element or a batchResponse element. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Load transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Load transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Load transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, fraudResult, giftCardResponse Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 593 cnpAPI Reference Guide cnpAPI Elements loadReversal 4.233 loadReversal The loadReversal element is the parent element for the transaction type that reverses the loading of a Gift Card. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) card, originalRefCode, originalAmount, originalTxnTime, originalSystemTraceId, originalSequenceNumber Child Elements: (Optional) litleTxnId 594 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide loadReversalResponse cnpAPI Elements 4.234 loadReversalResponse The loadReversalResponse element is the parent element for information returned to you in response to an loadReversal transaction. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Load Reversal transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Load Reversal transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Load Reversal transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message Optional: postDate, giftCardResponse Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 595 cnpAPI Reference Guide cnpAPI Elements mandateProvider 4.235 mandateProvider The mandateProvider element is a required child of the sepaDirectDebit element and defines whether the Merchant or Vantiv provides the mandate for customer approval. Type = String (Enum); Allowed Values = Merchant or Vantiv Parent Elements: sepaDirectDebit Attributes: None Child Elements: None 596 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide mandateReference cnpAPI Elements 4.236 mandateReference The mandateReference element is an optional child of both the sepaDirectDebit element and the sepaDirectDebitResponse element. You use this element for recurring payments (after the initial transaction) to provide the reference number that links subsequent payments in a recurring stream to the mandate agreed to at the time of the initial payment. Vantiv returns this value in the sepaDirectDebitResponse associated with the initial payment. It is not returned for subsequent payments in a recurring stream. Type = String; minLength = N/A; maxLength = 256 Parent Elements: sepaDirectDebit, sepaDirectDebitResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 597 cnpAPI Reference Guide cnpAPI Elements mandateSignatureDate 4.237 mandateSignatureDate The mandateSignatureDate element is an optional child of the sepaDirectDebit element and defines the date the consumer agreed to the mandate allowing the merchant to debit their account. Although optional, you should always provide this information when the value for the mandateProvider element is Merchant. Type = Date; Format = YYYY-MM-DD Parent Elements: sepaDirectDebit Attributes: None Child Elements: None 598 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide mandateURL cnpAPI Elements 4.238 mandateURL The mandateUrl element is an optional child of the sepaDirectDebit element and defines the URL of the mandate to which the consumer agreed, allowing the merchant to debit their account. Although optional, you should always provide this information when the value for the mandateProvider element is Merchant. Type = String; minLength = 1; maxLength = 2000 Parent Elements: sepaDirectDebit Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 599 cnpAPI Reference Guide cnpAPI Elements matchCount 4.239 matchCount The matchCount element is a required child of the queryTransactionResponse element and defines the number of found transactions that matched the criteria submitted in the queryTransaction. Type = Integer; totalDigits = 2 Parent Elements: queryTransactionResponse Attributes: None Child Elements: None 600 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide merchantData cnpAPI Elements 4.240 merchantData The merchantData element is an optional child element of several transaction types. You can use its children to track transactions based upon marketing campaigns, affiliates, or other user defined parameter. Parent Elements: authorization, captureGivenAuth, credit, echeckCredit, echeckPreNoteCredit, echeckPreNoteSale, echeckRedeposit, echeckSale, echeckVerification, forceCapture, sale Attributes: None Child Elements (all optional): affiliate, campaign, merchantGroupingId Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 601 cnpAPI Reference Guide cnpAPI Elements merchantGroupingId 4.241 merchantGroupingId The merchantGroupingId element is an optional child element of the merchantData element. You can use it to track transactions based upon this user defined parameter. Type = String; minLength = N/A; maxLength = 25 Parent Elements: merchantData Attributes: None Child Elements: None 602 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide merchantId cnpAPI Elements 4.242 merchantId The merchantId element is a child of the accountUpdateFileRequestData element used when you request an Account Update file. This value is a unique string used to identify the merchant within the system. Type = String; minLength = N/A; maxLength = 50 Parent Elements: accountUpdateFileRequestData Attributes: None Child Elements: None NOTE: Several elements use merchantId as an attribute, including batchRequest, batchResponse, and litleOnlineRequest. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 603 cnpAPI Reference Guide cnpAPI Elements message 4.243 message The message element contains a brief definition of the response code returned for the transaction. When it is a child of the extendedCardResponse element, the only values allowed are either "The account was closed," or "Contact the cardholder for updated information." For a complete list of response codes and associated messages, please refer to Appendix A. Type = String; minLength = N/A; maxLength = 512 Parent Elements: activateResponse, activateReversalResponse, authorizationResponse, captureResponse, captureGivenAuthResponse, creditResponse, deactivateResponse, deactivateReversalResponse, depositReversalResponse, echeckCreditResponse, echeckPreNoteCreditResponse, echeckPreNoteSaleResponse, echeckRedepositResponse, echeckSalesResponse, echeckVerificationResponse, echeckVoidResponse, extendedCardResponse, forceCaptureResponse, fraudCheckResponse, loadResponse, loadReversalResponse, queryTransactionResponse, queryTransactionUnavailableResponse, refundReversalResponse, saleResponse, unloadResponse, unloadReversalResponse, voidResponse, cancelSubscriptionResponse,updatePlanResponse, updateSubscriptionResponse, payFacCreditResponse, payFacDebitResponse, physicalCheckCreditResponse, physicalCheckDebitResponse, reserveCreditResponse, reserveDebitResponse, submerchantCreditResponse, submerchantDebitResponse, vendorCreditResponse, vendorDebitResponse Attributes: None Child Elements: None 604 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide middleInitial cnpAPI Elements 4.244 middleInitial The middleInitial element is a child of the billtoAddress element, which specifies the middle initial of the account holder. It is an optional element used for echeckVerification transactions. Type = String; minLength = N/A; maxLength = 1 Parent Elements: billToAddress Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 605 cnpAPI Reference Guide cnpAPI Elements mpos 4.245 mpos The mpos element defines payment card information when the transaction originates with a ROAM device. Parent Elements: authorization, captureGivenAuth, credit, forceCapture, sale, registerTokenRequest Attributes: None Child Elements: (all Required) ksn, formatId, encryptedTrack, track1Status, track2Status Example: mpos Structure Key Serial Number Format of Encrypted Track Encrypted Track Data Card Validation Number Card Validation Number 606 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide name cnpAPI Elements 4.246 name The name element defines the customer name in both the billToAddress and shipToAddress elements. When used as a child of one of the Recurring Engine associated parents (i.e., createAddOn, updateAddOn, createDiscount, updateDiscount, or createPlan), the name element specifies the name of the parent item being created/updated. Type = String; minLength = N/A; maxLength = 100 Parent Elements: billToAddress, shipToAddress, createAddOn, updateAddOn, createDiscount, updateDiscount, createPlan NOTE: The name element is required for Echeck transactions. If you do not submit the customer name in an Echeck transaction, we return Response Code 330 - Invalid Payment Type. The name element is required for sale transactions using the sepaDirectDebit method of payment and must be a minimum of two characters. Failure to include the name element results in a 901 - Missing Name Response Code. If the value is not at least two characters, the transaction declines with a response code of 902 - Invalid Name Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 607 cnpAPI Reference Guide cnpAPI Elements networkField 4.247 networkField The networkField element is an optional child of the networkResponse element. Its attributes and child elements define the Field Number, Field Name, (Raw) Field Value, as well as any Sub-fields, if applicable. Parent Elements: networkResponse Attributes: Attribute Name Type Required? Description fieldName String Yes This attribute defines the name of the ISO 8583 field containing the information returned. Type = Enum Allowed Values: • • • • • • • • • • • • • fieldNumber Integer Yes Transaction Amount Settlement Date Authorization Identification Response Response Code Additional Response Data Private Use Additional Data Settlement Currency Code Cardholder Billing Currency Code Additional Amounts Reserved Private Transaction Description Reserved For National Use Reserved For Private Use This attribute defines the number of the ISO 8583 field containing the information returned. Different card networks may use different Field Numbers for the same information. minLength = 1 maxLength = N/A Child Elements: fieldValue, networkSubField 608 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide networkField cnpAPI Elements Example: networkField Structure with fieldValue 000000001111 Example: networkField Structure with networkSubField 7 W Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 609 cnpAPI Reference Guide cnpAPI Elements networkResponse 4.248 networkResponse The networkResponse element is an optional child of the enhancedAuthResponse element. Its child elements provide a number of data points returned by the card networks in their ISO 8583 response messages. Parent Elements: enhancedAuthResponse Attributes: None Child Elements: endpoint, networkField Example: networkResponse Structure VISA 000000000962 7 W 610 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide networkSubField cnpAPI Elements 4.249 networkSubField The networkSubField element is a required child of the networkField element, when a subfield exists. Its child element provides the raw subfield data returned by the card networks in their ISO 8583 response messages. Parent Elements: networkField Attributes: Attribute Name Type Required? Description fieldNumber Integer Yes This attribute defines the number of the ISO 8583 field or subfield containing the information returned. Different card networks may use different Field Numbers for the same information. minLength = 1 maxLength = N/A Child Elements: fieldValue Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 611 cnpAPI Reference Guide cnpAPI Elements networkTransactionId 4.250 networkTransactionId The networkTransactionId element is an optional child of the authorizationResponse, and saleResponse transactions, returned for Visa and Discover transactions. Visa and Discover use this value to link subsequent payments in a recurring/installment stream back to the initial transaction. You must include this value in the request message (originalNetworkTransactionId element) for subsequent recurring payments, if the payment method is either Visa or Discover. Type = String; minLength = N/A; maxLength = 30 NOTE: In the initial transaction of the recurring/installment stream, you must set the processingType element to either initialRecurring or initialInstallment, as applicable. Parent Elements: authorizationResponse, saleResponse Attributes: None Child Elements: None 612 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide newAccountInfo cnpAPI Elements 4.251 newAccountInfo The newAccountInfo element is an optional child of the accountUpdater element, which contains child elements providing the updated information for the submitted account. Parent Elements: accountUpdater Attributes: None Child Elements: accType, accNum, routingNum Example: newAccountInfo Structure Account Type New Account Number New Routing Number Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 613 cnpAPI Reference Guide cnpAPI Elements newCardInfo 4.252 newCardInfo The newCardInfo element is an optional child of the accountUpdater element, which contains child elements providing the updated information for the submitted card. Parent Elements: accountUpdater Attributes: None Child Elements: type, number, expDate Example: newCardInfo Structure Card Type New Account Number New Expiration Date 614 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide newCardTokenInfo cnpAPI Elements 4.253 newCardTokenInfo The newCardTokenInfo element is an optional child of the accountUpdater element, which contains child elements providing the updated token information for the submitted token. Parent Elements: accountUpdater Attributes: None Child Elements: litleToken, type, expDate, bin Example: newCardInfo Structure New Token Card Type New Expiration Date New Card BIN Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 615 cnpAPI Reference Guide cnpAPI Elements newTokenInfo 4.254 newTokenInfo The newTokenInfo element is an optional child of the accountUpdater element, which contains child elements providing the updated information for the submitted account. The system returns this information when processing a tokenized eCheck transactions and a change (NOC) is found against the account. Parent Elements: accountUpdater Attributes: None Child Elements: accType, litleToken, routingNum Example: newAccountInfo Structure Account Type New Token Number New Routing Number 616 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide nextRecycleTime cnpAPI Elements 4.255 nextRecycleTime NOTE: The recycling Advice feature is no longer supported. The nextRecycleTime element is an optional child of the recycleAdvice element, which specifies the date and time (in GMT) recommended for the next recycle of the declined Authorization/Sale transaction. The format of the element is YYYY-MM-DDTHH:MM:SSZ. For example, 2011-04-21T11:00:00Z. NOTE: Per the ISO8601 standard, the Z appended to the end of the date/time stamp indicates the time is GMT. Type = dateTime; minLength = N/A; maxLength = 20 Parent Elements: recycleAdvice Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 617 cnpAPI Reference Guide cnpAPI Elements number 4.256 number The number element is defines the account number associated with the transaction or the new/old account number associated with an update. This is a required child of the card element for card-not-present transactions. Type = String; minLength = 13; maxLength = 25 Parent Elements: accountInformation, card, newCardInfo, originalCardInfo Attributes: None Child Elements: None 618 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide numberOfPayments cnpAPI Elements 4.257 numberOfPayments The numberOfPayments element is defines the number of payments in a recurring billing plan including the initial payment. The timing of subsequent charges is defined by the planCode element. This element is an optional child of both the subscription, and createPlan elements. When submitted as a child of the subscription element, the value overrides the default value defined in the Plan. NOTE: For an open-ended Plan, please omit the optional numberOfPayments element in createPlan. For an open-ended subscription, please omit the optional numberOfPayments element in subscription and reference an open-ended Plan. Type = Integer; minLength = 1; maxLength = 99 Parent Elements: subscription, createPlan Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 619 cnpAPI Reference Guide cnpAPI Elements onlinePaymentCryptogram 4.258 onlinePaymentCryptogram The onlinePaymentCryptogram element is an optional child of the applepayResponse element and provides the BASE64 Encoded signature cryptogram associated with the Apple Pay transaction. Type = Base 64 Encoded String; minLength = N/A; maxLength = 56 Parent Elements: applepayResponse Attributes: None Child Elements: None 620 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide orderDate cnpAPI Elements 4.259 orderDate The orderDate element is an optional child of the enhancedData element, which specifies the date the order was placed. If you do not know the order date, do not include this element. Type = Date; Format = YYYY-MM-DD Parent Elements: enhancedData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 621 cnpAPI Reference Guide cnpAPI Elements orderId 4.260 orderId The orderId element is a required child of several transaction types and defines a merchant-assigned value representing the order in the merchant’s system. Type = String; minLength = N/A; maxLength = 25 NOTE: If you are using the orderId element as the transaction signature for the Recycling Engine, do not use the pipe character ("|") in the orderId. Use of the pipe character in this scenario will cause recycling errors. Parent Elements: accountUpdate, accountUpdateResponse, activate, authorization, authorizationResponse, balanceInquiry, credit, captureGivenAuth, deactivate, echeckCredit, echeckPreNoteCredit, echeckPreNoteSale, echeckSale, echeckVerification, forceCapture, giftCardCredit, load, registerTokenRequest, sale, saleResponse, unload, updateCardValidationNumOnToken Attributes: None Child Elements: None 622 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide orderSource cnpAPI Elements 4.261 orderSource The orderSource element defines the order entry source for the type of transaction. Type = Choice (enum); minLength = N/A; maxLength = N/A Parent Elements: activate, authorization, balanceInquiry, captureGivenAuth, credit, deactivate, echeckCredit, echeckPreNoteCredit, echeckPreNoteSale, echeckSale, echeckVerification forceCapture, load, sale, unload Attributes: None Child Elements: None Enumerations: NOTE: If you submit the wrong orderSource value, we return the response code 370 - Internal System Error - Contact Litle. eCheckSale transactions must use an orderSource of one of the following: telephone, ecommerce, echeckppd, or recurringtel. Enumeration Description 3dsAuthenticated Use this value only if you authenticated the cardholder via an approved 3DS system such as Visa Verified By Visa and MasterCard SecureCode. This value applies to Visa and MasterCard transactions only. NOTE: Your Merchant Profile must be configured to process 3DS type payments and accept this value. 3dsAttempted Use this value only if you attempted to authenticate the cardholder via an approved 3DS system such as Visa VerifiedByVisa and MasterCard SecureCode, but either the Issuer or cardholder is not participating in the 3DS program. This value applies to Visa and MasterCard transactions only. If this is a MasterCard transaction, you must include the authenticationValue returned by MasterCard. NOTE: Your Merchant Profile must be configured to process 3DS type payments and accept this value. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 623 cnpAPI Reference Guide cnpAPI Elements orderSource Enumeration Description echeckppd (eCheck only) Use this value for eCheck PPD transactions (Prearranged Payment and Deposit Entries). This type of transaction occurs when a merchants receives a written authorization, including a voided paper check, from a consumer so that the merchant can debit the consumer account. These transactions can be single entry or recurring debits to a consumer's account. ecommerce The transaction is an Internet or electronic commerce transaction. installment The transaction in an installment payment. mailorder The transaction is for a single mail order transaction. recurring The transaction is a recurring transaction. For Visa transactions, you can use this value for all transactions in a recurring stream including the initial transaction. retail The transaction is a Swiped or Keyed Entered retail purchase transaction. telephone The transaction is for a single telephone order. recurringtel (eCheck only) The transaction is a recurring eCheck transaction initiated via telephone applepay The transaction uses the Apple Pay service. androidpay The transaction uses the Android Pay service. 624 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide originalAccountInfo cnpAPI Elements 4.262 originalAccountInfo The originalAccountInfo element is an optional child of the accountUpdater element, which contains child elements providing the original information for the submitted account. Parent Elements: accountUpdater Attributes: None Child Elements: accType, accNum, routingNum Example: originalAccountInfo Structure Account Type Original Token Number Original Routing Number Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 625 cnpAPI Reference Guide cnpAPI Elements origAccountNumber 4.263 origAccountNumber The origAccountNumber element is an optional child of the queryTransaction element and defines the account number of the credit/debit/gift card used in the original transaction. NOTE: If you are performing a query for an eCheck transaction, do not use this element to designate the checking/savings account number. You should use this element for Credit/Debit/Gift card account numbers only. Type = String; minLength = 13; maxLength = 25 Parent Elements: queryTransaction Attributes: None Child Elements: None 626 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide origActionType cnpAPI Elements 4.264 origActionType The origActionType element is a required child of the queryTransaction element and defines the transaction type of original transaction. Type = String (Enum); minLength = 1; maxLength = 2 (Valid values shown below) Parent Elements: queryTransaction Attributes: None Child Elements: None Enumerations: Enumeration Transaction Type A authorization AR activateReversal D deposit or sale G activate I unload J deactivate L load LR loadReversal P authReversal R credit RR refundReversal S echeckSale T echeckCredit UR unloadReversal V void W depositReversal Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 627 cnpAPI Reference Guide cnpAPI Elements 628 origActionType Enumeration Transaction Type X echeckVoid Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide origId cnpAPI Elements 4.265 origId The origId element is a required child of the queryTransaction element and defines the id attribute used in the original transaction. Type = String; minLength = N/A; maxLength = 25 Parent Elements: queryTransaction Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 629 cnpAPI Reference Guide cnpAPI Elements originalAmount 4.266 originalAmount The originalAmount element is a required child of several gift card reversal transactions, as well as the giftCardCapture transaction, where it specifies the amount of the original gift card transaction. In the case of the giftCardCapture transaction, this is the amount associated with the authorization. In the cast of a reversal transaction, it is the amount from the transaction you want to reverse. For example, for an loadReversal it specifies the amount from the load transaction. Type = Integer; totalDigits = 6 Parent Elements: activateReversal, deactivateReversal, depositReversal, giftCardAuthReversal,giftCardCapture, loadReversal, refundReversal, unloadReversal Attributes: None Child Elements: None 630 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide originalCard cnpAPI Elements 4.267 originalCard The originalCard element is an optional child of the accountUpdateResponse element, which contains child elements providing the original information for the submitted card. Parent Elements: accountUpdateResponse Attributes: None Child Elements: type, number, expDate Example: originalCard Structure Card Type Old Account Number Old Expiration Date Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 631 cnpAPI Reference Guide cnpAPI Elements originalCardInfo 4.268 originalCardInfo The originalCardInfo element is an optional child of the accountUpdater element, which contains child elements providing the original information for the submitted card. Parent Elements: accountUpdater Attributes: None Child Elements: type, number, expDate Example: originalCard Structure Card Type Old Account Number Old Expiration Date 632 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide originalCardTokenInfo cnpAPI Elements 4.269 originalCardTokenInfo The originalCardTokenInfo element is an optional child of the accountUpdater element, which contains child elements providing the original information for the submitted token. Parent Elements: accountUpdater Attributes: None Child Elements: litleToken, type, expDate, bin Example: originalCard Structure Old Token Card Type Old Expiration Date Old Card BIN Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 633 cnpAPI Reference Guide cnpAPI Elements originalNetworkTransactionId 4.270 originalNetworkTransactionId The originalNetworkTransactionId element is an optional child of the authorization, captureGivenAuth, and sale transactions. It defines the networkTransactionId returned in the response messages for Visa and Discover Auth/Sale transactions. You must include this element and the original value returned for subsequent (after the initial) Visa or Discover recurring/installment payments. Type = String; minLength = N/A; maxLength = 30 NOTE: In the initial transaction of the recurring/installment stream, you must set the processingType element to either initialRecurring or initialInstallment, as applicable. As of April 2017, if you fail to include this element/value for a recurring/installment Visa or Discover transaction, the card network rejects the transaction. Parent Elements: authorization, captureGivenAuth, sale Attributes: None Child Elements: None 634 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide originalRefCode cnpAPI Elements 4.271 originalRefCode The originalRefCode element is a required child of several gift card transactions, where it specifies the value returned in the refCode element of the associated giftCardResponse element of the response messages. Type = String; minLength = N/A; maxLength = 6 Parent Elements: activateReversal, deactivateReversal, depositReversal, giftCardAuthReversal, giftCardCapture, loadReversal, refundReversal, unloadReversal, Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 635 cnpAPI Reference Guide cnpAPI Elements originalSequenceNumber 4.272 originalSequenceNumber The originalSequenceNumber element is a required child of several gift card reversal transactions, where it specifies the value returned in the sequenceNumber element of the associated giftCardResponse element of the response messages. Type = String; totalDigits = 6; Allowed Characters: 0 - 9 Parent Elements: activateReversal, deactivateReversal, depositReversal, giftCardAuthReversal, loadReversal, refundReversal, unloadReversal, Attributes: None Child Elements: None 636 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide originalSystemTraceId cnpAPI Elements 4.273 originalSystemTraceId The originalSystemTraceId element is a required child of several gift card reversal transactions, where it specifies the value returned in the systemTraceId element of the associated giftCardResponse element from the response messages of the transaction you wish to reverse. For example, for a loadReversal transaction, you use the value returned in the loadResponse message. Type = Integer; totalDigits = 6 Parent Elements: activateReversal, deactivateReversal, depositReversal, giftCardAuthReversal, loadReversal, refundReversal, unloadReversal Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 637 cnpAPI Reference Guide cnpAPI Elements originalToken 4.274 originalToken The originalToken element is an optional child of the accountUpdateResponse element, which contains child elements providing the original information for the submitted token. Parent Elements: accountUpdateResponse Attributes: None Child Elements: type, number, expDate, bin Example: originalCard Structure Old Token Number Old Expiration Date Card Type Card BIN 638 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide originalTokenInfo cnpAPI Elements 4.275 originalTokenInfo The originalTokenInfo element is an optional child of the accountUpdater element, which contains child elements providing the original token information for the submitted account. The system returns this information when processing a tokenized eCheck transactions and a change (NOC) is found against the account. Parent Elements: accountUpdater Attributes: None Child Elements: accType, litleToken, routingNum Example: originalAccountInfo Structure Account Type Old Account Number Old Routing Number Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 639 cnpAPI Reference Guide cnpAPI Elements originalTransactionAmount 4.276 originalTransactionAmount The originalTransactionAmount element is an optional child of the authorization, captureGivenAuth, and sale transactions. It defines the amount from the initial transaction in a recurring/installment stream. You must include this element and the original amount in subsequent (after the initial) recurring/installment payments, if the payment method is Discover. You must also include the originalNetworkTransactionId element using the value from the networkTransactionId element returned in the initial transaction of the stream. NOTE: In the initial transaction of the recurring/installment stream, you must set the processingType element to either initialRecurring or initialInstallment, as applicable. As of April 2017, if you fail to include this element/value for a recurring/installment Discover transaction, the card network rejects the transaction. Type = Integer; totalDigits = 12 Parent Elements: authorization, captureGivenAuth, sale Attributes: None Child Elements: None 640 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide originalTxnTime cnpAPI Elements 4.277 originalTxnTime The originalTxnTime element is a required child of several gift card transactions, which specifies the date and time the original transaction was processed by Vantiv. The system returns this value in the txnTime child of the giftCardResponse element. The format of the element is YYYY-MM-DDTHH:MM:SS. For example, 2016-11-21T11:00:00. Type = dateTime; minLength = N/A; maxLength = 20 Parent Elements: activateReversal, deactivateReversal, depositReversal, giftCardAuthReversal, giftCardCapture, loadReversal, refundReversal, unloadReversal Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 641 cnpAPI Reference Guide cnpAPI Elements origLitleTxnId 4.278 origLitleTxnId The origLitleTxnId element is an optional child of the queryTransaction element and defines the value of the litleTxnId element assigned to the original transaction and returned in the response message. Type = Long; minLength = N/A; maxLength = 19 Parent Elements: queryTransaction Attributes: None Child Elements: None 642 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide origOrderId cnpAPI Elements 4.279 origOrderId The origOrderId element is an optional child of the queryTransaction element and defines the merchant-assigned value for the orderId element submitted in the original transaction. Type = String; minLength = N/A; maxLength = 25 Parent Elements: queryTransaction Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 643 cnpAPI Reference Guide cnpAPI Elements password 4.280 password The password element is a required child of the authentication element. It is used in combination with the user element to authenticate that the message is from a valid source. Type = String; minLength = N/A; maxLength = 20 Parent Elements: authentication Attributes: None Child Elements: None 644 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide payerId cnpAPI Elements 4.281 payerId The payerId element is a required child of the paypal element for all cases except for an Online Credit transaction, where you can choose between this element and the payerEmail element. This element specifies the Payer Id returned from PayPal. NOTE: The value of the element must match the PAYERID value returned by the GetExpressCheckout call operation to PayPal. Type = String; minLength = 1; maxLength = 17 Parent Elements: paypal Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 645 cnpAPI Reference Guide cnpAPI Elements payFacCredit 4.282 payFacCredit The payFacCredit element is the parent element for the transaction type that a PayFac uses to distribute funds to themselves (i.e., from the PayFac Settlement Account to the PayFac Operating Account). If you use V11.3 or above, you can submit this transaction type either in a Batch or Online. NOTE: You can submit funding instructions either Online or via Batch files, but not both. The two methodologies are mutually exclusive for funding instruction submissions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 duplicate boolean No maxLength = 25 If the request is a duplicate, the response includes the duplicate flag set to true and the entire original response. Note: This attribute applies only to Online Dynamic Payout Funding Instruction responses. Child Elements: Required: amount, fundingSubmerchantId, fundsTransferId 646 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide payFacCreditResponse cnpAPI Elements 4.283 payFacCreditResponse The payFacCreditResponse element is the parent element for information returned to you in response to a payFacCredit transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the payFacCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the payFacCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the payFacCredit transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, fundsTransferId, response, responseTime, message Required (Online): postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 647 cnpAPI Reference Guide cnpAPI Elements payFacDebit 4.284 payFacDebit The payFacDebit element is the parent element for the transaction type that a PayFac uses to move funds from the PayFac Operating Account back to the PayFac Settlement Account. If you use V11.3 or above, you can submit this transaction type either in a Batch or Online. NOTE: You can submit funding instructions either Online or via Batch files, but not both. The two methodologies are mutually exclusive for funding instruction submissions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 duplicate boolean No maxLength = 25 If the request is a duplicate, the response includes the duplicate flag set to true and the entire original response. Note: This attribute applies only to Online Dynamic Payout Funding Instruction responses. Child Elements: Required: amount, fundingSubmerchantId, fundsTransferId 648 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide payFacDebitResponse cnpAPI Elements 4.285 payFacDebitResponse The payFacDebitResponse element is the parent element for information returned to you in response to a payFacDebit transaction. Parent Elements: batchRequest, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the payFacCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the payFacDebit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the payFacCredit transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, fundsTransferId, response, responseTime, message Required (Online): postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 649 cnpAPI Reference Guide cnpAPI Elements paymentDataType 4.286 paymentDataType The paymentDataType element is an optional child of the applepayResponse element and specifies data type of the payment data associated with an Apple Pay transaction. Type = String; minLength = N/A; maxLength = 20 Parent Elements: applepayResponse Attributes: None Child Elements: None 650 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide paymentPurpose cnpAPI Elements 4.287 paymentPurpose The paymentPurpose element is an optional child of the idealResponse and giropayResponse elements where it specifies information (equivalent of Bill Descriptor for a credit card transaction) that appears on the consumer bank statement along with a reference string representing the transaction. The value has two components. The first part is a reference number assigned to the transaction. The second part is a default merchant descriptor established during implementation. Type = String; minLength = N/A; maxLength = 256 Parent Elements: idealResponse, giropayResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 651 cnpAPI Reference Guide cnpAPI Elements paypage 4.288 paypage The paypage element defines eProtect account information. It replaces the card or token elements in transactions using the eProtect feature of the Vault solution. When you submit the paypage element in a request, response messages will include token information. Parent Elements: authorization, captureGivenAuth, credit, forceCapture, sale, updateSubscription, fastAccessFunding Attributes: None Child Elements: Required: paypageRegistrationId Optional: expDate, cardValidationNum, type NOTE: Although the schema defines the expDate element as an optional child of the paypage element, you must submit a value for card-not-present transactions. Example: Example: paypage Structure Registration ID from eProtect Expiration Date Card Validation Number Method of Payment 652 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide paypageRegistrationId cnpAPI Elements 4.289 paypageRegistrationId The paypageRegistrationId element is a required child of the paypage element, and specifies the Registration ID generated by securepaypage.litle.com (eProtect). You can also use it in a Register Token Request to obtain a token based on eProtect activity prior to submitting an Authorization or Sale transaction. Type = String; minLength = N/A; maxLength = 512 Parent Elements: paypage, registerTokenRequest Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 653 cnpAPI Reference Guide cnpAPI Elements paypal 4.290 paypal The paypal element defines paypal account information. It replaces the card or token elements in transactions using PayPal as a payment method. Parent Elements: authorization, sale Attributes: None Child Elements: Required: payerId, transactionId Optional: token Example: paypal Structure PayPal Customer Identifier Token Value Returned PayPal Transaction ID 654 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide payPalNotes cnpAPI Elements 4.291 payPalNotes The payPalNotes element is an optional child of multiple transaction types. You use this field to record additional information about the PayPal transaction. Type = String; Type = String; minLength = N/A; maxLength = 255 Parent Elements: authReversal, capture, credit, sale Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 655 cnpAPI Reference Guide cnpAPI Elements payPalOrderComplete 4.292 payPalOrderComplete The payPalOrderComplete element is an optional child of both the capture and sale elements, but is required to close a PayPal order. Set the value to true to close the order, when you have fulfilled the order and do not need to send any further auths or deposits against it. Set the value to false to keep the order open for additional auths or deposits. Type = Boolean; Valid values = true or false Parent Elements: capture, sale Attributes: None Child Elements: None 656 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide phone cnpAPI Elements 4.293 phone The phone element has two different uses in cnpAPI depending upon the parent element. When used as a child of either the billToAddress or shipToAddress elements, it defines the customers phone number. When used as a child of the customBilling element, it defines the phone number of the merchant. 4.293.0.1 phone as a child of billToAddress and shipToAddress The phone element defines the customer’s phone number in both the billToAddress and shipToAddress elements. NOTE: When submitting an eCheck Verification, the string can only contain numbers (0 through 9). Letters and special characters are not allowed. Type = String; minLength = N/A; maxLength = 20 Parent Elements: billToAddress, shipFromPostalCode Attributes: None Child Elements: None 4.293.0.2 phone as a child of customBilling The phone element defines the merchant’s phone number. The string can only contain numbers (0 through 9). Letters and special characters are not allowed. Type = String; minLength = N/A; maxLength = 13 Parent Elements: customBilling Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 657 cnpAPI Reference Guide cnpAPI Elements physicalCheckCredit 4.294 physicalCheckCredit The physicalCheckCredit element is the parent element for the transaction type that a PayFac uses to distribute funds to a third party who issues physical checks on the PayFacs behalf. (i.e., from the PayFac Settlement Account to the Third Party Account). If you use V11.3 or above, you can submit this transaction type either in a Batch or Online. NOTE: You can submit funding instructions either Online or via Batch files, but not both. The two methodologies are mutually exclusive for funding instruction submissions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 duplicate boolean No maxLength = 25 If the request is a duplicate, the response includes the duplicate flag set to true and the entire original response. Note: This attribute applies only to Online Dynamic Payout Funding Instruction responses. Child Elements: Required: amount, fundingSubmerchantId, fundsTransferId 658 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide physicalCheckCreditResponse cnpAPI Elements 4.295 physicalCheckCreditResponse The physicalCheckCreditResponse element is the parent element for information returned to you in response to a physicalCheckCredit transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the physicalCheckCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the physicalCheckCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the physicalCheckCredit transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, fundsTransferId, response, responseTime, message Required (Online): postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 659 cnpAPI Reference Guide cnpAPI Elements physicalCheckDebit 4.296 physicalCheckDebit The physicalCheckDebit element is the parent element for the transaction type that a PayFac uses to move funds from a third party who issues physical checks on the PayFac’s behalf. (i.e., from the Third Party Account to the PayFac Settlement Account). If you use V11.3 or above, you can submit this transaction type either in a Batch or Online. NOTE: You can submit funding instructions either Online or via Batch files, but not both. The two methodologies are mutually exclusive for funding instruction submissions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 duplicate boolean No maxLength = 25 If the request is a duplicate, the response includes the duplicate flag set to true and the entire original response. Note: This attribute applies only to Online Dynamic Payout Funding Instruction responses. Child Elements: Required: amount, fundingSubmerchantId, fundsTransferId 660 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide physicalCheckDebitResponse cnpAPI Elements 4.297 physicalCheckDebitResponse The physicalCheckDebitResponse element is the parent element for information returned to you in response to a physicalCheckDebit transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the physicalCheckDebit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the physicalCheckDebit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the physicalCheckDebit transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, fundsTransferId, response, responseTime, message Required (Online): postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 661 cnpAPI Reference Guide cnpAPI Elements pin 4.298 pin The pin element is an optional child of the several transaction types, as well as the card element. It only applies to transactions involving closed-loop Gift Cards and defines the pin number associated with the Gift Card. Type = String; minLength = 4; maxLength = 12 Parent Elements: capture, card, credit, virtualGiftCardResponse Attributes: None Child Elements: None 662 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide planCode cnpAPI Elements 4.299 planCode The planCode element is the identifier of a defined recurring payment plan. You use it to specify the payment plan when submitting a recurring transaction to the Recurring Engine. For example, there could be a define plan called Monthly that instructs the Recurring Engine to bill the consumer the same amount every month for the number of months defined by the numberOfPayments element. This element is a required child of the subscription element. Type = String; minLength = N/A; maxLength = 25 Parent Elements: subscription, updateSubscription, createPlan, updatePlan, updatePlanResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 663 cnpAPI Reference Guide cnpAPI Elements pos 4.300 pos The pos element contains child elements used to specify information required when submitting authorization, captureGivenAuth, credit, forceCapture, and sale transactions from point of sale terminals. Parent Elements: authorization, captureGivenAuth, credit, forceCapture, sale Attributes: None Child Elements: capability, entryMode, cardholderId, terminalId, catLevel Example: pos Structure Capabilty Enumeration Entry Mode Enumeration Cardholder ID Enumeration 1234567890 Capabilty of CAT Terminal NOTE: 664 For CAT (Cardholder Activated Terminal) transactions, the capability element must be set to magstripe, the cardholderId element must be set to nopin, and the catLevel element must be set to self service. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide postDate cnpAPI Elements 4.301 postDate The postDate element defines the date the transaction was posted. The format is YYYY-MM-DD. It occurs only in response to Online transactions. NOTE: Although the schema defines this element as optional in most response messages, the system returns it in the response for all Online transactions. Type = Date; minLength = N/A; maxLength = 10 Parent Elements: activateResponse, activateReversalResponse, authorizationResponse, authReversalResponse, captureResponse, captureGivenAuthResponse, creditResponse, deactivateResponse, deactivateReversalResponse, depositReversalResponse, echeckCreditResponse, echeckSalesResponse, echeckVerificationResponse, forceCaptureResponse, loadResponse, loadReversalResponse, refundReversalResponse, saleResponse, unloadResponse, unloadReversalResponse, voidResponse, fastAccessFundingResponse, payFacCreditResponse, payFacDebitResponse, physicalCheckCreditResponse, physicalCheckDebitResponse, reserveCreditResponse, reserveDebitResponse, submerchantCreditResponse, submerchantDebitResponse, vendorCreditResponse, vendorDebitResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 665 cnpAPI Reference Guide cnpAPI Elements postDay 4.302 postDay The postDay element is an optional child of the accountUpdateFileRequestData element that defines the date you submitted the Account Updater request. The format is YYYY-MM-DD. NOTE: This is also the same date that the system created the Account Updater acknowledgment file. Type = Date; minLength = N/A; maxLength = 10 Parent Elements: accountUpdateFileRequestData Attributes: None Child Elements: None 666 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide preapprovalNumber cnpAPI Elements 4.303 preapprovalNumber The preapprovalNumber element is an optional child of the billMeLaterRequest element, which you use to specify the pre-approval number issued by PayPal Credit. If you include this element, the value must be 16 digits in length. Do not include this element to indicate there is no pre-approval. Internal pre-approval is indicated by using 1 as the first digit. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = String; minLength = 13; maxLength = 25 Parent Elements: billMeLaterRequest Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 667 cnpAPI Reference Guide cnpAPI Elements preferredLanguage 4.304 preferredLanguage The preferredLanguage element is an optional child of the sepaDirectDebit element. This defines the language in which the merchant prefers the mandate to appear. While the merchant could be able to select any language, the mandate may not be available in the selected language. If the selected language is not available, the mandate appears in English. If you do not include this element, the preferred language defaults to the language indicated by the country of the IBAN, unless it is not available, in which case the language defaults to English. Type = String (Enum); minLength = N/A; maxLength = 3 NOTE: The enumerations for this element are listed under in the cnpAPI Common XSD. The country names corresponding to the abbreviations can be found in the ISO 3166-1 standard. All Country Codes are 2-character except for the United States, which accepts both US and USA. Parent Elements: sepaDirectDebit, ideal, giropay Attributes: None Child Elements: None 668 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide prepaid cnpAPI Elements 4.305 prepaid The prepaid element is an optional child of the filtering element. How you choose to implement the Prepaid Filtering feature determines the use of the prepaid element. If your configuration filters all prepaid card transactions, you can disable the feature on selected transactions by including the prepaid element with a setting of false. If your configuration filters prepaid card transactions on a per transaction basis, you enable the filtering on a selected transaction by including the prepaid element with a setting of true. Type = Boolean; Valid Values = true or false Parent Elements: filtering Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 669 cnpAPI Reference Guide cnpAPI Elements prepaidCardType 4.306 prepaidCardType The prepaidCardType element is an optional child of the enhancedAuthResponse element, which specifies the type of prepaid card submitted in the Authorization or Sale transaction. For example, a few of the possible values are: GIFT, PAYROLL, and GENERAL_PREPAID Type = String; minLength = N/A; maxLength = 50 Parent Elements: fundingSource Attributes: None Child Elements: None 670 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide processingInstructions cnpAPI Elements 4.307 processingInstructions The processingInstructions element contains a child element that allows you to specify whether or not the system performs velocity checking on the transaction. Parent Elements: (optional for all) authorization, capture, captureGivenAuth, credit, forceCapture, sale, void Attributes: None Child Elements: bypassVelocityCheck NOTE: Please consult your Relationship Manager for additional information concerning Velocity Checking. Example: processingInstructions Structure true or false Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 671 cnpAPI Reference Guide cnpAPI Elements processingType 4.308 processingType The processingType element is an optional child of several transaction types. You use this element to define a Visa transaction is intended to fund a host-based prepaid product, a brokerage account, or an escrow account. For Visa and Discover transactions, you also use it to define the initial transaction in a recurring or installment stream. In this case, you must store the value of the networkTransactionId element returned in the response message. You use this value to populate the originalNetworkTransactionId element in subsequent recurring/installment transaction, so the networks can tie back to the original approval. Type = String (Enum); minLength = N/A; maxLength = N/A Parent Elements: authorization, captureGivenAuth, forceCapture, sale Attributes: None Child Elements: None Enumerations: Enum Description accountFunding Use this value to define a Visa transaction is intended to fund a host-based prepaid product, a brokerage account, or an escrow account. initialRecurring Use this value to specify the first in a series of recurring payments for Visa or Discover transactions. initialInstallment Use this value to specify the first in a series of installment payments for Visa or Discover transactions. 672 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide productCode cnpAPI Elements 4.309 productCode The productCode element is an optional child of the lineItemData element, which specifies the product code of the purchased item. This value is a merchant defined description code of the product/service. This could be an inventory number, UPC, catalog number, or some other value that the merchant uses to define the specific product. Although an optional element, it is required by Visa and MasterCard when specifying line item data. Type = String; minLength = 1; maxLength = 12 Parent Elements: lineItemData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 673 cnpAPI Reference Guide cnpAPI Elements publicKeyHash 4.310 publicKeyHash The publicKeyHash element is a required child of the header element and provides the BASE64 Encoded string that is a hash of the merchant’s certificate public key bytes associated with the Apple Pay transaction. Type = Base 64 Encoded String; minLength = N/A; maxLength = 200 Parent Elements: header Attributes: None Child Elements: None 674 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide quantity cnpAPI Elements 4.311 quantity The quantity element is an optional child of the lineItemData element, which specifies the number of items purchased. Although an optional element, it is required by Visa and MasterCard when specifying line item data. The value must be greater than zero, but no more than 12 digits not including the decimal point. NOTE: If you accidentally omit the quantity element, our system will submit the transaction using a default value of 1. Type = Decimal; minInclusive = 0; totalDigits = 12 Parent Elements: lineItemData Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 675 cnpAPI Reference Guide cnpAPI Elements queryTransaction 4.312 queryTransaction The queryTransaction element is the parent element for Query transactions. You use this transaction type to determine the status of a previously submitted transaction. You can submit this element only as an Online transaction. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: origId, origActionType Optional: origLitleTxnId, origOrderId, origAccountNumber 676 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide queryTransactionResponse cnpAPI Elements 4.313 queryTransactionResponse The queryTransactionResponse element is the parent element for the response to queryTransaction requests. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the capture transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the capture transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the capture transaction. minLength = 1 maxLength = 25 Child Elements: All Required: response, responseTime, message, matchCount, results_Max10 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 677 cnpAPI Reference Guide cnpAPI Elements queryTransactionUnavailableResponse 4.314 queryTransactionUnavailableResponse The queryTransactionUnavailableResponse element is an optional child of the results_Max10 element. If the query results is a response code of 152 - Transaction found, but response not yet available, the results_Max10 element will contain at least one queryTransactionUnavailableResponse child (see example results_Max10 Element for 152 Response Code). Parent Elements: results_Max10 Attributes: None Child Elements: All Required: litleTxnId, response, message 678 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide recurringRequest cnpAPI Elements 4.315 recurringRequest The recurringRequest element is the parent of several child element that define the number of payments and plan type of recurring transaction to be handled by the Recurring Engine. It is an optional child of the Authorization and Sale transactions. Parent Elements: authorization, sale Attributes: None Child Elements: subscription Example: recurringRequest Structure Plan Reference Code 1 to 99 Start Date of Recurring Cycle Amount of Recurring Payment Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 679 cnpAPI Reference Guide cnpAPI Elements recurringResponse 4.316 recurringResponse The recuringResponse element is the parent element for the subscriptionId, responseCode, responseMessage, and recurringTxnId elements associated with a requested recurring payment. The system returns this element only when the sale transaction includes a recurringRequest element. Parent Elements: authorizationResponse, saleResponse Attributes: None Child Elements: subscriptionId, responseCode, responseMessage, recurringTxnId Example: recurringResponse Structure 1234567890 Response Code Response Message 680 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide recurringTxnId cnpAPI Elements 4.317 recurringTxnId The recurringTxnId element is an optional child of the recurringResponse element used to identify the record of recurring, scheduled transactions. Type = Long; minLength = N/A; maxLength = 19 Parent Elements: recurringResponse, litleInternalRecurringRequest NOTE: Although the element is an optional child of the recurringResponse element, it will never be returned in the response to a merchant initiated transaction. Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 681 cnpAPI Reference Guide cnpAPI Elements recycleAdvice 4.318 recycleAdvice NOTE: The recycling Advice feature is no longer supported. The recyclingAdvice element contains a two child elements that either specifies the date and time (in GMT) recommended for the next recycle of the declined Authorization/Sale transaction or indicates that there is no additional recycling advice. The two children are mutually exclusive. Parent Elements: (optional for all) recycling Attributes: None Child Elements: nextRecycleTime, recycleAdviceEnd NOTE: The recycleAdvice element contains either a nextRecycleTime or recycleAdviceEnd element, but not both. Example: recycleAdvice Structure - with recommended Date:Time 2016-11-15T12:00:00 Example: recycleAdvice Structure - with end message End of Advice 682 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide recycleAdviceEnd cnpAPI Elements 4.319 recycleAdviceEnd NOTE: The recycling Advice feature is no longer supported. The recycleAdviceEnd element is an optional child of the recycleAdvice element and signifies that no further recycling recommendations are available. Type = String; minLength = N/A; maxLength = 20 Parent Elements: recycleAdvice Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 683 cnpAPI Reference Guide cnpAPI Elements recycleBy 4.320 recycleBy The recycleBy element is an optional child of the recyclingRequest element and determines the use of the Recycling Engine. The default setting is Litle, so omitting this element is the same as submitting a value of Litle. NOTE: Also, if your Merchant Profile includes a preset percentage split of transactions between merchant and Vantiv controlled, then settings of Merchant and Litle are ignored; you can still use a setting of None to exclude the transaction. Also, although the default setting is normally Litle, it can be altered in your merchant profile to a setting of Merchant. Type = String (Enum); minLength = N/A; maxLength = N/A Parent Elements: recyclingRequest Attributes: None Child Elements: None Enumerations: Enum Description Merchant This setting indicates that the merchant controls the recycling of the transaction. For A/B comparison testing, transactions using this setting will be counted as merchant controlled. After setting this value in the initial transaction, subsequent transactions should have same value. Any different value will be ignored. Litle This setting indicates either that the Recycling Engine controls the recycling of the transaction. For A/B comparison testing, transactions using this setting will be counted as Vantiv controlled. After setting this value in the initial transaction, subsequent transactions should have same value. Any different value will be ignored. None 684 For A/B comparison testing, transactions using this setting are excluded from all counts. These transactions will not be counted as either merchant or Vantiv controlled. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide recycleEngineActive cnpAPI Elements 4.321 recycleEngineActive The recycleEngineActive element is an optional child of the recycling element that indicates whether or not the engine is recycling the declined transaction. This element is returned only if you are using the Recycling Engine. Type = Boolean; Valid values = true or false Parent Elements: recycling Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 685 cnpAPI Reference Guide cnpAPI Elements recycleId 4.322 recycleId The recycleId element is an optional child of the recyclingRequest element. Merchants can use this identifier as part of the transaction signature used to track the recycling of a transaction. This element is an alternative to using the orderId element as part of the transaction signature. Type = String; minLength = N/A; maxLength = 25 Parent Elements: recyclingRequest Attributes: None Child Elements: None 686 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide recycling cnpAPI Elements 4.323 recycling The recycling element has two uses in the cnpAPI depending upon the parent. When used as a child of either the authorizationResponse or saleResponse elements, the recycling element contains a child element that specifies whether or not the engine is recycling the declined transaction. When used as a child of the voidResponse, the recycling element contains a child providing the Transaction Id of the Credit transaction issued. This occurs only if a Void transaction is used to halt the recycling of a transaction by the recycling engine and the transaction has already been approved and captured (see Using Void to Halt Recycling Engine on page 86). 4.323.1 recycling Element as a Child of authorizationResponse or saleResponse The recycling element contains child elements indicating that the Recycling Engine is active. Parent Elements: authorizationResponse, saleResponse Attributes: None Child Elements: recycleAdvice, recycleEngineActive NOTE: The recycling Advice feature is no longer supported. Example: recycling Structure - with engine active flag true or false 4.323.2 recycling Element as a Child of voidResponse The recycling element in an optional child of the voidResponse element and contains a child providing the Transaction Id of the Credit transaction issued. This element is present in the Void response only under the following circumstances (see Using Void to Halt Recycling Engine on page 86): Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 687 cnpAPI Reference Guide cnpAPI Elements recycling • You submitted a Void transaction to halt the recycling of a declined Sale transaction by the Recovery/Recycling Engine. • The Sale transaction has already been approved and captured. • Your Recovery/Recycling Engine configuration enables automatic refunds. • The system has successfully submitted a Credit transaction on your behalf. Parent Elements: voidResponse Attributes: None Child Elements: creditLitleTxnId Example: recycling Structure - child of voidResponse 1234567890123456789 688 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide recyclingRequest cnpAPI Elements 4.324 recyclingRequest The recyclingrequest element is an optional child of the authorization and sale transactions, which contains a child element that specifies who is responsible for recycling the transaction. It also contains an optional element for an identifier assigned by the merchant to track the recycling of the transaction. This element only applies to merchants using the Recycling Engine. Parent Elements: authorization, sale Attributes: None Child Elements: recycleBy, recycleId Example: recyclingRequest Structure Merchant or Litle or None abcdef1234567890 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 689 cnpAPI Reference Guide cnpAPI Elements redirectToken 4.325 redirectToken The redirectToken element is an optional child of the sepaDirectDebitResponse, idealResponse, and giropayResponse elements. It allows you to verify that the consumer accepted the Mandate by comparing it to the token_value parameter returned in the URL upon redirect from the Mandate site. Type = String; minLength = N/A; maxLength = 128 Parent Elements: sepaDirectDebitResponse, idealResponse, giropayResponse Attributes: None Child Elements: None 690 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide redirectUrl cnpAPI Elements 4.326 redirectUrl The redirectUrl element is an optional child of the sepaDirectDebit element and defines the URL that hosts the mandate, when Vantiv supplies the mandate. If you supply the mandate (Merchant), this element will not appear in the response. Type = String; minLength = N/A; maxLength = 256 Parent Elements: sepaDirectDebitResponse, idealResponse, giropayResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 691 cnpAPI Reference Guide cnpAPI Elements refCode 4.327 refCode The refCode element is an optional child of the giftCardResponse element, where it specifies the authorization code of the gift card transaction. Type = String; minLength = N/A; maxLength = 6 Parent Elements: giftCardResponse Attributes: None Child Elements: None 692 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide refundReversal cnpAPI Elements 4.328 refundReversal The refundReversal element is the parent element for a Gift Card specific transaction type that reverses the a refund associated with a Gift Card. Parent Elements: litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: (Required) card, originalRefCode, originalAmount, originalTxnTime, originalSystemTraceId, originalSequenceNumber Child Elements: (Optional) litleTxnId Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 693 cnpAPI Reference Guide cnpAPI Elements refundReversalResponse 4.329 refundReversalResponse The refundReversalResponse element is the parent element for information returned to you in response to an refundReversal transaction. Parent Elements: litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the Refund Reversal transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the Refund Reversal transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the Refund Reversal transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, responseTime, message, giftCardResponse Optional: postDate 694 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide registerTokenRequest cnpAPI Elements 4.330 registerTokenRequest The registerTokenRequest element is the parent element for the Register Token transaction. You use this transaction type when you wish to submit an account number for tokenization, but there is no associated payment transaction. You can use this element in either Online or Batch transactions. NOTE: When submitting registerTokenRequest elements in a batchRequest, you must also include a numTokenRegistrations= attribute in the batchRequest element. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute defining the merchant sub-group in the user interface where this transaction displays. Also see Coding for Report Groups on page 10 for information. minLength = 1 maxLength = 25 Child Elements: Required: either accountNumber, echeckForToken, mpos, paypageRegistrationId, or applepay Optional: orderId, cardValidationNum NOTE: The use of the cardValidationNum element in the registertokenRequest only applies when you submit an accountNumber element. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 695 cnpAPI Reference Guide cnpAPI Elements registerTokenResponse 4.331 registerTokenResponse The registerTokenResponse element is the parent element for the response to registerTokenRequest transactions. You receive this transaction type in response to the submission of an account number for tokenization in a registerTokenRequest transaction. Parent Elements: litleOnlineResponse, batchResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the registerTokenRequest transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the registerTokenRequest transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the registerTokenRequest transaction. minLength = 1 maxLength = 25 Child Elements: Required: litleTxnId, response, message, responseTime Optional: eCheckAccountSuffix, litleToken, bin, type, applepayResponse, androidpayResponse 696 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide reloadable cnpAPI Elements 4.332 reloadable The reloadable element is an optional child of the fundingSource element and defines whether the prepaid card is reloadable. NOTE: This element is never returned for American Express card transaction. Type = String (Enum); Enumerations = YES, NO, or UNKNOWN Parent Elements: fundingSource Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 697 cnpAPI Reference Guide cnpAPI Elements reserveCredit 4.333 reserveCredit The reserveCredit element is the parent element for the transaction type that a PayFac uses to move funds from the PayFac Settlement Account to the PayFac Reserve Account. If you use V11.3 or above, you can submit this transaction type either in a Batch or Online. NOTE: You can submit funding instructions either Online or via Batch files, but not both. The two methodologies are mutually exclusive for funding instruction submissions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 maxLength = 25 Child Elements: Required: amount, fundingSubmerchantId, fundsTransferId 698 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide reserveCreditResponse cnpAPI Elements 4.334 reserveCreditResponse The reserveCreditResponse element is the parent element for information returned to you in response to a reserveCredit transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the payFacCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the payFacCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the reserveCredit transaction. minLength = 1 duplicate boolean No maxLength = 25 If the request is a duplicate, the response includes the duplicate flag set to true and the entire original response. Note: This attribute applies only to Online Dynamic Payout Funding Instruction responses. Child Elements: Required: litleTxnId, fundsTransferId, response, responseTime, message Required (Online): postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 699 cnpAPI Reference Guide cnpAPI Elements reserveDebit 4.335 reserveDebit The reserveDebit element is the parent element for the transaction type that a PayFac uses to move funds from the PayFac Reserve Account to the PayFac Settlement Account. If you use V11.3 or above, you can submit this transaction type either in a Batch or Online. NOTE: You can submit funding instructions either Online or via Batch files, but not both. The two methodologies are mutually exclusive for funding instruction submissions. Parent Elements: batchRequest, litleOnlineRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes For PayFacs, this attribute does not segregate transactions in iQ. This field does appear in various SSR reports. minLength = 1 maxLength = 25 Child Elements: Required: amount, fundingSubmerchantId, fundsTransferId 700 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide reserveDebitResponse cnpAPI Elements 4.336 reserveDebitResponse The reserveDebitResponse element is the parent element for information returned to you in response to a reserveDebit transaction. Parent Elements: batchResponse, litleOnlineResponse Attributes: Attribute Name Type Required? Description id String Yes The response returns the same value submitted in the payFacCredit transaction. minLength = 1 customerId String No maxLength = 36 The response returns the same value submitted in the payFacCredit transaction. minLength = N/A maxLength = 50 reportGroup String Yes The response returns the same value submitted in the reserveDebit transaction. minLength = 1 duplicate boolean No maxLength = 25 If the request is a duplicate, the response includes the duplicate flag set to true and the entire original response. Note: This attribute applies only to Online Dynamic Payout Funding Instruction responses. Child Elements: Required: litleTxnId, fundsTransferId, response, responseTime, message Required (Online): postDate Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 701 cnpAPI Reference Guide cnpAPI Elements residenceStatus 4.337 residenceStatus The residenceStatus element is an optional child of the customerInfo element and defines the type of domicile in which the customer resides. It is used in combination with several other elements to provide required information for some PayPal Credit transactions. NOTE: As of September, 2016, the Vantiv eCommerce platform no longer supports PayPal Credit for new merchants or existing merchants not already using this payment method. Existing merchants already using PayPal Credit should consult their Vantiv Relationship Manager. Type = String (Enum); Enumerations = Own, Rent, or Other Parent Elements: customerInfo Attributes: None Child Elements: None 702 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide response cnpAPI Elements 4.338 response The response element contains a three digit numeric code which specifies either that the transaction is approved (000 code) or declined. The message element provides a brief definition of the response code. For a complete list of response codes and associated messages, please refer to Payment Transaction Response Codes on page 816. Type = String; minLength = N/A; maxLength = 3 Parent Elements: activateResponse, activateReversalResponse, authorizationResponse, authReversalResponse, captureResponse, captureGivenAuthResponse, creditResponse, deactivateResponse, deactivateReversalResponse, depositReversalResponse, echeckCreditResponse, echeckPreNoteCreditResponse, echeckPreNoteSaleResponse, echeckRedepositResponse, echeckSalesResponse, echeckVerificationResponse, echeckVoidResponse, forceCaptureResponse, fraudCheckResponse, loadResponse, loadReversalResponse, queryTransactionResponse, queryTransactionUnavailableResponse, registerTokenResponse, refundReversalResponse, saleResponse, voidResponse, cancelSubscriptionResponse, unloadResponse, updatePlanResponse, updateSubscriptionResponse, unloadReversalResponse, payFacCreditResponse, payFacDebitResponse, physicalCheckCreditResponse, physicalCheckDebitResponse, submerchantCreditResponse, reserveCreditResponse, reserveDebitResponse, submerchantDebitResponse, vendorCreditResponse, vendorDebitResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 703 cnpAPI Reference Guide cnpAPI Elements responseCode 4.339 responseCode The responseCode element contains a three digit numeric code which along with the responseMessage element specifies either acceptance by the Recurring Engine or the reason the recurring Engine was unable to schedule subsequent payments. Type = String; minLength = N/A; maxLength = 3 Parent Elements: recurringResponse Attributes: None Child Elements: None 704 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide responseMessage cnpAPI Elements 4.340 responseMessage The responseMessage element contains a brief definition of the responseCode returned for the recurring transaction. Type = String; minLength = N/A; maxLength = 512 Parent Elements: recurringResponse Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 705 cnpAPI Reference Guide cnpAPI Elements responseTime 4.341 responseTime The responseTime element provides a date/time stamp of the response. The format of the element is YYYY-MM-DDTHH:MM:SS. For example, 2009-12-21T11:37:04. Type = dateTime; minLength = N/A; maxLength = 19 Parent Elements: activateResponse, activateReversalResponse, authorizationResponse, authReversalResponse, captureResponse, captureGivenAuthResponse, creditResponse, deactivateResponse, deactivateReversalResponse, depositReversalResponse,echeckCreditResponse, echeckPreNoteCreditResponse, echeckPreNoteSaleResponse, echeckRedepositResponse, echeckSalesResponse, echeckVerificationResponse, echeckVoidResponse, forceCaptureResponse, fraudCheckResponse, loadResponse, loadReversalResponse, queryTransactionResponse, registerTokenResponse, refundReversalResponse, saleResponse, voidResponse, cancelSubscriptionResponse, unloadResponse, unloadReversalResponse, updatePlanResponse, updateSubscriptionResponse, payFacCreditResponse, payFacDebitResponse, physicalCheckCreditResponse, physicalCheckDebitResponse, reserveCreditResponse, reserveDebitResponse, submerchantCreditResponse, submerchantDebitResponse, vendorCreditResponse, vendorDebitResponse Attributes: None Child Elements: None 706 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide results_Max10 cnpAPI Elements 4.342 results_Max10 The results_Max10 element is a required child of the queryTransactionResponse. Any original transaction responses that match the criteria submitted in the queryTransaction appear as children of this element in the response. The system can return a maximum of ten responses as children of the results_Max10 element. The value for the matchCount element reflects the number of found transactions. If the system does not find any transactions matching the query criteria, the results_Max10 element will be empty. If the query results is a response code of 152 - Transaction found, but response not yet available, the results_Max10 element will contain at least one queryTransactionUnavailableResponse child and may contain other found responses. Parent Elements: queryTransactionResponse Attributes: None Child Elements: All Optional: activateResponse, activateReversalResponse, authorizationResponse, captureResponse, creditResponse, deactivateResponse, depositReversalResponse, echeckCreditResponse, echeckSalesResponse, loadResponse, loadReversalResponse, refundReversalResponse, saleResponse, unloadResponse, unloadReversalResponse, voidResponse, queryTransactionUnavailableResponse Example: results_Max10 Element with One Found Transaction 82827170811986124 150330_GCAuth 000 responseTime>2015-04-06T16:40:04 2015-04-06 Approved 111115 30 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 707 cnpAPI Reference Guide cnpAPI Elements results_Max10 M 125 Example: results_Max10 Element with Multiple Found Transactions 82827170811986215 150331_DupeAuth2 000 2015-04-06T16:40:12 2015-04-06 Approved 055858 32 M 82827170811986207 150331_DupeAuth1 000 2015-04-06T16:40:11 2015-04-06 Approved 111111 00 M 708 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide results_Max10 cnpAPI Elements Example: results_Max10 Element for 152 Response Code 82827170811986124 152 Original transaction found but response not yet available Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 709 cnpAPI Reference Guide cnpAPI Elements RFRRequest 4.343 RFRRequest The RFRRequest element is an optional child of a litleRequest element. You can use this type of request in one of two ways. • • To request a session response from a previously processed litleRequest, include the litleSessionId child. The resulting RFR response will duplicate the original session response (Authorization, Credit, Capture, or Sale response) associated with the litleSessionId. The session ID returned in the response will be the session ID of the original session. To request an Account Updater completion response file, include the accountUpdateFileRequestData element. If the completion file is ready, it is returned. If the completion file is not ready, you receive an RFRResponse message with the response attribute set to 1 and the message attribute reading, “The account Update file is not ready yet. Please try again later.” Parent Elements: litleRequest Attributes: None Child Elements: (Choice of) litleSessionId or accountUpdateFileRequestData Example: RFRRequest Structure - Batch Session ID Example: RFRRequest Structure - Account Updater Merchant ID Post Date 710 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide RFRResponse cnpAPI Elements 4.344 RFRResponse The RFRResponse element is an optional child of a litleResponse element returned in response to a RFRRequest. Parent Elements: litleResponse Attributes: Attribute Name Type Required? Description response String Yes The RFR Response Code indicating the result of the RFR request. minLength = N/A maxLength = 3 message String Yes A brief definition of the response code returned for this transaction. minLength = N/A maxLength = 512 Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 711 cnpAPI Reference Guide cnpAPI Elements routingNum 4.345 routingNum The routingNum element is a required child of the echeck, originalAccountInfo, and newAccountInfo elements defining the routing number of the Echeck account. Type = String; minLength = 8; maxLength = 9 Parent Elements: echeck, newAccountInfo, originalAccountInfo, newTokenInfo, originalTokenInfo, accountInfo Attributes: None Child Elements: None NOTE: 712 If you submit an invalid routing number, we return the XML Response Code 900 - Invalid Bank Routing Number. Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide RxAmount cnpAPI Elements 4.346 RxAmount The RxAmount element is an optional child of the healthcareAmounts element and defines the healthcare amount used for the purchased medications. The decimal is implied. Example: 500 = $5.00. Type = Integer; totalDigits = 8 Parent Elements: Optional: healthcareAmounts Attributes: None Child Elements: None Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. 713 cnpAPI Reference Guide cnpAPI Elements sale 4.347 sale The sale element is the parent element for all Sale transactions. A Sale transaction is a combination Authorization and Capture transaction. You can use this element in either Online or Batch transactions. Parent Elements: litleOnlineRequest, batchRequest Attributes: Attribute Name Type Required? Description id String Yes A unique identifier assigned by the presenter and mirrored back in the response. minLength = 1 customerId String No maxLength = 36 A value assigned by the merchant to identify the consumer. minLength = N/A maxLength = 50 reportGroup String Yes Required attribute that defines the merchant sub-group in the user interface where this transaction will be displayed. Please refer to Coding for Report Groups on page 10 for additional information. minLength = 1 maxLength = 25 Child Elements: Required: orderId, amount, orderSource, (choice of) card, paypal, paypage, mpos, token, applepay, ideal, sepaDirectDebit, giropay, or sofort NOTE: The cardholderAuthentication child element is required only for 3-D Secure transactions and for BML ecommerce transactions. The fraudCheck element has been deprecated; use the cardholderAuthentication element instead. Optional: litleTxnId, customerInfo, billToAddress, shipToAddress, billMeLaterRequest, cardholderAuthentication, customBilling, taxType, enhancedData, processingInstructions, pos, payPalNotes, payPalOrderComplete, amexAggregatorData, allowPartialAuth, healthcareIIAS, merchantData, recyclingRequest, fraudFilterOverride, secondaryAmount, surchargeAmount, recurringRequest, litleInternalRecurringRequest, debtRepayment, advancedFraudChecks, wallet, processingType, origOrderId, password, originalNetworkTransactionId, originalTransactionAmount 714 Document Version: 1.8 — cnpAPI Release: 11.3 © 2017 Vantiv, LLC - All Rights Reserved. cnpAPI Reference Guide saleResponse cnpAPI