Title Page

Credit Card Services

Using the Simple Order API

January 2016

CyberSource Corporation HQ | P.O. Box 8999 | San Francisco, CA 94128-8999 | Phone: 800-530-9095

CyberSource Contact Information

For general information about our company, products, and services, go to
http://www.cybersource.com.
For sales questions about any CyberSource Service, email sales@cybersource.com or
call 650-432-7350 or 888-330-2300 (toll free in the United States).
For support information about any CyberSource Service, visit the Support Center at
http://www.cybersource.com/support.

Copyright
2016 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this
document and the software described in this document under the applicable agreement between the reader of
this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in
accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information
contained in this document is subject to change without notice and therefore should not be interpreted in any way
as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors
that may appear in this document. The copyrighted software that accompanies this document is licensed to You
for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the
software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this
document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical,
recording, or otherwise, without the prior written consent of CyberSource.

Restricted Rights Legends

For Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies
is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS
252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.
For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a)
through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set
forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights
reserved under the copyright laws of the United States.

Trademarks
CyberSource, The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager,
CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and eCheck.net are trademarks and/or
service marks of CyberSource Corporation. All other brands and product names are trademarks or registered
trademarks of their respective owners.

CONTENTS

Contents

Recent Revisions to This Document

About This Guide

Audience
Purpose

16

16
16

Conventions

16

Related Documentation

Chapter 1

12

17

Introduction to the Credit Card Services

Cards and Payment Methods 18
Discover Acquisitions and Alliances

18

19

Types of Transactions 20
Card-Present Transactions 20
Card-Not-Present Transactions 20
Transactions with Special Data 21
International Transactions 21
Compliance 21
Merchant Remittance Funding 22
Banks and Associations 22
Acquiring (Merchant) Banks 22
Issuing (Consumer) Banks 23
Payment Card Companies 24
Services

24

Order Tracking 25
Request IDs 25
Reconciliation IDs
Payment Processors

26
27

Credit Card Services Using the Simple Order API | January 2016

Contents

Chapter 2

Credit Card Processing

31

Authorizing a Payment 31
Online Authorizations 31
Offline Authorizations 33
Creating an Authorization Request 33
Authorization Information for Specific Processors
Reversing an Authorization 39
Authorization Reversal After Void 39
Supported Processors and Card Types 40
Creating a Full Authorization Reversal Request

35

48

Capturing an Authorization 49
Captures 49
Creating a Capture Request 50
Capture Information for Specific Processors 52
Special Capture Functionality 61
Automatic Partial Authorization Reversals 61
Interchange Optimization 62
Authorization Refresh 63
Performing a Sale

63

Crediting a Payment 64
Types of Credits 64
Creating a Credit Request 65
Credit Information for Specific Processors
Voiding a Capture or Credit 70
Authorization Reversal After Void
Capture After Void 71
Creating a Void Request 71

Credit Card Services Using the Simple Order API | January 2016

67

70

Contents

Chapter 3

Authorization Features

72

Address Verification System (AVS) 72

Standard AVS 72
Relaxed Requirements for Address Data and Expiration Date
Processing AVS Codes 76
Controlling AVS Results 76
Enhanced AVS 77
Automated Address Verification Plus (AAV+) 77
Electronic Verification (EV)
Request Fields 79
Reply Fields 80

75

78

Card Verification Numbers (CVNs) 80

CVN Locations and Terminology 82
CVN Codes 83
Verbal Authorizations

Chapter 4

84

Debit Cards and Prepaid Cards

88

Partial Authorizations 88
Supported Processors and Card Types 89
Opting In 90
How a Partial Authorization Works 90
Special Processing for American Express Cards on Chase Paymentech Solutions
Special Processing for IDR and CLP on FDMS South 92
Real-Time Reversals
Balance Responses

92

93
94

Features for Maestro (UK Domestic) Cards

Unsupported Processors and Card Types

Credit Card Services Using the Simple Order API | January 2016

97
98

Contents

Chapter 5

Optional Features
$0 Authorizations

99

99

Additional Amounts 99
Shipping and Handling Fees
Taxes 100

100

Aggregator Support 100

Terminology 101
American Express Direct Aggregators 101
CyberSource through VisaNet Aggregators 104
FDC Nashville Global Aggregators 105
Airline Data

106

American Express SafeKey

106

Apple Pay 106

How Apple Pay Works 107
Processing Apple Pay Payments with CyberSource Credit Card Services
Optional Features for Apple Pay 108
Processor-Specific Information 108
Recurring Payments 109
Additional Information 109
Authorization Only
AVS Only

107

110

110

Balance Inquiries
Bill Me Later

110

111

Bill Payments with Visa

Card-Present Data

111

111

Card Type Indicators (CTIs)

Cash Advances

112

113

Customer Profiles

113

Dynamic Currency Conversion for First Data

Requirements and Limitations 114
Terminology 115
Using DCC 116
Additional Information 119
Encoded Account Numbers

119

Final Authorization Indicator

120

Forced Captures

121

Guaranteed Exchange Rates

Installment Payments

Level II Data

122

123

Japanese Payment Options

JCB J/Secure

114

128

129
130

Credit Card Services Using the Simple Order API | January 2016

Contents

Level III Data

130

MasterCard SecureCode
MasterPass

130

130

Merchant Descriptors 131

AIBMS Merchant Descriptors 132
American Express Direct Merchant Descriptors 133
Chase Paymentech Solutions Merchant Descriptors 136
Merchant Descriptor Logic 136
Characters 137
API Fields 138
Cielo Merchant Descriptors 139
CyberSource through VisaNet Merchant Descriptors 140
Elavon Merchant Descriptors 146
FDC Compass Merchant Descriptors 147
Characters 148
API Fields 148
FDC Nashville Global Merchant Descriptors 151
Merchant Descriptor Logic 151
API Fields 153
FDMS South Merchant Descriptors 156
Global Collect Merchant Descriptors 157
GPN Merchant Descriptors 158
Litle Merchant Descriptors 159
OmniPay Direct Merchant Descriptors 162
OmniPay-Ireland Merchant Descriptors 164
Streamline Merchant Descriptors 166
TSYS Acquiring Solutions Merchant Descriptors 167
Merchant-Initiated Reversals and Voids
Micropayments

168

169

Multi-Currency Service
Network Tokenization
Partial Shipments

170
170

170

Payer Authentication 171

Verified by Visa 171
JCB J/Secure 177
MasterCard SecureCode 177
American Express SafeKey 183
Payment Network Tokenization
Payment Tokenization
POS Transactions
Quasi-Cash
Recipients

185

185

186

186
187

Recurring Billing

188

Credit Card Services Using the Simple Order API | January 2016

Contents

Recurring Payments 189

AVS and Recurring Payments 193
CVN and Recurring Payments 194
Replacement Expiration Dates for Recurring Payments
Recurring Profiles
Report Groups

194

197

197

Retail POS Data

198

Secure Data

198

Service Fees

199

Soft Descriptors

199

Split Dial/Route

199

Split Shipments 199

Benefits of Using Split Shipments 200
Requirements 200
How Split Shipments Work 200
Additional Authorizations 200
Additional Captures 201
Split Shipment Scenarios 201
One Authorization and One Sale 201
One Authorization and Two Captures 202
Multiple Captures in a Batch File 203
Two Authorizations and One Capture 203
Obtaining the Status of a System-Generated Authorization
Additional Information 205
Subscriptions
Tokenization

205
206

Type II Cards

206

Verbal Authorizations
Verified by Visa

206

206

Visa Bill Payments

Visa Checkout

207

207

Visa Debt Repayments

208

Zero Amount Authorizations

Chapter 6

205

209

Testing the Credit Card Services

Requirements for Testing
Testing the Services

213

213

214

Using Amounts to Simulate Errors

214

Testing American Express Card Verification

Credit Card Services Using the Simple Order API | January 2016

215

Contents

Appendix A API Fields

216

Formatting Restrictions
Data Type Definitions
Request Fields
Reply Fields

Appendix B Examples

216
216

217

283

303

Name-Value Pair Examples 303

Basic Credit Card Examples 303
Apple Pay Examples 305
Asia, Middle East, and Africa Gateway Examples 306
Cielo Examples 307
CyberSource Latin American Processing Examples 310
Partial Authorization Examples 311
Fully Approved Request 311
Partially Approved Request 312
Split Shipment Examples 313
One Authorization and One Sale 313
One Authorization and Two Captures 315
Two Authorizations and One Capture 317
Visa Checkout Examples 319
XML Examples 320
Basic Credit Card Examples 320
Apple Pay Examples 323
Asia, Middle East, and Africa Gateway Examples 325
Cielo Examples 327
CyberSource Latin American Processing Examples 332
Partial Authorization Examples 334
Fully Approved Request 334
Partially Approved Request 336
Split Shipment Examples 338
One Authorization and One Sale 338
One Authorization and Two Captures 342
Two Authorizations and One Capture 345
Visa Checkout Examples 349

Credit Card Services Using the Simple Order API | January 2016

Contents

Appendix C Additional Amount Types

351

Appendix D American Express SafeKey Response Codes

Appendix E

AVS Codes

355

AVS Codes for CyberSource Latin American Processing

AVS Codes for All Other Processors

Appendix F

Commerce Indicators

Appendix G CVN Codes

355

356

359

360

Appendix H CyberSource through VisaNet Acquirers

361

Appendix I

Electronic Verification Response Codes

365

Appendix J

Frequently Asked Questions

366

Appendix K Global Collect Credit Card Reversals

Requests for Information
Chargebacks

354

369

369

370

Representments

371

Chargeback Reason Codes for Visa

372

Chargeback Reason Codes for MasterCard

Request for Information Example

373

374

Credit Card Services Using the Simple Order API | January 2016

10

Contents

Appendix L

Network Transaction Identifiers

Appendix M Product Codes

Appendix N Product IDs

Visa Product IDs

378

379
379

MasterCard Product IDs

Appendix O Reason Codes

Appendix P

380

384

Verified by Visa Response Codes

Appendix Q Values for the Wallet Type Field

Index

376

388

389

390

Credit Card Services Using the Simple Order API | January 2016

11

REVISIONS

Recent Revisions to This

Document

Release

Changes

January 2016

American Express Direct: added support for relaxed requirements for expiration dates. See
"Relaxed Requirements for Address Data and Expiration Date," page 75.
Barclays:

Added support for enhanced response codes. See the entry for Barclays in Table 10,
"Authorization Information for Specific Processors," on page 35.

Added support for multiple captures. See the entry for Barclays in Table 12, "Capture
Information for Specific Processors," on page 52.

Chase Paymentech Solutions:

Added support for relaxed requirements for expiration dates. See "Relaxed Requirements for
Address Data and Expiration Date," page 75.

Added information about MasterPass. See "MasterPass," page 130.

CyberSource through VisaNet:

Added support for "Relaxed Requirements for Address Data and Expiration Date," page 75.

Added information about MasterPass. See "MasterPass," page 130.

Elavon: added support for "Relaxed Requirements for Address Data and Expiration Date,"
page 75.
FDC Compass: added support for relaxed requirements for expiration dates. See "Relaxed
Requirements for Address Data and Expiration Date," page 75.
FDC Nashville Global:

Added support for aggregators. See "Aggregator Support," page 100.

Added support for relaxed requirements for expiration dates. See "Relaxed Requirements for
Address Data and Expiration Date," page 75.

FDI Australia: added support for "Relaxed Requirements for Address Data and Expiration Date,"
page 75.
FDMS South: added support for relaxed requirements for expiration dates. See "Relaxed
Requirements for Address Data and Expiration Date," page 75.
Global Collect: added support for "Relaxed Requirements for Address Data and Expiration Date,"
page 75.
GPN: added support for "Relaxed Requirements for Address Data and Expiration Date," page 75.

Credit Card Services Using the Simple Order API | January 2016

12

Recent Revisions to This Document

Release

Changes

January 2016
(continued)

OmniPay Direct:

December 2015

Added support for the ccCaptureService_sequence and ccCaptureService_totalCount

fields for multiple captures. See the information about OmniPay Direct in Table 12, "Capture
Information for Specific Processors," on page 52.

Added support for "Relaxed Requirements for Address Data and Expiration Date," page 75.

Added support for "MasterPass," page 130.

Added support for "Recurring Payments," page 189.

Added support for recurring payments for Apple Pay transactions. See "Optional Features for
Apple Pay," page 108.

All processors that return product IDs: added new values to the tables in Appendix N, "Product
IDs," on page 379.
All processors that support the wallet_type field: updated the possible values in Appendix Q,
"Values for the Wallet Type Field," on page 389.
American Express Direct: added support for relaxed requirements for address data. See "Relaxed
Requirements for Address Data and Expiration Date," page 75.
Chase Paymentech Solutions:

Added support for "Merchant-Initiated Reversals and Voids," page 168.

Added support for relaxed requirements for address data. See "Relaxed Requirements for
Address Data and Expiration Date," page 75.

CyberSource through VisaNet: added support for "Forced Captures," page 121.
FDC Compass:

Updated information about multiple captures in Table 12, "Capture Information for Specific
Processors," on page 52.

Added support for relaxed requirements for address data. See "Relaxed Requirements for
Address Data and Expiration Date," page 75.

FDC Nashville Global:

Added support for "Authorization Reversal After Void," page 39.

Added support for "Merchant-Initiated Reversals and Voids," page 168.

Added support for relaxed requirements for address data. See "Relaxed Requirements for
Address Data and Expiration Date," page 75.

FDMS Nashville: added support for "Authorization Reversal After Void," page 39.
FDMS South:

Added support for "Authorization Reversal After Void," page 39.

Added support for relaxed requirements for address data. See "Relaxed Requirements for
Address Data and Expiration Date," page 75.

GPN: added support for "Authorization Reversal After Void," page 39.
Litle: updated maximum length for billTo_firstName, billTo_lastName, shipTo_firstName, and
shipTo_lastName. See Table 58, "Request Fields," on page 217.
Moneris: added support for "Apple Pay," page 106.

Credit Card Services Using the Simple Order API | January 2016

13

Recent Revisions to This Document

Release

Changes

October 2015

Added information about a new processor named OmniPay Direct:

"Payment Processors," page 27

Chapter 3, "Authorization Features," on page 72

Chapter 5, "Optional Features," on page 99

All processors that support MasterCard Secure Code: updated the description for the UCAF
collection indicator. See Table 49, "Request Fields for MasterCard SecureCode," on page 180.
American Express Direct: added support for aggregators. See "Aggregator Support," page 100.
Chase Paymentech Solutions: added support for staged digital wallets and added new wallet type
value SDW for MasterPass transactions. See wallet_type in Table 58, "Request Fields," on
page 217.
CyberSource through VisaNet:

Added information about new acquirers. See Appendix H, "CyberSource through VisaNet
Acquirers," on page 361.

Added support for automatic authorization reversal after void. See "Authorization Reversal After
Void," page 39.

Added support for aggregators. See "Aggregator Support," page 100.

Added support for Colombian intra-country data. See nationalNetDomesticData in Table 58,
"Request Fields," on page 217.

Added support for Visa Checkout and added new wallet type value VCIND for Visa Checkout
transactions. See updated list of required fields in "Creating an Authorization Request,"
page 33, and see wallet_type in Table 58, "Request Fields," on page 217.

FDC Compass: added support for the ccCaptureService_sequence and ccCaptureService_

totalCount fields for multiple captures. See the entry for FDC Compass in Table 12, "Capture
Information for Specific Processors," on page 52.
September 2015

All processors: updated the endpoint information in "Requirements for Testing," page 213.
Santander: removed this processor.

August 2015

All processors that support AVS: added AVS code 5. See Appendix E, "AVS Codes," on page 355.
Global Collect: added requirements for the CAVV algorithm and PARes status fields. For Verified
by Visa and JCB J/Secure, see Table 48, "Request Fields for Verified by Visa and JCB J/Secure,"
on page 173. For MasterCard SecureCode, see Table 49, "Request Fields for MasterCard
SecureCode," on page 180.

Credit Card Services Using the Simple Order API | January 2016

14

Recent Revisions to This Document

Release

Changes

July 2015

All processors for which the authorization code is returned in the authorization reply message:
updated information about maximum length. See ccAuthReply_authorizationCode in Table 59,
"Reply Fields," on page 283.
All processors that support recurring payments: updated information about verifying new account
numbers for recurring payments. See "AVS and Recurring Payments," page 193.
American Express Direct, Chase Paymentech Solutions, FDC Compass, FDC Nashville Global,
and FDMS South: added support for relaxed AVS. See Table 15, "Processors That Support
Standard AVS," on page 72.
Atos: updated length of time before authorizations time out from six days to 5 days, 20 hours, and
30 minutes. See Table 10, "Authorization Information for Specific Processors," on page 35.
Barclays and Streamline: added information about enhanced authorization reversals to the entries
for these processors in Table 11, "Processors That Support Full Authorization Reversals," on
page 40.
CyberSource Latin American Processing: updated information about maximum length for first
name and last name. See billTo_firstName and billTo_lastName in Table 58, "Request Fields,"
on page 217.
FDC Nashville Global:

Updated information about balance response fields. See Table 21, "Processors Supported for
Balance Responses," on page 95.

Updated procedure for installment payments. See "Installment Payments," page 123.

LloydsTSB Cardnet: added support for payer authentication. See "Verified by Visa," page 171, and
"MasterCard SecureCode," page 177.
RBS WorldPay Atlanta: updated capture information to state that the reconciliation ID is not
returned for captures. See "Reconciliation IDs," page 26.
TSYS Acquiring Solutions:

Added support for Apple Pay. See "Apple Pay," page 106.

Added information about Electronic Verification for IP address field. See note about billTo_
ipAddress in "Electronic Verification (EV)," page 78.

Updated length for merchant descriptor contact field. See invoiceHeader_

merchantDescriptorContact in Table 46, "Merchant Descriptor Fields for TSYS Acquiring
Solutions," on page 167.

Credit Card Services Using the Simple Order API | January 2016

15

ABOUT GUIDE

About This Guide

Audience
This guide is written for application developers who want to use the CyberSource Simple
Order API to integrate credit card processing into their order management system.
Implementing the CyberSource credit card services requires software development skills.
You must write code that uses the API request and reply fields to integrate the credit card
services into your existing order management system.

Purpose
This guide describes tasks you must complete to integrate the credit card services into
your existing order management system.

Conventions
The following special statements are used in this document:
A Note contains helpful suggestions or references to material not contained in
this document.
Note

An Important statement contains information essential to successfully

completing a task or learning a concept.
Important

Credit Card Services Using the Simple Order API | January 2016

16

About This Guide

Warning

A Warning contains information or instructions, which, if not heeded, can result

in a security risk, irreversible loss of data, or significant cost in time or revenue
or both.

The following text conventions are used in this document:

Table 1

Text Conventions

Convention

Meaning

bold

Field and service names in text; for example:

Include the ccAuthService_run field.

italic

Titles of documents

monospace

XML elements

Code examples

Values for API fields; for example:

Set the ccAuthService_run field to true.

Related Documentation

Getting Started with CyberSource Advanced for the Simple Order API describes how
to get started using the Simple Order API. (PDF | HTML)

The Reporting Developer Guide describes how to download reports. (PDF | HTML)

The Secure Acceptance Silent Order POST Development Guide describes how to
create a Secure Acceptance Silent Order POST profile. (PDF | HTML)

The Secure Acceptance Web/Mobile Configuration Guide describes how to create a

Secure Acceptance Web/Mobile profile. (PDF | HTML)

Credit Card Services Using the Simple Order API | January 2016

17

CHAPTER

Introduction to the
Credit Card Services

Cards and Payment Methods

The credit card services can be used to process the types of cards and payment methods
in the following table.
Table 2

Cards and Payment Methods Processed with Credit Card Services

Card or
Payment
Method

Description

Credit cards

CyberSource can accept payments made with numerous types of credit

cards, including Visa, MasterCard, American Express, Discover,
Diners Club, and JCB.

Private label cards

Private label cards are credit cards that are issued by a private company
and can be used only at the issuing companys stores. If you are
interested in using CyberSource to process transactions for your
companys private label card, contact your CyberSource account
representative for information.

Debit cards and

prepaid cards

Prepaid cards, Visa-branded debit cards, and MasterCard-branded debit

cards can be processed with the credit card services. See Chapter 4,
"Debit Cards and Prepaid Cards," on page 88.

Quasi-cash

A quasi-cash transaction is a cash-like transaction for the sale of items

that are directly convertible to cash. See "Quasi-Cash," page 186.

Bill Me Later

Processing Bill Me Later transactions is covered in the Bill Me Later

Supplement to Credit Card Services Using the Simple Order API.

Note

You can process payments with PINless debit cards if your business is in one
of the acceptable merchant categories in which a card-not-present debit
transaction is low risk. These categories include educational institutions,
insurers, and utilities. Processing PINless debit cards is covered in PINless
Debit Card Services Using the Simple Order API.

Credit Card Services Using the Simple Order API | January 2016

18

Chapter 1

Introduction to the Credit Card Services

Discover Acquisitions and Alliances

Discover has acquired or entered into alliances with the payment card companies shown
in the following table.
Table 3

Discover Acquisitions and Alliances

Card Type

Description

China UnionPay
Alliance

In 2005, China UnionPay and Discover announced a strategic alliance

whereby China UnionPay cards would be routed to the Discover Network.
As a result of this alliance:

Diners Club
Acquisition

JCB (US Domestic)

Alliance

If you have been accepting Discover but not China UnionPay, you are
now able to accept and process China UnionPay cards that have been
reissued with Discover bank identification numbers (BINs).

If you have been accepting China UnionPay but not Discover, you are
now able to accept Discover cards.

In July 2008, Discover acquired Diners Club International whereby Diners

Club cards would be routed to the Discover Network starting October 16,
2009. As a result of this acquisition:

If you have been accepting Discover but not Diners Club, you are now
able to accept Diners Club cards.

If you have been accepting Diners Club but not Discover, you are now
able to accept Discover cards.

In December 2006, JCB and Discover announced a strategic alliance

whereby JCB cards would be routed to the Discover Network in the U.S.
and select U.S. Territories (Puerto Rico, Guam, U.S. Virgin Islands,
Northern Mariana Islands) that authorize, process, and fund in USD. As a
result of this alliance:

If you have been accepting Discover but not JCB, you are now able to
accept JCB cards.

If you have been accepting JCB but not Discover, you are now able to
accept Discover cards.

For some card types on some processors, the information in your CyberSource account
must include processor-issued IDs for these transactions to be processed successfully.
Call CyberSource Customer Support to update your account information.

Credit Card Services Using the Simple Order API | January 2016

19

Chapter 1

Introduction to the Credit Card Services

As a result of these acquisitions and alliances, the following card types are processed on
the Discover Network:

China UnionPay

Diners Club

Discover

JCB (US Domestic): For JCB cards, US Domestic means that the currency is USD
and your location is the U.S., Puerto Rico, Guam, U.S. Virgin Islands, or Northern
Mariana Islands.
Non-U.S. JCB transactions are still routed through JCB.
Note

Your processor takes care of routing your transactions; you do not need to do
any additional processing to route these card types to the Discover Network.
Note

Types of Transactions
Card-Present Transactions
When a customer uses a card that is physically present to make a purchase, the purchase
is known as a card-present transaction. This type of transaction typically occurs in a retail
environment. To process card-present transactions:

Use the credit card services described in this guide.

Provide card-present data as described in Card-Present Processing Using the Simple

Order API.

Card-Not-Present Transactions
When a customer provides a card number but you do not have access to the physical
card, the purchase is known as a card-not-present transaction. This type of transaction
typically occurs over the Internet or through a call center. To process card-not-present
transactions, use the credit card services described in this guide.

Credit Card Services Using the Simple Order API | January 2016

20

Chapter 1

Introduction to the Credit Card Services

Card-not-present transactions pose an additional level of risk to your business because

you cannot directly verify the customers identification. CyberSource offers features, such
as Address Verification System (AVS) and Card Verification Numbers (CVN), in the credit
card services that can reduce that risk by checking the validity of the customers
information and notifying you when discrepancies occur. For descriptions of AVS and
CVN, see Chapter 3, "Authorization Features," on page 72.

Transactions with Special Data

The credit card services can process these types of special data:

Airline data: see Airline Processing Using the Simple Order API.

Level II and Level III data: seeLevel II and Level III Processing Using the Simple Order
API.

Card-present data: see Card-Present Processing Using the Simple Order API.

International Transactions
Compliance
Accepting payments from a country other than your own requires that you observe the
processing rules and practices of the payment systems in that country. The following table
describes areas of compliance that have particular focus.

Table 4

Compliance for International Transactions

Area of Compliance

Description

Merchant account descriptor

requirements

The merchant account descriptor is a fixed text field that is

associated with a credit card account. The purpose of the
descriptor is to communicate merchant information to the
customer so that they can be reminded of the circumstances
that triggered the payment. Merchant descriptors reduce the
possibility of a chargeback. Accordingly, the merchant descriptor
displayed on the customers statement should be a close match
to the name on your web site. It is not good practice to
consolidate multiple web sites into a single credit card account
and use a generic descriptor that more-or-less covers all
offerings. For details about merchant descriptors, see "Merchant
Descriptors," page 131.

Credit Card Services Using the Simple Order API | January 2016

21

Chapter 1

Table 4

Introduction to the Credit Card Services

Compliance for International Transactions (Continued)

Area of Compliance

Description

Excessive chargebacks

You are responsible for maintaining good customer support,

rapid problem resolution, a high level of customer satisfaction,
and transaction management processes that minimize
fraudulent transactions. All of these are required to prevent an
excessive number of chargebacks. In the event that credit card
chargebacks become excessive, CyberSource can require you
to undertake business process changes to reduce chargebacks.
If the chargebacks are not reduced to a satisfactory level,
CyberSource can terminate the account.
If Global Collect is your processor, see Appendix K, "Global
Collect Credit Card Reversals," on page 369 for more
information about chargebacks.

Merchant Remittance Funding

In conjunction with processing international transactions, you can request that
CyberSource convert transaction proceeds to a currency other than the currency in which
the transaction took place for funding into an operating account. Currency conversion
uses a foreign exchange rate to calculate how much the transaction currency is worth in
terms of the funding currency. The foreign exchange rate might be explicitly stated as a
rate or implicitly stated as a transaction amount, and a funded amount and can vary from
day to day. The foreign exchange rate might also include a mark-up for the foreign
exchange risk, sales commissions, and handling costs.

Banks and Associations

In this document, the word processor can refer to a processor, acquirer, or
acquiring processor depending on your location.
Note

Acquiring (Merchant) Banks

An acquiring, or merchant, bank offers accounts to businesses that accept credit card
payments. Before you can accept payments, you must have a merchant bank account
from an acquiring bank. Your merchant bank account must be configured to process cardnot-present or mail order/telephone order (MOTO) transactions.

Note

Each acquiring bank has connections to a limited number of payment

processors. You must choose a payment processor that your acquiring bank
supports. See "Payment Processors," page 27.

Credit Card Services Using the Simple Order API | January 2016

22

Chapter 1

Introduction to the Credit Card Services

Expect to be charged the fees shown in the following table.

Table 5

Fees

Fee

Description

Discount rates

Your acquiring bank charges a fee and collects a percentage of every

transaction. The combination of the fee and the percentage is called the
discount rate. These charges can be bundled (combined into a single
charge) or unbundled (charged separately) depending on your acquiring
bank and other factors.

Interchange fees

Visa and MasterCard each have a base fee, called the interchange fee, for
each type of transaction. Your acquiring bank and processor can explain
how to minimize this fee.

Chargebacks

When customers dispute charges to their accounts, you can incur

chargebacks. A chargeback occurs when a charge on a customers
account is reversed. Your merchant bank removes the money from your
account and could charge you a fee for the chargeback.

You are responsible for maintaining:

Good customer support

Rapid problem resolution

A high level of customer satisfaction

Transaction management processes that minimize fraudulent transactions

The items in the preceding list are required to prevent an excessive number of credit card
chargebacks. In the event that credit card chargebacks become excessive, CyberSource
can require you to undertake business process changes to reduce chargebacks. If the
chargebacks are not reduced to a satisfactory level, CyberSource can terminate your
account.
If you receive a large number of chargebacks or if a large number of your transactions
involve fraud, your acquiring bank might increase your discount rate or revoke your
merchant bank account. Contact CyberSource for information about CyberSource
products that can help prevent fraud.

Issuing (Consumer) Banks

An issuing, or consumer, bank provides credit cards to and underwrites lines of credit for
consumers. The issuing bank provides monthly statements and collects payments. Issuing
banks must follow the rules of the payment card companies to which they belong.

Credit Card Services Using the Simple Order API | January 2016

23

Chapter 1

Introduction to the Credit Card Services

Payment Card Companies

Payment card companies manage communications between acquiring banks and issuing
banks. They also develop industry standards, support their brands, and establish fees for
acquiring banks.
Some payment card companies, such as Visa and MasterCard, are trade associations
that do not issue cards. Instead, issuing banks are members of these associations and
they issue cards under license from the associations.
Other card companies, such as Discover and American Express, act as the issuing banks
for their own cards. Before you use CyberSource to process cards from these companies,
you must sign agreements with the companies.

Services
The credit card services are:

Authorization: see "Authorizing a Payment," page 31.

Full authorization reversal: see "Reversing an Authorization," page 39.

Capture: see "Capturing an Authorization," page 49.

Credit: see "Crediting a Payment," page 64.

Void: see "Voiding a Capture or Credit," page 70. This service is not restricted to the
credit card services; it can also be used for other payment methods.

You can also request an authorization and capture together. See "Performing a Sale,"
page 63.

Note

The credit card services are also used to process Bill Me Later transactions.
See the Bill Me Later Supplement to Credit Card Services Using the Simple
Order API.

Credit Card Services Using the Simple Order API | January 2016

24

Chapter 1

Introduction to the Credit Card Services

Order Tracking
See Getting Started with CyberSource Advanced for the Simple Order API for information
about order tracking. This section provides the names of the API fields that are used for
order tracking for the credit card services.

Request IDs
For all CyberSource services, the request ID is returned in the reply messages in
requestID. The following table lists the fields for the request IDs in request messages.
Table 6

Fields for Request IDs in Request Messages

Service

Request ID Field

Authorization reversal

ccAuthReversalService_authRequestID

Capture

ccCaptureService_authRequestID

Credit

ccCreditService_captureRequestID

Void

voidService_voidRequestID

Credit Card Services Using the Simple Order API | January 2016

25

Chapter 1

Introduction to the Credit Card Services

Reconciliation IDs
The following table lists the fields for the reconciliation IDs, which are returned in the reply
messages.
Table 7

Fields for Reconciliation IDs

Service

Reconciliation ID Field

Notes

Authorization

ccAuthReply_reconciliationID

For authorization requests, the

reconciliation ID is returned only for
these processors:

American Express Direct

Asia, Middle East, and Africa

Gateway

Atos

BML Direct

Chase Paymentech Solutions

Cielo

CyberSource through VisaNet

FDC Compass

FDC Nashville Global

Litle

Moneris

Authorization
reversal

ccAuthReversalReply_
reconciliationID

For authorization reversal requests,

the reconciliation ID is returned only
for Moneris.

Capture

ccCaptureReply_reconciliationID

The reconciliation ID is returned for all

capture requests for all processors
except RBS WorldPay Atlanta.
When you perform multiple partial
captures for an authorization, each
reply includes a different reconciliation
ID for each capture request. To find
out whether your processor supports
multiple partial captures, see Table 12,
"Capture Information for Specific
Processors," on page 52.

Credit

ccCreditReply_reconciliationID

The reconciliation ID is returned for all

credit requests for all processors.

On CyberSource through VisaNet, the reconciliation ID is mapped to the

purchase identifier field which is sent to your acquirer.
Note

Credit Card Services Using the Simple Order API | January 2016

26

Chapter 1

Introduction to the Credit Card Services

CCS (CAFIS) does not support the reconciliation ID for any services.
Note

JCN Gateway does not support the reconciliation ID for any services.
Note

Payment Processors
In this document, the word processor can refer to processors, acquirers, or
acquiring processors depending on your location.
Note

Payment processors connect CyberSource servers with acquiring banks. Before you can
accept payments, you must register with a payment processor. Your acquiring bank might
require you to use a payment processor with which the bank has a business relationship.
CyberSource does not necessarily support all the features that are offered by each
processor. This guide describes the payment processing features supported by
CyberSource. The beginning of each feature description specifies which payment
processors support the feature.
Your processor provides you with unique identification numbers for your account. You
must provide these identification numbers to CyberSource Customer Support.
The following table lists the processors and corresponding card types that CyberSource
supports for the credit card services.
Only the card types explicitly listed here are supported.
Note

Credit Card Services Using the Simple Order API | January 2016

27

Chapter 1

Table 8

Introduction to the Credit Card Services

Payment Processors and Card Types

Payment Processor

Supported Card Types & Notes

AIBMS

Visa, MasterCard, Maestro (International),

Maestro (UK Domestic)

American Express Brighton

American Express
Depending on the country in which your business is located,
you might need to get special permission from American
Express before you can process transactions with American
Express Brighton. For more information, contact American
Express.

American Express Direct

American Express

Asia, Middle East, and Africa

Gateway

Visa, MasterCard, American Express, Diners Club, JCB

Atos

Visa, MasterCard, Diners Club, JCB, Carte Bleue,

Maestro (UK Domestic)

Barclays

Visa, MasterCard, JCB, Maestro (International),

Maestro (UK Domestic)
If you support Maestro (UK Domestic), you must also
support Maestro (International), and you must support
MasterCard SecureCode for both card types.
GBP currency only for JCB and Maestro (UK Domestic).

CCS (CAFIS)

Visa, MasterCard, American Express, Diners Club, JCB,

NICOS house card

Chase Paymentech Solutions

Visa, MasterCard, American Express, Discover, Diners Club,

JCB, Carte Blanche, Maestro (International)

Cielo

Visa, MasterCard, American Express, Discover, Diners Club,

JCB, Maestro (International), Elo, Aura, Visa Electron
The Visa Electron card type is processed the same way that
the Visa debit card is processed. Use card type value 001
(Visa) for Visa Electron.

Citibank India

For details about the Citibank India processor, contact your

CyberSource sales representative.

Credit Card Services Using the Simple Order API | January 2016

28

Chapter 1

Table 8

Introduction to the Credit Card Services

Payment Processors and Card Types (Continued)

Payment Processor

Supported Card Types & Notes

CyberSource Latin American

Processing

Not all card types are supported in all Latin American

countries. Contact CyberSource Customer Support for
details.
For some countries, you are required to submit the
authorization request and the capture request together in the
same message.

Note CyberSource Latin American Processing is the

CyberSource name for Braspag. CyberSource provides two
processors for Latin America: CyberSource Latin American
Processing (Braspag), which is supported in multiple Latin
American countries, and Cielo, which is supported in Brazil
only.
CyberSource through VisaNet

See Appendix H, "CyberSource through VisaNet Acquirers,"

on page 361 for the list of acquirers that are supported for
CyberSource through VisaNet and the card types supported
for each acquirer.
The Visa Electron card type is processed the same way that
the Visa debit card is processed. Use card type value 001
(Visa) for Visa Electron.

Elavon

Visa, MasterCard, Discover, Diners Club,

Maestro (UK Domestic), Maestro (International)

FDC Compass

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

FDC Germany

Visa, MasterCard, Maestro (UK Domestic),

Maestro (International)

FDC Nashville Global

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

FDI Australia

Visa, MasterCard, American Express, Diners Club, JCB

FDMS Nashville

Visa, MasterCard, American Express, Discover, Diners Club,

Carte Blanche, JCB

FDMS South

Visa, MasterCard, American Express, Discover, Diners Club,

JCB, Carte Blanche

Global Collect

Visa, MasterCard, American Express, JCB,

Maestro (UK Domestic), Delta, Visa Electron, Dankort, Carte
Bleue, Carta Si, Eurocard

GPN

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

GPN is the CyberSource name

for Global Payments, Inc.s East
processing platform.
HBoS

Visa, MasterCard, Maestro (UK Domestic),

Maestro (International)

Credit Card Services Using the Simple Order API | January 2016

29

Chapter 1

Table 8

Introduction to the Credit Card Services

Payment Processors and Card Types (Continued)

Payment Processor

Supported Card Types & Notes

HSBC

Visa, MasterCard, Maestro (UK Domestic),

Maestro (International)

HSBC is the CyberSource name

for HSBC U.K.
JCN Gateway

Visa, MasterCard, American Express, Diners Club, JCB,

NICOS house card, ORICO house card

Litle

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

Lloyds-OmniPay

Visa, MasterCard, Maestro (UK Domestic),

Maestro (International)

LloydsTSB Cardnet

Visa, MasterCard, Maestro (UK Domestic)

Lynk

Visa, MasterCard, American Express, Discover, Diners Club,

Carte Blanche, JCB

Moneris

Visa, MasterCard, American Express, Discover

OmniPay Direct

Visa, MasterCard, Maestro (International),

Maestro (UK Domestic)
The supported acquirer is Global Payments International
Acquiring.

OmniPay-Ireland

Visa, MasterCard

OmniPay-Ireland is the
CyberSource name for HSBC
International.
PayEase China Processing

Visa, MasterCard, American Express, JCB

The information in this guide does not apply to PayEase
China Processing. All information required for PayEase
China Processing is in the China Processing Implementation
Guide.

RBS WorldPay Atlanta

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

Streamline

Visa, MasterCard, JCB, Carte Bleue, Dankort,

Maestro (International), Maestro (UK Domestic)
For Maestro (International), SecureCode processing is
required.

TSYS Acquiring Solutions

Visa, MasterCard, American Express, Discover, Diners Club,

JCB, Carte Blanche

UATP

UATP

Credit Card Services Using the Simple Order API | January 2016

30

CHAPTER

Credit Card Processing

Authorizing a Payment
CyberSource supports authorizations for all processors.

Online Authorizations
Online authorization means that when you submit an order using a credit card, you
receive an immediate confirmation about the availability of the funds. If the funds are
available, the issuing bank reduces your customers open to buy, which is the amount of
credit available on the card. Most of the common credit cards are processed online. For
online authorizations, you typically start the process of order fulfillment soon after you
receive confirmation of the order.
Online authorizations expire with the issuing bank after a specific length of time if they
have not been captured and settled. Most authorizations expire within five to seven days.
The issuing bank sets the length of time.

Note

CyberSource is not informed by the issuing bank when an authorization

expires. By default, the authorization remains in the CyberSource system for 60
days after the authorization date, even after it expires with the issuing bank.

When an authorization expires with the issuing bank, your bank or processor might require
you to resubmit an authorization request and include a request for capture in the same
message.

Credit Card Services Using the Simple Order API | January 2016

31

Chapter 2

Credit Card Processing

The following figure shows the steps that occur when you request an online credit card
authorization.
Figure 1

Processing an Online Authorization

The customer places an order and provides the credit card number, the card
expiration date, and additional information about the card.

You send a request for authorization over a secure Internet connection. When the
customer buys a digitally delivered product or service, you can request both the
authorization and the capture at the same time. When the customer buys a physically
fulfilled product, do not request the capture until you ship the product.

CyberSource validates the order information then contacts your payment processor
and requests authorization.

The processor sends the transaction to the payment card company, which routes it to
the issuing bank for the customers credit card. Some card companies, including
Discover and American Express, act as their own issuing banks.

The issuing bank approves or declines the request.

Depending on the processor and card type, the issuing bank can use AVS to confirm
the billing address and CVN to verify that the customer has possession of the card.
See Chapter 3, "Authorization Features," on page 72.
For debit cards and prepaid cards, the issuing bank can approve a partial amount if
the balance on the card is less than the requested authorization amount and if the
transaction is enabled for partial authorization. For details about partial authorizations
and for a list of the processors and card types supported for partial authorizations, see
"Partial Authorizations," page 88.

Note

For a limited number of processors and card types, partial authorizations

and balance responses are supported for credit cards in addition to debit
cards and prepaid cards. See "Partial Authorizations," page 88, and
"Balance Responses," page 94.

CyberSource runs its own tests then tells you whether the authorization succeeded.

Credit Card Services Using the Simple Order API | January 2016

32

Chapter 2

Credit Card Processing

Offline Authorizations
Offline authorization means that when you submit an order using a credit card, you do not
know whether the funds are available until you capture the order and receive confirmation
of payment. You typically do not ship the goods until you receive this payment
confirmation. For offline credit cards, it usually takes five days longer to receive payment
confirmation than for online cards.

Creating an Authorization Request

Step 1

Set the ccAuthService_run field to true.

Step 2

Do not include any of these services in the request:

Full authorization reversal (ccAuthReversalService)

Credit (ccCreditService)

Services for other payment methods, such as electronic checks, PayPal, bank
transfers, and direct debits

Risk update (riskUpdateService)

Credit Card Services Using the Simple Order API | January 2016

33

Chapter 2

Step 3
Table 9

Credit Card Processing

Include the following required fields in the request:

Required Fields for ccAuthService

If You Are Using Apple Pay1

If You Are Using Visa

Checkout2

If You Are Not Using Apple Pay

or Visa Checkout

billTo_city8

ccAuthService_run

billTo_city8

billTo_country8

encryptedPayment_data

billTo_country8

billTo_email8

encryptedPayment_wrappedKey

billTo_email8

billTo_firstName8

merchantID

billTo_firstName8

billTo_lastName8

merchantReferenceCode

billTo_lastName8

billTo_postalCode3,8

paymentSolution

billTo_postalCode3,8

billTo_state3,8

purchaseTotals_currency

billTo_state3,8

billTo_street18

billTo_street18

ccAuthService_run

purchaseTotals_
grandTotalAmount4

card_accountNumber

vc_orderID

card_cardType6

card_expirationMonth8

encryptedPayment_data

7
wallet_type

encryptedPayment_descriptor

encryptedPayment_encoding

card_expirationYear8

merchantID

ccAuthService_run

merchantReferenceCode

merchantID

paymentSolution

merchantReferenceCode

purchaseTotals_
grandTotalAmount4,5

purchaseTotals_currency

purchaseTotals_
grandTotalAmount4

Important Do not include the

e-commerce indicator in your
authorization request.

1 See "Apple Pay," page 106.

2 See Getting Started with Visa Checkout.
3 Required only for transactions in the U.S. and Canada.
4 Either purchaseTotals_grandTotalAmount or item_#_unitPrice must be included in the request.
5 CyberSource sends this transaction amount to the processor, not the amount in the encrypted payment data.
6 Required for certain card types. CyberSource strongly recommends that you send the card type even if it is optional for your
processor. Omitting the card type can cause the transaction to be processed with the wrong card type.
7 Required only for Visa Checkout transactions on CyberSource through VisaNet.
8 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

See Appendix A, "API Fields," on page 216 for:

Step 4

Detailed descriptions of these required request fields

Optional request fields

Reply fields

If needed, modify the request to accommodate additional information for your processor.
See "Authorization Information for Specific Processors," page 35.

Credit Card Services Using the Simple Order API | January 2016

34

Chapter 2

Step 5

Credit Card Processing

Include authorization features in the request.

There are several authorization features that can be performed automatically depending
on the information included in your request. These features are described in Chapter 3,
"Authorization Features," on page 72.

Step 6

Include optional features in the request.

There are several optional features that you can include in your request. These features
are described in Chapter 5, "Optional Features," on page 99.

Authorization Information for Specific

Processors
The following table provides additional information about authorizations for specific
processors.
Table 10

Authorization Information for Specific Processors

Payment Processor

Authorization Information

American Express Direct

For USD, American Express Direct limits authorization and

capture amounts to $9,999,999.00. For other currencies, the
maximum amount depends on the currency. Contact American
Express for the maximum amounts for the currencies that you
are using. Regardless of exponent or currency, the maximum
number of digits for the amount value is 12 digits.

Asia, Middle East, and Africa

Gateway

The Asia, Middle East, and Africa Gateway limits authorization

and capture amounts to four bytes; therefore, the maximum
amount is 2147483647.
Certain acquirers that are connected to the Asia, Middle East,
and Africa Gateway require that an authorization be autocaptured. This means that an authorization always results in a
capture if the authorization is approved. If you use any of these
acquirers, you still must send CyberSource a capture request.
Contact your CyberSource Customer Support representative to
find out whether your acquirer uses delayed capture or auto
capture.

Atos

Atos limits authorization, capture, and credit amounts to 12

digits; therefore, the maximum amount is 999999999999.

Important Authorizations time out after 5 days, 20 hours, and

30 minutes. For Maestro (UK Domestic), when you submit a
capture request after 5 days, 20 hours, and 30 minutes, you
must reauthorize first. For all other card types, when you submit
a capture request after 5 days, 20 hours, and 30 minutes,
CyberSource tries to obtain a fresh authorization as described in
"Authorization Refresh," page 63.

Credit Card Services Using the Simple Order API | January 2016

35

Chapter 2

Table 10

Credit Card Processing

Authorization Information for Specific Processors (Continued)

Payment Processor

Authorization Information

Barclays

CyberSource rounds the amount to the correct number of

decimal places for the currency.
Barclays supports enhanced response codes in authorization
reply messages. Enhanced response codes provide detailed
information about declined transactions. Contact Barclays
customer support to have this capability enabled for your
Barclays account.

Credit Card Services Using the Simple Order API | January 2016

36

Chapter 2

Table 10

Credit Card Processing

Authorization Information for Specific Processors (Continued)

Payment Processor

Authorization Information

Cielo

Auto Capture and Standard Capture

Cielo supports standard captures and auto captures.
By default, your CyberSource account is configured to support
standard capture processing. When you contact Customer
Support to set up your account, you can request that the default
type of capture be auto capture instead of standard capture. To
override the default type of capture processing for a transaction,
include the ccAuthService_authType field in your request.
For auto capture on Cielo:

You must request the authorization and capture services

together. Settlement is performed on the processor side. No
settlement activity is performed by CyberSource.

The auth reversal service is not supported for auto capture

transactions.

The void service is not supported for auto capture

transactions.

For an Aura Card transaction, you must include authorization

type value AUTOCAPTURE.

Combo Cards
Some card types support two payment methods: they can be
processed as credit cards and debit cards. On Cielo:

The default payment method is credit card.

You can override the default payment method by including the

ccAuthService_overridePaymentMethod field, a flag that
indicates whether the card is being used as a credit card or
debit card, in the authorization request.

Debit Cards
For debit cards on Cielo:

You must request the authorization and capture services

together as an auto capture. See the Cielo auto capture
section for auto capture processing details.

You must include payer authentication data in the request for

cards that support it on the Cielo gateway. For a description
of payer authentication, see "Payer Authentication,"
page 171.

Some card types must always be processed as debit cards

and must be identified with the override payment method
field. Cards that must always be processed as debit cards
include:

Visa Electron

Maestro (International)

Credit Card Services Using the Simple Order API | January 2016

37

Chapter 2

Table 10

Credit Card Processing

Authorization Information for Specific Processors (Continued)

Payment Processor

Authorization Information

CyberSource Latin American

Processing

With CyberSource Latin American Processing, for some

countries you are required to submit the authorization request
and the capture request in the same message. For other
countries, you can submit the authorization and capture
requests separately. Contact CyberSource Customer Support
for each countrys requirements.
For transactions in Brazil, you must request the follow-on
capture within five days of the authorization request.

Note CyberSource Latin American Processing is the

CyberSource name for Braspag. CyberSource provides two
processors for Latin America: CyberSource Latin American
Processing (Braspag), which is supported in multiple Latin
American countries, and Cielo, which is supported in Brazil only.
CyberSource through
VisaNet

CyberSource through VisaNet limits authorization and capture

amounts to 12 digits; therefore, the maximum amount is
999999999999.

FDMS South

FDMS South no longer requires you to include all AVS data

fields in your requests. The only required AVS data fields are the
country code and postal code. All other AVS data fields are
optional even though they are marked as required in Table 58,
"Request Fields," on page 217. However, if you omit AVS data
fields that were previously required, you might experience an
increase in the number of declined transactions and
chargebacks. For additional information, contact your processor.
For the Indonesian rupiah (IDR) and Chilean peso (CLP)
currencies only:

Rounding occurs, which can cause a minor discrepancy that

consists of a maximum of one currency unit between the
amount you requested and the amount that is authorized.

When a transaction is enabled for partial authorization, you

must ensure that the requested amount does not include any
digits to the right of the decimal separator. For a description of
partial authorizations, see "Partial Authorizations," page 88.

Global Collect

For Carte Bleue, the authorization and capture amount must be

0.99 euros or more.

GPN

GPN limits the authorization, capture, and credit amounts to 10

digits.

Litle

Litle limits authorization and capture amounts to eight digits;

therefore, the maximum amount is 99999999.

Moneris

Moneris limits authorization and capture amounts to nine digits;

therefore, the maximum amount is 9999999.99.

Credit Card Services Using the Simple Order API | January 2016

38

Chapter 2

Table 10

Credit Card Processing

Authorization Information for Specific Processors (Continued)

Payment Processor

Authorization Information

RBS WorldPay Atlanta

RBS WorldPay Atlanta limits the authorization, capture, and

credit amounts to the equivalent of 999,999.99 USD.
Depending on the value you send, the decimal is either
truncated or appended. For example, if you send 1.123 the
decimal is truncated to 1.12. If you send 123 it is converted to
123.00.

Streamline

Streamline limits authorization and capture amounts to 11 digits;

therefore, the maximum amount is 999999999.99.

TSYS Acquiring Solutions

TSYS Acquiring Solutions limits authorization and capture

amounts to the equivalent of 99,999.99 USD. To process an
amount greater than this, contact TSYS Acquiring Solutions.

Reversing an Authorization
The full authorization reversal service releases the hold that the authorization placed on
the customers credit card funds. Use this service to reverse an unnecessary or undesired
authorization.

Note

Each issuing bank has its own rules for deciding whether a full authorization
reversal succeeds or fails. If your reversal fails, contact the issuing bank to find
out whether it is possible to reverse the authorization by alternate means.

Authorization Reversal After Void

On the following processors, you can reverse an authorization after you void the
associated capture:

American Express Direct

Barclays

Chase Paymentech Solutions

CyberSource through VisaNet

Note

On CyberSource through VisaNet, CyberSource supports automatic

authorization reversal after void (ARAV). Normally, you must send an
authorization reversal request after you void the associated capture. With
automatic ARAV, CyberSource automatically reverses the authorization
after you void the associated capture. To enable automatic ARAV, contact
CyberSource Customer Support to have your account configured for this
feature.

Credit Card Services Using the Simple Order API | January 2016

39

Chapter 2

FDC Compass

FDC Germany

FDC Nashville Global

FDMS Nashville

FDMS South

GPN

HBoS

Litle

Lloyds-OmniPay

LloydsTSB Cardnet

OmniPay Direct

Streamline

TSYS Acquiring Solutions

Credit Card Processing

For details about each processor, see Table 11, "Processors That Support Full
Authorization Reversals," on page 40.
On all other processors, you can use the full authorization reversal service only for an
authorization that has not been captured and settled.

Supported Processors and Card Types

The following table lists the processors that are supported for full authorization reversals.
For processors that support debit cards and prepaid cards, the full authorization reversal
service works for debit cards and prepaid cards in addition to credit cards.
Table 11

Processors That Support Full Authorization Reversals

Processor

Card Types and Notes

AIBMS

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information.

American Express Direct

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
American Express for more information.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.

Credit Card Services Using the Simple Order API | January 2016

40

Chapter 2

Table 11

Credit Card Processing

Processors That Support Full Authorization Reversals (Continued)

Processor

Card Types and Notes

Barclays

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information. CyberSource supports
enhanced authorization reversals on this processor;
therefore CyberSource sends the processor extra data in the
authorization reversal request. You do not need to process
or monitor the extra data.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.
CCS (CAFIS)

Visa, MasterCard, American Express, Diners Club, JCB.

Chase Paymentech Solutions

Full authorization reversals:

Are supported for Visa, MasterCard,

Maestro (International), Discover, and Diners Club.

Must occur within three days of the authorization.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds. For an authorization that
has multiple associated captures:

Cielo

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Visa, MasterCard, American Express.

Credit Card Services Using the Simple Order API | January 2016

41

Chapter 2

Table 11

Credit Card Processing

Processors That Support Full Authorization Reversals (Continued)

Processor

Card Types and Notes

CyberSource through VisaNet

Visa, MasterCard, American Express, Diners Club, JCB,

Discover.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds. In addition to supporting
authorization reversal after void (ARAV), CyberSource
supports automatic ARAV. Normally, you must send an
authorization reversal request after you void the associated
capture. With automatic ARAV, CyberSource automatically
reverses the authorization after you void the associated
capture. To enable automatic ARAV, contact CyberSource
Customer Support to have your account configured for this
feature.
Elavon

FDC Compass

Full authorization reversals:

Are supported for Visa, MasterCard, Discover, Diners

Club, Maestro (UK Domestic), Maestro (International).

Must occur before 10:00 PM GMT on the same business

day as the authorization.

Full authorization reversals:

Are supported for Visa, MasterCard, Discover, and Diners

Club.

Must occur within three days of the authorization.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds. For an authorization that
has multiple associated captures:

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Credit Card Services Using the Simple Order API | January 2016

42

Chapter 2

Table 11

Credit Card Processing

Processors That Support Full Authorization Reversals (Continued)

Processor

Card Types and Notes

FDC Germany

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.
FDC Nashville Global

Full authorization reversals are supported for Visa,

MasterCard, American Express, Discover, Diners Club, and
JCB (US Domestic).

Note For JCB cards, US Domestic means that the

currency is USD and your location is the U.S., Puerto Rico,
Guam, U.S. Virgin Islands, or Northern Mariana Islands.
Note For Discover, Diners Club, and JCB (US Domestic),
full authorization reversals are supported for USD
transactions only. There are no currency restrictions for full
authorization reversals for Visa, MasterCard, and American
Express.
Important You can reverse an authorization after you void
the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.
FDMS Nashville

Full authorization reversals are supported for Visa,

MasterCard, Discover, Diners Club, and JCB (US Domestic).

Note For JCB cards, US Domestic means that the

currency is USD and your location is the U.S., Puerto Rico,
Guam, U.S. Virgin Islands, or Northern Mariana Islands.
Important You can reverse an authorization after you void
the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.

Credit Card Services Using the Simple Order API | January 2016

43

Chapter 2

Table 11

Credit Card Processing

Processors That Support Full Authorization Reversals (Continued)

Processor

Card Types and Notes

FDMS South

Full authorization reversals:

Are supported for Visa, MasterCard, Discover, and

JCB (US Domestic).

Note For JCB cards, US Domestic means that the

currency is USD and your location is the U.S., Puerto
Rico, Guam, U.S. Virgin Islands, or Northern Mariana
Islands.

Are supported only for transactions that do not go through

a currency conversion.

Are supported for the following types of merchants and

currencies:

Merchants located in the U.S. who authorize, settle,

and fund in U.S. dollars.

Merchants located in Canada who authorize, settle,

and fund in Canadian dollars.

Merchants located in Latin America or the Caribbean

who authorize, settle, and fund in U.S. dollars.

Merchants located in Europe who authorize, settle, and

fund in the currency for the country in which the
merchant is located.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.
GPN

Full authorization reversals are supported for Visa,

MasterCard, Discover, Diners Club, and JCB.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds. For an authorization that
has multiple associated captures:

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Credit Card Services Using the Simple Order API | January 2016

44

Chapter 2

Table 11

Credit Card Processing

Processors That Support Full Authorization Reversals (Continued)

Processor

Card Types and Notes

HBoS

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.
JCN Gateway

Visa, MasterCard, American Express, Diners Club, JCB,

NICOS house card, ORICO house card.

Litle

Full authorization reversals are supported for Visa,

MasterCard, Discover, Diners Club, and JCB.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds. For an authorization that
has multiple associated captures:

Lloyds-OmniPay

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.
LloydsTSB Cardnet

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.

Credit Card Services Using the Simple Order API | January 2016

45

Chapter 2

Table 11

Credit Card Processing

Processors That Support Full Authorization Reversals (Continued)

Processor

Card Types and Notes

Moneris

Full authorization reversals are supported for Visa,

MasterCard, American Express, and Discover.

OmniPay Direct

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds. For an authorization that
has multiple associated captures:

RBS WorldPay Atlanta

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Full authorization reversals are supported for Visa,

MasterCard, American Express, and Discover.

Credit Card Services Using the Simple Order API | January 2016

46

Chapter 2

Table 11

Credit Card Processing

Processors That Support Full Authorization Reversals (Continued)

Processor

Card Types and Notes

Streamline

You are responsible for complying with the processors

specific requirements for full authorization reversals. Contact
the processor for more information. CyberSource supports
enhanced authorization reversals on this processor;
therefore, CyberSource sends the processor extra data in
the authorization reversal request. You do not need to
process or monitor the extra data.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds.
TSYS Acquiring Solutions

Full authorization reversals are supported for Visa,

MasterCard, American Express, Discover, Diners Club, and
JCB.

Important You can reverse an authorization after you void

the associated capture. This functionality enables you to
meet the Visa mandate requirements to reverse unused
authorizations and benefits the cardholder by releasing the
hold on unused credit card funds. For an authorization that
has multiple associated captures:

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Credit Card Services Using the Simple Order API | January 2016

47

Chapter 2

Credit Card Processing

Creating a Full Authorization Reversal

Request
Step 1

Set the ccAuthReversalService_run field to true.

Step 2

Send the request ID value in the ccAuthReversalService_authRequestID field.

A full authorization reversal is a follow-on transaction that uses the request ID returned
from a previous authorization. The request ID links the full authorization reversal to the
authorization. CyberSource uses the request ID to look up the customers billing and
account information from the original authorization, so you are not required to include
those fields in your full authorization reversal request.
For information about requesting a follow-on service, see Getting Started with
CyberSource Advanced for the Simple Order API.

Step 3

Do not include any other CyberSource services in the request.

Step 4

Include the following required fields in the request:

ccAuthReversalService_run

ccAuthReversalService_authRequestID

merchantID

merchantReferenceCode

paymentSolution: include this field only if you are using Visa Checkout.

purchaseTotals_currency

purchaseTotals_grandTotalAmount: either this field or item_#_unitPrice must be

included in the request.

vc_orderID: include this field only if you are using Visa Checkout.

See Appendix A, "API Fields," on page 216 for:

Step 5

Detailed descriptions of these required request fields

Optional request fields

Reply fields

Make sure the amount of the reversal is the same as the amount that was authorized:

You cannot partially reverse an authorization; you can reverse an authorization only
for its full amount.

When you use a debit card or prepaid card and only a partial amount was approved,
the amount of the reversal must be the amount that was authorized, not the amount
that was requested.

Credit Card Services Using the Simple Order API | January 2016

48

Chapter 2

Credit Card Processing

Capturing an Authorization
CyberSource supports captures for all processors.
When you are ready to fulfill a customers order and transfer funds from the customers
bank to your bank, capture the authorization for that order.
If you can fulfill only part of a customers order, do not capture the full amount of the
authorization. Capture only the cost of the items that you ship. When you ship the
remaining items, request a new authorization, then capture the new authorization.

Captures
Unlike authorizations, a capture does not happen in real time. All of the capture requests
for a day are placed in a batch file and sent to the processor. In most cases, the batch is
settled at night. It usually takes two to four days for your acquiring bank to deposit funds in
your merchant bank account.
The following figure shows the steps that occur when you request a capture or credit.
Figure 2

Processing a Capture or Credit

You send a request for capture or credit over a secure Internet connection.

CyberSource validates the order information then stores the capture or credit request
in a batch file.

After midnight, CyberSource sends the batch file to your payment processor.

The processor settles the capture or credit request and transfers funds to the
appropriate bank account.

Note

The processor does not notify CyberSource when a transaction is declined.

To ensure that all captures and credits are processed, reconcile your
systems reports with the reports from your processor. See Getting Started
with CyberSource Advanced for the Simple Order API for information about
reconciliation.

Credit Card Services Using the Simple Order API | January 2016

49

Chapter 2

Credit Card Processing

Due to the potential delay between authorization and capture, the authorization might
expire with the issuing bank before you request capture. Most authorizations expire within
five to seven days. If an authorization expires with the issuing bank before you request the
capture, your bank or processor might require you to resubmit an authorization request
and include a request for capture in the same message.

Note

CyberSource is not informed by the issuing bank when an authorization

expires. By default, the authorization remains in the CyberSource system for 60
days after the authorization date, even after it expires with the issuing bank.

Creating a Capture Request

Step 1

Set the ccCaptureService_run field to true.

Step 2

Send the request ID value in the ccCaptureService_authRequestID field.

A capture is a follow-on transaction that uses the request ID returned from a previous
authorization. The request ID links the capture to the authorization. CyberSource uses the
request ID to look up the customers billing and account information from the original
authorization, so you are not required to include those fields in your capture request.
For information about requesting a follow-on service, see Getting Started with
CyberSource Advanced for the Simple Order API.

Note

Step 3

For Atos, your request for a capture must also include the request token
returned from a previous authorization in addition to the request ID. Like the
request ID, the request token links the capture to the authorization. Send the
request token in the orderRequestToken field.

Do not include any of these services in the request:

Full authorization reversal (ccAuthReversalService)

Credit (ccCreditService)

Services for other payment methods, such as electronic checks, PayPal, bank
transfers, and direct debits

Risk update (riskUpdateService)

Advanced fraud screen (afsService)

Credit Card Services Using the Simple Order API | January 2016

50

Chapter 2

Step 4

Credit Card Processing

Include the following required fields in the request:

ccCaptureService_run

ccCaptureService_authRequestID: optional when ccAuthService and

ccCaptureService are in the same request

orderRequestToken: required only for Atos

merchantID

merchantReferenceCode

paymentSolution: include this field only if you are using Visa Checkout.

purchaseTotals_currency

purchaseTotals_grandTotalAmount: either this field or item_#_unitPrice must be

included in the request.

vc_orderID: include this field only if you are using Visa Checkout.

See Appendix A, "API Fields," on page 216 for:

Step 5

Detailed descriptions of these required request fields

Optional request fields

Reply fields

If needed, modify the request to accommodate additional information for your processor.
See Table 12, "Capture Information for Specific Processors," on page 52.
For Carte Bleue cards, your capture request cannot be for less than 0.99 euros.
Note

Step 6

Include optional features in the request.

There are several optional features that you can include in your request. These features
are described in Chapter 5, "Optional Features," on page 99.

Credit Card Services Using the Simple Order API | January 2016

51

Chapter 2

Credit Card Processing

Capture Information for Specific Processors

The following table provides additional information about captures for some processors.
Table 12

Capture Information for Specific Processors

Payment Processor

Capture Information

AIBMS

On AIBMS, you can request multiple partial captures for one

authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount.

American Express Direct

For USD, American Express Direct limits authorization and

capture amounts to $9,999,999.00. For other currencies, the
maximum amount depends on the currency. Contact American
Express for the maximum amounts for the currencies that you
are using. Regardless of exponent or currency, the maximum
number of digits for the amount value is 12 digits.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.
Asia, Middle East, and Africa
Gateway

On the Asia, Middle East, and Africa Gateway, you can request
multiple partial captures for one authorization. You must ensure
that the total amount for all captures does not exceed the
authorized amount.
The Asia, Middle East, and Africa Gateway limits authorization
and capture amounts to four bytes, which is 2147483647.
Certain acquirers that are connected to the Asia, Middle East,
and Africa Gateway require that an authorization be autocaptured. This means that an authorization always results in a
capture if the authorization is approved. If you use any of these
acquirers, you still must send CyberSource a capture request.
Contact your CyberSource Customer Support representative to
find out whether your acquirer uses delayed capture or auto
capture.

Atos

Atos limits authorization, capture, and credit amounts to 12

digits; therefore, the maximum amount is 999999999999.

Important Authorizations time out after 5 days, 20 hours, and

30 minutes. For Maestro (UK Domestic), when you submit a
capture request after 5 days, 20 hours, and 30 minutes, you
must reauthorize first. For all other card types, when you submit
a capture request after 5 days, 20 hours, and 30 minutes,
CyberSource tries to obtain a fresh authorization as described in
"Authorization Refresh," page 63.

Credit Card Services Using the Simple Order API | January 2016

52

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

Barclays

On Barclays, you can request multiple partial captures for one

authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount. You must
include the following fields in each capture request when you
are requesting multiple partial captures:

ccCaptureService_sequence

ccCaptureService_totalCount

If you do not know the total number of captures that you are
going to request, do the following:
1 Set the capture total count to an estimated value or 99 for all
capture requests except the final one.
2 For the final capture request, set the capture total count and
the capture sequence to the same value.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.
CCS (CAFIS)

On CCS (CAFIS), you can request multiple partial captures for

one authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount.

Chase Paymentech Solutions

On Chase Paymentech Solutions, you can request multiple

partial captures for one authorization. You must ensure that the
total amount for all captures does not exceed the authorized
amount.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds. For an authorization that has multiple
associated captures:

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Credit Card Services Using the Simple Order API | January 2016

53

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

Cielo

Cielo supports standard captures and auto captures.

By default, your CyberSource account is configured to support
standard capture processing. When you contact Customer
Support to set up your account, you can request that the default
type of capture be auto capture instead of standard capture. To
override the default type of capture processing for a transaction,
include the ccAuthService_authType field in your request.
For auto capture on Cielo:

CyberSource Latin American

Processing

You must request the authorization and capture services

together. Settlement is performed on the processor side. No
settlement activity is performed by CyberSource.

The auth reversal service is not supported for auto capture

transactions.

The void service is not supported for auto capture

transactions.

For an Aura Card transaction, you must include authorization

type value AUTOCAPTURE.

Payment card company rules generally specify that you must

not capture a payment until you have shipped the products to
the customer. However, with CyberSource Latin American
Processing, for some countries you are required to submit the
authorization request and the capture request together in the
same message. For other countries, you can submit the
authorization and capture requests separately. Contact
CyberSource Customer Support for each countrys
requirements. With CyberSource Latin American Processing, it
takes 31 days for the funds to be deposited in your merchant
bank account.
For transactions in Brazil:

You must request the follow-on capture within five days of the
authorization request.

The capture amount can be less than the authorization

amount.

You can request only one capture per authorization.

Note CyberSource Latin American Processing is the

CyberSource name for Braspag. CyberSource provides two
processors for Latin America: CyberSource Latin American
Processing (Braspag), which is supported in multiple Latin
American countries, and Cielo, which is supported in Brazil only.

Credit Card Services Using the Simple Order API | January 2016

54

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

CyberSource through
VisaNet

CyberSource through VisaNet limits authorization and capture

amounts to 12 digits; therefore, the maximum amount is
999999999999.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds. In addition to supporting authorization reversal
after void (ARAV), CyberSource supports automatic ARAV.
Normally, you must send an authorization reversal request after
you void the associated capture. With automatic ARAV,
CyberSource automatically reverses the authorization after you
void the associated capture. To enable automatic ARAV, contact
CyberSource Customer Support to have your account
configured for this feature.

Credit Card Services Using the Simple Order API | January 2016

55

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

FDC Compass

On FDC Compass, you can request multiple partial captures for

one authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount. To avoid a
downgrade for a Visa transaction, you must include the following
fields in each capture request when you are requesting multiple
partial captures. For other card types, CyberSource strongly
recommends that you include the following fields in each
capture request when you are requesting multiple partial
captures:

ccCaptureService_sequence

ccCaptureService_totalCount

If you do not know the total number of captures that you are
going to request, do the following:
1 Set the capture total count to an estimated value or 99 for all
capture requests except the final one.
2 For the final capture request, set the capture total count and
the capture sequence to the same value.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds. For an authorization that has multiple
associated captures:

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

FDC Germany

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

FDC Nashville Global

CyberSource always provides merchant descriptor information

to the processor for you for all capture and credit transactions.
See "Merchant Descriptors," page 131.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

Credit Card Services Using the Simple Order API | January 2016

56

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

FDMS Nashville

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

FDMS South

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

Global Collect

Captures for cards using Global Collect are not batched.

CyberSource submits these captures immediately to Global
Collect when they are received.
On Carte Bleue, the authorization and capture amount must be
0.99 euros or more.

GPN

On GPN, you can request multiple partial captures for one

authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount.
GPN limits the authorization, capture, and credit amounts to 10
digits.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds. For an authorization that has multiple
associated captures:

HSBC

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

On HSBC, you can request multiple partial captures for one

authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount.

Important This feature has restrictions. Contact CyberSource

Customer Support for details.
Note To enable multiple partial captures, contact CyberSource
Customer Support to have your account configured for this
feature.

Credit Card Services Using the Simple Order API | January 2016

57

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

HBoS

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

JCN Gateway

On JCN Gateway, you can request multiple partial captures for

one authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount.

Litle

On Litle, you can request multiple partial captures for one

authorization.
Litle limits authorization and capture amounts to eight digits;
therefore, the maximum amount is 99999999.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds. For an authorization that has multiple
associated captures:

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Lloyds-OmniPay

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

LloydsTSB Cardnet

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

Moneris

Moneris limits authorization and capture amounts to nine digits;

therefore, the maximum amount is 9999999.99.

Credit Card Services Using the Simple Order API | January 2016

58

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

OmniPay Direct

On OmniPay Direct, you can request multiple partial captures for

one authorization. You must ensure that the total amount for all
captures does not exceed the authorized amount. CyberSource
strongly recommends that you include the following fields in
each capture request when you are requesting multiple partial
captures:

ccCaptureService_sequence

ccCaptureService_totalCount

If you do not know the total number of captures that you are
going to request, do the following:
1 Set the capture total count to an estimated value or 99 for all
capture requests except the final one.
2 For the final capture request, set the capture total count and
the capture sequence to the same value.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds. For an authorization that has multiple
associated captures:

OmniPay-Ireland

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

On OmniPay-Ireland, you can request multiple partial captures

for one authorization. You must ensure that the total amount for
all captures does not exceed the authorized amount.

Important This feature has restrictions. Contact CyberSource

Customer Support for details.
Note To enable multiple partial captures, contact CyberSource
Customer Support to have your account configured for this
feature.
Streamline

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds.

Credit Card Services Using the Simple Order API | January 2016

59

Chapter 2

Table 12

Credit Card Processing

Capture Information for Specific Processors (Continued)

Payment Processor

Capture Information

TSYS Acquiring Solutions

On TSYS Acquiring Solutions, you can request multiple partial

captures for one authorization. You must ensure that the total
amount for all captures does not exceed the authorized amount.
Additionally, you must include the following fields in each
capture request when you are requesting multiple partial
captures:

ccCaptureService_sequence

ccCaptureService_totalCount

TSYS Acquiring Solutions limits authorization and capture

amounts to the equivalent of 99,999.99 USD. To process a
greater amount, contact TSYS Acquiring Solutions.

Important You can reverse an authorization after you void the

associated capture. This functionality enables you to meet the
Visa mandate requirements to reverse unused authorizations
and benefits the cardholder by releasing the hold on unused
credit card funds. For an authorization that has multiple
associated captures:

If you reverse the authorization, CyberSource declines

subsequent capture requests.

If you void only one of the multiple captures, CyberSource

declines subsequent authorization reversal requests.

If you void all of the multiple captures, you can reverse the
authorization.

Credit Card Services Using the Simple Order API | January 2016

60

Chapter 2

Credit Card Processing

Special Capture Functionality

Automatic Partial Authorization Reversals
Automatic partial authorization reversals are supported for the processors and card types
listed in the following table. In addition to being supported for credit cards, automatic
partial authorization reversals are also supported for:

Debit cards and prepaid cards: see Chapter 4, "Debit Cards and Prepaid Cards," on
page 88.

Quasi-cash: see "Quasi-Cash," page 186.

Table 13

Processors That Support Automatic Partial

Authorization Reversals

Processor

Card Types
Solutions1

Visa, MasterCard

CyberSource through VisaNet

Visa, MasterCard

FDC Compass1

Visa, MasterCard

FDC Nashville Global

Visa, MasterCard, Discover, Diners Club,

JCB (US Domestic)2

FDMS Nashville

Visa, MasterCard, Discover, Diners Club,

JCB (US Domestic)2

FDMS South

Visa, MasterCard, Discover, JCB (US Domestic)2

GPN

Visa: Automatic partial authorization reversal is performed

as part of interchange optimization, which is described in
"Interchange Optimization," page 62.

Litle

Visa1, MasterCard, Discover, Diners Club, JCB

OmniPay-Ireland

Visa

Chase Paymentech

OmniPay-Ireland is the
CyberSource name for HSBC
International.
TSYS Acquiring Solutions

Visa, MasterCard, Discover, Diners Club, JCB

1 The processor performs an automatic partial authorization reversal when there is an interchange benefit.
The processor does not allow CyberSource to perform this functionality.
2 For JCB cards, US Domestic means that the currency is USD and your location is the U.S., Puerto Rico,
Guam, U.S. Virgin Islands, or Northern Mariana Islands.

Credit Card Services Using the Simple Order API | January 2016

61

Chapter 2

Credit Card Processing

If the capture amount is less than the authorization amount, CyberSource automatically
performs a partial authorization reversal before it sends the capture request to the
processor. The results of a successful partial authorization reversal are:

The capture amount matches the new authorization amount at the payment card
company.

The hold on the unused credit card funds might be released. The issuing bank
decides whether or not to release the hold on unused funds.
Not all issuers act on a request for a partial authorization reversal.
Therefore CyberSource cannot guarantee that the funds will be released.
Note

Interchange Optimization
Processors:

CyberSource through VisaNet: Visa and MasterCard

Interchange optimization is not available for MasterCard transactions in the
IDR currency on CyberSource through VisaNet.
Important

GPN acquiring merchants: Visa

Interchange optimization helps you reduce your interchange fees. Interchange

optimization consists of:

Automatic authorization refresh: When the capture request occurs more than six days
after the date of the original authorization, CyberSource automatically obtains a fresh
authorization for the capture amount.

Automatic partial authorization reversal: If the capture does not need a fresh
authorization but the capture amount is less than the authorization amount,
CyberSource automatically performs a partial authorization reversal which releases
the hold on unused credit card funds and ensures that the settlement amount matches
the authorization amount.
Interchange optimization does not work for card-present transactions.
Note

To enable interchange optimization, contact CyberSource Customer Support to have your

account configured for this feature.

Credit Card Services Using the Simple Order API | January 2016

62

Chapter 2

Credit Card Processing

Authorization Refresh
CyberSource provides authorization refresh functionality to Atos merchants for all card
types except Maestro (UK Domestic).
When a capture request occurs more than 5 days, 20 hours, and 30 minutes after the date
of the original authorization, CyberSource tries to obtain a fresh authorization for the
capture amount by performing a system-generated authorization using the payment data
from the original authorization.
Payer authentication data and CVN data are not included in system-generated
authorizations. Regardless of whether or not you included payer authentication data in
your original authorization request, you will not receive payer authentication protection for
a system-generated authorization.
If the system-generated authorization is successful, CyberSource submits the capture
request with the information from the new authorization. If the system-generated
authorization is not successful, CyberSource submits the capture request with the
information from the original authorization.
The system-generated authorization is linked to the original authorization in the Business
Center and in reports. The subsequent capture is linked to both authorizations in the
Business Center and in reports through the request IDs as with any capture.

Performing a Sale
A sale is a bundled authorization and capture. You can use a sale instead of a separate
authorization and capture if there is no delay between taking a customers order and
shipping the goods. A sale is typically used for electronic goods and for services that you
can turn on immediately.
To perform a sale, request the authorization and capture services at the same time.
Include the request fields that are required for the authorization. No additional fields are
required for the capture.
If the authorization is successful, CyberSource processes the capture immediately and the
reply message includes results for the authorization and for the capture. If the
authorization is declined, CyberSource does not process the capture and the reply
message includes results only for the authorization.
For debit cards and prepaid cards, the issuing bank can approve a partial amount if the
balance on the card is less than the requested authorization amount and if the transaction
is enabled for partial authorization. When this happens, CyberSource does not process
the capture. However, you can submit a capture request for the approved amount. For
details about partial authorizations and for a list of the processors and card types
supported for partial authorizations, see "Partial Authorizations," page 88.

Credit Card Services Using the Simple Order API | January 2016

63

Chapter 2

Note

Credit Card Processing

For a limited number of processors and card types, partial authorizations are
supported for credit cards in addition to debit cards and prepaid cards. See
"Partial Authorizations," page 88.

For details about authorizations and captures, see "Authorizing a Payment," page 31, and
"Capturing an Authorization," page 49.

Crediting a Payment
CyberSource supports credits for all processors.
When your request for a credit is successful, the issuing bank for the credit card takes
money out of your merchant bank account and returns it to the customer. It usually takes
two to four days for your acquiring bank to transfer funds from your merchant bank
account.

Warning

Carefully control access to this service to prevent unauthorized credits. Do not

request this service directly from your customer interface. Instead, incorporate
this service as part of your customer service process.

Credit requests are batched in the same manner as captures. See "Captures," page 49.

Types of Credits
A follow-on credit is linked to a capture in the CyberSource system. You can request
multiple follow-on credits against a single capture. On CyberSource through VisaNet, you
must request a follow-on credit within 180 days of the authorization. For all other
processors, you must request a follow-on credit within 60 days of the authorization.

Note

Important

On Atos, your request for a follow-on credit must also include the request token
returned from a previous capture request in addition to the request ID. Like the
request ID, the request token links the follow-on credit to the capture. Send the
request token in the orderRequestToken field.

When you combine a request for a follow-on credit with a request for another
service, such as the tax calculation service, you must provide the customers
billing and account information.

Credit Card Services Using the Simple Order API | January 2016

64

Chapter 2

Credit Card Processing

A stand-alone credit is not linked to a capture. There is no time limit for requesting standalone credits. Instead of sending the request ID field in the credit request, the request
must include the fields for the customers billing and account information.
For stand-alone credits, CyberSource does not validate billTo_postalCode or
shipTo_postalCode.
Note

Creating a Credit Request

Step 1

Set the ccCreditService_run field to true.

Step 2

For a follow-on credit, send the request ID value in the ccCreditService_

captureRequestID field.
A follow-on credit uses the request ID returned from a previous capture to link the credit to
the capture. CyberSource uses the request ID to look up the customers billing and
account information from the original authorization, so you are not required to include
those fields in your credit request. To perform multiple partial follow-on credits, send the
same request ID in each follow-on credit request.
For information about requesting a follow-on service, see Getting Started with
CyberSource Advanced for the Simple Order API.

Step 3

Step 4

Do not include any of these services in the request:

Any other credit card services (ccAuthService, ccAuthReversalService, or

ccCaptureService)

Services for other payment methods, such as electronic checks, PayPal, bank
transfers, and direct debits

Risk update (riskUpdateService)

Include the following required fields in the request:

ccCreditService_run

merchantID

merchantReferenceCode

paymentSolution: include this field only if you are using Visa Checkout.

purchaseTotals_currency

purchaseTotals_grandTotalAmount: either this field or item_#_unitPrice must be

included in the request.

vc_orderID: include this field only if you are using Visa Checkout.

Credit Card Services Using the Simple Order API | January 2016

65

Chapter 2

Credit Card Processing

See Appendix A, "API Fields," on page 216 for:

Step 5

Detailed descriptions of these required request fields

Optional request fields

Reply fields

For a stand-alone credit, also include the following required fields:

billTo_city: optional if your CyberSource account is configured for relaxed

requirements for address data. See "Relaxed Requirements for Address Data and
Expiration Date," page 75.

billTo_country: optional if your CyberSource account is configured for relaxed

requirements for address data. See "Relaxed Requirements for Address Data and
Expiration Date," page 75.

billTo_email: optional if your CyberSource account is configured for relaxed

requirements for address data. See "Relaxed Requirements for Address Data and
Expiration Date," page 75.

billTo_firstName: optional if your CyberSource account is configured for relaxed

requirements for address data. See "Relaxed Requirements for Address Data and
Expiration Date," page 75.

billTo_lastName: optional if your CyberSource account is configured for relaxed

requirements for address data. See "Relaxed Requirements for Address Data and
Expiration Date," page 75.

billTo_postalCode: required only for transactions in the U.S. and Canada; optional if
your CyberSource account is configured for relaxed requirements for address data.
See "Relaxed Requirements for Address Data and Expiration Date," page 75.

billTo_state: required only for transactions in the U.S. and Canada; optional if your
CyberSource account is configured for relaxed requirements for address data. See
"Relaxed Requirements for Address Data and Expiration Date," page 75.

billTo_street1: required only for transactions in the U.S. and Canada; optional if your
CyberSource account is configured for relaxed requirements for address data. See
"Relaxed Requirements for Address Data and Expiration Date," page 75.

card_accountNumber

card_cardType: required for certain card types

CyberSource strongly recommends that you send the card type even if it is optional
for your processor. Omitting the card type can cause the transaction to be processed
with the wrong card type.

card_expirationMonth: optional if your CyberSource account is configured for relaxed

requirements for expiration date. See "Relaxed Requirements for Address Data and
Expiration Date," page 75.

card_expirationYear: optional if your CyberSource account is configured for relaxed

requirements for expiration date. See "Relaxed Requirements for Address Data and
Expiration Date," page 75.

Credit Card Services Using the Simple Order API | January 2016

66

Chapter 2

Credit Card Processing

Step 6

If needed, modify the request to accommodate additional information for your processor.
See "Credit Information for Specific Processors," page 67.

Step 7

Include optional features in the request. See Chapter 5, "Optional Features," on page 99.

Credit Information for Specific Processors

The following table provides additional information about credits for some processors.

Table 14

Credit Information for Specific Processors

Payment Processor

Credit Information

Atos

Atos supports only follow-on credits. Stand-alone credits are

not supported. The credit amount cannot exceed the capture
amount.
Atos limits authorization, capture, and credit amounts to 12
digits; therefore, the maximum amount is 999999999999.
A credit cannot be processed on the same day as the
capture that is being credited. You must wait until the day
after the capture before requesting a credit.

CCS (CAFIS)

CCS (CAFIS) supports stand-alone credits. However, when

a request for a stand-alone credit is made, most acquirers
make inquiries about the purpose of such a request.
CyberSource recommends using follow-on credits instead of
stand-alone credits whenever possible.

Cielo

Cielo does not support stand-alone credits.

CyberSource recommends that you do not submit a followon credit request on the same day as the capture that is
being credited.

CyberSource Latin American

Processing

CyberSource Latin American Processing supports only

follow-on credits. Stand-alone credits are not supported. The
60-day limit for follow-on credits does not apply to
CyberSource Latin American Processing: you can request a
follow-on credit more than 60 days after the original charge.
CyberSource Latin American Processing does not support
the credit service for Aura Card and Hipercard. You must
make manual refunds for these card types.

Note CyberSource Latin American Processing is the

CyberSource name for Braspag. CyberSource provides two
processors for Latin America: CyberSource Latin American
Processing (Braspag), which is supported in multiple Latin
American countries, and Cielo, which is supported in Brazil
only.

Credit Card Services Using the Simple Order API | January 2016

67

Chapter 2

Table 14

Credit Card Processing

Credit Information for Specific Processors (Continued)

Payment Processor

Credit Information

CyberSource through VisaNet

CyberSource through VisaNet supports only follow-on

credits. Stand-alone credits are not supported. CyberSource
recommends that you do not submit a follow-on credit
request on the same day as the capture that is being
credited.

FDC Nashville Global

CyberSource always provides information to the processor

for you for all capture and credit transactions. See "Merchant
Descriptors," page 131.

FDMS South

FDMS South no longer requires you to include all AVS data

fields in your requests. The only required AVS data fields are
the country code and postal code. All other AVS data fields
are optional even though they are marked as required in
Table 58, "Request Fields," on page 217. However, if you
omit AVS data fields that were previously required, you might
experience an increase in the number of declined
transactions and chargebacks. For additional information,
contact your processor.

Global Collect

With Global Collect, you can process only one follow-on

credit against a specific captured authorization each day. For
example, if you want to process a follow-on credit of 15.00
against an original capture of 50.00, and then later you want
to process a follow-on credit of 35.00 against the same
capture, you must request the two credits on two separate
days.
Before performing stand-alone credits with Global Collect,
you must contact CyberSource Customer Support.
Credits for cards using Global Collect are not batched.
CyberSource submits these captures immediately to Global
Collect when they are received.

GPN

GPN limits the authorization, capture, and credit amounts to

10 digits.

JCN Gateway

JCN Gateway supports stand-alone credits. However, when

a request for a stand-alone credit is made, most acquirers
make inquiries about the purpose of such a request.
CyberSource recommends using follow-on credits instead of
stand-alone credits whenever possible.

Credit Card Services Using the Simple Order API | January 2016

68

Chapter 2

Table 14

Credit Card Processing

Credit Information for Specific Processors (Continued)

Payment Processor

Credit Information

Litle

For a follow-on credit to be successfully processed, the

capture that is being credited must have been processed
successfully. To ensure that the capture is processed before
the follow-on credit request is received, do not batch the
follow-on credit on the same day as the capture.
If the capture has not been processed yet, CyberSource
sends this error message: The follow-on credit

cannot be processed because the capture

transaction has not been processed yet.
If the capture has been processed but was not successful,
CyberSource sends this error message: The follow-on

credit cannot be processed because the

capture transaction failed.
RBS WorldPay Atlanta

Follow-on refunds for verbal authorizations are not

supported. You must process these refunds as stand-alone
refunds.

Credit Card Services Using the Simple Order API | January 2016

69

Chapter 2

Credit Card Processing

Voiding a Capture or Credit

CyberSource supports voids for all processors except:

Atos

Global Collect

Lynk

Note

CyberSource Latin American Processing does not support voids for Aura Card
and Hipercard because transactions with these cards are captured
immediately.
CyberSource Latin American Processing is the CyberSource name for
Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil only.
The information in this note applies only to CyberSource Latin American
Processing (Braspag).

Cielo does not support voids for auto capture or debit transactions.
Note

A void cancels a capture or credit request that you submitted to CyberSource. A

transaction can be voided only when CyberSource has not already submitted the capture
or credit request to your processor. CyberSource usually submits capture and credit
requests to your processor once a day, so your window for successfully voiding a capture
or credit request is small. CyberSource declines your void request when the capture or
credit request has already been sent to the processor.
You cannot perform a follow-on credit for a transaction that has been voided.
You cannot undo a void.

Authorization Reversal After Void

When you void a capture, a hold remains on the unused credit card funds. If you are not
going to re-capture the authorization as described in "Capture After Void," page 71, and if
your processor supports authorization reversal after void as described in "Authorization
Reversal After Void," page 39, CyberSource recommends that you request an
authorization reversal to release the hold on the unused credit card funds.

Credit Card Services Using the Simple Order API | January 2016

70

Chapter 2

Credit Card Processing

Capture After Void

If your processor supports multiple captures, you can capture an authorization after you
void previous captures associated with the authorization. For example, you can perform
the following sequence:
1

Authorize a payment.

Capture the authorization.

Void the capture.

Capture the authorization again.

To find out if your processor supports multiple captures, see Table 12, "Capture
Information for Specific Processors," on page 52.
On all other processors, when you void a transaction the transaction is at the end of its life
and cannot be the source of another follow-on capture or credit. For example, if you
authorize and capture a transaction, and then you void the capture, you cannot submit
another capture request that uses the authorization code or CyberSource request ID from
the original authorization. If you still want to capture that transaction, you must
re-authorize the transaction and capture the new authorization.

Creating a Void Request

Step 1

Set the voidService_run field to true.

Step 2

Send the request ID value in the voidService_voidRequestID field.

A void is a follow-on transaction that uses the request ID returned from a capture or credit.
The request ID links the void to the service that is being voided. CyberSource uses the
request ID to look up the customers billing and account information from the capture or
credit, so you are not required to include those fields in your void request.
For information about requesting a follow-on service, see Getting Started with
CyberSource Advanced for the Simple Order API.

Step 3

Do not include any other CyberSource services in the request.

Step 4

Include the following required fields in the request:

voidService_run

voidService_voidRequestID

orderRequestToken: required only for Atos

merchantID

merchantReferenceCode

See Appendix A, "API Fields," on page 216 for:

Detailed descriptions of these required request fields

Reply fields

Credit Card Services Using the Simple Order API | January 2016

71

CHAPTER

Authorization Features

You must support the authorization features that your processor supports.

Address Verification System (AVS)

AVS is supported only for cards issued in the U.K., the U.S., and Canada.
Note

Standard AVS
The following table lists the processors and card types for which CyberSource returns
standard AVS results.

Table 15

Processors That Support Standard AVS

Processors

Credit Card Types

AIBMS

Visa, MasterCard, Maestro (International), Maestro (UK Domestic)

American Express
Brighton

American Express

American Express
Direct

American Express

Atos

Visa and MasterCard: The billing country must be Great Britain.

Barclays

Visa, MasterCard, Maestro (UK Domestic)

Chase Paymentech
Solutions

Visa, MasterCard, and American Express: The billing country must be

the U.S., Canada, or Great Britain.

You must contact CyberSource Customer Support to activate

standard AVS for American Express Brighton.

You must contact CyberSource Customer Support to activate

standard AVS for American Express Direct.

Discover, Diners Club, and JCB: The billing country must be the U.S.

Credit Card Services Using the Simple Order API | January 2016

72

Chapter 3

Table 15

Authorization Features

Processors That Support Standard AVS (Continued)

Processors

Credit Card Types

Cielo

Visa, MasterCard, American Express

Cielo can charge you additional fees for AVS processing. You must
contact Cielo and CyberSource Customer Support to activate
standard AVS for Cielo.
AVS is supported only for credit card transactions, not debit card
transactions.
Format for Raw AVS Codes
The raw AVS response code is a concatenation of two values:

The first value is the raw AVS code for the postal code.

The second value is the raw AVS code for the street address.

If Cielo returns only one of the values, the missing value is indicated
by a question mark (?). Examples:

CyberSource Latin
American Processing

?N indicates that the raw AVS code for the postal code is missing
and that the raw AVS code for the street address is N.

T? indicates that the raw AVS code for the postal code is T and that
the raw AVS code for the street address is missing.

Visa, MasterCard, American Express, Diners Club

In Brazil, AVS is supported only for Redecard. To perform AVS for
Redecard in Brazil, you must provide the CPF (Cadastro de Pessoas
Fisicas) and the building number.
For AVS in Mexico, contact CyberSource Customer Support to have
your account enabled for this feature.

Note CyberSource Latin American Processing is the CyberSource

name for Braspag. CyberSource provides two processors for Latin
America: CyberSource Latin American Processing (Braspag), which
is supported in multiple Latin American countries, and Cielo, which is
supported in Brazil only.
CyberSource through
VisaNet

Visa, MasterCard, American Express, Diners Club, JCB, Discover

Elavon

Visa, MasterCard, Discover, Diners Club, MasterCard,

Maestro (UK Domestic), Maestro (International)

Important When you populate billing street address 1 and billing

street address 2, CyberSource through VisaNet concatenates the two
values. If the concatenated value exceeds 40 characters,
CyberSource through VisaNet truncates the value at 40 characters
before sending it to Visa and the issuing bank. Truncating this value
affects AVS results and therefore might also affect risk decisions and
chargebacks.

Your country and the billing country must be Great Britain. The
currency must be British pounds.

Credit Card Services Using the Simple Order API | January 2016

73

Chapter 3

Table 15

Authorization Features

Processors That Support Standard AVS (Continued)

Processors

Credit Card Types

FDC Compass

Visa, MasterCard, and American Express: The billing country must be

the U.S., Canada, or Great Britain.
Discover and Diners Club: The billing country must be the U.S.

FDC Germany

Visa, MasterCard

FDC Nashville Global

Visa, MasterCard, American Express, Discover, Diners Club,

JCB (US Domestic)
For JCB cards, US Domestic means that the currency is USD and
your location is the U.S., Puerto Rico, Guam, U.S. Virgin Islands, or
Northern Mariana Islands.

FDMS Nashville

Visa, MasterCard, American Express, Discover, Diners Club,

JCB (US Domestic)
For JCB cards, US Domestic means that the currency is USD and
your location is the U.S., Puerto Rico, Guam, U.S. Virgin Islands, or
Northern Mariana Islands.

FDMS South

Visa, MasterCard, American Express, Discover, Diners Club,

JCB (US Domestic)
For JCB cards, US Domestic means that the currency is USD and
your location is the U.S., Puerto Rico, Guam, U.S. Virgin Islands, or
Northern Mariana Islands.

GPN

Visa, MasterCard, American Express, Discover, Diners Club, JCB

HBoS

Visa, MasterCard

HSBC

Visa, MasterCard, Maestro (UK Domestic), Maestro (International)

HSBC is the
CyberSource name for
HSBC U.K.
Litle

Visa, MasterCard, American Express, Discover, Diners Club, JCB

Lloyds-OmniPay

Visa, MasterCard

LloydsTSB Cardnet

Visa, MasterCard

Lynk

Visa, MasterCard, American Express, Discover, Diners Club

Moneris

Visa, MasterCard, Discover

OmniPay Direct

Visa, MasterCard, Maestro (UK Domestic), Maestro (International)

OmniPay-Ireland

Visa, MasterCard

OmniPay-Ireland is the
CyberSource name for
HSBC International.
RBS WorldPay Atlanta

Visa, MasterCard, American Express, Discover, Diners Club

Streamline

Visa, MasterCard, Maestro (UK Domestic), Carte Bleue, Dankort

You must contact Streamline to activate standard AVS.

TSYS Acquiring
Solutions

Visa, MasterCard, American Express, Diners Club: The billing country

must be the U.S.

Credit Card Services Using the Simple Order API | January 2016

74

Chapter 3

Authorization Features

Relaxed Requirements for Address Data and Expiration

Date
Services:

Authorization

Stand-alone credit

Processors:

American Express Direct

Chase Paymentech Solutions

CyberSource through VisaNet

Elavon

FDC Compass

FDC Nashville Global

FDI Australia

FDMS South

Global Collect

GPN

OmniPay Direct

To enable relaxed requirements for address data and expiration date, contact
CyberSource Customer Support to have your account configured for this feature.
Historically, this data was mandated by CyberSource. With the advent of digital payments
and an increasingly global e-commerce environment, CyberSource decided to relax the
requirements for address data and expiration date.
Relaxed requirements for address data and expiration date make the following fields
optional for payment processing:

billTo_city

billTo_country

billTo_email

billTo_firstname

billTo_lastname

billTo_postalCode

billTo_state

billTo_street1

card_expirationMonth

card_expirationYear

Credit Card Services Using the Simple Order API | January 2016

75

Chapter 3

Important

Authorization Features

When relaxed requirements for address data and expiration date are enabled
for your CyberSource account, and your service request does not include one
or more of the fields in the preceding list, you increase the risk of declined
transactions and fraud depending on your location, your processor, and the
cardholder's issuing bank.
It is your responsibility to determine whether a field is required for the
transaction you are requesting. For example, effective October 2014, an
issuing bank can decline an authorization request for a recurring transaction
with a Visa Europe card if the expiration date is incorrect, invalid, or missing. If
you do not provide the correct expiration date for a recurring transaction the
authorization request may be declined.

Processing AVS Codes

When a processor supports AVS for a transactions card type, the issuing bank uses AVS
to confirm that the customer has provided the correct billing address. When a customer
provides incorrect information, the transaction might be fraudulent.
AVS occurs automatically with every authorization request. The authorization reply
includes the ccAuthReply_avsCode field, which contains the AVS code from the issuing
bank that indicates whether AVS matched the address and whether the address match
was partial or complete. See Appendix E, "AVS Codes," on page 355.
When AVS cannot verify the address, but the authorization is otherwise valid, you might
receive an AVS decline. You can capture authorizations that receive an AVS decline.
However, you must review these orders to ensure that they are legitimate. Settling
authorizations that fail the AVS check might have an impact on the fees charged by your
bank. Contact your bank for details about how AVS management might affect your
discount rate.
The ccAuthReply_avsCodeRaw field is the raw AVS code sent directly from the
processor. Do not use this value to handle the AVS response. Use the value only for
debugging purposes.

Controlling AVS Results

By default, only the AVS code N results in an AVS decline. You can change this behavior
by using the businessRules_declineAVSFlags field to specify a list of AVS codes that
should result in an AVS decline.
When you use businessRules_declineAVSFlags, you must include the value
N in the list if you want to receive declines for the AVS code N.
Important

Credit Card Services Using the Simple Order API | January 2016

76

Chapter 3

Authorization Features

When your request includes the businessRules_ignoreAVSResult field set to true, you
receive no AVS declines, even when you use businessRules_declineAVSFlags.

Enhanced AVS
Processor:

American Express Direct

You must contact CyberSource Customer Support and American Express
to register for Enhanced AVS.
Note

Card type:

American Express

Enhanced AVS consists of the standard AVS functionality plus verification of some
additional fields. The additional fields that are verified for Enhanced AVS are:

billTo_firstName

billTo_lastName

Automated Address Verification Plus (AAV+)

Processor:

American Express Direct

You must contact CyberSource Customer Support and American Express
to register for AAV+.
Note

Card type:

American Express

AAV+ consists of the Enhanced AVS functionality plus verification of some additional
fields. This service is intended for merchants who deliver physical goods to a different
address than the billing address. AAV+ verifies the additional fields only when the
standard and Enhanced AVS tests pass first.

Credit Card Services Using the Simple Order API | January 2016

77

Chapter 3

Authorization Features

The additional fields that are verified for AAV+ are:

shipTo_firstName

shipTo_lastName

shipTo_street1

shipTo_country

shipTo_postalCode

shipTo_phoneNumber

billTo_phoneNumber: American Express Direct only

Note

For American Express Direct, when your account is enabled for AAV+ and
when you include the first name, last name, and phone number in your request
message, the reply message includes EV response codes for those fields. See
"Electronic Verification (EV)," page 78.

Electronic Verification (EV)

Processors:

American Express Direct

FDC Nashville Global

Litle: For EV, Litle verifies only the email address, first name, last name, and phone
number.
If Litle is your processor, you must contact Litle to register for EV.
Note

TSYS Acquiring Solutions

Card types:

American Express

Discoveronly on TSYS Acquiring Solutions. Only the first name and last name are
checked.

EV confirms the customers billing information. When a customer provides incorrect

information, the transaction might be fraudulent.

Credit Card Services Using the Simple Order API | January 2016

78

Chapter 3

Authorization Features

As part of EV for Litle and TSYS Acquiring Solutions, you can provide the IP
address in the billTo_ipAddress field. When you provide the IP address,
American Express does not send a response for it. Instead, American Express
uses the IP address to run a check in their internal database to ensure that the
IP address does not match previously fraudulent transactions with the same IP
address and is not from countries that American Express has determined to be
a high risk for fraud. If, based on the IP address, American Express determines
that the transaction is fraudulent or is a high risk for fraud, American Express
declines the transaction.

Note

Request Fields
To receive an EV response code for a particular value, you must include that value in your
authorization request. Table 16, "Request Fields for Electronic Verification," on page 79
lists the request fields for each value that EV can verify. In the table, the R/O column
indicates whether the field is required or optional for the authorization service.
Some merchants use placeholder data for some required fields, such as
addresses and phone numbers, because their customers do not provide them
with the required information. The benefit of using certain specific placeholder
values is that Decision Manager ignores the values instead of attempting to
process them. However, when you use placeholder data in any of the fields that
are used for EV, the corresponding EV results are invalid.

Note

Table 16

Request Fields for Electronic Verification

Value That Is
Being Verified

R/O for
Authorizations

Request Field

Email

billTo_email

billTo_firstName

billTo_lastName

billTo_phoneNumber

Postal code

R/O1

billTo_postalCode

Street address

billTo_street1

First name2
2

Last name

Phone number

1 Required when the billing country is the U.S. or Canada; otherwise, optional.
2 On American Express Direct, to receive EV response codes for the first name,
last name, and phone number, your account must be enabled for AAV+. See
"Automated Address Verification Plus (AAV+)," page 77.

Credit Card Services Using the Simple Order API | January 2016

79

Chapter 3

Authorization Features

Reply Fields
For each verified value, EV returns a raw response code and a mapped response code:

The raw response code is the value returned by the processor.

The mapped response code is the pre-defined CyberSource value that corresponds to
the raw response code. Appendix I, "Electronic Verification Response Codes," on
page 365 describes the mapped response codes.

The following table lists the reply fields for each value that EV can verify.
Table 17

API Fields for Electronic Verification Responses

Value That Is
Being Verified

API Field for Mapped

Response

API Field for Raw Response

Email

ccAuthReply_evEmail

ccAuthReply_evEmailRaw

First name and

last name

ccAuthReply_evName

ccAuthReply_evNameRaw

Phone number

ccAuthReply_evPhoneNumber

ccAuthReply_evPhoneNumberRaw

Postal code

ccAuthReply_evPostalCode

ccAuthReply_evPostalCodeRaw

Street address

ccAuthReply_evStreet

ccAuthReply_evStreetRaw

Card Verification Numbers (CVNs)

Table 18

Processors That Support CVNs

Processors

Credit Card Types

AIBMS

Visa, MasterCard, Maestro (International),

Maestro (UK Domestic)

American Express Brighton

American Express

American Express Direct

American Express

Asia, Middle East, and Africa

Gateway

Visa, MasterCard, American Express, Diners Club

Atos

Visa, MasterCard, Carte Bleue

Barclays

Visa, MasterCard, Maestro (UK Domestic)

CCS (CAFIS)

Visa, MasterCard, American Express, Diners Club, JCB

Chase Paymentech Solutions

Visa, MasterCard, American Express, Discover

Cielo

Visa, MasterCard, American Express, Discover, Diners Club,

JCB, Maestro (International), Elo, Aura

Credit Card Services Using the Simple Order API | January 2016

80

Chapter 3

Table 18

Authorization Features

Processors That Support CVNs (Continued)

Processors

Credit Card Types

CyberSource Latin American

Processing

Visa, MasterCard, American Express, Elo

Note CyberSource Latin American Processing is the

CyberSource name for Braspag. CyberSource provides two
processors for Latin America: CyberSource Latin American
Processing (Braspag), which is supported in multiple Latin
American countries, and Cielo, which is supported in Brazil
only.

CyberSource through VisaNet

Visa, MasterCard, American Express, Diners Club, JCB,

Discover

Elavon

Visa, MasterCard, Discover, Diners Club, MasterCard,

Maestro (UK Domestic), Maestro (International)

Note Elavon does not return a separate CVN response

field in the authorization reply. When the card fails the CVN
check, Elavon declines the authorization.
FDC Compass

Visa, MasterCard, American Express, Discover

FDC Germany

Visa, MasterCard

FDC Nashville Global

Visa, MasterCard, American Express, Discover, Diners Club,

JCB (US Domestic)

Note For JCB cards, US Domestic means that the

currency is USD and your location is the U.S., Puerto Rico,
Guam, U.S. Virgin Islands, or Northern Mariana Islands.
FDI Australia

Visa, MasterCard, American Express, Diners Club

FDMS Nashville

Visa, MasterCard, American Express, Discover, Diners Club,

JCB (US Domestic)

Note For JCB cards, US Domestic means that the

currency is USD and your location is the U.S., Puerto Rico,
Guam, U.S. Virgin Islands, or Northern Mariana Islands.
FDMS South

Visa, MasterCard, American Express, Discover, Diners Club,

JCB (US Domestic)

Note For JCB cards, US Domestic means that the

currency is USD and your location is the U.S., Puerto Rico,
Guam, U.S. Virgin Islands, or Northern Mariana Islands.
Global Collect

Visa, MasterCard

Note Do not include the CVN in a request for a recurring

payment. See "Recurring Payments," page 189.
GPN

Visa, MasterCard, American Express, Discover, Diners Club

HBoS

Visa, MasterCard

HSBC

Visa, MasterCard, Maestro (International)

HSBC is the CyberSource name

for HSBC U.K.

Credit Card Services Using the Simple Order API | January 2016

81

Chapter 3

Table 18

Authorization Features

Processors That Support CVNs (Continued)

Processors

Credit Card Types

JCN Gateway

Visa, MasterCard, American Express, Diners Club, JCB,

NICOS house card

Litle

Visa, MasterCard, American Express, Discover

Lloyds-Omnipay

Visa, MasterCard

LloydsTSB Cardnet

Visa, MasterCard

Lynk

Visa, MasterCard, American Express, Discover, Diners Club

Moneris

Visa, MasterCard, American Express

OmniPay Direct

Visa, MasterCard, Maestro (UK Domestic),

Maestro (International)

OmniPay-Ireland

Visa, MasterCard

OmniPay-Ireland is the
CyberSource name for HSBC
International.
RBS WorldPay Atlanta

Visa, MasterCard, American Express, Discover, Diners Club

Streamline

Visa, MasterCard, Maestro (UK Domestic), Carte Bleue,

Dankort

TSYS Acquiring Solutions

Visa, MasterCard, American Express, Discover, Diners Club

CVN Locations and Terminology

The CVN, which is printed or embossed on the back of the card, can be sent with the
request and verified to help reduce the risk of fraud.
Figure 3

Example of a Visa Card Verification Number

Each payment card company has its own name for this value:

Visa calls it the Card Verification Value (CVV2).

American Express and Discover call it the Card Identification Digits (CID).

MasterCard calls it the Card Validation Code (CVC2).

To use CVN, include the card_cvNumber field in the request. This number is never
transferred during card swipes and should be known only by the cardholder.

Credit Card Services Using the Simple Order API | January 2016

82

Chapter 3

Authorization Features

CVN Codes
The reply message includes a raw response code and a mapped response code:

The raw response code is the value returned by the processor. This value is returned
in the ccAuthReply_cvCodeRaw field. Use this value only for debugging purposes;
do not use it to determine the card verification response.

The mapped response code is the pre-defined CyberSource value that corresponds to
the raw response code. This value is returned in the ccAuthReply_cvCode field.
Appendix G, "CVN Codes," on page 360 describes the mapped response codes.

Even when the CVN does not match the expected value, the issuing bank might still
authorize the transaction. You will receive a CVN decline from CyberSource, but you can
still capture the transaction because it has been authorized by the bank. However, you
must review the order to ensure that it is legitimate.
Settling authorizations that fail the CVN check might have an impact on the fees charged
by your bank. Contact your bank for details about how card verification management
might affect your discount rate.
When a CVN decline is received for the authorization in a sale request, CyberSource does
not process the capture unless you set the businessRules_ignoreCVResult field to
true.

Credit Card Services Using the Simple Order API | January 2016

83

Chapter 3

Table 19

Authorization Features

CVN Results for Each Card Type

Card Type

CVN Results

American Express

A ccAuthReply_cvCode value of 1 indicates that your account is not configured for

CVN. Contact CyberSource Customer Support to have your account enabled for this
feature.
To use CVN with American Express, see "Testing American Express Card Verification,"
page 215.

Discover

For FDC Nashville Global, FDMS Nashville, and FDMS South:

CVN results can be returned for any of the card types on the Discover Network as
described in "Discover Acquisitions and Alliances," page 19.

The CVN results are returned to you and it is your responsibility to decide whether or
not to accept the transaction.

For all other processors, when the CVN does not match:

Visa and MasterCard

Discover refuses the card and the request is declined.

The reply message does not include the ccAuthReply_cvCode field, which indicates
that the CVN failed.

A CVN code of D or N causes CyberSource to decline the request with reason code 230.
You can still capture the transaction, but you must review the order to ensure that it is
legitimate.

Note CyberSource, not the issuing bank, assigns the CVN decline to the authorization.
You can capture any authorization that has a valid authorization code from the issuing
bank, even when the request receives a CVN decline.
When the issuing bank does not authorize the transaction and the CVN does not match,
the request is declined because the card is refused. You cannot capture the transaction.

Verbal Authorizations
CyberSource supports verbal authorizations for these processors:

AIBMS

American Express Brighton

American Express Direct

Asia, Middle East, and Africa Gateway

Barclays

CCS (CAFIS)

Chase Paymentech Solutions

CyberSource through VisaNet

Elavon

FDC Compass

Credit Card Services Using the Simple Order API | January 2016

84

Chapter 3

Authorization Features

FDC Germany

FDI Australia

FDC Nashville Global

FDMS Nashville

FDMS South

GPN

HBoS

HSBC: HSBC is the CyberSource name for HSBC U.K.

JCN Gateway

Litle

Lloyds-OmniPay

LloydsTSB Cardnet

Lynk

Moneris

OmniPay-Ireland: OmniPay-Ireland is the CyberSource name for HSBC International.

RBS WorldPay Atlanta

TSYS Acquiring Solutions

UATP
Verbal authorizations are not supported for CyberSource Latin American
Processing.
Note

CyberSource Latin American Processing is the CyberSource name for

Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil
only. The information in this note applies only to CyberSource Latin
American Processing (Braspag).

Do not use Dynamic Currency Conversion with a verbal authorization.

Important

When you request an authorization through CyberSource, the issuing bank might ask you
to call the payment processor to answer questions about the transaction. When this
happens, the processor gives you a verbal authorization code for the transaction. To
capture a verbally authorized transaction, send the verbal authorization code in the
capture request. Make sure your customer service and point-of-sale staff can enter verbal
authorization codes into your system.

Credit Card Services Using the Simple Order API | January 2016

85

Chapter 3

Authorization Features

You can use a verbal authorization to capture an authorization that was declined for any of
these reasons:

Verbal authorization required

Card expired

Card refused

Invalid card
Do not confuse verbal authorizations with forced captures:

With a verbal authorization, you obtain the authorization code directly

from the processor or issuing bank after requesting an authorization
through CyberSource and receiving a CyberSource decline.

With a forced capture, you get the authorization code by authorizing a

payment outside of CyberSource. See "Forced Captures," page 121.

Important

In both cases, you must follow up with a capture that uses the CyberSource
system.
A verbal authorization works as follows:
1

The authorization reply includes reason code 201, which indicates that the issuing
bank is requiring a verbal authorization.
For an American Express card with FDMS Nashville, the authorization reply also
includes a referral response number in ccAuthReply_referralResponseNumber.
You will be asked for this number, which identifies the failed transaction, when you call
American Express for the verbal authorization.

You call the processor to answer questions about the transaction.

When the processor verbally authorizes the transaction, the processor gives you a
verbal authorization code.

You include the verbal authorization code in your capture request:

Send the verbal authorization code in the ccCaptureService_verbalAuthCode

field.

Send the word verbal in the ccCaptureService_authType field.

If you dont set ccCaptureService_authType to verbal, the
ccCaptureService_verbalAuthCode field is ignored.

For the American Express card type on FDMS South, the ccCaptureService_
posData and ccCaptureService_transactionID fields are required to comply
with the CAPN requirements.

Credit Card Services Using the Simple Order API | January 2016

86

Chapter 3

Note

Authorization Features

When you obtain a verbal authorization, American Express does not provide a
transaction ID. However, American Express requires that the transaction ID be
provided in capture requests. Because no transaction ID is available from
American Express for verbal authorizations, CyberSource enters zeros in the
transaction ID field in the capture request. American Express has indicated that
capture requests submitted without a valid transaction ID, including
transactions that originated as verbal authorizations, might incur additional
transaction charges. Contact your American Express account representative to
find out whether your processing is affected by these additional transaction
charges.

Credit Card Services Using the Simple Order API | January 2016

87

CHAPTER

Debit Cards and

Prepaid Cards

Debit cards and prepaid cards are processed using the credit card services described in
this document. This chapter describes the special features that are available for debit
cards and prepaid cards.

Note

To process domestic debit transactions on CyberSource through VisaNet with

MasterCard in Canada, you must contact CyberSource Customer Support to
have your account configured for this feature.

Note

When you use the Simple Order API in XML format, you must use version 1.52
or later of the XML schema to implement partial authorizations or balance
responses.

Partial Authorizations
The partial authorization functionality does not apply to credit cards.
Note

For debit cards and prepaid cards, the issuing bank can approve a partial amount if the
balance on the card is less than the requested authorization amount.

Credit Card Services Using the Simple Order API | January 2016

88

Chapter 4

Debit Cards and Prepaid Cards

Supported Processors and Card Types

The following table lists the processors and card types for which CyberSource supports
partial authorizations. If your processor and card type are not listed in the table, see
"Unsupported Processors and Card Types," page 98.
Table 20

Processors Supported for Partial Authorizations

Processor

Card Types for Debit Cards and Prepaid Cards

American Express Direct

American Express

Chase Paymentech Solutions

Visa, MasterCard, American Express, Discover, Diners Club

CyberSource through
VisaNet

Visa, MasterCard, American Express, Diners Club, JCB,

Discover

Important Partial authorizations are not available for

MasterCard transactions in the IDR currency on CyberSource
through VisaNet.
FDC Compass1

Visa, MasterCard, American Express, Discover

FDC Nashville Global

Visa, MasterCard, American Express, Discover2, Diners Club2,

JCB (US Domestic)2,3

FDMS Nashville

Visa, MasterCard, American Express, Discover2, Diners Club2,

JCB (US Domestic)2,3

FDMS South4

Visa, MasterCard, American Express, Discover2,

JCB (US Domestic)2,3

GPN

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

Litle

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

TSYS Acquiring Solutions

Visa, MasterCard, American Express, Discover, Diners Club,

JCB

1 FDC Compass might support partial authorizations for additional card types in the future so be prepared to
handle partial authorizations for all card types if your account is enabled for partial authorizations.
2 For this card type on the specified processor, partial authorizations are supported for credit cards in addition
to debit cards and prepaid cards.
3 For JCB cards, US Domestic means that the currency is USD and your location is the U.S., Puerto Rico,
Guam, U.S. Virgin Islands, or Northern Mariana Islands.
4 FDMS South might support partial authorizations for additional card types in the future so be prepared to
handle partial authorizations for all card types if your account is enabled for partial authorizations.

Credit Card Services Using the Simple Order API | January 2016

89

Chapter 4

Debit Cards and Prepaid Cards

Opting In

Note

If you accept American Express cards and Chase Paymentech Solutions is

your processor, see "Special Processing for American Express Cards on
Chase Paymentech Solutions," page 92.

You must opt in to be able to receive and capture partial authorizations. There are two
ways to opt in:
You can call CyberSource Customer Support to have your account enabled for partial
authorizations. When you do this, all your authorization requests are enabled for
partial authorizations.

or

You can set ccAuthService_partialAuthIndicator to true in your authorization or

sale request. When you do this, only that specific transaction is enabled for partial
authorization.

Note

When your account is enabled for partial authorizations, you can disable partial
authorization for a specific transaction by setting ccAuthService_
partialAuthIndicator to false in your authorization or sale request.

How a Partial Authorization Works

Note

Support for your processor and card type does not guarantee a partial
authorization. The issuing bank decides whether or not to approve a partial
amount.

When the balance on a debit card or prepaid card is less than the requested authorization
amount, the issuing bank can approve a partial amount. When this happens, you can
accept multiple forms of payment for the order starting with some or all of the approved
amount followed by one or more different payment methods:
1

If your account is not configured for partial authorizations, you must enable partial
authorizations for the transaction by setting ccAuthService_partialAuthIndicator to
true in your request.

Note

If you accept American Express cards and Chase Paymentech Solutions is

your processor, see "Special Processing for American Express Cards on
Chase Paymentech Solutions," page 92.

Credit Card Services Using the Simple Order API | January 2016

90

Chapter 4

Debit Cards and Prepaid Cards

If you accept IDR or CLP currencies on FDMS South, see "Special

Processing for IDR and CLP on FDMS South," page 92.
Note

You submit an authorization request or a sale request for a debit card or prepaid card.

The authorization reply message from CyberSource includes:

ccAuthReply_requestAmount: amount you requested

ccAuthReply_requestCurrency: currency for the amount you requested

ccAuthReply_amount: amount that was authorized

purchaseTotals_currency: currency for the amount that was authorized

requestID: value you can use to link this authorization request to subsequent
transactions
If you requested a sale, the authorization was not captured.
Note

You submit a capture request for the partial authorization.

If you capture only part of the approved amount, CyberSource or your processor might
be able to perform an automatic partial authorization reversal for you. See "Automatic
Partial Authorization Reversals," page 61.

Note

If you do not capture the partial authorization, you must request a full
authorization reversal if this service is supported for your processor and
card type. See "Reversing an Authorization," page 39.

You use one or more different payment methods for the rest of the order amount.
When you process these payment methods through CyberSource, you can use the
linkToRequest field to link the payment requests to the original authorization request.
Set linkToRequest to the requestID value that was returned in the reply message for
the original authorization request.

Credit Card Services Using the Simple Order API | January 2016

91

Chapter 4

Debit Cards and Prepaid Cards

Special Processing for American Express

Cards on Chase Paymentech Solutions
If you accept American Express cards and Chase Paymentech Solutions is your
processor, perform the following procedure to opt in to partial authorizations.

To opt in to partial authorizations for American Express cards on

Chase Paymentech Solutions:
Step 1

Contact Chase Paymentech Solutions to have your account enabled for partial
authorizations for the American Express card type. The transaction division for partial
authorizations for American Express should be set to 3.

Important

Step 2

This step is only for the American Express card type on Chase Paymentech
Solutions. For all other card types on Chase Paymentech Solutions, the
transaction division for partial authorizations should be set to the default value
of 0 (zero).

Contact CyberSource Customer Support to have your account enabled for partial
authorizations.
After your accounts have been enabled for partial authorizations at Chase Paymentech
Solutions and at CyberSource, you can disable partial authorizations for a specific
transaction by setting ccAuthService_partialAuthIndicator to false in your
authorization or sale request.

Special Processing for IDR and CLP on FDMS

South
For the Indonesian rupiah (IDR) and Chilean peso (CLP) currencies only:

Rounding occurs, which can cause a minor discrepancy of up to one currency unit
between the amount you requested and the amount that is authorized.

When a transaction is enabled for partial authorization, you must ensure that the
requested amount does not include any digits to the right of the decimal separator.

Credit Card Services Using the Simple Order API | January 2016

92

Chapter 4

Debit Cards and Prepaid Cards

Real-Time Reversals
There are two kinds of real-time reversals:

A full authorization reversal is a service that you can request.

If you do not capture a partial authorization and if full authorization reversals are
supported for your processor and card type, you must request a full authorization
reversal to release the hold that the authorization placed on the customers funds. The
amount of the reversal must be the amount that was authorized, not the amount that
was requested. For details about this service and to see the processors and card
types for which this service is supported, see "Reversing an Authorization," page 39.

An automatic partial authorization reversal is performed automatically by CyberSource

or your processor under certain conditions.
If you capture a partial authorization for an amount that is less than the approved
amount, CyberSource automatically performs a partial authorization reversal if it is
supported for your processor and card type. CyberSource performs the automatic
partial authorization reversal before sending the capture request to the processor.

Note

Some processors perform an automatic partial authorization reversal when

there is an interchange benefit. These processors do not allow
CyberSource to perform this functionality.

For details about automatic partial authorization reversals and for a list of the
processors and card types for which it is supported, see "Automatic Partial
Authorization Reversals," page 61.

Credit Card Services Using the Simple Order API | January 2016

93

Chapter 4

Debit Cards and Prepaid Cards

Balance Responses
Normally, balance responses are not returned for debit cards.
Note

To receive balance responses from Litle, your Litle account must be enabled
for this feature.
Note

When there is a balance remaining on a prepaid card after an authorization, the

authorization reply can include the balance amount. Depending on what data your
processor sends to CyberSource, the following fields might be included in the reply:

ccAuthReply_accountBalance: balance amount remaining on the prepaid card after

the authorization
For Discover, some processors return the balance in the ccAuthReply_
authorizationCode field.
Note

ccAuthReply_accountBalanceCurrency: currency of the balance amount

ccAuthReply_accountBalanceSign: sign for the balance amount

For descriptions of these fields, see Appendix A, "API Fields," on page 216.

Credit Card Services Using the Simple Order API | January 2016

94

Chapter 4

Debit Cards and Prepaid Cards

The following table lists the processors and card types for which balance responses are
supported. Depending on what data your processor sends to CyberSource, the following
fields might be included in the reply.
Table 21

Processors Supported for Balance Responses

Processor

Card Type

American Express Direct

Chase Paymentech
Solutions

CyberSource through
VisaNet

FDC Compass

FDC Nashville Global

FDMS Nashville

Balance
Field 1

Currency
Field

Sign
Field

American Express

Yes

Yes

no

Visa

Yes

Yes

no

MasterCard

Yes

Yes

no

American Express

Yes

Yes

no

Discover

Yes

Yes

no

Diners Club

Yes

Yes

no

Maestro (International)

Yes

Yes

no

Visa

Yes

Yes

Yes

MasterCard

Yes

Yes

Yes

American Express

Yes

Yes

Yes

Discover

Yes

Yes

Yes

Diners Club

Yes

Yes

Yes

JCB

Yes

Yes

Yes

Visa

Yes

Yes

no

MasterCard

Yes

Yes

no

American Express

Yes

Yes

no

Discover

Yes

Yes

no

Visa

Yes

Yes

Yes

MasterCard

Yes

Yes

Yes

American Express

Yes

Yes

Yes

Discover

Yes

Yes

Yes

Diners Club

Yes

Yes

Yes

JCB

Yes

Yes

Yes

Visa

Yes

Yes

Yes

MasterCard

no

no

no

American Express

Yes

Yes

Yes

Discover

no

no

no

Diners Club

no

no

no

JCB

no

no

no

1 For Discover, some processors return the balance in the ccAuthReply_authorizationCode field.

Credit Card Services Using the Simple Order API | January 2016

95

Chapter 4

Table 21

Debit Cards and Prepaid Cards

Processors Supported for Balance Responses (Continued)

Processor

Card Type

FDMS South

GPN

Litle

TSYS Acquiring
Solutions

Balance
Field 1

Currency
Field

Sign
Field

Visa

Yes

Yes

Yes

MasterCard

no

no

no

American Express

Yes

Yes

Yes

Discover

no

no

no

Diners Club

no

no

no

JCB

no

no

no

Visa

Yes

Yes

Yes

MasterCard

Yes

Yes

Yes

American Express

Yes

Yes

Yes

Discover

Yes

Yes

Yes

Diners Club

Yes

Yes

Yes

JCB

Yes

Yes

Yes

Visa

Yes

Yes

no

MasterCard

Yes

Yes

no

American Express

Yes

Yes

no

Discover

Yes

Yes

no

Diners Club

Yes

Yes

no

JCB

Yes

Yes

no

Visa

Yes

Yes

Yes

MasterCard

Yes

Yes

Yes

American Express

Yes

Yes

Yes

Discover

Yes

Yes

Yes

Diners Club

Yes

Yes

Yes

JCB

Yes

Yes

Yes

1 For Discover, some processors return the balance in the ccAuthReply_authorizationCode field.

Credit Card Services Using the Simple Order API | January 2016

96

Chapter 4

Debit Cards and Prepaid Cards

Features for Maestro

(UK Domestic) Cards
To see which processors support Maestro (UK Domestic) cards, see "Payment
Processors," page 27.
This section previously covered Solo cards, but Solo cards are being phased
out.
Note

Maestro (UK Domestic) cards were previously called Switch cards.

Note

Maestro (UK Domestic) cards are debit cards that originate in the United Kingdom. These
cards can have the following features:

Issue number: A Maestro (UK Domestic) card might have an issue number embossed
on it. The issue number can consist of one or two digits; the first digit can be a zero.
An issue number of 2 is different from 02.
Effective May 2011, the issue number is no longer required for
Maestro (UK Domestic) transactions.
Note

Start date: A Maestro (UK Domestic) card might have a start date embossed on it. The
start date consists of a month and year.
Effective May 2011, the start date is no longer required for
Maestro (UK Domestic) transactions.
Note

Credit Card Services Using the Simple Order API | January 2016

97

Chapter 4

Debit Cards and Prepaid Cards

Unsupported Processors and

Card Types
Prepaid cards and debit cards that do not appear in Table 20, "Processors Supported for
Partial Authorizations," on page 89 are processed as follows:

When the card balance is sufficient for the requested transaction, the transaction is
successful.

When the card balance is not sufficient for the requested transaction, the request is
declined.

Credit Card Services Using the Simple Order API | January 2016

98

CHAPTER

Optional Features

$0 Authorizations
See "Zero Amount Authorizations," page 209.

Additional Amounts
Services:

Capture

Credit

Processor:

American Express Direct

This feature enables you to provide detailed information about specific amounts included
in a transaction. For example, if a transaction amount includes a gratuity of 5.00, you can
include these fields in the capture or credit request:
purchaseTotals_additionalAmount0=5.0
purchaseTotals_additionalAmountType0=058

You can include a maximum of five additional amounts in a transaction. For each amount,
you must include an amount field and an amount type field:

purchaseTotals_additionalAmount0 through purchaseTotals_additionalAmount4

purchaseTotals_additionalAmountType0 through purchaseTotals_

additionalAmountType4

The additional amount type values are listed in Appendix C, "Additional Amount Types,"
on page 351.

Credit Card Services Using the Simple Order API | January 2016

99

Chapter 5

Optional Features

Shipping and Handling Fees

Additional amount fields for shipping and handling fees take precedence over item-level
fields. See the following example.
Example 1
1

Shipping and Handling Fees

You include the following lines in your request:

purchaseTotals_additionalAmount0=9.95
purchaseTotals_additionalAmountType0=055
item_0_productCode=shipping_and_handling
item_0_unitPrice=12.95

CyberSource processes the additional amount fields for the shipping and handling
amount of 9.95. The item-level fields for the shipping and handling amount are
ignored.

Taxes
Additional amount fields for taxes take precedence over item-level fields. See the following
example.
Example 2
1

Taxes

You include the following lines in your request:

purchaseTotals_additionalAmount0=7.95
purchaseTotals_additionalAmountType0=046
item_0_taxAmount=5.95

CyberSource processes the additional amount fields for the tax amount of 7.95. The
item-level field for the tax amount is ignored.

Aggregator Support
This feature enables a third-party agent to act as a payment aggregator and process credit
card transactions for sub-merchants. Independent sales organizations (ISOs) and
member service providers (MSPs) are agents that can also leverage these aggregator
features.
Contact CyberSource Customer Support to have your account configured for this feature.

Credit Card Services Using the Simple Order API | January 2016

100

Chapter 5

Optional Features

Terminology
Table 22

Aggregator Terminology

Term

Definition

aggregator

Also known as payment aggregator. Organization that aggregates submerchants under a single account and settles funds directly to the submerchants. An aggregator is usually an ISO or MSP.

independent sales
organization (ISO)

Organization that does one or more of the following:

Works with acquirers to sponsor merchant accounts and usually

assumes the risks associated with the merchants processing.

Procures new merchant relationships based on contracts with

acquirers.

Connects with a gateway to process online credit card transactions

for small businesses, usually in exchange for a fee or percentage of
sales.

member service
provider (MSP)

Same as an ISO although an MSP has no financial responsibility to the

merchant.

payment facilitator

Payment aggregator.

service provider

Third-party or outsource provider of payment processing services. A

service provider typically provides a single service with no role in settling
funds to a merchant.

sub-merchant

Merchant whose transactions are submitted to CyberSource by a

payment aggregator.

third-party agent

Umbrella term for independent sales organizations, member service

providers, payment aggregators, and payment facilitators.

American Express Direct Aggregators

Services:

Authorization

Capture

Credit

To indicate that you are acting as a payment aggregator, you must include the following
fields in your requests for authorization, capture, and credit services:

ccAuthService_aggregatorIDrequired only for the authorization service

ccAuthService_aggregatorNamerequired only for the authorization service

ccCaptureService_aggregatorIDrequired only for the capture service

ccCaptureService_aggregatorNamerequired only for the capture service

ccCreditService_aggregatorIDrequired only for the credit service

ccCreditService_aggregatorNamerequired only for the credit service

Credit Card Services Using the Simple Order API | January 2016

101

Chapter 5

invoiceHeader_submerchantCity

invoiceHeader_submerchantCountry

invoiceHeader_submerchantEmail

invoiceHeader_submerchantID

invoiceHeader_submerchantName

invoiceHeader_submerchantPostalCode

invoiceHeader_submerchantState

invoiceHeader_submerchantStreet

invoiceHeader_submerchantTelephoneNumber

merchantCategoryCode

Optional Features

These fields are described in Appendix A, "API Fields," on page 216.

The following fields are optional:

invoiceHeader_merchantDescriptor

invoiceHeader_merchantDescriptorCity

invoiceHeader_merchantDescriptorContact

invoiceHeader_merchantDescriptorCountry

invoiceHeader_merchantDescriptorPostalCode

invoiceHeader_merchantDescriptorState

invoiceHeader_merchantDescriptorStreet

These fields are described in Table 31, "Merchant Descriptor Fields for American Express
Direct," on page 133.
Typically, the merchant descriptor field is used to display your business name on the
cardholder's statement. However, when you are a payment aggregator, you can use other
values to provide the sub-merchants business name for capture and credit requests. The
following table describes these values. The order of the values in the table is the order that
CyberSource uses to determine which values to use.

Credit Card Services Using the Simple Order API | January 2016

102

Chapter 5

Table 23

Optional Features

Values for Providing a Sub-Merchants Business Name

Option

Values

Description

Aggregator Name +
Sub-merchant
Name

Aggregator Name
The aggregator name is an API field you can include in your request. The API
fields are ccAuthService_aggregatorName, ccCaptureService_
aggregatorName, and ccCreditService_aggregatorName.
Sub-merchant Name
The sub-merchant name is the value from the invoiceHeader_
suberchantName field.
Aggregator Name + Sub-merchant Name
When you include the aggregator name field in your request and when your
CyberSource account information includes a sub-merchant name,
CyberSource combines these two values to provide the business name
information for the cardholders statement. This approach is advantageous
because it allows the business name information to be longer than the size of
the merchant descriptor field, which has a length of 27 characters.
The total length of the value that CyberSource sends to the processor is 36
characters. It is formatted with an asterisk (*) between the aggregator name
and the sub-merchant name:

aggregator name*sub-merchant name

Because the asterisk uses one character, 35 characters remain for the
combined length of the aggregator name and sub-merchant name.

Important If the combined length of the aggregator name and sub-merchant

name exceeds 36 characters, CyberSource declines the transaction.
2

Merchant Descriptor

When you do not provide the values for the preceding option, you can provide
the business name in the merchant descriptor field invoiceHeader_
merchantDescriptor. This field is described in Table 31, "Merchant Descriptor
Fields for American Express Direct," on page 133.

Merchant Name

When you do not provide the values for the preceding two options,
CyberSource uses the merchant name in your CyberSource account. To add
this value to your CyberSource account, contact CyberSource Customer
Support.

Credit Card Services Using the Simple Order API | January 2016

103

Chapter 5

Optional Features

CyberSource through VisaNet Aggregators

Services:

Authorization

Capture

Credit

To indicate that you are acting as a payment aggregator, you must include the following
fields in your requests for authorization service with MasterCard transactions. If you send
them for transactions other than MasterCard, they will not be delivered to the processor.

ccAuthService_aggregatorID

invoiceHeader_salesOrganizationID

invoiceHeader_submerchantID

These fields are described in Appendix A, "API Fields," on page 216.

The following fields are optional for aggregator transactions with any card type supported
by your acquirer:

invoiceHeader_merchantDescriptor

invoiceHeader_merchantDescriptorCity

invoiceHeader_merchantDescriptorContact

invoiceHeader_merchantDescriptorCountry

invoiceHeader_merchantDescriptorPostalCode

invoiceHeader_merchantDescriptorState

invoiceHeader_merchantDescriptorStreet

merchantCategoryCode

The merchant descriptor fields are described in Table 34, "Merchant Descriptor Fields for
Authorizations for CyberSource through VisaNet," on page 140 for authorizations, and in
Table 35, "Merchant Descriptor Fields for Captures and Credits for CyberSource through
VisaNet," on page 143 for captures and credits.
The merchant category code field is described in Appendix A, "API Fields," on page 216.
Typically, the merchant descriptor field is used to display your business name on the
cardholder's statement. However, when you are a payment aggregator, you can use other
values to provide the sub-merchants business name for capture and credit requests.
When you do not provide a value in the merchant descriptor fields, CyberSource uses the
values in your CyberSource account. To add or validate the values in your CyberSource
account, contact CyberSource Customer Support.

Credit Card Services Using the Simple Order API | January 2016

104

Chapter 5

Optional Features

FDC Nashville Global Aggregators

Services:

Authorization

Capture

Credit

Card types:

American Express

MasterCard

To indicate that you are acting as a payment aggregator, you must include the following
fields in your requests for authorization, capture, and credit services:

ccAuthService_aggregatorIDrequired only for the authorization service

ccAuthService_aggregatorNamerequired only for the authorization service

ccCaptureService_aggregatorIDrequired only for the capture service

ccCaptureService_aggregatorNamerequired only for the capture service

ccCreditService_aggregatorIDrequired only for the credit service

ccCreditService_aggregatorNamerequired only for the credit service

invoiceHeader_submerchantCity

invoiceHeader_submerchantCountry

invoiceHeader_submerchantEmail

invoiceHeader_submerchantID

invoiceHeader_submerchantName

invoiceHeader_submerchantPostalCode

invoiceHeader_submerchantState

invoiceHeader_submerchantStreet

invoiceHeader_submerchantTelephoneNumber

merchantCategoryCode

These fields are described in Appendix A, "API Fields," on page 216.

The following fields are optional:

invoiceHeader_submerchantMerchantIDsupported only for American Express

invoiceHeader_submerchantRegion

These fields are described in Appendix A, "API Fields," on page 216.

Credit Card Services Using the Simple Order API | January 2016

105

Chapter 5

Optional Features

Airline Data
Services:

Authorization

Capture

Credit

For information about airline data, including the list of processors for which CyberSource
supports airline data, see Airline Processing Using the Simple Order API.

American Express SafeKey

See "Payer Authentication," page 171.

Apple Pay
Processors:

American Express Direct

Chase Paymentech Solutions

FDC Compass

FDC Nashville Global

GPN

Moneris

OmniPay Direct

TSYS Acquiring Solutions

See Getting Started with Apple Pay on the CyberSource Platform for
information about requirements.

Important

Credit Card Services Using the Simple Order API | January 2016

106

Chapter 5

Optional Features

How Apple Pay Works

The following diagram shows how to use the CyberSource credit card services to integrate
Apple Pay into your order management system.

Your iOS application (Merchant App) uses the Apple PassKit Framework to request
payment data from Apple.

Apple sends encrypted payment data to your iOS application. The encrypted payment
data includes a token instead of a primary account number (PAN).

Your iOS application forwards the encrypted payment data to your order management
system (Merchant Server).

Your order management system requests the CyberSource authorization service and
includes the encrypted payment data in the authorization request.

CyberSource decrypts the payment data and forwards the information to the payment
network, including your processor and the relevant payment card company.

Processing Apple Pay Payments with

CyberSource Credit Card Services
Step 1

Use the Apple PassKit Framework to extract the Apple encrypted payment data from your
iOS application. For more information see the PassKit Framework Reference.

Step 2

Send the encrypted payment data to your server.

Credit Card Services Using the Simple Order API | January 2016

107

Chapter 5

Step 3

Optional Features

Request the credit card authorization service as described in "Creating an Authorization

Request," page 33.
After receiving the authorization request, CyberSource decrypts the encrypted payment
data and includes some of the decrypted data as needed in the authorization request that
CyberSource sends to your processor.

Step 4

Receive the reply message from CyberSource.

The fields that CyberSource includes in the authorization reply message are the same as
the fields included in the reply for a normal authorization.

Step 5

Continue to process the credit card as described in this guide.

Optional Features for Apple Pay

Processor-Specific Information
Table 24

Optional Features Supported for Each Processor

Processor

Supported Optional Features

American Express Direct

Apple Pay is supported for recurring payments.

Chase Paymentech Solutions

Apple Pay is supported for multiple captures and recurring

payments.

FDC Compass

Apple Pay is supported for multiple captures and recurring

payments.

FDC Nashville Global

Apple Pay is supported for recurring payments.

GPN

Apple Pay is supported for multiple captures, split shipments,

and recurring payments.

Moneris

Apple Pay is supported for recurring payments.

OmniPay Direct

Apple Pay is supported for multiple captures and recurring

payments.

TSYS Acquiring Solutions

Apple Pay is supported for recurring payments.

Credit Card Services Using the Simple Order API | January 2016

108

Chapter 5

Optional Features

Recurring Payments
To create a recurring payment using Apple Pay:
Step 1

For the first payment, the type of request you need to send depends on which processor
and card type you are using.

For MasterCard and American Express transactions on FDC Nashville Global, include
the following fields and values in the request for the first payment:
ccAuthService_commerceIndicator=recurring
ccAuthService_firstRecurringPayment=TRUE
card_cvNumber

For all card types on OmniPay Direct, request a non-recurring transaction and include
the following field and value in the request for the first payment:
ccAuthService_firstRecurringPayment=Y

Step 2

For all other processors and card types, request a non-recurring transaction for a
credit card authorization. Do not include the e-commerce indicator field in the
authorization request.

For each subsequent recurring payment:

Set the e-commerce indicator to recurring. The e-commerce indicator field is

ccAuthService_commerceIndicator.

Include the transaction type field, which is paymentNetworkToken_

transactionType.

For more information see "Recurring Payments," page 189.

Additional Information
CyberSource Documentation:

Getting Started with Apple Pay on the CyberSource Platform

For descriptions of the required fields for the credit card services and to see which
fields are optional, see Appendix A, "API Fields," on page 216.

For examples of Apple Pay requests and replies, see:

Name-value pair examples: "Apple Pay Examples," page 305.

XML examples: "Apple Pay Examples," page 323.

Apple Documentation:

PassKit Framework Reference

Credit Card Services Using the Simple Order API | January 2016

109

Chapter 5

Optional Features

Authorization Only
Service:

Authorization

Processor:

American Express Direct

In the authorization reply message, CyberSource provides you with point-of-sale (POS)
and transaction ID (TID) values. If you perform authorizations through CyberSource and
perform captures and credits through other financial institutions, you can include these
values in your capture requests and follow-on credit requests:

POS data: Get this value from ccAuthReply_posData.

TID: Get this value from ccAuthReply_transactionID.

Including these values in your capture requests and follow-on credit requests enables you
to comply with the CAPN requirements, thus avoiding noncompliance fees.
When you use the Simple Order API in XML format, you must use version 1.63
or later of the XML schema to implement the authorization only feature.
Note

AVS Only
See "Zero Amount Authorizations," page 209.

Balance Inquiries
Service:

Authorization

Processor:

CyberSource through VisaNet

This feature enables you to request balance information for an account.

To use this feature, include the balanceInquiry field in an authorization request. The
amount in the request must be zero.

Credit Card Services Using the Simple Order API | January 2016

110

Chapter 5

Optional Features

CyberSource returns the following fields:

ccAuthReply_accountBalance

ccAuthReply_accountBalanceCurrency

ccAuthReply_accountBalanceSign

ccAuthReply_accountType

ccAuthReply_amountType

These fields are described in "API Fields," page 216.

Bill Me Later
Services:

Authorization

Capture

Credit

For information about Bill Me Later, including the list of processors for which CyberSource
supports Bill Me Later, see the Bill Me Later Supplement to Credit Card Services Using the
Simple Order API.

Bill Payments with Visa

See "Visa Bill Payments," page 207.

Card-Present Data
Service:

Authorization

For a description of card-present data, including the list of processors for which
CyberSource supports card-present transactions, see Card-Present Processing Using the
Simple Order API.

Credit Card Services Using the Simple Order API | January 2016

111

Chapter 5

Optional Features

Card Type Indicators (CTIs)

Service:

Authorization

Processor:

Chase Paymentech Solutions

Contact CyberSource Customer Support to have your account configured for
this feature.
Note

This feature enables you to receive CTI information in your authorization reply messages.
The processor can provide CTI information for approved or declined transactions, not for
rejected transactions.

To receive CTI information:

Your authorization request message must comply with the CTI acceptance criteria as
described in the following table.
Table 25

CTI Acceptance Criteria

Card Type

Acceptance Criteria

American Express

CTI is not supported.

Carte Blanche

CTI is not supported.

Diners Club

Currency is USD or CAD.

Discover

Currency is USD or CAD.

JCB

Currency is USD.

MasterCard

Any currency.

Visa

Amount is not 0 (zero). Any currency.

The CTI information is returned in the following fields:

ccAuthReply_affluenceIndicator

ccAuthReply_cardCommercial

ccAuthReply_cardHealthcare

ccAuthReply_cardIssuerCountry

ccAuthReply_cardLevel3Eligible

ccAuthReply_cardPayroll

ccAuthReply_cardPINlessDebit

ccAuthReply_cardPrepaid

Credit Card Services Using the Simple Order API | January 2016

112

Chapter 5

ccAuthReply_cardRegulated

ccAuthReply_cardSignatureDebit

Optional Features

The CTI fields are described in Appendix A, "API Fields," on page 216.

Cash Advances
Services:

Authorization

Capture

Processors:

Barclays

LloydsTSB Cardnet

A cash advance enables a customer to use a credit card to purchase foreign currency or
travelers checks. The currency the customer uses to fund the transactions must be British
pounds.
Before processing cash advances, you must:

Contact the processor to obtain an agreement to process cash advance transactions.

Contact CyberSource Customer Support to have your account configured for this
feature. You must have a separate CyberSource merchant ID that you use only for
cash advance transactions.

Process a cash advance transaction the same way you process a regular credit card
transaction: with an authorization and a capture.
You cannot process a cash advance and airline data in the same transaction.
Important

Customer Profiles
See "Payment Tokenization," page 185.

Credit Card Services Using the Simple Order API | January 2016

113

Chapter 5

Optional Features

Dynamic Currency Conversion for

First Data
Services:

Authorization

Capture

Credit

Processors:

FDC Nashville Global

FDMS South

Card types:

Visa

MasterCard

The Dynamic Currency Conversion (DCC) service converts a foreign cardholders

purchase from your local currency to the cardholders billing currency. This service can
help you improve or create business relationships with customers who prefer to make
purchases in their own currency.

Requirements and Limitations

The requirements for using the DCC service are:

Your local currency must be USD.

You must contact CyberSource Customer Support to have your account configured for
this feature.

You must provide the customer with a receipt showing the US Dollar amount, the
foreign currency amount, and the rate of exchange used to convert the transaction.
You must also have the customer sign an acknowledgement that the customer had a
choice to pay in US Dollars and that the choice of currency is final.
Partial authorizations cannot be performed with the DCC service.
Note

Credit Card Services Using the Simple Order API | January 2016

114

Chapter 5

Optional Features

When requesting the DCC service, do not request any of these services in the same
request message:

Tax calculation

Authorization

Capture

Credit

Do not use Level II or Level III processing with DCC.

Important

For DCC transactions, USD is the only supported currency for full authorization
reversals. You can reverse an authorization when the DCC indicator is 2 or 3
because these values indicate that the transaction was in USD. When you
request a full authorization reversal when the DCC indicator is 1, which
indicates that the transaction was in a foreign currency, the reversed amount is
incorrect.

Terminology
Table 26

DCC Terminology

Term

Definition

Billing currency
or
Cardholder billing currency

Cardholders currency in which their card is denominated

and in which transactions are posted to the cardholders
account.

Converted amount

Amount of the transaction, denominated in the cardholders

billing currency.

DCC disclosure

Legally required message that a customer must agree to

before DCC can be used for the transaction. A typical
message is I acknowledge that I was offered a choice of
currencies in which to perform this transaction and I
understand that this choice is final.

Exchange rate
or
DCC exchange rate

Conversion factor used to convert an original amount to a

converted amount.

Local currency
or
Merchant local currency

Your selling currency that you use for pricing your goods
and in which you usually submit transactions for
processing.

Original amount

Amount of the transaction, denominated in your local

currency.

Prefix
or
Account prefix

First 6 to 10 digits of a Visa or MasterCard credit card

number.

Credit Card Services Using the Simple Order API | January 2016

115

Chapter 5

Optional Features

Using DCC
Step 1

Request the DCC service:

a

Include the statement ccDCCService_run=true in your request.

Include the required DCC fields in your request:

Step 2

card_accountNumber: first 6 to 10 digits of the credit card number

item_#_unitPrice: original amount

merchantID

merchantReferenceCode

purchaseTotals_currency: local currency

Receive the DCC reply fields:

ccDCCReply_dccSupported: flag that indicates whether DCC is supported for this

transaction

ccDCCReply_marginRatePercentage: currency selection fee

purchaseTotals_exchangeRate: exchange rate

purchaseTotals_exchangeRateTimeStamp: exchange rate timestamp

purchaseTotals_foreignAmount: converted amount

purchaseTotals_foreignCurrency: converted currency code

If necessary, handle a lack of availability.

If the purchase is not eligible for DCC or DCC processing is not available, proceed with
the transaction in your local currency:

In your transaction requests (authorization, capture, credit), include the DCC indicator
set to 2, which indicates that the transaction amount could not be converted.

Do not perform the rest of this procedure.

Credit Card Services Using the Simple Order API | January 2016

116

Chapter 5

Step 3

Optional Features

Query the customer.

If the purchase is eligible for DCC, you must get permission from the customer before you
can proceed:
a

Explain to your customer that the transaction is a candidate for DCC.

Display the required DCC information to the customer. Contact your acquirer for these
requirements.

Ask your customer if they would like to complete the transaction in their billing
currency.

Important

Step 4

Before you can use DCC for a purchase, the cardholder must opt in to the
process and explicitly choose to have the purchases subjected to DCC.
Because of this requirement, you cannot use DCC for recurring payments
or a recurring subscription.

If necessary, proceed in the local currency.

If the customer does not opt in, proceed with the transaction in your local currency:

Step 5

In your transaction requests (authorization, capture, credit), include the DCC indicator
set to 3, which indicates that the cardholder declined the currency conversion.

Continue with this procedure.

Authorize the payment.

The following table lists the DCC fields required for the authorization, capture, and credit
services. These request field names are the same as the names of the DCC service reply
fields.

Table 27

DCC Fields Required for the Authorization, Capture, and Credit Services

Request Field for the

Authorization, Capture, and
Credit Services

Reply Field for the DCC

Service

Value

dcc_dccIndicator

No corresponding field.

DCC indicator: If the customer opted in, set

the indicator to 1. If the customer did not opt
in, set the indicator to 3.

purchaseTotals_exchangeRate

purchaseTotals_exchangeRate

Exchange rate

purchaseTotals_
exchangeRateTimeStamp

purchaseTotals_
exchangeRateTimeStamp

Exchange rate timestamp

purchaseTotals_foreignAmount

purchaseTotals_foreignAmount

Converted amount

purchaseTotals_foreignCurrency

purchaseTotals_
foreignCurrency

Converted currency code

Credit Card Services Using the Simple Order API | January 2016

117

Chapter 5

Step 6

Optional Features

Display DCC information.

If the customer opted in, notify your customer that the transaction was successfully
authorized and display required DCC information to the customer.

Step 7

Capture the authorization.

If DCC data was included in the authorization request, then DCC data must be included in
the capture request:

Step 8

If the capture amount is the same as the authorization amount, submit a capture
request that includes the same DCC values that were included in the authorization
request.

If the capture amount is different from the authorization amount, call the DCC service
with the capture amount and then submit a capture request that includes the new
DCC values.

Optional: credit the payment.

If DCC data was included in the capture request, then DCC data must be included in the
credit request:

If this is a follow-on credit and if the credit amount is the same as the capture amount,
submit a credit request that includes the same DCC values that were included in the
capture request.

If this is a follow-on credit and if the credit amount is different from the capture
amount, call the DCC service with the credit amount and then submit a credit request
that includes the new DCC values.

If this is a stand-alone credit, call the DCC service with the credit amount and then
submit a credit request that includes the new DCC values.
If the customer did not opt in, use the DCC values you already obtained.
Note

Step 9

View the transaction results.

If the customer opted in, you can see the following DCC values in the transaction results
that are displayed on the Business Center:

Original amount

Converted amount

Exchange rate

You can also see the DCC values in the XML version of the Payment Submission Detail
Report. For a description of this report, see the Reporting Developer Guide.

Credit Card Services Using the Simple Order API | January 2016

118

Chapter 5

Important

Optional Features

DCC values are only in the XML version of the Payment Submission Detail
Report. To see these values, you must subscribe to the Payment Submission
Detail Report.

Additional Information
For descriptions of the required fields and to see which fields are optional, see
Appendix A, "API Fields," on page 216.

Encoded Account Numbers

Services:

Authorization

Credit

Processor:

Chase Paymentech Solutions Credit Card Encryption program

Depending on your type of business, you might be eligible to acquire from an issuing bank
a list of the customers who have credit cards issued by that bank. The list does not include
the customers credit card numbers, but instead includes encoded account numbers.
Some processors refer to this type of program as issuer encryption and to the numbers as
encrypted account numbers. This type of program is designed to protect customer
information according to the provisions of the Gramm-Leach-Bliley Act.
When processing a payment or credit for one of these customers, you use the encoded
account number instead of the customers credit card number. The issuing bank then
matches the encoded account number to the customers credit card number when
processing the payment.
You must contact your processor to obtain the information required for the Credit Card
Encryption program and you must have a relationship with the bank in order to acquire
their list of customers.

Credit Card Services Using the Simple Order API | January 2016

119

Chapter 5

Optional Features

Final Authorization Indicator

Service:

Authorization

Processors:

Barclays

Chase Paymentech SolutionsMasterCard and Maestro (International) only. Chase

Paymentech Solutions does not support this feature for Maestro (UK Domestic).

CyberSource through VisaNet

Elavon

HBoS

HSBC

Lloyds-OmniPay

LloydsTSB Cardnet

OmniPay Direct

OmniPay-IrelandMasterCard only. OmniPay-Ireland does not support Maestro

(International) or Maestro (UK Domestic).

Card types:

MasterCard

Maestro (International)

Maestro (UK Domestic)

This feature supports a mandate from MasterCard. The purpose of the mandate is to
prevent a consumers funds from being unavailable when there is a risk that the order will
not be fulfilled. This mandate applies to you if your acquirer is in the MasterCard Europe
region, which includes Russia.
For an authorization with an amount greater than 0 (zero), you must indicate whether the
authorization is a final authorization or a preauthorization.
For a final authorization:

The authorization amount is the final amount that the consumer agrees to pay.

The authorization cannot be reversed except in the case of a system error.

You must submit the authorization for capture within four business days after
requesting the authorization.

The capture amount must be the same as the authorization amount.

Credit Card Services Using the Simple Order API | January 2016

120

Chapter 5

Optional Features

For a preauthorization:

The preauthorization enables you to obtain a payment guarantee when the consumer
places an order.

The authorization amount can be an estimated amount.

The capture amount does not need to be the same as the authorization amount.

You can submit the authorization for capture more than four business days after
requesting the authorization.

If you do not capture the authorization, you must reverse it.

MasterCard charges additional fees for performing a preauthorization and for
failing to capture or reverse a preauthorization.
Note

To indicate whether an authorization is a final authorization or a

preauthorization:
Include the authIndicator field in your authorization request. This field is described in
Appendix A, "API Fields," on page 216.
For all processors except CyberSource through VisaNet, the default value for
this field is 1 (final authorization). To change the default value for this field,
contact CyberSource Customer Support.

Note

Forced Captures
Service:

Authorization

Processors:

AIBMS

American Express Direct

Asia, Middle East, and Africa Gateway

CCS (CAFIS)

CyberSource through VisaNet. The supported acquirer is:

CTBC Bank Ltd.

FDC Nashville Global

FDMS Nashville

Credit Card Services Using the Simple Order API | January 2016

121

Chapter 5

FDMS South

GPN

JCN Gateway

TSYS Acquiring Solutions

Optional Features

Forced captures are not supported for CyberSource Latin American

Processing.
Note

CyberSource Latin American Processing is the CyberSource name for

Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil only.
The information in this note applies only to CyberSource Latin American
Processing (Braspag).

A forced capture occurs when you process an authorization outside the CyberSource
system but then capture the order through CyberSource.

To perform a forced capture:

After you process the authorization outside the CyberSource system, request the
CyberSource authorization and capture services at the same time as described in
"Creating an Authorization Request," page 33, and "Creating a Capture Request,"
page 50:

Include the request fields that are required for the authorization.

Include these fields in the request:

ccAuthService_authType=verbal
ccAuthService_verbalAuthCode= the authorization code you received in the
response for the authorization that was processed outside the CyberSource system

No additional fields are required for the capture.

For the American Express card type on FDMS South, you must include the
ccCaptureService_posData and ccCaptureService_transactionID fields in the capture
request to support the CAPN requirements. Obtain the values for these fields from the
response for the authorization that was processed outside the CyberSource system.

Guaranteed Exchange Rates

See "Multi-Currency Service," page 170.

Credit Card Services Using the Simple Order API | January 2016

122

Chapter 5

Optional Features

Installment Payments
Services:

Authorization

Captureonly on CyberSource through VisaNet with American Express or on FDC

Nashville Global

Processors and card types:

See the following table.

Table 28

Processors That Support Installment Payments

Processors

Credit Card Types

Chase Paymentech Solutions

Visa

Cielo

Visa, MasterCard, American Express, Diners

Club, JCB, Elo, Aura
On Cielo, installment payments are not
supported for debit transactions.

CyberSource Latin American Processing

Visa

Note CyberSource Latin American Processing

is the CyberSource name for Braspag.
CyberSource provides two processors for Latin
America: CyberSource Latin American
Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo,
which is supported in Brazil only.

Credit Card Services Using the Simple Order API | January 2016

123

Chapter 5

Table 28

Optional Features

Processors That Support Installment Payments (Continued)

Processors

Credit Card Types

CyberSource through VisaNet

Visa, American Express

Note Not all card types are supported for all

acquirers.
The supported acquirers are:

Arab African International Bank (AAIB)

Asia Commercial Bank (ACB)

Auckland Savings Bank (ASB)

Australia and New Zealand Banking Group

Limited (ANZ)

Axis Bank Ltd of India

Banco Nacional de Mxico (Banamex)

Bank of Ayudhya (BAY)

Bank of China (BOC)

Banque Pour Le Commerce Exterieur Lao

(BCEL)

Commercial Bank of Qatar

CrediMax (Bahrain)

CTBC Bank Ltd.

Habib Bank Ltd (HBL)

HDFC Bank Ltd of India

Mashreq

National Bank of Abu Dhabi (NBAD)

Overseas Chinese Banking Corp (OCBC)

Rosbank

Vantiv

Vietcombank

VietinBank

Wing Hang Bank

Wing Lung Bank

FDC Compass

Visa

FDC Nashville Global

Visa, Discover, Diners Club, JCB (US Domestic)

For JCB cards, US Domestic means that the
currency is USD and your location is the U.S.,
Puerto Rico, Guam, U.S. Virgin Islands, or
Northern Mariana Islands.

FDMS Nashville

Visa

FDMS South

Visa

Litle

Visa

Credit Card Services Using the Simple Order API | January 2016

124

Chapter 5

Table 28

Optional Features

Processors That Support Installment Payments (Continued)

Processors

Credit Card Types

OmniPay-Ireland

Visa

OmniPay-Ireland is the CyberSource name

for HSBC International.
TSYS Acquiring Solutions

Visa

This feature enables your customer to pay for a single purchase of goods or services by
making multiple payments over a period of time agreed upon by you and your customer.

To indicate that a transaction on Chase Paymentech Solutions or FDC

Compass is an installment payment:
Step 1

Set ccAuthService_commerceIndicator to install.

Step 2

Include the following required fields in your authorization request:

invoiceHeader_merchantDescriptor

invoiceHeader_merchantDescriptorContact

For information about these fields, see "Chase Paymentech Solutions Merchant
Descriptors," page 136, and "FDC Compass Merchant Descriptors," page 147.
Step 3

You can include the following optional fields in your authorization request:

installment_sequence

installment_totalCount

For information about these fields, see Appendix A, "API Fields," on page 216.

To indicate that a transaction on Cielo is an installment payment:

Before submitting installment transactions, contact CyberSource Customer Support to
have your account configured for this feature.
Step 1

Include the following required field in your authorization request.

Step 2

installment_totalCount

You can include the optional ccAuthService_commerceIndicator field in your

authorization request. Set it to one of the following values:

internete-commerce transaction. This is the default value that CyberSource uses

when you do not include the commerce indicator field in the request.

spaMasterCard SecureCode transaction.

vbvVerified by Visa transaction.

Credit Card Services Using the Simple Order API | January 2016

125

Chapter 5

Step 3

Optional Features

You must include the following field in your authorization request if the corresponding
value is not set in your CyberSource account. If this value is set in your CyberSource
account, you can include the following field in your authorization request to override the
value in your CyberSource account:

installment_planType

For information about these fields, see Appendix A, "API Fields," on page 216.

To indicate that a transaction on CyberSource Latin American

Processing is an installment payment:

Note

CyberSource Latin American Processing is the CyberSource name for

Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil only.
The information in this section applies only to CyberSource Latin American
Processing (Braspag).

Step 1

Set ccAuthService_commerceIndicator to install.

Step 2

For a transaction in Brazil, you can include the following optional fields in your
authorization request:

installment_planType

installment_totalCount

For information about these fields, see Appendix A, "API Fields," on page 216.
Step 3

For a transaction in Mexico, installment payments are supported, but conditions vary, so
contact CyberSource Customer Support or your CyberSource account manager.

To indicate that a transaction on CyberSource through VisaNet is an

installment payment with American Express:
Include installment_planType or installment_totalCount in your authorization or
capture request.
For details about these fields, see Appendix A, "API Fields," on page 216.

Credit Card Services Using the Simple Order API | January 2016

126

Chapter 5

Optional Features

To indicate that a transaction on CyberSource through VisaNet is an

installment payment with Visa:
Step 1

Step 2

Set ccAuthService_commerceIndicator to install or install_internet:

installU.S. transaction or non-U.S. mail order / telephone order (MOTO)

transaction

install_internetnon-U.S. e-commerce (internet) transaction

You can include the following optional fields in your authorization request:

installment_amount

installment_frequency

installment_sequence

installment_totalAmount

installment_totalCount

For information about these fields, see Appendix A, "API Fields," on page 216.

To indicate that a transaction on FDC Nashville Global is an

installment payment:
Step 1

When you request the authorization service, set ccAuthService_commerceIndicator to

install.

Step 2

When you request the capture service, include the following required fields in the request:

installment_sequence

installment_totalCount

For information about these fields, see Appendix A, "API Fields," on page 216.

To indicate that a transaction on any other supported processor is an

installment payment:
Step 1

Set ccAuthService_commerceIndicator to install.

Step 2

Include the following required fields in your authorization request:

installment_sequence

installment_totalCount

For information about these fields, see Appendix A, "API Fields," on page 216.

Credit Card Services Using the Simple Order API | January 2016

127

Chapter 5

Optional Features

Japanese Payment Options

Services:

Authorization

Capture

Credit

Processors:

CCS (CAFIS)

JCN Gateway

Card types:

Visa

MasterCard

American Express

Diners Club

JCB

NICOS house card

ORICO house card

In addition to standard single payments, Japanese acquirers support the following

payment options:

Bonus payment

Installment payments (2 to 36 payments)

Revolving repayments

Before using one of these payment options, you must sign a contract with your acquirer.
Additionally, the funding cycle could differ when using these options. Contact your account
provider for details about contracts and funding cycles.
Some acquirers might not support all of these payment options. Additionally, a card holder
must sign a contract with an issuing bank before using one of these payment options.
Therefore, not all card holders take advantage of these payment options. Confirm
payment option availability with your account provider and the card holder before
implementing one of these payment options.

Important

CyberSource accepts requests with these payment options independently of

your agreements with acquirers. If you submit a request with one of these
payment options but do not have the necessary contracts and agreements in
place, an error might not occur until the acquirer processes the settlement file,
which usually occurs only once a month.

Credit Card Services Using the Simple Order API | January 2016

128

Chapter 5

Optional Features

The following table lists the API fields required for each payment option.
Table 29

API Fields for Japanese Payment Options

Payment Option

API Fields Required

Bonus payment

jpo_paymentMethod

Installment payments
(2 to 36 payments)

jpo_paymentMethod, jpo_installments

Revolving repayments

jpo_paymentMethod

When you omit jpo_paymentMethod from your request, CyberSource processes the
request as a single payment.

Verbal Authorizations
When you submit a capture request with a verbal authorization, if the initial authorization
included Japanese payment option fields, the capture request also must include the
Japanese payment option fields.

Stand-Alone Credits
When you perform a stand-alone credit for a transaction that included Japanese payment
option fields, the request for the stand-alone credit must also include the Japanese
payment option fields. When a request for a stand-alone credit is made with CCS (CAFIS)
or JCN Gateway, most acquirers make inquiries about the purpose of such a request.
CyberSource recommends using follow-on credits instead of stand-alone credits
whenever possible.

Additional Information
For more information about the Japanese payment options, contact Customer Support of
CyberSource KK (Japan).

JCB J/Secure
See "Payer Authentication," page 171.

Credit Card Services Using the Simple Order API | January 2016

129

Chapter 5

Optional Features

Level II Data
Services:

Capture

Credit

For a description of Level II data, including the list of processors and card types for which
CyberSource supports Level II, see Level II and Level III Processing Using the Simple
Order API.

Level III Data

Services:

Capture

Credit

For a description of Level III data, including the list of processors and card types for which
CyberSource supports Level III, see Level II and Level III Processing Using the Simple
Order API.

MasterCard SecureCode
See "Payer Authentication," page 171.

MasterPass
Services:

Authorization

CreditChase Paymentech Solutions and CyberSource through VisaNet only

Processors:

Chase Paymentech Solutions

CyberSource through VisaNet

OmniPay Direct

Credit Card Services Using the Simple Order API | January 2016

130

Chapter 5

Optional Features

To indicate that a request is for a MasterPass transaction:

Before requesting MasterPass transactions, contact CyberSource Customer Support to
have your account configured for this feature.
On Chase Paymentech Solutions or CyberSource through VisaNet, include the wallet_
type field in your authorization or credit request.
On OmniPay Direct, include the following fields in your authorization request:

wallet_type

paymentSolution

For details about these fields, see Appendix A, "API Fields," on page 216.

Merchant Descriptors
Processors:

"AIBMS Merchant Descriptors," page 132

"American Express Direct Merchant Descriptors," page 133

"Chase Paymentech Solutions Merchant Descriptors," page 136

"Cielo Merchant Descriptors," page 139

"CyberSource through VisaNet Merchant Descriptors," page 140

"Elavon Merchant Descriptors," page 146

"FDC Compass Merchant Descriptors," page 147

"FDC Nashville Global Merchant Descriptors," page 151

"FDMS South Merchant Descriptors," page 156

"Global Collect Merchant Descriptors," page 157

"GPN Merchant Descriptors," page 158

"Litle Merchant Descriptors," page 159

"OmniPay Direct Merchant Descriptors," page 162

"OmniPay-Ireland Merchant Descriptors," page 164

"Streamline Merchant Descriptors," page 166

"TSYS Acquiring Solutions Merchant Descriptors," page 167

Credit Card Services Using the Simple Order API | January 2016

131

Chapter 5

Optional Features

AIBMS Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests, check with your bank to find out
whether you must pre-register your merchant descriptor information with them.
AIBMS supports the merchant descriptors listed in the following table.

Table 30

Merchant Descriptor Fields for AIBMS

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Merchant description that is displayed on the

cardholder's statement.

ccAuthService

String (22)

When you include more than one consecutive

space, extra spaces are removed.

ccCaptureService
ccCreditService
Required when
invoiceHeader_
merchantDescriptor
Contact is included in
the request.

invoiceHeader_
merchantDescriptor
Contact

Merchant contact information, such as a phone

number, that is displayed on the cardholder's
statement.
When you include more than one consecutive
space, extra spaces are removed.

Credit Card Services Using the Simple Order API | January 2016

ccAuthService (O)

String (13)

ccCaptureService (O)
ccCreditService (O)

132

Chapter 5

Optional Features

American Express Direct Merchant

Descriptors
Services:

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests:

Contact American Express Direct to register to use merchant descriptors.

Contact CyberSource Customer Support to have your account configured for this
feature.

American Express Direct supports the merchant descriptors listed in the following table.
Even though the following fields are supported, American Express Direct does not always
include all these fields on the cardholders statement.

Table 31

Merchant Descriptor Fields for American Express Direct

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. American Express

displays this value on the cardholders
statement. When you include more than
one consecutive space, extra spaces are
removed.

ccCaptureService

String (27)

ccCreditService
See the description.

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1
When you include the merchant descriptor
contact field in your request, you must
provide a merchant descriptor in this field or
in your CyberSource account. When you do
not include the merchant descriptor contact
in your request, the merchant descriptor is
optional.
Aggregator Merchants
If you are an aggregator, see "Aggregator
Support," page 100, for information about
merchant descriptors for aggregator
merchants.
1 To add this value to your CyberSource account, contact CyberSource Customer Support.

Credit Card Services Using the Simple Order API | January 2016

133

Chapter 5

Table 31

Optional Features

Merchant Descriptor Fields for American Express Direct (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptorCity

City or phone number for your business.

American Express might display this value
on the cardholders statement.

ccCaptureService (O)

String (21)

ccCreditService (O)

For card-present transactions, American

Express recommends that this field contain
the city in which your business is located.
For card-not-present transactions,
American Express recommends that this
field contain the phone number for your
business. It should be a toll free number or
a local number.
When you do not include this value in your
request, CyberSource uses the value that is
in your CyberSource account.1
invoiceHeader_
merchantDescriptor
Contact

Contact information for your business.

American Express might display this value
on the cardholders statement. This value
could be used to resolve billing inquiries
and disputes. When you include more than
one consecutive space, extra spaces are
removed.

ccCaptureService (O)

String (40)

ccCreditService (O)

For card-present transactions, American

Express recommends that this field contain
your phone number. For card-not-present
transactions, American Express
recommends that this field contain the URL
for your web site.
When you do not include this value in your
request, CyberSource uses the URL or
phone number in your CyberSource
account.1
invoiceHeader_
merchantDescriptor
Country

Country code for your business location.

American Express might display this value
on the cardholders statement. Use the
standard ISO Standard Country Codes.

ccCaptureService (O)

String (2)

ccCreditService (O)

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1
1 To add this value to your CyberSource account, contact CyberSource Customer Support.

Credit Card Services Using the Simple Order API | January 2016

134

Chapter 5

Table 31

Optional Features

Merchant Descriptor Fields for American Express Direct (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
PostalCode

Postal code for your business location.

American Express might display this value
on the cardholders statement.

ccCaptureService (O)

String (15)

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1

ccCreditService
(Required when you are
an aggregator;
otherwise, optional)

Before sending the postal code to the

processor, CyberSource removes all nonalphanumeric characters and, if the
remaining value is longer than nine
characters, truncates the value starting from
the right side.
invoiceHeader_
merchantDescriptor
State

State code or region code for your business

location. American Express might display
this value on the cardholders statement.
For the U.S. and Canada, use the standard
State, Province, and Territory Codes for the
United States and Canada.

ccCaptureService (O)

String (3)

ccCreditService (O)

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1
invoiceHeader_
merchantDescriptor
Street

Street address for your business location.

American Express might display this value
on the cardholders statement. If the street
address is more than 38 characters, use
meaningful abbreviations.

ccCaptureService (O)

String (38)

ccCreditService
(Required when you are
an aggregator;
otherwise, optional)

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1
1 To add this value to your CyberSource account, contact CyberSource Customer Support.

Credit Card Services Using the Simple Order API | January 2016

135

Chapter 5

Optional Features

Chase Paymentech Solutions Merchant

Descriptors
Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Chase Paymentech Solutions restricts the number of merchant descriptors you
can use.
Note

Before including merchant descriptors in your requests:

Prepare a list of the merchant descriptors you plan to use.

Contact Chase Paymentech Solutions for information about working with merchant
descriptors.

Contact CyberSource Customer Support to have your account enabled for this
feature.

Chase Paymentech Solutions supports the merchant descriptors described in "API

Fields," page 138. The information in that section supersedes the information in
Appendix A, "API Fields," on page 216.

Merchant Descriptor Logic

Important

Some of the logic described in this section might not apply to your
implementation depending on which parts of the merchant descriptor
functionality are enabled in your CyberSource account.

The logic described in this section applies to the invoiceHeader_merchantDescriptor

and invoiceHeader_merchantDescriptorContact fields. It does not apply to the
Transaction Advice Addendum (TAA) fields.
For authorizations, CyberSource provides merchant descriptor information to Chase
Paymentech Solutions only if you include merchant descriptor information in the
authorization request.
For captures, CyberSource provides merchant descriptor information to Chase
Paymentech Solutions if you provide merchant descriptor information in the capture
request, authorization request, or your CyberSource account. When you do not include

Credit Card Services Using the Simple Order API | January 2016

136

Chapter 5

Optional Features

the merchant descriptor values in a capture request, CyberSource uses the values from
the authorization request. If you did not include the merchant descriptor values in the
authorization request, CyberSource uses the corresponding values from your
CyberSource account.
For follow-on credits, CyberSource provides merchant descriptor information to Chase
Paymentech Solutions if you provide merchant descriptor information in the credit request,
capture request, authorization request, or your CyberSource account. When you do not
include the merchant descriptor values in a follow-on credit request, CyberSource uses
the values from the capture request. If you did not include the merchant descriptor values
in the capture request, CyberSource uses the values from the authorization request. If you
did not include the merchant descriptor values in the authorization request, CyberSource
uses the corresponding values from your CyberSource account.
For stand-alone credits, CyberSource provides merchant descriptor information to Chase
Paymentech Solutions if you provide merchant descriptor information in the credit request
or your CyberSource account. When you do not include the merchant descriptor values in
a stand-alone credit request, CyberSource uses the corresponding values from your
CyberSource account.
To add a merchant descriptor value to your CyberSource account, contact CyberSource
Customer Support.

Characters
In the merchant descriptor fields, question marks are replaced with spaces.
Do not use the following punctuation characters in the merchant descriptor fields because
they will cause the transaction to be rejected with reason code 233:

caret ( ^ )

backslash ( \ )

open bracket ( [ )

close bracket ( ] )

tilde ( ~ )

accent ( ` )

Credit Card Services Using the Simple Order API | January 2016

137

Chapter 5

Optional Features

API Fields
Table 32

Merchant Descriptor Fields for Chase Paymentech Solutions

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
amexDataTAA1

Four Transaction Advice Addendum (TAA)

fields. These fields are used to display
descriptive information about a transaction on
the customers American Express card
statement. When you send TAA fields, start
with invoiceHeader_amexDataTAA1,
then ...TAA2, and so on. Skipping a TAA field
causes subsequent TAA fields to be ignored.

ccCaptureService (O)

String (40)

invoiceHeader_
amexDataTAA2
invoiceHeader_
amexDataTAA3
invoiceHeader_
amexDataTAA4

invoiceHeader_
merchantDescriptor

ccCreditService (O)

These fields are frequently used for Level II

transactions. See Level II and Level III
Processing Using the Simple Order API.
Merchant description that is displayed on the
cardholder's statement. When you include
more than one consecutive space, extra
spaces are removed.

ccAuthService

For an installment transaction, you must use

one of the following formats:

Required when
invoiceHeader_
merchantDescriptor
Contact is included in
the request.

<12-character merchant name>*PYMT<N>

OF<M>

<7-character merchant name>*PYMT<N>

OF<M>

<3-character merchant name>*PYMT<N>

OF<M>

String (22)

ccCaptureService
ccCreditService

where <N> is the payment number and <M> is

the total number of payments. For example, for
the third installment in a series of seven
payments, the PYMT<N>OF<M> portion of the
merchant descriptor would be PYMT3OF7.
For other types of transactions, you must use
one of the following formats:

<12-character merchant name>*

<9-character product description>

<7-character merchant name>*

<14-character product description>

<3-character merchant name>*

<18-character product description>

This field is supported only for Visa,

MasterCard, and Discover.

Credit Card Services Using the Simple Order API | January 2016

138

Chapter 5

Table 32

Optional Features

Merchant Descriptor Fields for Chase Paymentech Solutions (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
Contact

Merchant contact information, such as a phone

number, that is displayed on the cardholder's
statement. When you include more than one
consecutive space, extra spaces are removed.

ccAuthService

String (13)

You must use one of the following formats:

Required when
invoiceHeader_
merchantDescriptor is
included in the request.

PCCCCCCCCCCCC

NNN-NNN-NNNN

NNN-NNN-NAAA

NNN-NNN-AAAA

NNN-AAAAAAA

ccCaptureService
ccCreditService

where:

A: Alphanumeric (alpha or numeric)

C: Character (alpha or blank)

N: Numeric

P: Alpha

This field is supported only for Visa,

MasterCard, and Discover.

Cielo Merchant Descriptors

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Services:

Table 33

Authorization

Merchant Descriptor Fields for Authorizations for Cielo

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. This name is displayed

on the cardholders statement. When you do
not include this value in your authorization
request, CyberSource uses the value from
your CyberSource account.

ccAuthService (O)

String (13)

Credit Card Services Using the Simple Order API | January 2016

139

Chapter 5

Optional Features

CyberSource through VisaNet Merchant

Descriptors
Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.

Important

Before using merchant descriptors in your requests, check with your bank to
find out if you must pre-register your merchant descriptor information with
them.

CyberSource through VisaNet supports the merchant descriptors shown in Table 34,
"Merchant Descriptor Fields for Authorizations for CyberSource through VisaNet," on
page 140 for authorizations, and the merchant descriptors shown in Table 35, "Merchant
Descriptor Fields for Captures and Credits for CyberSource through VisaNet," on
page 143 for captures and credits.
CyberSource always provides merchant descriptor information to the acquirer for all your
authorization, capture, and credit transactions. The field descriptions in the following two
tables describe the values that CyberSource uses when you do not include merchant
descriptor information in your requests.

Table 34

Merchant Descriptor Fields for Authorizations for

CyberSource through VisaNet

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. This name is displayed

on the cardholders statement. When you
include more than one consecutive space,
extra spaces are removed.

ccAuthService (O)

String (23)

When you do not include this value in your

authorization request, CyberSource uses the
merchant name from your CyberSource
account.

Important This value must consist of

English characters.

Credit Card Services Using the Simple Order API | January 2016

140

Chapter 5

Table 34

Optional Features

Merchant Descriptor Fields for Authorizations for

CyberSource through VisaNet (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptorCity

City for your business location. This value

might be displayed on the cardholders
statement.

ccAuthService (O)

String (13)

ccAuthService (O)

String (14)

ccAuthService (O)

String (2)

When you do not include this value in your

authorization request, CyberSource uses the
merchant city from your CyberSource
account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptor
Contact

Telephone number for your business. This

value might be displayed on the cardholders
statement. When you include more than one
consecutive space, extra spaces are
removed.
When you do not include this value in your
authorization request, CyberSource uses the
merchant phone number from your
CyberSource account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptor
Country

Country code for your business location. Use

the standard ISO Standard Country Codes.
This value might be displayed on the
cardholders statement.
When you do not include this value in your
authorization request, CyberSource uses the
merchant country from your CyberSource
account.

Important This value must consist of

English characters.

Credit Card Services Using the Simple Order API | January 2016

141

Chapter 5

Table 34

Optional Features

Merchant Descriptor Fields for Authorizations for

CyberSource through VisaNet (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
PostalCode

Postal code for your business location. This

value might be displayed on the cardholders
statement.

ccAuthService (O)

String (14)

ccAuthService (O)

String (3)

If your business is domiciled in the U.S., you

can use a 5-digit or 9-digit postal code. A
9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
If your business is domiciled in Canada, you
can use a 6-digit or 9-digit postal code. A
6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
When you do not include this value in your
authorization request, CyberSource uses the
merchant postal code from your CyberSource
account.

Important This value must consist of

English characters.
Important MasterCard requires a postal
code for any country that uses postal codes.
You can provide the postal code in your
CyberSource account or you can include this
field in your request.
invoiceHeader_
merchantDescriptor
State

State code or region code for your business

location. This value might be displayed on the
cardholders statement.
For the U.S. and Canada, use the standard
State, Province, and Territory Codes for the
United States and Canada.
When you do not include this value in your
authorization request, CyberSource uses the
merchant state from your CyberSource
account.

Important This value must consist of

English characters.

Credit Card Services Using the Simple Order API | January 2016

142

Chapter 5

Table 35

Optional Features

Merchant Descriptor Fields for Captures and Credits for

CyberSource through VisaNet

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. This name is displayed

on the cardholders statement. When you
include more than one consecutive space,
extra spaces are removed.

ccCaptureService (O)

String (23)

ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant name from your CyberSource
account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptor
Alternate

Alternate contact information for your

business, such as an email address or URL.
This value might be displayed on the
cardholders statement.

ccCaptureService (O)

String (13)

ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the merchant URL from your CyberSource
account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptorCity

City for your business location. This value

might be displayed on the cardholders
statement.

ccCaptureService (O)

String (13)

ccCreditService (O)

When you do not include this value in your

capture or credit request for a card-present
transaction, CyberSource uses the value from
your authorization request. If you did not
include this value in your authorization
request, CyberSource uses the merchant city
from your CyberSource account.
When you do not include this value in your
capture or credit request for a card-notpresent transaction, CyberSource uses the
merchant city from your CyberSource account.

Important This value must consist of

English characters.

Credit Card Services Using the Simple Order API | January 2016

143

Chapter 5

Table 35

Optional Features

Merchant Descriptor Fields for Captures and Credits for

CyberSource through VisaNet (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
Contact

Telephone number for your business. This

value might be displayed on the cardholders
statement. When you include more than one
consecutive space, extra spaces are removed.

ccCaptureService (O)

String (14)

ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant phone number from your
CyberSource account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptor
Country

Country code for your business location. Use

the standard ISO Standard Country Codes.
This value might be displayed on the
cardholders statement.

ccCaptureService (O)

String (2)

ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant country from your CyberSource
account.

Important This value must consist of

English characters.

Credit Card Services Using the Simple Order API | January 2016

144

Chapter 5

Table 35

Optional Features

Merchant Descriptor Fields for Captures and Credits for

CyberSource through VisaNet (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
PostalCode

Postal code for your business location. This

value might be displayed on the cardholders
statement.

ccCaptureService (O)

String (14)

ccCreditService (O)

If your business is domiciled in the U.S., you

can use a 5-digit or 9-digit postal code. A
9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
If your business is domiciled in Canada, you
can use a 6-digit or 9-digit postal code. A
6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
When you do not include this value in your
capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant postal code from your CyberSource
account.

Important This value must consist of

English characters.
Important MasterCard requires a postal
code for any country that uses postal codes.
You can provide the postal code in your
CyberSource account or you can include this
field in your request.

Credit Card Services Using the Simple Order API | January 2016

145

Chapter 5

Table 35

Optional Features

Merchant Descriptor Fields for Captures and Credits for

CyberSource through VisaNet (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
State

State code or region code for your business

location. This value might be displayed on the
cardholders statement.

ccCaptureService (O)

String (3)

ccCreditService (O)

For the U.S. and Canada, use the standard

State, Province, and Territory Codes for the
United States and Canada.
When you do not include this value in your
capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant state from your CyberSource
account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptor
Street

Street address for your business location. This

value might be displayed on the cardholders
statement.

ccCaptureService (O)

String (60)

ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the merchant street name from your
CyberSource account.

Important This value must consist of

English characters.

Elavon Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that can be displayed on a
cardholders statement.
Before including merchant descriptors in your requests, check with your bank to find out
whether you must pre-register your merchant descriptor information with them.
Elavon supports the merchant descriptor described in the following table for transactions
with Diner Club.

Credit Card Services Using the Simple Order API | January 2016

146

Chapter 5

Optional Features

Table 36

Merchant Descriptor Field for Elavon

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Merchant description that is displayed on the

cardholder's statement.

ccAuthService

String (22)

When you include more than one consecutive

space, extra spaces are removed.

ccCaptureService
ccCreditService

This field is supported only for Diners Club.

FDC Compass Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
FDC Compass restricts the number of merchant descriptors you can use.
Note

Before including merchant descriptors in your requests:

Prepare a list of the merchant descriptors you plan to use.

Contact FDC Compass for information about working with merchant descriptors.

Contact CyberSource Customer Support to have your account enabled for this
feature.

FDC Compass supports the merchant descriptors described in "API Fields," page 148.
The information in that section supersedes the information in Appendix A, "API Fields," on
page 216.

Credit Card Services Using the Simple Order API | January 2016

147

Chapter 5

Optional Features

Characters
In the merchant descriptor fields, question marks are replaced with spaces.
Do not use the following punctuation characters in the merchant descriptor fields because
they will cause the transaction to be rejected with reason code 233:

caret ( ^ )

backslash ( \ )

open bracket ( [ )

close bracket ( ] )

tilde ( ~ )

accent ( ` )

API Fields
Table 37

Merchant Descriptor Fields for FDC Compass

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
amexDataTAA1

Four Transaction Advice Addendum (TAA)

fields. These fields are used to display
descriptive information about a transaction on
the customers American Express card
statement. When you send TAA fields, start
with invoiceHeader_amexDataTAA1,
then ...TAA2, and so on. Skipping a TAA field
causes subsequent TAA fields to be ignored.

ccCaptureService (O)

String (40)

invoiceHeader_
amexDataTAA2
invoiceHeader_
amexDataTAA3
invoiceHeader_
amexDataTAA4

ccCreditService (O)

These fields are frequently used for Level II

transactions. See Level II and Level III
Processing Using the Simple Order API.

Credit Card Services Using the Simple Order API | January 2016

148

Chapter 5

Table 37

Optional Features

Merchant Descriptor Fields for FDC Compass (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Merchant description that is displayed on the

cardholder's statement. When you include
more than one consecutive space, extra
spaces are removed.

ccAuthService

String (22)

For an installment transaction, you must use

one of the following formats:

Required when
invoiceHeader_
merchantDescriptor
Contact is included in
the request.

<12-character merchant name>*PYMT<N>

OF<M>

<7-character merchant name>*PYMT<N>

OF<M>

<3-character merchant name>*PYMT<N>

OF<M>

ccCaptureService
ccCreditService

where <N> is the payment number and <M> is

the total number of payments. For example, for
the third installment in a series of seven
payments, the PYMT<N>OF<M> portion of the
merchant descriptor would be PYMT3OF7.
For other types of transactions, you must use
one of the following formats:

<12-character merchant name>*

<9-character product description>

<7-character merchant name>*

<14-character product description>

<3-character merchant name>*

<18-character product description>

Credit Card Services Using the Simple Order API | January 2016

149

Chapter 5

Table 37

Optional Features

Merchant Descriptor Fields for FDC Compass (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
Contact

Merchant contact information, such as a phone

number, that is displayed on the cardholder's
statement. When you include more than one
consecutive space, extra spaces are removed.

ccAuthService

String (13)

You must use one of the following formats:

Required when
invoiceHeader_
merchantDescriptor is
included in the request.

PCCCCCCCCCCCC

NNN-NNN-NNNN

NNN-NNN-NAAA

NNN-NNN-AAAA

NNN-AAAAAAA

ccCaptureService
ccCreditService

where:

A: Alphanumeric (alpha or numeric)

C: Character (alpha or blank)

N: Numeric

P: Alpha

Credit Card Services Using the Simple Order API | January 2016

150

Chapter 5

Optional Features

FDC Nashville Global Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests:

Contact FDC Nashville Global to register to use merchant descriptors.

Contact CyberSource Customer Support to have your account enabled for this
feature.

FDC Nashville Global supports the merchant descriptors described in "API Fields,"
page 153. The information in that section supersedes the information in Appendix A, "API
Fields," on page 216.

Merchant Descriptor Logic

Important

Some of the logic described in this section might not apply to your
implementation depending on which parts of the merchant descriptor
functionality are enabled in your CyberSource account.

You are responsible for ensuring that all the merchant descriptor location
information that CyberSource sends to the processor is compatible.
Important

For example, if a request message includes one merchant descriptor location

field, CyberSource might use the information in your CyberSource account to
populate the remaining merchant descriptor location values that it sends to
the processor. CyberSource does not check the merchant descriptor values to
ensure that the combination of values from the request message and from
your CyberSource account are compatible.
To avoid a mismatch of merchant descriptor location values, CyberSource
recommends that you include all the merchant descriptor location fields in a
request or do not include any merchant descriptor location fields in a request.
For authorizations, CyberSource provides merchant descriptor information to FDC
Nashville Global only if you include merchant descriptor information in the authorization
request. For each merchant descriptor, when you do not include the merchant descriptor
value in an authorization request, CyberSource does not send a merchant descriptor
value to FDC Nashville Global.

Credit Card Services Using the Simple Order API | January 2016

151

Chapter 5

Optional Features

For captures, CyberSource provides merchant descriptor information to FDC Nashville

Global if you provide merchant descriptor information in the capture request, authorization
request, or your CyberSource account. For each merchant descriptor, when you do not
include the merchant descriptor value in a capture request, CyberSource uses the value
from the authorization request. If you did not include the merchant descriptor value in the
authorization request, CyberSource uses the corresponding value from your CyberSource
account. If the value is not included in your CyberSource account, FDC Nashville Global
uses the value from your First Data merchant master file.
For follow-on credits, CyberSource provides merchant descriptor information to FDC
Nashville Global if you provide merchant descriptor information in the credit request,
capture request, authorization request, or your CyberSource account. For each merchant
descriptor, when you do not include the merchant descriptor value in a follow-on credit
request, CyberSource uses the value from the capture request. If you did not include the
merchant descriptor value in the capture request, CyberSource uses the value from the
authorization request. If you did not include the merchant descriptor value in the
authorization request, CyberSource uses the corresponding value from your CyberSource
account. If the value is not included in your CyberSource account, FDC Nashville Global
uses the value from your First Data merchant master file.
For stand-alone credits, CyberSource provides merchant descriptor information to FDC
Nashville Global if you provide merchant descriptor information in the credit request or
your CyberSource account. For each merchant descriptor, when you do not include the
merchant descriptor value in a stand-alone credit request, CyberSource uses the
corresponding value from your CyberSource account. If the value is not included in your
CyberSource account, FDC Nashville Global uses the value from your First Data
merchant master file.
To add a merchant descriptor value to your CyberSource account, contact CyberSource
Customer Support.

Credit Card Services Using the Simple Order API | January 2016

152

Chapter 5

Optional Features

API Fields
Table 38

Merchant Descriptor Fields for FDC Nashville Global

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Business description. This value must consist

of your business name. When payments are
made in installments, this value must also
include installment information such as 1 of 5
or 3 of 7.

ccAuthService (O)

String (22)

This value is displayed on the cardholders

statement.
For information about what happens when you
do not include this value in your request, see
"Merchant Descriptor Logic," page 151.

invoiceHeader_
merchantDescriptor
Alternate

Alternate contact information for your

business, such as an email address or URL.
This value might be displayed on the
cardholders statement.

ccCaptureService (O)
ccCreditService (O)
If you include this field
in a request, you must
also include
invoiceHeader_
merchantDescriptor
Contact and
invoiceHeader_
merchantDescriptor
State.
ccAuthService (O)

String (13)

ccCaptureService (O)
ccCreditService (O)

For information about what happens when you

do not include this value in your request, see
"Merchant Descriptor Logic," page 151. For
authorizations, CyberSource does not provide
this value to the processor. Instead,
CyberSource stores this value and sends it to
the processor for captures and follow-on
credits.
invoiceHeader_
merchantDescriptor
Contact

Contact information for your business. For a

card-present request, this value must be the
city in which your store or outlet is located. For
a card-not-present request, this value must be
your customer service telephone number.
When you include more than one consecutive
space, extra spaces are removed.
This value might be displayed on the
cardholders statement.
For information about what happens when you
do not include this value in your request, see
"Merchant Descriptor Logic," page 151.

Credit Card Services Using the Simple Order API | January 2016

ccAuthService (O)

String (11)

ccCaptureService (O)
ccCreditService (O)
If you include this field
in a request, you must
also include
invoiceHeader_
merchantDescriptor
and invoiceHeader_
merchantDescriptor
State.

153

Chapter 5

Table 38

Optional Features

Merchant Descriptor Fields for FDC Nashville Global (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
Country

Country in which your business is located. Use

the two-character ISO Standard Country
Codes.

ccAuthService (O)

String (2)

This value might be displayed on the

cardholders statement.

ccCaptureService (O)
ccCreditService (O)

For information about what happens when you

do not include this value in your request, see
"Merchant Descriptor Logic," page 151.
invoiceHeader_
merchantDescriptor
PostalCode

Postal code for your business location.

ccAuthService (O)

This value might be displayed on the

cardholders statement.

ccCaptureService (O)

String (10)

ccCreditService (O)

When the merchant descriptor country is the

U.S., the postal code must consist of five digits
or nine digits. A 9-digit postal code must follow
this format:
[5 digits][dash][4 digits]
Example: 12345-6789
When the merchant descriptor country is
Canada, the 6-digit postal code must follow
this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
For information about what happens when you
do not include this value in your request, see
"Merchant Descriptor Logic," page 151.

Credit Card Services Using the Simple Order API | January 2016

154

Chapter 5

Table 38

Optional Features

Merchant Descriptor Fields for FDC Nashville Global (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
State

State or territory in which your business is

located. cardholders statement.

ccAuthService (O)

String (20)

When the merchant descriptor country is the

U.S. or Canada, use the State, Province, and
Territory Codes for the United States and
Canada.

ccCreditService (O)

For information about what happens when you

do not include this value in your request, see
"Merchant Descriptor Logic," page 151.

If you include this field

in a request, you must
also include
invoiceHeader_
merchantDescriptor
and invoiceHeader_
merchantDescriptor
Contact.

Street address for your business location.

ccAuthService (O)

When you include this value in your request,

CyberSource recommends the following:

ccCaptureService (O)

This value might be displayed on the

cardholders statement.

invoiceHeader_
merchantDescriptor
Street

ccCaptureService (O)

If you are located in the United States or

Canada, also include the merchant
descriptor country, merchant descriptor
state, and merchant descriptor postal code
in your request.

If you are not located in the United States or

Canada, also include the merchant
descriptor country and merchant descriptor
postal code in your request.

String (60)

ccCreditService (O)
FDC Nashville Global
recommends that you
include this value for
debit card requests and
for American Express
credit card requests.

This value might be displayed on the

cardholders statement.
For information about what happens when you
do not include this value in your request, see
"Merchant Descriptor Logic," page 151.

Credit Card Services Using the Simple Order API | January 2016

155

Chapter 5

Optional Features

FDMS South Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests:

Contact FDMS South to register to use merchant descriptors.

Contact CyberSource Customer Support to have your account configured for this
feature.

FDMS South permits you to send a unique merchant descriptor with every transaction.
This is useful if you want to include the order number as part of the merchant descriptor.
FDMS South supports the merchant descriptor described in the following table.

Table 39

Merchant Descriptor Field for FDMS South

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Merchant description that is displayed on the

cardholder's statement.

ccAuthService

String (22)

When you include more than one consecutive

space, extra spaces are removed.

ccCaptureService
ccCreditService
Required when
invoiceHeader_
merchantDescriptor
Contact is included in
the request.

Credit Card Services Using the Simple Order API | January 2016

156

Chapter 5

Optional Features

Global Collect Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests, contact CyberSource Customer
Support to have your account configured for this feature.
Global Collect supports the merchant descriptor described in the following table.

Table 40

Merchant Descriptor Field for Global Collect

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Merchant description that is displayed on the

cardholder's statement.

ccAuthService

String (22)

When you include more than one consecutive

space, extra spaces are removed.

ccCaptureService
ccCreditService
Required when
invoiceHeader_
merchantDescriptor
Contact is included in
the request.

Credit Card Services Using the Simple Order API | January 2016

157

Chapter 5

Optional Features

GPN Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests, contact your merchant account
provider to register to use merchant descriptors.
GPN supports the merchant descriptors listed in the following table.

Table 41

Merchant Descriptor Fields for GPN

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Merchant description that is displayed on the

cardholder's statement.

ccAuthService

String (22)

When you include more than one consecutive

space, extra spaces are removed.

ccCaptureService
ccCreditService
Required when
invoiceHeader_
merchantDescriptor
Contact is included in
the request.

invoiceHeader_
merchantDescriptor
Contact

Merchant contact information, such as a phone

number, that is displayed on the cardholder's
statement.
When you include more than one consecutive
space, extra spaces are removed.

Credit Card Services Using the Simple Order API | January 2016

ccAuthService (O)

String (13)

ccCaptureService (O)
ccCreditService (O)

158

Chapter 5

Optional Features

Litle Merchant Descriptors

Services:

Authorization

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests:

Contact Litle to register to use merchant descriptors.

Contact CyberSource Customer Support to have your account configured for this
feature.

Note

Litle accepts merchant descriptors in authorization requests and stand-alone

credit requests, not in capture requests or follow-on credit requests. Merchant
descriptors included in capture or follow-on credit requests are not sent to Litle.

If merchant descriptors are enabled for your CyberSource account, CyberSource always
provides merchant descriptor information to the processor for you for all authorization
transactions. When you do not include merchant descriptor information in your
authorization requests, CyberSource uses the default values in your CyberSource
account.
American Express Direct supports the merchant descriptors listed in the following table.
Even though the following fields are supported, American Express Direct does not always
include all these fields on the cardholders statement.

Credit Card Services Using the Simple Order API | January 2016

159

Chapter 5

Table 42

Optional Features

Merchant Descriptor Fields for Litle

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. This name is

displayed on the cardholders statement.
When you include more than one
consecutive space, extra spaces are
removed.

ccAuthService

String (22)

ccCreditService
See the description.

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1
When you include the merchant descriptor
contact field in your request, you must
provide a merchant descriptor in this field or
in your CyberSource account. When you do
not include the merchant descriptor contact
in your request, the merchant descriptor is
optional.
You can use one of the following formats for
the merchant descriptor field. You are not
required to use these formats.

<12-character prefix>*<9-character
product description>

<7-character prefix>*<14-character
product description>

<3-character prefix>*<18-character
product description>

When you use one of these formats:

The prefix in the merchant descriptor

field must be exactly the same as the
prefix set in your Litle account. Typically,
the prefix is your merchant name.

The valid characters for the merchant

descriptor are:

Numbers

Letters

The following special characters:

ampersand (&), asterisk (*), dash (-),
pound sign (#), comma, and period

1 To add this value to your CyberSource account, contact CyberSource Customer Support.

Credit Card Services Using the Simple Order API | January 2016

160

Chapter 5

Table 42

Optional Features

Merchant Descriptor Fields for Litle (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
Alternate

Alternate contact information for your

business, such as an email address or URL.
This value might be displayed on the
cardholders statement.

ccAuthService (O)

String (13)

ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource
uses the merchant URL from your
CyberSource account.
invoiceHeader_
merchantDescriptorCity

City or phone number for your business.

This value might be displayed on the
cardholders statement.

ccAuthService (O)

String (50)

ccCreditService (O)

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1
invoiceHeader_
merchantDescriptor
Contact

Contact information for your business. This

value might be displayed on the
cardholders statement. This value could be
used to resolve billing inquiries and
disputes. When you include more than one
consecutive space, extra spaces are
removed.

ccAuthService (O)

String (13)

ccCreditService (O)

When you do not include this value in your

request, CyberSource uses the URL or
phone number in your CyberSource
account.1
1 To add this value to your CyberSource account, contact CyberSource Customer Support.

Credit Card Services Using the Simple Order API | January 2016

161

Chapter 5

Optional Features

OmniPay Direct Merchant Descriptors

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.

Table 43

Merchant Descriptor Fields for OmniPay Direct

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. This name is displayed

on the cardholders statement. When you
include more than one consecutive space,
extra spaces are removed.

ccAuthService (O)

String (23)

ccCaptureService (O)
ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant name from your CyberSource
account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptorCity

City for your business location. This value

might be displayed on the cardholders
statement.
When you do not include this value in your
capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant city from your CyberSource account.

ccAuthService (O)

String (13)

ccCaptureService (O)
ccCreditService (O)

Important This value must consist of

English characters.

Credit Card Services Using the Simple Order API | January 2016

162

Chapter 5

Table 43

Optional Features

Merchant Descriptor Fields for OmniPay Direct (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
Country

Country code for your business location. Use

the standard ISO Standard Country Codes.
This value might be displayed on the
cardholders statement.

ccAuthService (O)

String (2)

ccCaptureService (O)
ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant country from your CyberSource
account.

Important This value must consist of

English characters.
invoiceHeader_
merchantDescriptor
PostalCode

Postal code for your business location. This

value might be displayed on the cardholders
statement.
If your business is domiciled in the U.S., you
can use a 5-digit or 9-digit postal code. A
9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789

ccAuthService (O)

String (10)

ccCaptureService (O)
ccCreditService (O)

If your business is domiciled in Canada, you

can use a 6-digit or 9-digit postal code. A
6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
When you do not include this value in your
capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant postal code from your CyberSource
account.

Important This value must consist of

English characters.
Important MasterCard requires a postal
code for any country that uses postal codes.
You can provide the postal code in your
CyberSource account or you can include this
field in your request.

Credit Card Services Using the Simple Order API | January 2016

163

Chapter 5

Table 43

Optional Features

Merchant Descriptor Fields for OmniPay Direct (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
State

State code or region code for your business

location. This value might be displayed on the
cardholders statement.

ccAuthService (O)

String (3)

For the U.S. and Canada, use the standard

State, Province, and Territory Codes for the
United States and Canada.

ccCaptureService (O)
ccCreditService (O)

When you do not include this value in your

capture or credit request, CyberSource uses
the value from your authorization request. If
you did not include this value in your
authorization request, CyberSource uses the
merchant state from your CyberSource
account.

Important This value must consist of

English characters.

OmniPay-Ireland Merchant Descriptors

OmniPay-Ireland is the CyberSource name for HSBC International.
Note

Services:

Authorization

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.

Credit Card Services Using the Simple Order API | January 2016

164

Chapter 5

Optional Features

Before including merchant descriptors in your requests:

Contact OmniPay-Ireland to register to use merchant descriptors.

Contact CyberSource Customer Support to have your account configured for this
feature.

OmniPay-Ireland supports the merchant descriptor field listed in the following table.

Table 44

Merchant Descriptor Fields for OmniPay-Ireland

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Merchant description that is displayed on the

cardholder's statement. When you include
more than one consecutive space, extra
spaces are removed.

ccAuthService

String (23)

ccCaptureService
ccCreditService

You must use one of the following formats:

<12-character merchant name>*

<10-character product description>

<7-character merchant name>*

<15-character product description>

<3-character merchant name>*

<19-character product description>

This field is supported only for Visa,

MasterCard, and Discover.

Credit Card Services Using the Simple Order API | January 2016

165

Chapter 5

Optional Features

Streamline Merchant Descriptors

Services:

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests:

Contact Streamline to let them know the values you will be sending in these fields.

Contact CyberSource Customer Support to have your account configured for this
feature.

Streamline supports the merchant descriptor fields listed in the following table. When you
include any merchant descriptors in a request, you must include all the fields in the
following table.

Table 45

Merchant Descriptor Fields for Streamline

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. When you include

more than one consecutive space, extra
spaces are removed.

ccCaptureService

String (22)

invoiceHeader_
merchantDescriptor
Contact

Contact information for your business.

When you include more than one
consecutive space, extra spaces are
removed.

ccCaptureService (O)

ccCreditService
String (13)

ccCreditService (O)

For card-present transactions, Streamline

recommends that this field contain your city.
For card-not-present transactions,
Streamline recommends that this field
contain the telephone number for your help
desk or the URL for your web site. When
you provide a telephone number in this
field, the first three digits must be numeric.
invoiceHeader_
merchantDescriptor
PostalCode

Postal code for your business location.

invoiceHeader_
merchantDescriptor
Street

Street address for your business location.

ccCaptureService (O)

String (10)

ccCreditService (O)

Credit Card Services Using the Simple Order API | January 2016

ccCaptureService (O)

String (26)

ccCreditService (O)

166

Chapter 5

Optional Features

TSYS Acquiring Solutions Merchant

Descriptors
Services:

Capture

Credit

This feature enables you to submit merchant descriptor values that are displayed on a
cardholders statement.
Before including merchant descriptors in your requests, contact CyberSource Customer
Support to have your account configured for this feature.
TSYS Acquiring Solutions supports the merchant descriptor fields listed in the following
table.

Table 46

Merchant Descriptor Fields for TSYS Acquiring Solutions

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor

Your business name. When you include

more than one consecutive space, extra
spaces are removed.

ccCaptureService

American
Express card
type: String
(38)

invoiceHeader_
merchantDescriptorCity

ccCreditService

When you do not include this value in your

capture or credit request, CyberSource
uses the business name from your
CyberSource account.1

Required when the

merchant descriptor
contact field is included
in the request;
otherwise, optional.

City for your business location.

ccCaptureService (O)

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1

ccCreditService (O)

All other card

types: String
(23)
American
Express card
type: String
(21)
All other card
types: String
(13)

1 To add this value to your CyberSource account, contact CyberSource Customer Support.

Credit Card Services Using the Simple Order API | January 2016

167

Chapter 5

Table 46

Optional Features

Merchant Descriptor Fields for TSYS Acquiring Solutions (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
merchantDescriptor
Contact

For card-present transactions, TSYS

Acquiring Solutions recommends that this
field contain the street address for your
business location. For card-not-present
transactions, TSYS Acquiring Solutions
recommends that this field contain the
phone number for your business or the URL
for your web site.

ccCaptureService (O)

String (13)

ccCreditService (O)

When you do not include this value in your

request, CyberSource uses the value that is
in your CyberSource account.1
1 To add this value to your CyberSource account, contact CyberSource Customer Support.

Merchant-Initiated Reversals and

Voids
Services:

Authorization

Capture

Credit

Processors:

Chase Paymentech Solutions

FDC Nashville Global

When you do not receive a reply message after sending a request to CyberSource, this
feature enables you to reverse or void the transaction that you requested.

To use merchant-initiated reversals and voids:

Step 1

Include the merchantTransactionIdentifier field in your original request for an

authorization, capture, sale, follow-on credit, or stand-alone credit.
The value of the merchant transaction ID must be unique for 60 days.
Note

Credit Card Services Using the Simple Order API | January 2016

168

Chapter 5

Step 2

Optional Features

When you do not receive a reply message for your original transaction request, reverse or
void the original transaction as described in the following table.

Transaction to
Reverse or Void

Procedure

Authorization

Request the full authorization reversal service as described in

"Creating a Full Authorization Reversal Request," page 48. Instead of
including the request ID in your request message, include the
merchantTransactionIdentifier field. The merchant transaction ID
links your reversal request to your original request.

Capture or sale

1 Request the void service as described in "Creating a Void

Request," page 71. Instead of including the request ID in your
request message, include the merchantTransactionIdentifier
field. The merchant transaction ID links your void request to your
original request.
2 Request the authorization reversal service as described in
"Creating a Full Authorization Reversal Request," page 48. Instead
of including the request ID in your request message, include the
merchantTransactionIdentifier field. The merchant transaction ID
links your reversal request to your original request.

Credit

Step 3

Request the void service as described in "Creating a Void Request,"

page 71. Instead of including the request ID in your request message,
include the merchantTransactionIdentifier field. The merchant
transaction ID links your void request to your original request.

If the data for the original transaction is in the CyberSource database, the reply message
for the reversal or void request includes the following fields:

originalTransaction_amount

originalTransaction_reasonCode

Micropayments
Services:

Authorization

Capture

Credit

Processors:

Most of the card types and processors that are supported by CyberSource

Micropayments are payments for less than one unit in the transactions currency.

Credit Card Services Using the Simple Order API | January 2016

169

Chapter 5

Optional Features

Multi-Currency Service
Services:

Authorization

Capture

Credit

Processor:

Chase Paymentech Solutions

If you sell your products in multiple countries, you might want to list your product prices in
your customers local currencies. The CyberSource multi-currency service provides
current, guaranteed exchange rates, which enables customers to pay using their local
currencies while enabling you to do business and settle transactions in your desired
currency.
For more information about the CyberSource multi-currency service, see the
Multicurrency Service for Chase Paymentech Solutions Using the Simple Order API.

Network Tokenization
See "Payment Network Tokenization," page 185.

Partial Shipments
See "Split Shipments," page 199.

Credit Card Services Using the Simple Order API | January 2016

170

Chapter 5

Optional Features

Payer Authentication
Before you implement payer authentication, you must contact CyberSource
Customer Support to have your account configured for this feature.
Important

When you request an authorization using a supported card type and a supported
processor, you can include payer authentication data in the request. You can use the
CyberSource payer authentication services to add Verified by Visa, JCB J/Secure,
MasterCard SecureCode, or American Express SafeKey support to your web site
without running additional software on your own server. The following table lists the cards
supported for each type of payer authentication. For a description of the CyberSource
payer authentication services, see the Payer Authentication Using the Simple Order API.

Table 47

Supported Card Types for Payer Authentication

Type of Payer
Authentication

Card Types

Verified by Visa

Visa

JCB J/Secure

JCB

MasterCard SecureCode

MasterCard, Maestro (International), Maestro (UK Domestic)

American Express SafeKey

American Express

Verified by Visa
Service:

Authorization

Processors:

AIBMS

Asia, Middle East, and Africa Gateway

Atos

Barclays

CCS (CAFIS)

Chase Paymentech Solutions

Cielo

CyberSource Latin American Processing: Verified by Visa is an emerging feature in

the Latin American region. It is not fully supported in all countries. Contact
CyberSource Customer Support for details.

Credit Card Services Using the Simple Order API | January 2016

171

Chapter 5

Note

Optional Features

CyberSource Latin American Processing is the CyberSource name for

Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil
only.

CyberSource through VisaNet: This feature is supported for acquirers that support the
Visa card type.

Elavon

FDC Compass

FDC Germany

FDI Australia

FDC Nashville Global

FDMS Nashville

FDMS South

Global Collect

GPN

HBoS

HSBC: HSBC is the CyberSource name for HSBC U.K.

JCN Gateway

Litle

LloydsTSB Cardnet

Moneris

OmniPay Direct

OmniPay-Ireland: OmniPay-Ireland is the CyberSource name for HSBC International.

RBS WorldPay Atlanta

Streamline

TSYS Acquiring Solutions

Verified by Visa reduces the risk of unauthorized use of a cardholder account. Verified by
Visa enables you to verify a customers identity through the use of a password, and
provides results to you in real time during the checkout process. For details about signing
up for and using Verified by Visa, contact your acquiring bank or go to the Visa web site:
http://visa.com/

Credit Card Services Using the Simple Order API | January 2016

172

Chapter 5

Note

Optional Features

For Visa Checkout transactions, do not map the Verified by Visa data from the
decrypt Visa Checkout data service reply message to the payer authentication
fields in the authorization request. CyberSource maps the data for you. The
transaction information that CyberSource sends to the processor includes the
Verified by Visa data.

To request the authorization of a Verified by Visa transaction:

Step 1

Add the fields listed in the following table to your ccAuthService request. The values for
these fields are in the reply from the validate authentication service
payerAuthValidateService. When you request payerAuthValidateService and
ccAuthService together, the data is automatically passed from one service to the other.
The authorization service returns a raw response code and a mapped response code:

Table 48

The raw response code is the value returned by the processor. CyberSource returns
this value in the ccAuthReply_cavvResponseCodeRaw field.

The mapped response code is the predefined CyberSource value that corresponds to
the raw response code. CyberSource returns this value in the ccAuthReply_
cavvResponseCode field. Appendix P, "Verified by Visa Response Codes," on
page 388 describes the mapped response codes.

Request Fields for Verified by Visa and JCB J/Secure

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

CAVVcardholder authentication verification value.

This value is a transaction identifier generated by the
issuing bank during Verified by Visa or JCB J/Secure
payer authentication. Must be 28-character base64
or 40-character hex binary.

ccAuthService_cavv

payerAuthValidateReply_
cavv

Used for all processors that support Verified by

Visa and/or JCB J/Secure.

Required when the commerce indicator is js,

vbv, or vbv_attempted.

Optional when the commerce indicator is

js_attempted.

For Verified by Visa on FDC Nashville Global,

CyberSource sets this field to the value for the
transaction identifier (XID) if the XID is present in
the authorization request and the CAVV is not
present.

Credit Card Services Using the Simple Order API | January 2016

173

Chapter 5

Table 48

Optional Features

Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

CAVV Algorithmalgorithm for generating the

CAVV.

ccAuthService_
cavvAlgorithm

payerAuthValidateReply_
cavvAlgorithm

ccAuthService_
commerceIndicator

payerAuthValidateReply_
commerceIndicator

ccAuthService_eciRaw

payerAuthValidateReply_
eciRaw

Used only for these processors:

Atos

Global Collect when a third-party provider

authenticates the transaction

Required when you include the CAVV in your

request.

You must not include the CAVV algorithm value in

your request when the CAVV is not included in
your request or when your processor is not Atos or
Global Collect.

Possible values:
0: HMAC (hash-based message authentication
code)
1: CVV
2: CVV with ATN

ECIelectronic commerce indicator.

Used for all processors that support Verified by

Visa and/or JCB J/Secure.

Always required.

Possible values for a Verified by Visa or JCB

J/Secure transaction:

js: Successful JCB J/Secure transaction.

js_attempted: JCB J/Secure transaction
was attempted but not authenticated.

vbv: Successful Verified by Visa transaction.

vbv_attempted: Verified by Visa
transaction was attempted but not
authenticated.

vbv_failure: Verified by Visa

authentication failed. Available only for HSBC
and Streamline.

ECI Rawraw electronic commerce indicator.

Used for all processors that support Verified by

Visa and/or JCB J/Secure.

Required when the payer authentication validation

service returns a raw ECI value.

Some processors require the raw ECI to

guarantee chargeback protection. Contact
CyberSource Customer Support for information
about your processors requirements.

Credit Card Services Using the Simple Order API | January 2016

174

Chapter 5

Table 48

Optional Features

Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

PARes Statuspayer authentication response

status.

ccAuthService_
paresStatus

payerAuthValidateReply_
paresStatus

Used only for these processors:

Asia, Middle East, and Africa Gateway

Atos

Global Collect when a third-party provider

authenticates the transaction

For Atos and Global Collect: required for a

successful Verified by Visa transaction, which is
indicated when the commerce indicator is vbv.

For the Asia, Middle East, and Africa Gateway:

required unless all of the following are true:

You are requesting the payer authentication and

the authorization in separate requests.

This is a successful or attempted Verified by

Visa transaction, which is indicated when the
commerce indicator is vbv or
vbv_attempted.

The card is not enrolled, which is indicated

when the VERes enrolled status is not Y.
When all the preceding conditions are true, do
not include the PARes status in the
authorization request. If you do, CyberSource
sends the value to the processor without
modification. CyberSource does not decline the
transaction; declines are generated by the
processor.

Possible values:

Y: Customer was successfully authenticated.

A: Proof of authentication attempt was
generated.

N: Customer failed or cancelled authentication.

Transaction denied.

U: Authentication not completed regardless of

the reason.

Credit Card Services Using the Simple Order API | January 2016

175

Chapter 5

Table 48

Optional Features

Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

VERes Enrolledverification response enrollment

status.

ccAuthService_
veresEnrolled

payerAuthEnrollReply_
veresEnrolled

ccAuthService_xid

payerAuthValidateReply_xid

Used only for the Asia, Middle East, and Africa

Gateway.

Required for all payer authentication transactions.

Possible values:

Y: Authentication available.
N: Cardholder not participating.
U: Unable to authenticate regardless of the
reason.

XIDtransaction identifier. Must be 28-character

base64 or 40-character hex binary.

Used for all processors that support Verified by

Visa and/or JCB J/Secure.

For Atos: required for a successful Verified by Visa

transaction, which is indicated when the
commerce indicator is vbv.

For all other processors: required when the

commerce indicator is js or vbv.

Optional when the commerce indicator is

js_attempted or vbv_attempted.

For Verified by Visa on FDC Nashville Global,

CyberSource sets the cardholder authentication
verification value (CAVV) field to the XID value if
the XID is present in the authorization request and
the CAVV is not present.

Credit Card Services Using the Simple Order API | January 2016

176

Chapter 5

Optional Features

JCB J/Secure
Service:

Authorization

Processors:

CCS (CAFIS)

CyberSource through VisaNet: This feature is supported for acquirers that support the
JCB card type.

Global Collect

JCN Gateway

TSYS Acquiring Solutions

JCB J/Secure authenticates the customer by adding a password identification step to the
online shopping process. For details about signing up for and using J/Secure, contact your
acquiring bank or go to the JCB web site:
http://www.jcb-global.com/

To request the authorization of a JCB J/Secure transaction:

Step 1

Add the fields listed in Table 48, "Request Fields for Verified by Visa and JCB J/Secure,"
on page 173 to your ccAuthService request. The values for these fields are in the reply
from the validate authentication service payerAuthValidateService. When you request
payerAuthValidateService and ccAuthService together, the data is automatically
passed from one service to the other.

MasterCard SecureCode
Service:

Authorization

Processors:

AIBMS

Asia, Middle East, and Africa Gateway

Atos

Barclays

Chase Paymentech Solutions

CCS (CAFIS)

Cielo

Credit Card Services Using the Simple Order API | January 2016

177

Chapter 5

Optional Features

CyberSource Latin American Processing: MasterCard SecureCode is an emerging

feature in the Latin American region. It is not fully supported in all countries. Contact
CyberSource Customer Support for details.

Note

CyberSource Latin American Processing is the CyberSource name for

Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil
only.

CyberSource through VisaNet: This feature is supported for acquirers that support
MasterCard.

Elavon

FDC Compass

FDC Germany

FDI Australia

FDC Nashville Global

FDMS Nashville

FDMS South

Global Collect

GPN

HBoS

HSBC: HSBC is the CyberSource name for HSBC U.K.

JCN Gateway

Litle

LloydsTSB Cardnet

Moneris

OmniPay Direct

OmniPay-Ireland: OmniPay-Ireland is the CyberSource name for HSBC International.

RBS WorldPay Atlanta

Streamline

TSYS Acquiring Solutions

MasterCard SecureCode adds security to online transactions by authenticating

SecureCode account holders for specific transactions. SecureCode generates a unique,
32-character transaction token, called the account authentication value (AAV), each time a
SecureCode-enabled account holder makes an online purchase. The AAV binds the

Credit Card Services Using the Simple Order API | January 2016

178

Chapter 5

Optional Features

account holder to a specific transaction. SecureCode transactions use the universal

cardholder authentication field (UCAF) as a standard to collect and pass AAV data. For
details about signing up for and using SecureCode or UCAF, contact your acquiring bank
or go to the MasterCard web site:
http://www.mastercard.com/

To request the authorization of a MasterCard SecureCode

transaction:
Step 1

Add the fields in Table 49, "Request Fields for MasterCard SecureCode," to your
ccAuthService request. The values for these fields are in the reply from the validate
authentication service payerAuthValidateService. When you request
payerAuthValidateService and ccAuthService together, the data is automatically
passed from one service to the other.

Credit Card Services Using the Simple Order API | January 2016

179

Chapter 5

Table 49

Optional Features

Request Fields for MasterCard SecureCode

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

CAVV Algorithmalgorithm for generating the

UCAF authentication data.

ccAuthService_
cavvAlgorithm

payerAuthValidateReply_
cavvAlgorithm

ccAuthService_
commerceIndicator

payerAuthValidateReply_
commerceIndicator

ccAuthService_eciRaw

payerAuthValidateReply_
eciRaw

Used only for these processors:

Atos

Global Collect when a third-party provider

authenticates the transaction

Required when you include the UCAF

authentication data in your request.

You must not include the CAVV algorithm value in

your request when the UCAF authentication data
is not included in your request or when your
processor is not Atos or Global Collect.

Possible values:
0: HMAC (hash-based message authentication
code)
1: CVV
2: CVV with ATN
3: MasterCard SPA (secure payment algorithm)

ECIelectronic commerce indicator.

Used for all processors that support MasterCard

SecureCode.

Always required.

Possible values for a MasterCard SecureCode

transaction:

spa: MasterCard SecureCode transaction.

spa_failure: MasterCard SecureCode
authentication failed. Available only for Elavon,
HSBC, and Streamline.

ECI Rawraw electronic commerce indicator.

Used for all processors that support MasterCard

SecureCode.

Required when the payer authentication validation

service returns a raw ECI value.

Some processors require the raw ECI to

guarantee chargeback protection. Contact
CyberSource Customer Support for information
about your processors requirements.

Credit Card Services Using the Simple Order API | January 2016

180

Chapter 5

Table 49

Optional Features

Request Fields for MasterCard SecureCode (Continued)

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

PARes Statuspayer authentication response

status.

ccAuthService_
paresStatus

payerAuthValidateReply_
paresStatus

Used only for these processors:

Asia, Middle East, and Africa Gateway

Atos

Global Collect when a third-party provider

authenticates the transaction

For Atos and Global Collect: required for a

successful MasterCard SecureCode transaction,
which is indicated when the UCAF collection
indicator is 2.

For the Asia, Middle East, and Africa Gateway:

required unless all of the following are true:

You are requesting the payer authentication and

the authorization in separate requests.

This is a successful MasterCard SecureCode

transaction, which is indicated when the
commerce indicator is spa.

The card is not enrolled, which is indicated

when the VERes enrolled status is not Y.
When all the preceding conditions are true, do
not include the PARes status in the
authorization request. If you do, CyberSource
sends the value to the processor without
modification. CyberSource does not decline the
transaction; declines are generated by the
processor.

Possible values:

Y: Customer was successfully authenticated.

A: Proof of authentication attempt was
generated.

N: Customer failed or cancelled authentication.

Transaction denied.

U: Authentication not completed regardless of

the reason.

Credit Card Services Using the Simple Order API | January 2016

181

Chapter 5

Table 49

Optional Features

Request Fields for MasterCard SecureCode (Continued)

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

UCAF Authentication Dataauthentication data for

the universal cardholder authentication field.

ucaf_authenticationData

payerAuthValidateReply_
ucafAuthenticationData

ucaf_collectionIndicator

payerAuthValidateReply_
ucafCollectionIndicator

Used for all processors that support MasterCard

SecureCode.

Required when the UCAF collection indicator is 2

or 5. Optional when the UCAF collection indicator
is 1. Do not include the UCAF authentication data
in the authorization request if the UCAF collection
indicator is not 1, 2, or 5.

UCAF Collection Indicatorcollection indicator for

the universal cardholder authentication field.

Used for all processors that support MasterCard

SecureCode.

Always required.

Possible values:

0: UCAF collection is not supported at your web

site.

1: UCAF collection is supported at your web

site and the UCAF might have been populated.

2: UCAF collection is supported at your web

site and the UCAF was populated. This value
indicates a successful MasterCard SecureCode
transaction.

5: UCAF collection is supported at your web

site, and the UCAF was populated based on the
risk assessment that the issuer performed. This
value is supported only for MasterPass
transactions.

6: UCAF collection is supported at your web

site, and the UCAF was populated based on the
risk assessment that you performed. This value
is supported only for MasterPass transactions.

Credit Card Services Using the Simple Order API | January 2016

182

Chapter 5

Table 49

Optional Features

Request Fields for MasterCard SecureCode (Continued)

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

VERes Enrolledverification response enrollment

status.

ccAuthService_
veresEnrolled

payerAuthEnrollReply_
veresEnrolled

ccAuthService_xid

payerAuthValidateReply_xid

Used only for the Asia, Middle East, and Africa

Gateway.

Required for all payer authentication transactions.

Possible values:

Y: Authentication available.
N: Cardholder not participating.
U: Unable to authenticate regardless of the
reason.

XIDtransaction identifier. Must be 28-character

base64 or 40-character hex binary.

Used for all processors that support MasterCard

SecureCode.

For Atos: required for a successful MasterCard

SecureCode transaction, which is indicated when
the UCAF collection indicator is 2.

For all other processors: required when the payer

authentication validation service returns an XID
value.

American Express SafeKey

Service:

Authorization

Processors:

American Express Direct: this feature is mandatory for transactions that originate in
Singapore.

CyberSource through VisaNet: this feature is supported for acquirers that support the
American Express card type.

FDC Nashville Global

JCN Gateway

Credit Card Services Using the Simple Order API | January 2016

183

Chapter 5

Optional Features

American Express SafeKey (AESK) authenticates the cardholder during an online

purchase and protects payment information as it is transmitted over the Internet.

To request the authorization of an AESK transaction:

Step 1

Add the fields in the following table to your ccAuthService request. The values for these
fields are in the reply from the validate authentication service payerAuthValidateService.
When you request payerAuthValidateService and ccAuthService together, the data is
automatically passed from one service to the other.
The authorization service returns a raw response code and a mapped response code:

Table 50

The raw response code is the value returned by the processor. CyberSource returns
this value in the ccAuthReply_cavvResponseCodeRaw field.

The mapped response code is the predefined CyberSource value that corresponds to
the raw response code. CyberSource returns this value in the ccAuthReply_
cavvResponseCode field. Appendix D, "American Express SafeKey Response
Codes," on page 354, describes the mapped response codes.

Request Fields for American Express SafeKey

Value and Requirements

Request Field for the

Authorization Service

Get the Value from this

Payer Authentication
Reply Field

CAVVcardholder authentication verification value.

This value is a transaction identifier generated by the
issuing bank during American Express SafeKey
payer authentication. This value is required.

ccAuthService_cavv

payerAuthValidateReply_
cavv

ECIelectronic commerce indicator. This value is

required. Possible values:

ccAuthService_
commerceIndicator

payerAuthValidateReply_
commerceIndicator

ccAuthService_xid

payerAuthValidateReply_xid

aesk: Successful AESK transaction.

aesk_attempted: AESK transaction was

attempted but not authenticated.

XIDtransaction identifier. This value is optional.

Credit Card Services Using the Simple Order API | January 2016

184

Chapter 5

Optional Features

Payment Network Tokenization

Payment network tokenization and CyberSource payment tokenization are not
the same feature.
Note

With payment network tokenization, the token is created by a token

service provider and can be used throughout the financial network.

With CyberSource payment tokenization, the token is created by

CyberSource and can be used only with CyberSource services.

For a description of network tokenization, including the list of processors for which
CyberSource supports payment network tokenization, see Payment Network Tokenization
Using the Simple Order API.

Payment Tokenization
Services:

Authorization

Credit

Processors:

See Payment Tokenization Using the Simple Order API.

Payment network tokenization and CyberSource payment tokenization are not
the same feature.
Note

With payment network tokenization, the token is created by a token

service provider and can be used throughout the financial network.

With CyberSource payment tokenization, the token is created by

CyberSource and can be used only with CyberSource services.

When you use Payment Tokenization, you can process an authorization, capture, or credit
by using information that is stored in a customer profile. CyberSource uses the
subscription ID to reference the customer profile information in the CyberSource
database. Instead of providing all the information that is normally required for a
transaction, you only need to provide the following values:

Merchant ID

Merchant reference code

Amount of the payment or credit

Subscription ID

Credit Card Services Using the Simple Order API | January 2016

185

Chapter 5

Optional Features

You can override most of the information stored in the customer profile by including the
relevant API fields in the payment or credit request. For example, you could provide a
different billing or shipping address in the request. You cannot override the credit card
account number.
For complete information about Payment Tokenization, see Payment Tokenization Using
the Simple Order API.

POS Transactions
See "Card-Present Data," page 111.

Quasi-Cash
Services:

Authorization

Full authorization reversal

Capture

Credit

Void

Processors:

Atos: Full authorization reversals and automatic partial authorization reversals are not
supported for Atos.

CyberSource through VisaNet. The supported acquirers are:

Auckland Savings Bank (ASB)

Australia and New Zealand Banking Group Limited (ANZ)

Axis Bank Ltd of India

Habib Bank Ltd (HBL)

HDFC Bank Ltd of India

QIWI Bank

Raiffeisenbank

Vantiv

Westpac

GPN

TSYS Acquiring Solutions

Credit Card Services Using the Simple Order API | January 2016

186

Chapter 5

Optional Features

Before processing quasi-cash transactions, contact CyberSource Customer Support to

have your account configured for this feature. If you have questions about the supported
card types, contact your processor.
A quasi-cash transaction is a cash-like transaction for the sale of items that are directly
convertible to cash, such as:

Casino gaming chips

Money orders

Wire transfers

Automatic partial authorization reversals are supported for quasi-cash transactions. See
"Automatic Partial Authorization Reversals," page 61.

Recipients
Service:

Authorization

Processors:

Barclays

Elavon

HBoS

LloydsTSB Cardnet

Streamline

In the United Kingdom there is a regulation that permits cardholders to use a debit card to
pay outstanding debt for another person. This person is referred to as the payment
recipient. For example, a cardholder can pay the entire balance or part of the balance on a
recipients credit card or payday loan. To help reduce the high levels of fraud that occur for
these kinds of transactions, you must include information about the recipient in the
authorization request. The following fields are required in the United Kingdom for Visa
debit transactions that are characterized under merchant category code 6012:

recipient_accountID

recipient_dateOfBirth

recipient_lastName

recipient_postalCode

These fields are described in Appendix A, "API Fields," on page 216.

Credit Card Services Using the Simple Order API | January 2016

187

Chapter 5

Optional Features

Recurring Billing
Services:

Authorization

Credit

Processors:

See Recurring Billing Using the Simple Order API.

When you use Recurring Billing, you can process an authorization, capture, or credit by
using information that is stored in a subscription. CyberSource uses the subscription ID to
reference the subscription information in the CyberSource database. Instead of providing
all the information that is normally required for a transaction, you only need to provide the
following values:

Merchant ID

Merchant reference code

Amount of the payment or credit

Subscription ID

You can override most of the information stored in the subscription by including the
relevant API fields in the payment or credit request. For example, you could provide a
different billing or shipping address in the request. You cannot override the credit card
account number.
For complete information about Recurring Billing, see Recurring Billing Using the Simple
Order API.

Credit Card Services Using the Simple Order API | January 2016

188

Chapter 5

Optional Features

Recurring Payments
Service:

Authorization

Processors and card types:

See the following table.

Table 51

Processors That Support Recurring Payments

Processors

Credit Card Types

AIBMS

Visa, MasterCard, Maestro (International)

American Express Brighton

American Express

American Express Direct

American Express

Asia, Middle East, and Africa Gateway

Visa, MasterCard, American Express, Diners

Club, JCB

Atos

Visa, MasterCard
Before processing recurring payments on Atos,
you must:

Contact your acquirer to ensure that you are

permitted to accept recurring transactions.

Contact Atos to have your account configured

to accept recurring transactions.

Barclays

Visa, MasterCard, JCB

Chase Paymentech Solutions

Visa, MasterCard, American Express, Discover

Cielo

Visa, MasterCard, American Express, Diners

Club, Discover, JCB, Maestro (International), Elo,
Aura
On Cielo, recurring payments are not supported
for debit transactions.

Credit Card Services Using the Simple Order API | January 2016

189

Chapter 5

Table 51

Optional Features

Processors That Support Recurring Payments (Continued)

Processors

Credit Card Types

CyberSource through VisaNet

Visa, MasterCard, American Express, Diners

Club, JCB, Discover

Note Not all card types are supported for all

acquirers.
The supported acquirers are:

Elavon

Credit Card Services Using the Simple Order API | January 2016

Arab African International Bank (AAIB)

Asia Commercial Bank (ACB)

Auckland Savings Bank (ASB)

Australia and New Zealand Banking Group

Limited (ANZ)

Axis Bank Ltd of India

Banco Nacional de Mxico (Banamex)

Bank Muscat of Oman

Bank of Ayudhya (BAY)

Bank of China (BOC)

Banque Pour Le Commerce Exterieur Lao

(BCEL)

CitiBank Singapore LTD

Commercial Bank of Qatar

CrediMax (Bahrain)

CTBC Bank Ltd.

Global Payment Asia Pacific

Habib Bank Ltd (HBL)

HDFC Bank Ltd of India

I&M Bank

ICICI of India

Mashreq

National Bank of Abu Dhabi (NBAD)

National Bank of Kuwait (NBK)

Overseas Chinese Banking Corp (OCBC)

Qatar National Bank (QNB Group)

QIWI Bank

Rosbank

Vantiv

Vietcombank

VietinBank

VTB24

Westpac

Wing Hang Bank

Wing Lung Bank

Visa, MasterCard, Maestro (UK), Diners Club

190

Chapter 5

Table 51

Optional Features

Processors That Support Recurring Payments (Continued)

Processors

Credit Card Types

FDC Compass

Visa, MasterCard, American Express, Discover,

Diners Club, JCB

FDC Germany

Visa, MasterCard

FDC Nashville Global

Visa, MasterCard, American Express, Discover

FDI Australia

Visa, MasterCard

FDMS South

Visa, MasterCard, Discover

On FDMS South, recurring payments are not
supported for the CAD currency on the Visa card
type.

FDMS Nashville

Visa, MasterCard, American Express, Discover

Global Collect

Carte Bleue

GPN

Visa, MasterCard, American Express, Discover,

Diners Club, JCB

HBoS

Visa, MasterCard

HSBC
HSBC is the CyberSource name for HSBC U.K.
To process recurring payments with HSBC, contact the CyberSource European office. For the
European offices phone number, go to the CyberSource web site and click the Contact Us link:
www.cybersource.com
Litle

Visa, MasterCard, American Express, Discover,

Diners Club, JCB

Lloyds-OmniPay

Visa, MasterCard

LloydsTSB Cardnet

Visa, MasterCard

Moneris

Visa, MasterCard, American Express, Discover

OmniPay Direct

Visa, MasterCard

OmniPay-Ireland

Visa, MasterCard

OmniPay-Ireland is the CyberSource name for HSBC International.

To process recurring payments with OmniPay-Ireland, contact the CyberSource European office.
For the European offices phone number, go to the CyberSource web site and click the Contact
Us link: www.cybersource.com
RBS WorldPay Atlanta

Visa, MasterCard, American Express, Discover,

Diners Club, JCB

Streamline
To process recurring payments with Streamline, contact the CyberSource European office. For
the European offices phone number, go to the CyberSource web site and click the Contact Us
link: www.cybersource.com
TSYS Acquiring Solutions

Credit Card Services Using the Simple Order API | January 2016

Visa, MasterCard, American Express, Discover

191

Chapter 5

Note

Optional Features

American Express and Discover have programs that you must register for if you
want to process recurring payments. Contact American Express and Discover
for details about their programs.

Depending on the types of products and services you sell, you might want to process
recurring payments for a customer. For example, you might want to charge a customer
19.95 USD each month to access a service that you offer.
A customers recurring payment does not have to be the same amount each
time.
Note

You must disclose clearly to customers when they make a purchase what the amount will
be for the recurring payments. If the amount varies based on usage, make it clear.

To create a recurring payment:

Step 1

For the first payment, the type of request you need to send depends on which processor
and card type you are using.

For MasterCard and American Express transactions on FDC Nashville Global, include
the following fields and values in the request for the first payment:
ccAuthService_commerceIndicator=recurring
ccAuthService_firstRecurringPayment=TRUE
card_cvNumber

For all card types on Atos, include the following fields and values in the request for the
first payment:
ccAuthService_commerceIndicator=recurring
ccAuthService_firstRecurringPayment=Y
card_cvNumber

For all card types on OmniPay Direct, request a non-recurring transaction and include
the following field and value in the request for the first payment:
ccAuthService_firstRecurringPayment=Y

Credit Card Services Using the Simple Order API | January 2016

192

Chapter 5

Optional Features

For all other processors and card types, request a non-recurring transaction for a
credit card authorization.

If the first authorization is successful, you can submit subsequent authorizations for
recurring payments using that card. If the first authorization is not successful, do not
submit subsequent authorizations using that card.
You must perform Step 1 once per year to verify the account.
Important

Step 2

For each subsequent recurring payment, send an authorization request using the
e-commerce indicator to indicate that the payment is a recurring payment:
ccAuthService_commerceIndicator=recurring

CyberSource also offers services that enable you to create a subscription or customer
profile for a customer in the CyberSource system and then use that subscription or
customer profile later to manually or automatically bill the customer. The CyberSource
system eliminates the need for you to handle or store the customers sensitive credit card
information or create your own system for billing the customer on a regular basis. For
more information, see "Payment Tokenization," page 185, and "Recurring Billing,"
page 188.

AVS and Recurring Payments

FDMS Nashville does not support AVS for recurring payments.
Note

If AVS is supported for your processor and card type, AVS is run for every authorization
request that you submit. For recurring payments, check the AVS result for the first
payment to ensure that the payment information is accurate and to reduce the risk of
fraud.
You must decide what to do with the AVS results for subsequent payments. You might
want to ignore the AVS results for the these payments because you have already
confirmed with the first payment that the credit card number is valid and not fraudulent.

Credit Card Services Using the Simple Order API | January 2016

193

Chapter 5

Optional Features

When you need to change the credit card number used for a series of recurring payments,
follow Step 1 in creating a recurring payment to verify the new account number. Closely
evaluate the AVS results. If the first authorization is successful, you can submit
subsequent authorizations for recurring payments using that card. If the first authorization
is not successful, do not submit subsequent authorizations using that card. For
subsequent payments, follow Step 2 in creating a recurring payment. You can choose to
ignore the AVS results.

CVN and Recurring Payments

FDMS Nashville does not support CVN for recurring payments.
Note

With Global Collect, you must not include the CVN in a recurring payment request. If you
do, CyberSource rejects the request because of invalid data.

Replacement Expiration Dates for Recurring

Payments
Service:

Authorization

Processors and card types:

Table 52

See the following table.

Processors That Support Replacement Expiration Dates

for Recurring Payments

Processors

Credit Card Types

AIBMS

Visa, MasterCard, Maestro (International)

American Express Brighton

American Express
You must contact American Express Brighton to get approval for
using replacement expiration dates before using this feature.

American Express Direct

American Express

Barclays

Visa, MasterCard, JCB

Credit Card Services Using the Simple Order API | January 2016

194

Chapter 5

Table 52

Optional Features

Processors That Support Replacement Expiration Dates

for Recurring Payments (Continued)

Processors

Credit Card Types

Chase Paymentech Solutions

Visa, MasterCard

CyberSource through VisaNet

Visa, MasterCard, American Express, Diners Club, JCB, Discover

Note Not all card types are supported for all acquirers.
If an acquirer is supported for recurring payments, the acquirer is also
supported for replacement expiration dates for recurring payments.
For the list of supported acquirers, see the entry for CyberSource
through VisaNet in Table 28, "Processors That Support Installment
Payments," on page 123.
FDC Compass

Visa, MasterCard, American Express, Discover, Diners Club

FDC Germany

Visa, MasterCard

FDI Australia

Visa, MasterCard

FDMS South

Visa, MasterCard

HBoS

Visa, MasterCard

HSBC

Visa, MasterCard, Maestro (International)

HSBC is the CyberSource name for HSBC

U.K.
Lloyds-OmniPay

Visa, MasterCard

LloydsTSB Cardnet

Visa, MasterCard

Streamline

To process recurring payments with Streamline, contact the

CyberSource European office. For the European offices phone
number, go to the CyberSource web site and click the Contact Us
link: www.cybersource.com

Normally when you request a credit card authorization, you must provide a valid expiration
date for the credit card. If you are processing a recurring payment, and the credit card that
you have on file for the customer has expired, you might still be able to request the
authorization depending on which processor you use. Instead of sending the out-of-date
expiration date, you can include a replacement expiration date in your request.

Important

Do not use a replacement expiration date for cards that have not expired. Use
a replacement expiration date only for cards that have expired and only for
recurring payments.
Using a replacement expiration date for a recurring payment does not
guarantee that the authorization will be successful. The issuing bank
determines whether a card is authorized; some issuing banks do not accept
an expiration date that does not match the expiration date in the banks
database.

Credit Card Services Using the Simple Order API | January 2016

195

Chapter 5

Important

Optional Features

Effective October 17, 2014, an issuing bank can decline an authorization

request for a recurring transaction with a Visa Europe card if the expiration date
is incorrect, invalid, or missing. If you do not provide the correct expiration date
for a recurring transaction the authorization request may be declined.

CyberSource supports the following replacement expiration dates:

12/2021

12/2099This date is supported only for the processors listed in Table 53.

To use the12/2021 date, include these fields and values in your authorization request:
card_expirationMonth=12
card_expirationYear=2021

To use the 12/2099 date, include these fields and values in your authorization request:
card_expirationMonth=12
card_expirationYear=2099

The 12/2021 replacement expiration date has recently become a valid expiration date.
Consequently, CyberSource is transitioning to a new replacement expiration date of
12/2099 and has implemented support for 12/2021 as a valid expiration date:

In March 2015, CyberSource will discontinue support for the 12/2021 replacement
expiration date and will support only the 12/2099 replacement expiration date. The
following table identifies the processors that support the 12/2099 replacement
expiration date and the month and year that the replacement expiration date is
supported.
Table 53

Processors that Support the 12/2099 Replacement

Expiration Date

Processor

Month and Year 12/2099

Replacement Expiration
Date Is Supported

AIBMS

October 2014

American Express Brighton

October 2014

American Express Direct

October 2014

Barclays

October 2014

Chase Paymentech Solutions

August 2014

FDC Compass

August 2014

FDC Germany

October 2014

FDMS South

October 2014

HSBC

October 2014

HSBC is the CyberSource name for HSBC U.K.

HBoS

October 2014

Lloyds-OmniPay

October 2014

Credit Card Services Using the Simple Order API | January 2016

196

Chapter 5

Table 53

Optional Features

Processors that Support the 12/2099 Replacement

Expiration Date (Continued)

Processor

Month and Year 12/2099

Replacement Expiration
Date Is Supported

LloydsTSB Cardnet

October 2014

Streamline

October 2014

Effective August 2014, CyberSource supports 12/2021 as a valid expiration date for
the following processors:

Chase Paymentech Solutions

FDC Compass

To enable 12/2021 as a valid expiration date, contact CyberSource Customer Support

to have your account configured for this feature.

Recurring Profiles
See "Recurring Billing," page 188.

Report Groups
Services:

Authorization

Full authorization reversal

Capture

Credit

Processor:

Litle

Report group values enable you to define custom groups for your processor reports. You
can put your transactions into groups and then request processor reports for each group.
This value is case sensitive and space sensitive.
If you do not have a specific report group structure in mind, Litle recommends
that you use your merchant ID as your report group value.
Note

Credit Card Services Using the Simple Order API | January 2016

197

Chapter 5

Important

Optional Features

To use multiple report groups for your transactions, you must contact Litle to
have your Litle account configured for this feature. If you use one report group
for all your transactions, you do not need to have your Litle account configured
for this feature.

The following table describes the logic that CyberSource uses for each kind of request to
determine which report group value to use.

Table 54

Determining Which Report Group Value to Use

Kind of Request

Report Group Value

Authorization or
Stand-Alone Credit

CyberSource checks the following locations, in the order given, for a report
group value and uses the first value it finds:

Capture or
Full Authorization
Reversal

Follow-on Credit

reportGroup field in the authorization or stand-alone credit request

Report group value in your CyberSource account: Your CyberSource

account can have a different report group value for each currency that
you process. CyberSource uses the report group value that
corresponds to the currency for the transaction. To create a default
report group value in your CyberSource account, contact CyberSource
Customer Support.

Your Litle merchant ID

CyberSource checks the following locations, in the order given, for a report
group value and uses the first value it finds:

reportGroup field in the capture or full authorization reversal request

Report group value that was used for the authorization request

CyberSource checks the following locations, in the order given, for a report
group value and uses the first value it finds:

reportGroup field in the follow-on credit request

Report group value that was used for the capture that is being credited

Report group value that was used for the authorization request

Retail POS Data

See "Card-Present Data," page 111.

Secure Data
See "Payment Tokenization," page 185.

Credit Card Services Using the Simple Order API | January 2016

198

Chapter 5

Optional Features

Service Fees
Services:

Authorization

Authorization reversal

Capture

For information about service fees, including the processors for which CyberSource
supports service fees, see Service Fee Processing Using the Simple Order API.

Soft Descriptors
See "Merchant Descriptors," page 131.

Split Dial/Route
See "Forced Captures," page 121.

Split Shipments
Services:

Authorization

Capture

Processors:

CyberSource through VisaNet

Split shipments are not available for MasterCard transactions in the IDR
currency on CyberSource through VisaNet.
Important

GPN: only for acquiring merchants

The split shipment feature enables you to split an order into multiple shipments with
multiple captures.

Credit Card Services Using the Simple Order API | January 2016

199

Chapter 5

Optional Features

Benefits of Using Split Shipments

The benefits of using split shipments are:

All the transactions for a split shipment are linked together in the Business Center and
in reports.

When you split an order into multiple shipments with multiple captures, you do not
need to request additional authorizations; CyberSource takes care of the additional
authorizations for you.

Requirements
The requirements for using split shipments are:

You must be a GPN acquiring merchant or use CyberSource through VisaNet.

You must contact CyberSource Customer Support to have your account configured for
this feature.

How Split Shipments Work

Additional Authorizations
When you need an additional authorization for an order, you can use the link-to-request
field to link the additional authorization to the first authorization. For the additional
authorization, you must submit an authorization request that includes the link-to-request
field in addition to the basic fields required for every authorization request. The additional
authorization is linked to the original authorization in the Business Center and in reports.
The captures for these authorizations are also linked to the original authorization in the
Business Center and in reports.
For scenarios that use an additional authorization, see the following sections:

"One Authorization and One Sale," page 201

"Two Authorizations and One Capture," page 203

For examples that use an additional authorization, see:

Name-value pair examples: "Split Shipment Examples," page 313

XML examples: "Split Shipment Examples," page 338

Credit Card Services Using the Simple Order API | January 2016

200

Chapter 5

Optional Features

Additional Captures
When you need an additional capture for an order, CyberSource performs a systemgenerated authorization for the additional capture request, using the payment data from
the original authorization. The system-generated authorization is linked to the original
authorization in the Business Center and in reports. The captures are linked to the
authorizations in the Business Center and in reports through the request IDs as with any
capture.
For scenarios that use an additional capture, see the following sections:

"One Authorization and Two Captures," page 202

"Multiple Captures in a Batch File," page 203

For examples that use an additional capture, see:

Name-value pair examples: "Split Shipment Examples," page 313

XML examples: "Split Shipment Examples," page 338

Split Shipment Scenarios

One Authorization and One Sale
In this scenario, your customer orders a product that is not available yet.
1

You request an authorization to ensure that funds are available.

The product is not available for immediate shipment, so you wait for the product to
become available.

After the product becomes available, you ship the product and request a sale.
For the second authorization, you must submit an authorization request that includes
the link-to-request field in addition to the basic fields required for every authorization
request. Set the link-to-request field to the request ID from the first authorizations
reply:
First Authorization Reply Message: requestID=SWVdPS5IM
Second Authorization Request: linkToRequest=SWVdPS5IM
Including the link-to-request field in your authorization request triggers the split
shipment functionality. Because you are requesting the second authorization and
capture together, you do not need to include the request ID in your capture request.

CyberSource tries to link the second authorization request to the first authorization:

If the link-to-request value is valid, the second authorization is linked to the

original authorization in the Business Center and in reports.

If the link-to-request value is not valid, the second authorization is not linked to the
original authorization in the Business Center and in reports.

Credit Card Services Using the Simple Order API | January 2016

201

Chapter 5

Optional Features

CyberSource links the capture request:

If the link-to-request value for the second authorization was valid, all three
transactions (first authorization, second authorization, capture) are linked together
in the Business Center and in reports.

If the link-to-request value for the second authorization was not valid, the second
authorization and capture are linked to each other in the Business Center and in
reports, but they are not linked to the first authorization.

One Authorization and Two Captures

In this scenario, your customer orders multiple products, one of which is not available yet.
1

You request an authorization to ensure that funds are available.

You ship the available products and request a capture for the amount of the shipped
products.
One of the products is not available for immediate shipment, so you ship the available
products and wait for the remaining product to become available.

After the remaining product becomes available, you ship the product and request a
capture for the amount of that product.

CyberSource performs a system-generated authorization for the second capture

request.
Because your account is enabled for split shipment, instead of rejecting the capture
request as a duplicate capture, CyberSource processes the capture request as a split
shipment request.
The system-generated authorization is linked to the original authorization in the
Business Center and in reports.

CyberSource links the capture request.

The capture is linked to the authorizations in the Business Center and in reports
through the request IDs as with any capture. All four transactions (first authorization,
system-generated authorization, first capture, second capture) are linked together in
the Business Center and in reports.

You get the status of the second capture request and its associated system-generated
authorization.
See "Obtaining the Status of a System-Generated Authorization," page 205.

Credit Card Services Using the Simple Order API | January 2016

202

Chapter 5

Optional Features

Multiple Captures in a Batch File

You can also request authorizations in a batch file.
Note

You create and upload a batch file using one of these methods:

Business Center Transaction Batch Functionality: This functionality is described in

the Offline Transaction File Submission Implementation Guide and in the Online
Help for the Business Center.

Offline Transaction File Submission System: This system is described in the

Offline Transaction File Submission Implementation Guide.

CyberSource processes the batch file.

You get the status of your batch requests by viewing the Batch Submission Detail
Report.
Get the report by using one of these methods, both of which are described in the
Offline Transaction File Submission Implementation Guide:

View the report on the Business Center.

Download the report programmatically.

You get the status of your split shipment transactions.

Two Authorizations and One Capture

In this scenario, your customer orders a product that is not available yet.
1

You request an authorization to ensure that funds are available.

The product is not available for immediate shipment, so you wait for the product to
become available.

After the product becomes available, you request a second authorization to ensure
that funds are still available.
For the second authorization, you must submit an authorization request that includes
the link-to-request field in addition to the basic fields required for every authorization
request. Set the link-to-request field to the request ID from the first authorizations
reply:
First Authorization Reply Message: requestID=SWVdPS5IM
Second Authorization Request: linkToRequest=SWVdPS5IM
Including the link-to-request field in your authorization request triggers the split
shipment functionality.

Credit Card Services Using the Simple Order API | January 2016

203

Chapter 5

Optional Features

CyberSource tries to link the second authorization request to the first authorization:

If the link-to-request value is valid, the second authorization is linked to the

original authorization in the Business Center and in reports.

If the link-to-request value is not valid, the second authorization is not linked to the
original authorization in the Business Center and in reports.

You ship the product and request a capture.

Set the request ID in the capture request to the request ID from the second
authorizations reply:
Second Authorization Reply Message: requestID=sl39cmdSlkJ
Capture Request: ccCaptureService_authRequestID=sl39cmdSlkJ

CyberSource links the capture request:

If the link-to-request value for the second authorization was valid, all three
transactions (first authorization, second authorization, capture) are linked together
in the Business Center and in reports.

If the link-to-request value for the second authorization was not valid, the second
authorization and capture are linked to each other in the Business Center and in
reports, but they are not linked to the first authorization.

Credit Card Services Using the Simple Order API | January 2016

204

Chapter 5

Optional Features

Obtaining the Status of a System-Generated

Authorization
A system-generated authorization is not performed in real time. The reply message that
you receive from CyberSource simply indicates that the request was received; it does not
indicate whether the system-generated authorization was approved or declined. A
system-generated authorization can be declined for the same reasons that a regular
authorization can be declined.
CyberSource recommends that you use one of the methods described in the following
table to get the status of the system-generated authorization request before shipping the
product.
Table 55

Methods for Obtaining the Status of a System-Generated Authorization

Method

Description

Business Center

Use the capture request ID to search for the second capture. The
details for all related transactions are displayed on the Transaction
Search Details page. It can take a maximum of six hours for the
status of the system-generated authorization request to be
available.

On-Demand Single
Transaction Report

This report is described in the Reporting Developer Guide. You

must use version 1.3 or later and include the parameter
includeExtendedDetail in your query. It can take a maximum of six
hours for the status of the system-generated authorization request
to be available.

Transaction Exception
Detail Report

This report is described in the Reporting Developer Guide.

CyberSource recommends that you use this report on a daily basis
to identify transactions that have been declined.

Additional Information
For descriptions of the required fields for authorization and capture requests, and to see
which fields are optional, see Appendix A, "API Fields," on page 216.
For examples of split shipment requests and replies, see:

Name-value pair examples: "Split Shipment Examples," page 313

XML examples: "Split Shipment Examples," page 338

Subscriptions
See "Recurring Billing," page 188.

Credit Card Services Using the Simple Order API | January 2016

205

Chapter 5

Optional Features

Tokenization
Payment network tokenization and CyberSource payment tokenization are not
the same feature.
Note

With payment network tokenization, the token is created by a token

service provider and can be used throughout the financial network.

With CyberSource payment tokenization, the token is created by

CyberSource and can be used only with CyberSource services.

See "Payment Network Tokenization," page 185, and "Payment Tokenization," page 185.

Type II Cards
See "Level II Data," page 130.

Verbal Authorizations
See "Verbal Authorizations," page 84.

Verified by Visa
See "Payer Authentication," page 171.

Credit Card Services Using the Simple Order API | January 2016

206

Chapter 5

Optional Features

Visa Bill Payments

Services:

Authorization

Credit

Processors:

Chase Paymentech Solutions

FDC Compass

FDC Nashville Global

FDMS Nashville

GPN

OmniPay-Ireland: OmniPay-Ireland is the CyberSource name for HSBC International.

TSYS Acquiring Solutions

Visa provides a Bill Payment program that enables customers to use their Visa cards to
pay their bills. When you participate in this program, Visa requests that you flag the bill
payments and credits so they can be easily identified. To flag these transactions, include
the ccAuthService_billPayment field in your transaction requests.
Although CyberSource accepts the bill payment indicator no matter which processor you
are using, do not use this indicator if you have not signed up with Visa to participate in the
program.

Visa Checkout
For a description of Visa Checkout, see Getting Started with Visa Checkout.

Credit Card Services Using the Simple Order API | January 2016

207

Chapter 5

Optional Features

Visa Debt Repayments

Services:

Authorization

Credit

Processors:

FDC Nashville Global

FDMS Nashville

GPN

Visa provides a Debt Repayment program that enables customers to use their Visa debit
cards to make a payment towards an existing contractual loan. The types of loans that can
qualify for this program are:

Consumer auto loans

Consumer credit cards

Consumer mortgages

Student loans

To participate in this program, contact your processor for details and requirements.
When you participate in this program, Visa requests that you flag the debt repayments and
credits so they can be easily identified. To flag these transactions, include these fields in
your transaction requests:

ccAuthService_billPayment

debtIndicator

Credit Card Services Using the Simple Order API | January 2016

208

Chapter 5

Optional Features

Zero Amount Authorizations

Service:

Authorization

Processors and card types:

Table 56

See the following table.

Processors That Support Zero Amount Authorizations

Processor

AVS

CVN

Card Types and Notes

American Express Direct

Yes

No

American Express

All currencies that are supported for standard

authorizations for American Express Direct are
also supported for zero amount authorizations.
Barclays

Yes

Yes

Visa

MasterCard

All currencies that are supported for standard

authorizations for Barclays are also supported
for zero amount authorizations.
CyberSource rounds the amount to the correct
number of decimal places for the currency.
For zero amount authorizations on Barclays,
the commerce indicator must be internet or
moto.
Visa Electron cards are not supported for zero
amount authorizations on Barclays.
Chase Paymentech Solutions

CyberSource through VisaNet

Yes

Yes

Yes

Yes

Visa

MasterCard

Diners Club

Visa

MasterCard

For CyberSource through VisaNet, zero amount

authorizations are supported for internet, moto,
and card-present transactions. Do not try to
perform a zero amount authorization for a
recurring, installment, or payer authorization
transaction.

Credit Card Services Using the Simple Order API | January 2016

209

Chapter 5

Table 56

Optional Features

Processors That Support Zero Amount Authorizations (Continued)

Processor

AVS

CVN

Card Types and Notes

Elavon

Yes

Yes

Visa

MasterCard

Maestro (UK Domestic)

Maestro (International)

All currencies that are supported for standard

authorizations for Elavon are also supported for
zero amount authorizations.
FDC Compass

FDC Nashville Global

Yes

Yes

Yes

Yes for all card

types except
American Express

Visa

MasterCard

American Express

Diners Club

Visa

MasterCard

American Express

Discover

Diners Club

For a zero amount authorization on FDC

Nashville Global:

For Visa, MasterCard, and American

Express, all currencies that are supported for
standard authorizations are also supported
for zero amount authorizations.

For Discover and Diners Club, only USD is

supported for zero amount authorizations.

FDMS Nashville

Yes

Yes

Visa

FDMS South

Yes

Yes for Visa. No

for all other card
types.

Visa

MasterCard

American Express

Diners Club

Discover

Visa

MasterCard

American Express: CVN is not supported for

zero amount authorizations with American
Express.

Discover

JCB

GPN

Yes

Yes for all card

types except
American Express

Credit Card Services Using the Simple Order API | January 2016

210

Chapter 5

Table 56

Optional Features

Processors That Support Zero Amount Authorizations (Continued)

Processor

AVS

CVN

Card Types and Notes

HSBC

Yes

Yes

Visa

MasterCard

Maestro (UK Domestic)

Maestro (International)

HSBC is the CyberSource

name for HSBC U.K.

For zero amount authorizations on HSBC:

JCN Gateway

Litle

Moneris

OmniPay Direct

OmniPay-Ireland

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

OmniPay-Ireland is the
CyberSource name for HSBC
International.
RBS WorldPay Atlanta

Yes

Yes

Credit Card Services Using the Simple Order API | January 2016

The commerce indicator must be

internet or moto.

The authorization code is not returned.

Visa

MasterCard

American Express

Diners Club

JCB

NICOS house card

ORICO house card

Visa

MasterCard

American Express

Discover

Diners Club

JCB

Visa

MasterCard

Visa

MasterCard

Maestro (UK Domestic)

Maestro (International)

Visa

MasterCard

Visa

MasterCard

Diners Club

211

Chapter 5

Table 56

Optional Features

Processors That Support Zero Amount Authorizations (Continued)

Processor

AVS

CVN

Card Types and Notes

Streamline

Yes

Yes

Visa

MasterCard

Maestro (International)

Maestro (UK Domestic)

Carte Bleue

Dankort

All currencies that are supported for standard

authorizations for Streamline are also
supported for zero amount authorizations.
For a zero amount authorization:

TSYS Acquiring Solutions

Yes

Yes for Visa and

MasterCard. No
for American
Express and
Discover.

The commerce indicator must be

internet or moto.

Payer authentication is not supported.

Visa

MasterCard

American Express: CVN is not supported for

zero amount authorizations with American
Express.

Discover: CVN is not supported for zero

amount authorizations with Discover.

Authorizing a payment for a zero amount shows whether a credit card account is valid and
whether the card is lost or stolen. You cannot capture a zero amount authorization.

Credit Card Services Using the Simple Order API | January 2016

212

CHAPTER

Testing the Credit Card

Services

To ensure that your requests are processed correctly, you must test the basic success and
error conditions for each CyberSource service you plan to use.

Requirements for Testing

Important

Before you can test, you must contact CyberSource Customer Support to
activate the credit card services and configure your account for testing. You
must also contact your processor to set up your processor account.

Use your regular CyberSource merchant ID when you test your system.

Unless otherwise specified, use test credit card numbers, not real ones. See Table 57,
"Test Credit Card Numbers," on page 214.

Use a real combination for the city, state, and postal code.

Use a real combination for the area code and telephone number.

Use a nonexistent account and domain name for the customers email address.

When testing a Global Collect country-specific credit card, such as Italys Carta Si,
specify the appropriate country code when sending the customers address and
specify the currency used in that country.

When testing the Simple Order API, use the test URL:
https://ics2wstesta.ic3.com/commerce/1.x/transactionProcessor

Note

When you test captures on Global Collect, you must capture the full amount of
the authorization. Although a capture request for a partial amount is not
rejected during testing, it will be rejected by the processor in production.

Credit Card Services Using the Simple Order API | January 2016

213

Chapter 6

Testing the Credit Card Services

Testing the Services

Use the credit card numbers in the following table to test the authorization, capture, and
credit services. Do not use real credit card numbers. To test card types not listed in the
table, use an account number that is within the cards bin range. For best results, try each
test with a different CyberSource service request and with different test credit card
numbers.
Table 57

Test Credit Card Numbers

Credit Card Type

Test Account Number

(Remove spaces when sending to CyberSource.)

American Express

3782 8224 6310 005

Discover

6011 1111 1111 1117

JCB

3566 1111 1111 1113

Maestro (International)

5033 9619 8909 17

5868 2416 0825 5333 38

Maestro (UK Domestic)

6759 4111 0000 0008

6759 5600 4500 5727 054
5641 8211 1116 6669
Note Effective May 2011, the issue number is no longer
required for Maestro (UK Domestic) transactions.

MasterCard

5555 5555 5555 4444

UATP

1354 1234 5678 911

Visa

4111 1111 1111 1111

Using Amounts to Simulate Errors

You can simulate the CyberSource error messages by requesting authorization, capture,
or credit services with specific amounts that trigger the error messages. These triggers
work only on the test server, not on the production server. Each payment processor uses
its own error messages.
For trigger amounts and responses, see Simple Order API and SOAP Toolkit API Testing
Information page.

Credit Card Services Using the Simple Order API | January 2016

214

Chapter 6

Testing the Credit Card Services

Testing American Express Card

Verification
Before using CVN with American Express, CyberSource strongly recommends that you
perform this procedure.

To test American Express card verification:

Step 1

Contact CyberSource Customer Support to have your account configured for CVN. Until
you do this, you will receive a 1 in the ccAuthReply_cvCode reply field.

Step 2

Test your system in production using a small currency amount, such as one currency unit.
Instead of using the test account numbers, use a real credit card account number, and
send an incorrect CVN in the request for authorization. The card should be refused and
the request declined.

Credit Card Services Using the Simple Order API | January 2016

215

APPENDIX

API Fields

Formatting Restrictions
Unless otherwise noted, all field names are case sensitive and all fields accept special
characters such as @, #, and %.
The values of the item_#_ fields must not contain carets (^) or colons (:)
because these characters are reserved for use by the CyberSource services.
Note

Values for request-level and item-level fields must not contain new lines or
carriage returns. However, they can contain embedded spaces and any other
printable characters. CyberSource removes all leading and trailing spaces.
Atos
The billTo_ fields must not contain colons (:).
Moneris
Values for request-level and item-level fields must not contain these special
characters: ampersands (&), single quotes (), double quotes (), less than
signs (<), and greater than signs (>).

Data Type Definitions

For more information about these data types, see the World Wide Web Consortium (W3C)
XML Schema Part 2: Datatypes specification.
Data Type

Description

Integer

Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}

String

Sequence of letters, numbers, spaces, and special characters

Credit Card Services Using the Simple Order API | January 2016

216

Appendix A

API Fields

Request Fields
See Getting Started with CyberSource Advanced for the Simple Order API for a
description of how name-value pair names relate to their corresponding XML element
names.
When you use Payment Tokenization or Recurring Billing and you include a
subscription ID in your request, many of the fields in the following table that are
normally required for an authorization or credit become optional. See "Payment
Tokenization," page 185, and "Recurring Billing," page 188.

Note

Table 58

Request Fields

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

authIndicator

Flag that specifies the purpose of the

authorization. Possible values:

ccAuthService
(Required for
MasterCard
transactions for
merchants in the
MasterCard Europe
region and merchants
with acquirers in the
MasterCard Europe
region, which includes
Russia; optional for all
other regions; not used
for all other card types)

String (1)

ccAuthService
(Required for a balance
inquiry; otherwise, not
used.)

String (5)

0: Preauthorization

1: Final authorization (default for Barclays

and Elavon)

See "Final Authorization Indicator," page 120.

Barclays and Elavon
To change the default value for this field,
contact CyberSource Customer Support.

balanceInquiry

Flag that indicates whether to return balance

information. See "Balance Inquiries,"
page 110.
Possible values:

true

false

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

217

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_buildingNumber

Building number in the street address. For

example, if the street address is:

ccAuthService (O for
Cielo. R for Redecard
customer validation with
CyberSource Latin
American Processing.
Otherwise, not used.)

String (256)

City of the billing address.

ccAuthService (R)6

Atos
This field must not contain colons (:).

ccCaptureService (O)

Atos:
String (32)

Rua da Quitanda 187

then the building number is 187. This field is
supported only for:

billTo_city

Cielo transactions.

Redecard customer validation with

CyberSource Latin American Processing.

CyberSource through VisaNet

Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

ccCreditService (R)1,6
ccDCCService (O)

All other
processors:
String (50)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

218

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_company

Name of the customers company.

ccAuthService (O)

String (60)

CyberSource through VisaNet

Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

ccCaptureService (O)

Country of the billing address. Use the twocharacter ISO Standard Country Codes.

ccAuthService (R)6

CyberSource through VisaNet

Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

ccCreditService (R)1,6

billTo_country

ccCreditService (O)

String (2)

ccCaptureService (O)

ccDCCService (O)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

219

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_customerID

Your identifier for the customer. When a

subscription or customer profile is being
created, the maximum length for this field is
30. Otherwise, the maximum length is 100.

ccAuthService (O)

String (100)

ccCaptureService (O)
ccCreditService (O)

Litle
For a follow-on credit with Litle, CyberSource
checks the following locations, in the order
given, for a customer account ID value and
uses the first value it finds:
1 billTo_customerID value in the follow-on
credit request
2 Customer account ID value that was used
for the capture that is being credited
3 Customer account ID value that was used
for the original authorization
If a customer account ID value cannot be
found in any of these locations, then no value
is used.
billTo_district

Customers neighborhood, community, or

region (a barrio in Brazil) within the city or
municipality. This field is available only on
Cielo.

ccAuthService (O)

String (50)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

220

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_email

Customers email address, including the full

domain name.

ccAuthService (R)6

String (255)

CyberSource through VisaNet

Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

ccCreditService (R)1,6

ccCaptureService (O)

ccDCCService (O)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

221

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_firstName

Customers first name. This name must be the

same as the name on the card.

ccAuthService (R)6

CyberSource Latin American Processing

ccCreditService (R)1,6

CyberSource
Latin
American
Processing:
see field
description

Important For an authorization request,

CyberSource Latin American Processing
concatenates billTo_firstName and billTo_
lastName. If the concatenated value exceeds
30 characters, CyberSource Latin American
Processing declines the authorization request.
Note CyberSource Latin American
Processing is the CyberSource name for
Braspag. CyberSource provides two
processors for Latin America: CyberSource
Latin American Processing (Braspag), which is
supported in multiple Latin American countries,
and Cielo, which is supported in Brazil only.
The information in this field description applies
only to CyberSource Latin American
Processing (Braspag).

ccCaptureService (O)

ccDCCService (O)

Litle:
String (25)
All other
processors:
String (60)

CyberSource through VisaNet

Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

222

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_hostname

DNS resolved hostname from billTo_

ipAddress.

ccAuthService (O)

String (60)

ccCaptureService (O)
ccCreditService (O)

billTo_httpBrowserType

Customers browser as identified from the

HTTP header data. For example, Mozilla is
the value that identifies the Netscape browser.

ccAuthService (O)

String (40)

ccCaptureService (O)
ccCreditService (O)

billTo_ipAddress

Customers IP address.

ccAuthService (O)

String (15)

ccCaptureService (O)
ccCreditService (O)
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

223

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_lastName

Customers last name. This name must be the

same as the name on the card.

ccAuthService (R)6

CyberSource Latin American Processing

ccCreditService (R)1,6

CyberSource
Latin
American
Processing:
see field
description

Important For an authorization request,

CyberSource Latin American Processing
concatenates billTo_firstName and billTo_
lastName. If the concatenated value exceeds
30 characters, CyberSource Latin American
Processing declines the authorization request.
Note CyberSource Latin American
Processing is the CyberSource name for
Braspag. CyberSource provides two
processors for Latin America: CyberSource
Latin American Processing (Braspag), which is
supported in multiple Latin American countries,
and Cielo, which is supported in Brazil only.
The information in this field description applies
only to CyberSource Latin American
Processing (Braspag).

ccCaptureService (O)

ccDCCService (O)

Litle:
String (25)
All other
processors:
String (60)

CyberSource through VisaNet

Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

224

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_personalID

Personal identifier. This field is supported only

for Redecard in Brazil for CyberSource Latin
American Processing. Set this field to the
Cadastro de Pessoas Fisicas (CPF), which is
required for AVS for Redecard in Brazil.

ccAuthService (See the

field description.)

String (26)

ccAuthService (O)

String (15)

Note CyberSource Latin American

Processing is the CyberSource name for
Braspag. CyberSource provides two
processors for Latin America: CyberSource
Latin American Processing (Braspag), which is
supported in multiple Latin American countries,
and Cielo, which is supported in Brazil only.
The information in this field description applies
only to CyberSource Latin American
Processing (Braspag).
billTo_phoneNumber

Customers phone number. CyberSource

recommends that you include the country code
when the order is from outside the U.S.
CyberSource through VisaNet
Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

ccCaptureService (O)
ccCreditService (O)
ccDCCService (O)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

225

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_postalCode

Postal code for the billing address. The postal

code must consist of 5 to 9 digits.

ccAuthService
(Required when the
billing country is the
U.S. or Canada;
otherwise, optional.)6

CyberSource
through
VisaNet:
String (9)

When the billing country is the U.S., the 9-digit

postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789

ccCaptureService (O)

When the billing country is Canada, the 6-digit

postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3

ccCreditService
(Required when the
billing country is the
U.S. or Canada;
otherwise, optional.)1,6

American Express Direct

Before sending the postal code to the
processor, CyberSource removes all nonalphanumeric characters and, if the remaining
value is longer than nine characters, truncates
the value starting from the right side.

ccDCCService (O)

All other
processors:
String (10)

Atos
This field must not contain colons (:).
CyberSource through VisaNet
Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

226

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_state

State or province of the billing address. Use

the State, Province, and Territory Codes for the
United States and Canada.

ccAuthService
(Required when the
billing country is the
U.S. or Canada;
otherwise, optional.)6

String (2)

CyberSource through VisaNet

Credit card networks cannot process
transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

ccCaptureService (O)
ccCreditService
(Required when the
billing country is the
U.S. or Canada;
otherwise, optional.)1,6
ccDCCService (O)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

227

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_street1

First line of the billing street address as it

appears on the credit card issuers records.

ccAuthService (R)6

Atos:
String (29)

Atos
This field must not contain colons (:).

ccCreditService (R)1,6

CyberSource through VisaNet

Important When you populate billing street

address 1 and billing street address 2,
CyberSource through VisaNet concatenates
the two values. If the concatenated value
exceeds 40 characters, CyberSource through
VisaNet truncates the value at 40 characters
before sending it to Visa and the issuing bank.
Truncating this value affects AVS results and
therefore might also affect risk decisions and
chargebacks.

ccCaptureService (O)

CyberSource
through
VisaNet:
String (40)
Litle:
String (35)
Moneris:
String (50)
All other
processors:
String (60)

Credit card networks cannot process

transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

228

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

billTo_street2

Additional address information. Example:

ccAuthService (O)

Atos:
String (29)

Attention: Accounts Payable

Atos
This field must not contain colons (:).
Chase Paymentech Solutions, FDC
Compass, and TSYS Acquiring Solutions
This value is used for AVS.
CyberSource through VisaNet

Important When you populate billing street

address 1 and billing street address 2,
CyberSource through VisaNet concatenates
the two values. If the concatenated value
exceeds 40 characters, CyberSource through
VisaNet truncates the value at 40 characters
before sending it to Visa and the issuing bank.
Truncating this value affects AVS results and
therefore might also affect risk decisions and
chargebacks.

ccCaptureService (O)
ccCreditService (O)

CyberSource
through
VisaNet:
String (40)
Litle:
String (35)
Moneris:
String (50)
All other
processors:
String (60)

Credit card networks cannot process

transactions that contain non-ASCII
characters. CyberSource through VisaNet
accepts and stores non-ASCII characters
correctly and displays them correctly in
reports. However, the limitations of the credit
card networks prevent CyberSource through
VisaNet from transmitting non-ASCII
characters to the credit card networks.
Therefore, CyberSource through VisaNet
replaces non-ASCII characters with
meaningless ASCII characters for transmission
to the credit card networks.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

229

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

businessRules_
declineAVSFlags

List of AVS flags that cause the request to be

declined for AVS reasons. Use a space to
separate the flags in the list.

ccAuthService (O)

String (255)

ccAuthService (O)

String (5)

ccAuthService (O)

String (5)

Important To receive declines for the AVS

code N, include the value N in the list.
businessRules_
ignoreAVSResult

Flag for a sale request that indicates whether

to allow the capture service to run even when
the authorization receives an AVS decline.
Possible values:

true: Ignore the results of AVS checking

and run the capture service.

false (default): If the authorization

receives an AVS decline, do not run the
capture service.

When the value of this field is true, the list in

the businessRules_declineAVSFlags field is
ignored.

businessRules_
ignoreCVResult

Flag for a sale request that indicates whether

to allow the capture service to run even when
the authorization receives a CVN decline, as
indicated by a ccAuthReply_cvCode value of
D or N.
Possible values:

true: Ignore the results of CVN checking

and run the capture service.

false (default): If the authorization

receives a CVN decline, do not run the
capture service.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

230

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

card_
accountEncoderID

Identifier for the issuing bank that provided the

customers encoded account number. Contact
your processor for the banks ID. See
"Encoded Account Numbers," page 119.

ccAuthService
(Required when
processing encoded
account numbers;
otherwise, not used.)

String (3)

ccCreditService
(Required when
processing encoded
account numbers;
otherwise, not used.)1
card_accountNumber

Customers credit card number.

Encoded Account Numbers
When processing encoded account numbers,
use this field for the encoded account number.

ccAuthService (R)
ccCreditService

(R)1

String with
numbers
only (20)

ccDCCService (R)

DCC for First Data

Set this to the first 6 to 10 digits of the credit
card number.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

231

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

card_cardType

Type of card to authorize. To see which cards

can be handled by each processor, see
"Payment Processors," page 27. Possible
values:

ccAuthService

String (3)

001: Visa

002: MasterCard, Eurocard2: European

regional brand of MasterCard

003: American Express

004: Discover

005: Diners Club: see "Discover

Acquisitions and Alliances," page 19.
Blanche2

006: Carte

007: JCB2

014: EnRoute2

021: JAL2

024: Maestro (UK Domestic)2

027: NICOS house card2

031: Delta2: Use this value only for Global

Collect. For other processors, use 001 for

ccCreditService1
For all processors
except Global Collect,
the Visa Electron card
type is processed the
same way that the Visa
debit card is processed.
Use card type value
001 for Visa Electron.

Important
CyberSource strongly
recommends that you
send the card type even
if it is optional for your
processor and card
type. Omitting the card
type can cause the
transaction to be
processed with the
wrong card type.

all Visa card types.

033: Visa Electron2

034: Dankort2

036: Carte Bleue2

037: Carta Si2

039: Encoded account number2

040: UATP2

042: Maestro (International)2

053: ORICO house card2

054: Elo

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

232

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

card_cvIndicator

Flag that indicates whether a CVN code was

sent. Possible values:

ccAuthService (O)

String with
numbers
only (1)

ccAuthService (O)

String with
numbers
only (4)

card_cvNumber

0 (default): CVN service not requested.

CyberSource uses this default value when
you do not include card_cvNumber in the
request.

1 (default): CVN service requested and

supported. CyberSource uses this default
value when you include card_cvNumber in
the request.

2: CVN on credit card is illegible.

9: CVN was not imprinted on credit card.

CVN. See "Card Verification Numbers

(CVNs)," page 80, for a list of processors that
support CVN.
Global Collect
Do not include this field when ccAuthService_
commerceIndicator=recurring.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

233

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

card_expirationMonth

Two-digit month in which the credit card

expires.
Format: MM.
Possible values: 01 through 12.

ccAuthService (R)6

String (2)

ccCreditService (R)1,6
ccDCCService (O)

Barclays and Streamline

For Maestro (UK Domestic) and
Maestro (International) cards on Barclays and
Streamline, this must be a valid value (01
through 12) but is not required to be a valid
expiration date. In other words, an expiration
date that is in the past does not cause
CyberSource to reject the request. However,
an invalid expiration date might cause the
issuer to reject your request.
Encoded Account Numbers
For encoded account numbers (card_
cardType=039), use 12 if there is no
expiration date available.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

234

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

card_expirationYear

Four-digit year in which the credit card expires.

Format: YYYY.

ccAuthService (R)6

FDC
Nashville
Global and
FDMS
South:
String (See
description)

Barclays and Streamline

For Maestro (UK Domestic) and
Maestro (International) cards on Barclays and
Streamline, this must be a valid value (1900
through 3000) but is not required to be a valid
expiration date. In other words, an expiration
date that is in the past does not cause
CyberSource to reject the request. However,
an invalid expiration date might cause the
issuer to reject your request.

ccCreditService (R)1,6
ccDCCService (O)

All other
processors:
String (4)

FDC Nashville Global and FDMS South

You can send in 2 digits or 4 digits. When you
send in 2 digits, they must be the last 2 digits of
the year.
Encoded Account Numbers
For encoded account numbers (card_
cardType=039), if there is no expiration date
available, use 2021.
card_issueNumber

Number of times a Maestro (UK Domestic)

card has been issued to the account holder.
The card might or might not have an issue
number. The number can consist of one or two
digits, and the first digit might be a zero. When
you include this value in your request, include
exactly what is printed on the card. A value of
2 is different than a value of 02. Do not include
the field, even with a blank value, if the card is
not a Maestro (UK Domestic) card.

ccAuthService (O)

String (5)

ccCreditService (O)

Note The issue number is not required for

Maestro (UK Domestic) transactions.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

235

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

card_startMonth

Month of the start of the

Maestro (UK Domestic) card validity period.
Do not include the field, even with a blank
value, if the card is not a
Maestro (UK Domestic) card.

ccAuthService (O)

String (2)

ccCreditService (O)

Format: MM.
Possible values: 01 through 12.

Note The start date is not required for

Maestro (UK Domestic) transactions.
card_startYear

Year of the start of the Maestro (UK Domestic)

card validity period. Do not include the field,
even with a blank value, if the card is not a
Maestro (UK Domestic) card.

ccAuthService (O)

String (4)

ccCreditService (O)

Format: YYYY.

Note The start date is not required for

Maestro (UK Domestic) transactions.
ccAuthReversalService
_authRequestID

Request ID for the authorization that you want

to reverse.

ccAuthReversal
Service (R)

String (26)

ccAuthReversalService
_authRequestToken

Value of the request token returned from a

previous request for ccAuthService.

ccAuthReversal
Service (O)

String (256)

ccAuthReversal
Service (O)

String (3)

The field is an encoded string that contains no

confidential information, such as an account
number or card verification number. The string
can contain a maximum of 256 characters.

ccAuthReversalService
_reversalReason

Reason for the authorization reversal. Possible

value:

34: Suspected fraud

CyberSource ignores this field for processors

that do not support this value.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

236

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccAuthReversalService
_run

Whether to include ccAuthReversalService in

your request. Possible values:

ccAuthReversal
Service (R)

String (5)

ccAuthService

CyberSource
through
VisaNet:
String (11)

ccAuthService_
aggregatorID

true: Include the service in your request.

false (default): Do not include the service

in your request.

Value that identifies you as a payment

aggregator. Get this value from the processor.
See "Aggregator Support," page 100.

See field description.

This field is required for aggregator

transactions on:

American Express Direct

CyberSource through VisaNetMasterCard

only

FDC Nashville Global

All other
processors:
String (15)

CyberSource through VisaNet

The value for this field corresponds to the
following data in the TC 33 capture file5:

ccAuthService_
aggregatorName

Record: CP01 TCR6

Position: 95-105

Field: MasterCard Payment Facilitator ID

Your payment aggregator business name.

See "Aggregator Support," page 100.

ccAuthService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

American
Express
Direct:
String (37)
FDC
Nashville
Global:
String (12)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

237

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccAuthService_
authType

Authorization type.

ccAuthService
(Required for an auto
capture on Cielo or for a
forced capture;
otherwise, not used.)

String (11)

ccAuthService (O)

String (5)

Cielo
Set this field to AUTOCAPTURE and include it
in the authorization request to indicate that you
are requesting an auto capture. For more
information, see the entry for Cielo in Table 8,
"Payment Processors and Card Types," on
page 28.
Forced Capture
Set this field to verbal and include it in the
authorization request to indicate that you are
performing a forced capture; therefore, you
received the authorization code outside the
CyberSource system. For more information,
see "Forced Captures," page 121.

ccAuthService_
billPayment

Flag that indicates that this is a payment for a

bill or for an existing contractual loan. See
"Visa Bill Payments," page 207, and "Visa Debt
Repayments," page 208, for lists of processors
that support these features. This value is case
sensitive. Possible values:

true: Bill payment or loan payment.

false (default): Not a bill payment or loan

payment.

ccAuthService_
captureDate

Date on which you want the capture to occur.

This field is supported only for CyberSource
through VisaNet.
Format: MMDD

ccAuthService (O)

String (4)

ccAuthService_cavv

Cardholder authentication verification value

(CAVV). For the description and requirements,
see "Payer Authentication," page 171.

ccAuthService

String (40)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

238

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccAuthService_
cavvAlgorithm

Algorithm used to generate the CAVV for

Verified by Visa or the UCAF authentication
data for MasterCard SecureCode. For the
description and requirements, see "Payer
Authentication," page 171.

ccAuthService

String (1)

ccAuthService_
commerceIndicator

Type of transaction. Some payment card

companies use this information when
determining discount rates. When you omit this
field for Global Collect, the processor uses the
default transaction type they have on file for
you instead of the default value listed here.

ccAuthService
(Required for payer
authentication
transactions; otherwise,
optional.)

String (20)

ccAuthService

String (2)

Payer Authentication Transactions

For the possible values and requirements, see
"Payer Authentication," page 171.
Other Types of Transactions
See Appendix F, "Commerce Indicators," on
page 359.
ccAuthService_eciRaw

Raw electronic commerce indicator (ECI). For

the description and requirements, see "Payer
Authentication," page 171.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

239

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccAuthService_
firstRecurringPayment

Flag that indicates whether this transaction is

the first in a series of recurring payments. See
"Recurring Payments," page 189. This field is
supported only for Atos, FDC Nashville Global,
and OmniPay Direct.

ccAuthService (O)

String (1)

Atos and OmniPay Direct

Possible values:

Y: Yes, this is the first payment in a series of

recurring payments.

N (default): No, this is not the first payment

in a series of recurring payments.

FDC Nashville Global

Possible values:

TRUE: Yes, this is the first payment in a

series of recurring payments.

FALSE (default): No, this is not the first

payment in a series of recurring payments.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

240

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccAuthService_
overridePayment
Method

Flag that specifies the type of account

associated with the card. The cardholder
provides this information during the payment
process.

ccAuthService (O)

String (2)

ccAuthService

String (1)

Cielo
Possible values:

CR: Credit card

DB: Debit card

CyberSource through VisaNet

Possible values:

CH: Checking account

CR: Credit card account

SA: Savings account

This field is required for:

Debit transactions on Cielo.

Transactions with Brazilian-issued cards on

CyberSource through VisaNet.

Note Combo cards in Brazil contain credit

and debit functionality in a single card. Visa
systems use a credit bank identification
number (BIN) for this type of card. Using the
BIN to determine whether a card is debit or
credit can cause transactions with these cards
to be processed incorrectly. CyberSource
strongly recommends that you include this field
for combo card transactions.
ccAuthService_
paresStatus

Payer authentication response status. For the

description and requirements, see "Payer
Authentication," page 171.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

241

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccAuthService_
partialAuthIndicator

Flag that indicates whether the transaction is

enabled for partial authorization. When the
request includes this field, this value overrides
the information in your CyberSource account.
Possible values:

ccAuthService (O)

String (5)

ccAuthService (R)

String (5)

true: Enable the transaction for partial

authorization.

false: Do not enable the transaction for

partial authorization.

See "Partial Authorizations," page 88.

ccAuthService_run

Whether to include ccAuthService in your

request. Possible values:

true: Include the service in your request.

false (default): Do not include the service

in your request.

ccAuthService_
verbalAuthCode

Authorization code you received from an

authorization that you performed outside the
CyberSource system. See "Forced Captures,"
page 121.

ccAuthService
(Required for a forced
capture; otherwise, not
used.)

String (6)

ccAuthService_
veresEnrolled

Verification response enrollment status. For

the description and requirements, see "Payer
Authentication," page 171.

ccAuthService

String (1)

ccAuthService_xid

Transaction identifier. For the description and

requirements, see "Payer Authentication,"
page 171.

ccAuthService

String (40)

ccCaptureService_
aggregatorID

Value that identifies you as a payment

aggregator. Get this value from the processor.
See "Aggregator Support," page 100.

ccCaptureService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

String (15)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

242

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccCaptureService_
aggregatorName

Your payment aggregator business name.

See "Aggregator Support," page 100.

ccCaptureService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

American
Express
Direct:
String (37)

String (26)

ccCaptureService_
authRequestID

Value of the request ID returned from a

previous ccAuthReply.

ccCaptureService

ccCaptureService_
authRequestToken

Value of the request token returned from a

previous request for ccAuthService.

ccCaptureService
(Required for Atos;
otherwise, optional.)

The field is an encoded string that contains no

confidential information, such as an account
number or card verification number. The string
can contain a maximum of 256 characters.

ccCaptureService_
authType

Authorization type.

FDC
Nashville
Global:
String (12)

Required unless
ccAuthService and
ccCaptureService are
both called in the same
request.
String (256)

Atos
When you request the
authorization and
capture services
together, the capture
request does not
require a request token.
ccCaptureService (O)

String (6)

When the transaction contains a verbally

authorized transaction, this field must contain
the value verbal.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

243

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccCaptureService_
dpdeBillingMonth

Dynamic payment descriptor extension

(DPDE) that specifies the month for which you
are billing the cardholder. Depending on your
business model, you might bill for a service
that has already been provided, such as a
telephone service, or you might bill for a
service that is going to be provided, such as a
subscription to investment information. This
value lets the cardholder know which month
the payment is for.

ccCaptureService (O)

String (4)

ccCaptureService (See
the field description.)

String (12)

ccCaptureService (R)

String (5)

Format: YYMM
This field is supported only for JCN Gateway
and is not supported for all Japanese
acquirers.
ccCaptureService_
posData

ccCaptureService_run

Point-of-sale data. On FDMS South, this field

is required for verbal authorizations and forced
captures with the American Express card type
to comply with the CAPN requirements:

Forced capture: Obtain the value for this

field from the authorization response.

Verbal authorization: You cannot obtain a

value for this field so CyberSource uses the
default value. The default value is
generated by CyberSource based on
various factors of the transaction such as
e-commerce or not, card present or not, and
swiped or keyed. See "Verbal
Authorizations," page 84.

Whether to include ccCaptureService in your

request. Possible values:

true: Include the service in your request.

false (default): Do not include the service

in your request.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

244

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccCaptureService_
sequence

Capture number when requesting multiple

partial captures for one authorization. Used
along with ccCaptureService_totalCount to
track which capture is being processed. For
example, the second of five captures would be
passed to CyberSource as
ccCaptureService_sequence = 2 and
ccCaptureService_totalCount = 5.

ccCaptureService
(Required for multiple
captures on Barclays
and TSYS Acquiring
Solutions. Optional for
multiple captures on
FDC Compass and
OmniPay Direct.
Otherwise, not used.)

Integer (2)

ccCaptureService_
totalCount

Total number of captures when requesting

multiple partial captures for one authorization.
Used along with ccCaptureService_
sequence to track which capture is being
processed. For example, the second of five
captures would be passed to CyberSource as
ccCaptureService_sequence = 2 and
ccCaptureService_totalCount = 5.

ccCaptureService
(Required for multiple
captures on Barclays
and TSYS Acquiring
Solutions. Optional for
multiple captures on
FDC Compass and
OmniPay Direct.
Otherwise, not used.)

Integer (2)

ccCaptureService_
transactionID

Transaction ID (TID). On FDMS South, this

field is required for verbal authorizations and
forced captures with the American Express
card type to comply with the CAPN
requirements:

ccCaptureService (See
the field description.)

String (15)

Forced capture: Obtain the value for this

field from the authorization response.

Verbal authorization: You cannot obtain a

value for this field so CyberSource uses the
default value of 000000000000000 (15
zeros). See "Verbal Authorizations,"
page 84, for important information about
using this default value.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

245

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccCaptureService_
verbalAuthCode

Verbally received authorization code.

ccCaptureService (O)

CCS
(CAFIS):
String (7)
JCN
Gateway:
String (7)
All other
processors:
String (6)

ccCreditService_
aggregatorID

Value that identifies you as a payment

aggregator. Get this value from the processor.
See "Aggregator Support," page 100.

ccCreditService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

String (15)

ccCreditService_
aggregatorName

Your payment aggregator business name.

See "Aggregator Support," page 100.

ccCreditService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

American
Express
Direct:
String (37)

ccCreditService (O)

String (5)

ccCreditService_
billPayment

Flag that indicates whether this is a credit for a

bill that the customer paid with a Visa card.
See "Visa Bill Payments," page 207, for a list of
processors that support bill payments with
Visa. This value is case sensitive. Possible
values:

true: Credit for a bill payment.

false (default): Not a credit for a bill

payment

FDC
Nashville
Global:
String (12)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

246

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccCreditService_
captureRequestID

Value of the request ID returned from a

previous request for ccCaptureService.
Creates a follow-on credit by linking the credit
to the previous capture. When you send this
field, you do not need to send several other
credit request fields. See "Crediting a
Payment," page 64, for a description of followon credits.

ccCreditService (O)

String (26)

ccCreditService_
captureRequestToken

Value of the request token returned from a

previous request for ccCaptureService.

ccCreditService
(Required for Atos;
otherwise, optional)

String (256)

ccCreditService (O)

String (13)

The field is an encoded string that contains no

confidential information, such as an account
number or card verification number. The string
can contain a maximum of 256 characters.

ccCreditService_
commerceIndicator

Type of transaction. Use with stand-alone

credits. Some payment card companies use
this information when determining discount
rates. Possible values:

internet (default)

moto

recurring

recurring_internet

For details about these values, see

Appendix F, "Commerce Indicators," on
page 359.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

247

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccCreditService_
dpdeBillingMonth

Dynamic payment descriptor extension

(DPDE) that specifies the month for which you
are billing the cardholder. Depending on your
business model, you might bill for a service
that has already been provided, such as a
telephone service, or you might bill for a
service that is going to be provided, such as a
subscription to investment information. This
value lets the cardholder know which month
the payment is for.

ccCreditService (O)

String (4)

ccCreditService (R)

String (5)

ccDCCService (R)

String (5)

Format: YYMM
This field is supported only for JCN Gateway
and is not supported for all Japanese
acquirers.
ccCreditService_run

ccDCCService_run

Whether to include ccCreditService in your

request. Possible values:

true: Include the service in your request.

false (default): Do not include the service

in your request.

DCC for First Data

Flag that indicates whether ccDCCService
must be called for your request. Possible
values:

true: The service is included in your

request.

false (default): The service is not

included in your request.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

248

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

dcc_dccIndicator

DCC for First Data

Flag that indicates whether DCC is being used
for the transaction. Possible values:

DCC for First Data

ccAuthService (R if you
called the DCC service
for the purchase)

String (1)

debtIndicator

encryptedPayment_
data

1: Converted: DCC is being used.

2: Nonconvertible: DCC cannot be used.

3: Declined: DCC could be used, but the

customer declined it.

ccCaptureService (R if
you called the DCC
service for the
purchase)

For details, see "Dynamic Currency

Conversion for First Data," page 114.

ccCreditService (R if
you called the DCC
service for the
purchase)

Flag that Indicates whether this is a payment

towards an existing contractual loan. See "Visa
Debt Repayments," page 208, for a list of
processors that support this feature. Possible
values:

ccAuthService (O)

true: Loan payment

false (default): Not a loan payment

Apple Pay
Encrypted Apple Pay payment data. Obtain the
encrypted payment data from the
paymentData property of the
PKPaymentToken object as described in the
PassKit Framework Reference. See "Apple
Pay," page 106.

String (5)

ccCreditService (O)

ccAuthService
(Required for Apple Pay
and Visa Checkout
transactions. Otherwise,
not used.)

Apple Pay:
String (3072)

ccAuthService
(Required for Apple Pay
transactions. Otherwise,
not used.)

String (128)

Visa
Checkout:
String (no
maximum
length)

Visa Checkout
Encrypted Visa Checkout payment data.
Obtain the encrypted payment data from Visa
Checkout. See Visa Checkout Using the
Simple Order API.
encryptedPayment_
descriptor

Format of the encrypted payment data. The

value for Apple Pay is RklEPUNPTU1PTi
5BUFBMRS5JTkFQUC5QQVlNRU5U.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

249

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

encryptedPayment_
encoding

Encoding method used to encrypt the payment

data. The value for Apple Pay is Base64.

ccAuthService
(Required for Apple Pay
transactions. Otherwise,
not used.)

String (6)

encryptedPayment_
wrappedKey

Encrypted key that CyberSource uses to

decrypt the payment data. Obtain this value
from the Business Center or your local
CyberSource sales representative. See Visa
Checkout Using the Simple Order API.

ccAuthService4

String (128)

extendedCreditTotal
Count

Number of months the cardholder can use to

pay for the purchase. You can use this field
when offering extended credit to a cardholder
at a retail location. The cardholder provides
this value. The issuer pays you for the
purchase in one payment, and then the
cardholder pays the issuer in the number of
monthly payments specified by this value.

ccAuthService (O)

String (2)

Note This field is supported only for acquirers

in South Africa and only for CyberSource
through VisaNet.

installment_amount

Amount for the current installment payment.

This field is supported only for CyberSource
through VisaNet. See "Installment Payments,"
page 123.

ccAuthService (O)

String (12)

installment_frequency

Frequency of the installment payments. This

field is supported only for CyberSource
through VisaNet. Possible values:

ccAuthService (O)

String (1)

B: Biweekly

M: Monthly

W: Weekly

See "Installment Payments," page 123.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

250

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

installment_planType

Cielo and CyberSource Latin American

Processing
Flag that indicates the type of funding for the
installment plan associated with the payment.
Possible values:

ccAuthService (O)

Cielo:
String (1)

1: Merchant-funded installment plan

2: Issuer-funded installment plan

If you do not include this field in the request,

CyberSource uses the value in your
CyberSource account. To change the value in
your CyberSource account, contact
CyberSource Customer Service. See
"Installment Payments," page 123.

ccCaptureService (O)

CyberSource
Latin
American
Processing:
String (1)
CyberSource
through
VisaNet:
String (2)

CyberSource through VisaNet

American Express-defined code that indicates
the type of installment plan for this transaction.
Contact American Express for:

Information about the kinds of installment

plans that American Express provides

Values for this field

See "Installment Payments," page 123.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

251

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

installment_sequence

Installment number when making payments in

installments. Used along with installment_
totalCount to track which payment is being
processed. For example, the second of 5
payments would be passed to CyberSource as
installment_sequence = 2 and installment_
totalCount = 5. See "Installment Payments,"
page 123.

ccAuthService

Integer (2)

Chase Paymentech Solutions and FDC

Compass
This field is optional because this value is
required in the merchant descriptors. See
"Chase Paymentech Solutions Merchant
Descriptors," page 136, and "FDC Compass
Merchant Descriptors," page 147.
installment_totalAmount

Total amount of the loan that is being paid in

installments. This field is supported only for
CyberSource through VisaNet. See
"Installment Payments," page 123.

Chase Paymentech
Solutions, CyberSource
through VisaNet, and
FDC Compass:
Optional.
CyberSource Latin
American Processing in
Brazil: Not used.
All other processors:
Required for installment
payments

ccAuthService (O)

String (12)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

252

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

installment_totalCount

Total number of installments when making

payments in installments. See"Installment
Payments," page 123.

ccAuthService

Integer (2)

Chase Paymentech Solutions and FDC

Compass
This field is optional because this value is
required in the merchant descriptors. See
"Chase Paymentech Solutions Merchant
Descriptors," page 136, and "FDC Compass
Merchant Descriptors," page 147.
Cielo
This value is the total number of installations
you approved.

Chase Paymentech
Solutions, CyberSource
Latin American
Processing,
CyberSource through
VisaNet, and FDC
Compass: Optional.
All other processors:
Required for installment
payments

CyberSource Latin American Processing in

Brazil
This value is the total number of installments
that you approved. The default is 1.
All Other Processors
This value is used along with installment_
sequence to track which payment is being
processed. For example, the second of 5
payments would be passed to CyberSource as
installment_sequence = 2 and installment_
totalCount = 5.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

253

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
amexDataTAA1

Four Transaction Advice Addendum (TAA)

fields. These fields are used to display
descriptive information about a transaction on
the customers American Express card
statement. When you send TAA fields, start
with invoiceHeader_amexDataTAA1,
then ...TAA2, and so on. Skipping a TAA field
causes subsequent TAA fields to be ignored.

ccCaptureService (O)

String (40)

invoiceHeader_
amexDataTAA2
invoiceHeader_
amexDataTAA3
invoiceHeader_
amexDataTAA4

ccCreditService (O)

To use these fields, contact CyberSource

Customer Support to have your account
enabled for this feature.
For information about merchant descriptors,
including which processors support this field,
see "Merchant Descriptors," page 131.
These fields are frequently used for Level II
transactions. See Level II and Level III
Processing Using the Simple Order API.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

254

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

invoiceHeader_
merchantDescriptor

For the descriptions, used-by information, data

types, and lengths for these fields, see
"Merchant Descriptors," page 131.

invoiceHeader_
merchantDescriptor
Alternate

Used By:
Required (R)
or Optional (O)

Data Type
& Length

ccAuthService
(Required for
MasterCard aggregator
transactions on
CyberSource through
VisaNet; otherwise, not
used.)

Nonnegative
integer (11)

invoiceHeader_
merchantDescriptor
City
invoiceHeader_
merchantDescriptor
Contact
invoiceHeader_
merchantDescriptor
Country
invoiceHeader_
merchantDescriptor
PostalCode
invoiceHeader_
merchantDescriptor
Street
invoiceHeader_
salesOrganizationID

Company ID assigned to an independent sales

organization. Get this value from MasterCard.
See "Aggregator Support," page 100.
CyberSource through VisaNet
The value for this field corresponds to the
following data in the TC 33 capture file5:

Record: CP01 TCR6

Position: 106-116

Field: MasterCard Independent Sales

Organization ID

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

255

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
submerchantCity

Sub-merchants city. See "Aggregator

Support," page 100.

ccAuthService

American
Express
Direct:
String (14)

ccCaptureService
ccCreditService

invoiceHeader_
submerchantCountry

Sub-merchants country. Use the two-character

ISO Standard Country Codes. See
"Aggregator Support," page 100.

Required for aggregator

transactions on
American Express
Direct and FDC
Nashville Global.

FDC
Nashville
Global:
String (11)

ccAuthService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

String (3)

ccCaptureService
(Required for
aggregator transactions
on American Express
Direct.)
ccCreditService
(Required for
aggregator transactions
on American Express
Direct.)
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

256

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
submerchantEmail

Sub-merchants email address. See

"Aggregator Support," page 100.

ccAuthService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

American
Express
Direct:
String (40)

ccCaptureService
(Required for
aggregator transactions
on American Express
Direct.)

FDC
Nashville
Global:
String (19)

ccCreditService
(Required for
aggregator transactions
on American Express
Direct.)
invoiceHeader_
submerchantID

The ID you assigned to your sub-merchant.

See "Aggregator Support," page 100.
This field is required for aggregator
transactions on:

American Express Direct

CyberSource through VisaNetMasterCard

only

FDC Nashville Global

CyberSource through VisaNet

The value for this field corresponds to the
following data in the TC 33 capture file5:

Record: CP01 TCR6

Position: 117-131

Field: MasterCard Sub-Merchant ID

ccAuthService
ccCaptureService
ccCreditService
See field description.

American
Express
Direct:
String (20)
CyberSource
through
VisaNet:
String (15)
FDC
Nashville
Global:
String (14)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

257

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
submerchant
MerchantID

Unique identifier assigned by the payment card

company to the sub-merchant. See
"Aggregator Support," page 100.

ccAuthService (Optional
for aggregator
transactions FDC
Nashville Global.)

String (15)

ccAuthService

American
Express
Direct:
String (36)

This value is supported only for American

Express on FDC Nashville Global aggregator
transactions.
invoiceHeader_
submerchantName

Sub-merchants business name. See

"Aggregator Support," page 100.

ccCaptureService
ccCreditService
Required for aggregator
transactions on
American Express
Direct and FDC
Nashville Global.

FDC
Nashville
Global:
String (12)

invoiceHeader_
submerchantRegion

Sub-merchants region. Example: NE indicates

that the sub-merchant is in the northeast
region. See "Aggregator Support," page 100.

ccAuthService (Optional
for aggregator
transactions FDC
Nashville Global.)

String (3)

invoiceHeader_
submerchantPostal
Code

Partial postal code for the sub-merchants

address. See "Aggregator Support," page 100.

ccAuthService

String (9)

ccCaptureService
ccCreditService
Required for aggregator
transactions on FDC
Nashville Global.

invoiceHeader_
submerchantState

Sub-merchants state or province. Use the

State, Province, and Territory Codes for the
United States and Canada. See "Aggregator
Support," page 100.

ccAuthService

String (3)

ccCaptureService
ccCreditService
Required for aggregator
transactions on
American Express
Direct and FDC
Nashville Global.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

258

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

invoiceHeader_
submerchantStreet

First line of the sub-merchants street address.

See "Aggregator Support," page 100.

ccAuthService

American
Express
Direct:
String (29)

ccCaptureService
ccCreditService

invoiceHeader_
submerchantTelephone
Number

Sub-merchants telephone number. See

"Aggregator Support," page 100.

Required for aggregator

transactions on
American Express
Direct and FDC
Nashville Global.

FDC
Nashville
Global:
String (25)

ccAuthService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global.)

American
Express
Direct:
String (20)

ccCaptureService
(Required for
aggregator transactions
on American Express
Direct.)

FDC
Nashville
Global:
String (10)

ccCreditService
(Required for
aggregator transactions
on American Express
Direct.)
item_#_productCode

Type of product. This value is used to

determine the category that the product is in:
electronic, handling, physical, service, or
shipping. The default value is default. See
Table 70, "Product Codes," on page 378 for a
list of valid values.

ccAuthService (O)

String (255)

ccCaptureService (O)
ccCreditService (O)
ccDCCService (O)

For ccAuthService, when you set this field to

a value other than default or any of the
values related to shipping and/or handling, the
item_#_quantity, item_#_productName, and
item_#_productSKU fields are required.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

259

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

item_#_productName

For ccAuthService and ccCaptureService,

this field is required when item_#_
productCode is not default or one of the
values related to shipping and/or handling.

ccAuthService (See the

field description.)

String (255)

ccCaptureService (See
the field description.)
ccDCCService (O)

item_#_productSKU

Identification code for the product. For

ccAuthService and ccCaptureService, this
field is required when item_#_productCode is
not default or one of the values related to
shipping and/or handling.

ccAuthService (See the

field description.)

String (255)

ccCaptureService (See
the field description.)
ccDCCService (O)

item_#_quantity

The default is 1. For ccAuthService and

ccCaptureService, this field is required when
item_#_productCode is not default or one
of the values related to shipping and/or
handling.

ccAuthService (See the

field description.)

Integer (10)

ccAuthReversal
Service (O)
ccCaptureService (See
the field description.)
ccCreditService (O)
ccDCCService (O)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

260

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

item_#_taxAmount

Total tax to apply to the product. This value

cannot be negative. The tax amount and the
unit price must be in the same currency.

ccAuthService (O)

String (15)

The tax amount field is additive. The following

example uses a two-exponent currency such
as USD:

ccCaptureService (O)
ccCreditService (O)

1 You include the following items in your

request:

item_0_unitPrice=10.00
item_0_quantity=1
item_0_taxAmount=0.80
item_1_unitPrice=20.00
item_1_quantity=1
item_1_taxAmount=1.60
2 The total amount authorized will be 32.40,
not 30.00 with 2.40 of tax included.
If you want to include the tax amount and also
request the taxService service, see Tax
Calculation Service Using the Simple Order
API.
This field is frequently used for Level II and
Level III transactions. See Level II and Level III
Processing Using the Simple Order API.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

261

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

item_#_unitPrice

Per-item price of the product. This value

cannot be negative. You can include a decimal
point (.), but you cannot include any other
special characters. CyberSource truncates the
amount to the correct number of decimal
places.

ccAuthService3

String (15)

ccAuthReversal
Service3
ccCaptureService3
ccCreditService3

Important Some processors have specific

requirements and limitations, such as
maximum amounts and maximum field
lengths. This information is covered in:

Table 10, "Authorization Information for

Specific Processors," on page 35

Table 12, "Capture Information for Specific

Processors," on page 52

Table 14, "Credit Information for Specific

Processors," on page 67

DCC for First Data

This value is the original amount in your local
currency. You must include this field. You
cannot use purchaseTotals_
grandTotalAmount. See "Dynamic Currency
Conversion for First Data," page 114.
FDMS South
If you accept IDR or CLP currencies, see the
entry for FDMS South in Table 10,
"Authorization Information for Specific
Processors," on page 35.
Zero Amount Authorizations
If your processor supports zero amount
authorizations, you can set this field to 0 for
the authorization to check if the card is lost or
stolen. See "Zero Amount Authorizations,"
page 209.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

262

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

jpo_bonusAmount

Japanese payment option bonus amount:

Amount of the payment during the bonus
month. The value must be greater than 0.

ccAuthService

Nonnegative
integer (8)

ccCaptureService
ccCreditService
Required when jpo_
paymentMethod is 6;
otherwise, not used.

jpo_bonuses

Japanese payment option bonuses: Number of

bonus payments.

ccAuthService

Integer (2)

ccCaptureService
ccCreditService
Required when jpo_
paymentMethod is 3 or
6; otherwise, not used.

jpo_installments

Japanese payment option installments:

Number of installment payments.

ccAuthService

Integer (2)

ccCaptureService
ccCreditService
Required when jpo_
paymentMethod is 4 or
6; otherwise, not used.

jpo_paymentMethod

Japanese payment option payment method:

type of payment option. Possible values:

1 (default): Single payment

2: Bonus payment

3: Installment bonus payment

4: Installment

5: Revolving repayment

6: Combination of installment and bonus

payment

ccAuthService (O)

Integer (1)

ccCaptureService (O)
ccCreditService (O)

See "Japanese Payment Options," page 128.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

263

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

linkToRequest

Value that links the current authorization

request to the original authorization request.
Set this value to the request ID that was
returned in the reply message from the original
authorization request.

ccAuthService (O)

String (26)

This value is used for:

Partial authorizations: see "Partial

Authorizations," page 88.

Split shipments: see "Split Shipments,"

page 199.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

264

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

merchantCategoryCode

Four-digit number that the payment card

industry uses to classify merchants into market
segments. Visa assigned one or more of these
values to your business when you started
accepting Visa cards.

ccAuthService
(Required for
aggregator transactions
on American Express
Direct and FDC
Nashville Global;
otherwise optional.)

Integer (4)

If you do not include this field in your request,

CyberSource uses the value in your
CyberSource account.
This field is supported only for:

American Express Direct on aggregator

transactionswill not be populated by the
value in your CyberSource account.

CyberSource through VisaNet.

FDC Nashville Global

See "Aggregator Support," page 100.

ccCaptureService
(Required for
aggregator transactions
on FDC Nashville
Global.)
ccCreditService
(Required for
aggregator transactions
on FDC Nashville
Global.)

CyberSource through VisaNet

The value for this field corresponds to the
following data in the TC 33 capture file5:

Record: CP01 TCR4

Position: 150-153

Field: Merchant Category Code

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

265

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

merchantDefinedData_
field1 to
merchantDefinedData_
field20

Fields that you can use to store information.

ccAuthService (O)

String (255)

Important These fields have been replaced

by merchantDefinedData_mddField_1 to
100. CyberSource recommends that you
update your order management system to use
the new fields.

ccCaptureService (O)
ccCreditService (O)

Warning Merchant-defined fields must not

be used to capture personally identifying
information as stated in the warning under the
following field description for
merchantDefinedData_mddField_1 to 100.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

266

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

merchantDefinedData_
mddField_1 to
merchantDefinedData_
mddField_100

Fields that you can use to store information.

ccAuthService (O)

String (255)

Important These fields override the old

merchant-defined data fields. For example, if
you use the obsolete field
merchantDefinedData_field15 and the new
field merchantDefinedData_mddField_15 in
the same request, the value for the new field
overwrites the value for the obsolete field.

ccCaptureService (O)
ccCreditService (O)

Warning Merchant-defined data fields are

not intended to and must not be used to
capture personally identifying information.
Accordingly, merchants are prohibited from
capturing, obtaining, and/or transmitting any
personally identifying information in or via the
merchant-defined data fields. Personally
identifying information includes, but is not
limited to, address, credit card number, social
security number, driver's license number,
state-issued identification number, passport
number, and card verification numbers (CVV,
CVC2, CVV2, CID, CVN). In the event
CyberSource discovers that a merchant is
capturing and/or transmitting personally
identifying information via the merchantdefined data fields, whether or not intentionally,
CyberSource will immediately suspend the
merchant's account, which will result in a
rejection of any and all transaction requests
submitted by the merchant after the point of
suspension.
merchantID

Your CyberSource merchant ID. Use the same

merchant ID for evaluation, testing, and
production.

Required for all credit

card services.

String (30)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

267

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

merchantReference
Code

Merchant-generated order reference or

tracking number. CyberSource recommends
that you send a unique value for each
transaction so that you can perform meaningful
searches for the transaction. For information
about tracking orders, see Getting Started with
CyberSource Advanced for the Simple Order
API.

Required for all credit

card services.

Asia, Middle
East, and
Africa
Gateway:
String (40)
Atos:
String (32)
All other
processors:
String (50)

FDC Nashville Global

Certain circumstances can cause the
processor to truncate this value to 15 or 17
characters for Level II and Level III processing,
which can cause a discrepancy between the
value you submit and the value included in
some processor reports.
merchantTransaction
Identifier

Identifier that you assign to the transaction.

See "Merchant-Initiated Reversals and Voids,"
page 168.

ccAuthService (O)

String (15)

ccAuthReversal
Service (O)
ccCaptureService (O)
ccCreditService (O)
voidService (O)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

268

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

nationalNetDomestic
Data

Supplementary domestic transaction

information provided by the acquirer for
National Net Settlement Service (NNSS)
transactions. NNSS is a settlement service that
Visa provides. For transactions on
CyberSource through VisaNet in countries that
subscribe to NNSS:

ccAuthService (O)

String (123)

VisaNet clears transactions; VisaNet

transfers funds to the acquirer after
deducting processing fees and interchange
fees.

VisaNet settles transactions in the local

currency through a local financial institution.

ccAuthReversal
Service (O)
ccCaptureService (O)
ccCreditService (O)

This field is supported only on CyberSource

through VisaNet for domestic data in
Colombia.
orderRequestToken

The request token value returned from a

previous request. This value links the previous
request to the current follow-on request. This
field is an encoded string that does not contain
any confidential information, such as account
numbers or card verification numbers. The
string can contain a maximum of 256
characters.

ccAuthReversal
Service (O)

String (256)

ccCaptureService
(Required for Atos;
otherwise, optional.
When you request the
authorization and
capture services
together, the capture
request does not
require a request
token.)
ccCreditService
(Required for Atos;
otherwise, optional.)
voidService (Required
for Atos; otherwise,
optional.)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

269

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

paymentSolution

Type of payment solution that is being used for

the transaction. Possible Values:

ccAuthService (See
description.)

Apple Pay
and
MasterPass:
String (3)

001: Apple Pay. This value is required for

Apple Pay transactions See "Apple Pay,"
page 106.

005: MasterPass. This value is required for

MasterPass transactions on OmniPay
Direct. See "MasterPass," page 130.

ccAuthReversal
Service4
ccCaptureService4
ccCreditService4

Visa
Checkout:
String (12)

visacheckout: Visa Checkout. This

value is required for Visa Checkout
transactions. See Visa Checkout Using the
Simple Order API.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

270

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

pos_environment

Operating environment. Possible values:

ccAuthService (O)

String (1)

0: No terminal used or unknown

environment.

1: On merchant premises, attended.

2: On merchant premises, unattended, or

cardholder terminal. Examples: oil, kiosks,
self-checkout, home computer, mobile
telephone, personal digital assistant (PDA).
Cardholder terminal is supported only for
MasterCard transactions on CyberSource
through VisaNet.

3: Off merchant premises, attended.

Examples: portable POS devices at trade
shows, at service calls, or in taxis.

4: Off merchant premises, unattended, or

cardholder terminal. Examples: vending
machines, home computer, mobile
telephone, PDA. Cardholder terminal is
supported only for MasterCard transactions
on CyberSource through VisaNet.

5: On premises of cardholder, unattended.

9: Unknown delivery mode.

S: Electronic delivery of product. Examples:

music, software, or eTickets that are
downloaded over the internet.

T: Physical delivery of product. Examples:

music or software that is delivered by mail or
by a courier.

This field is supported only for American

Express Direct and CyberSource through
VisaNet.
CyberSource through VisaNet
For MasterCard transactions, the only valid
values are 2 and 4.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.
Credit Card Services Using the Simple Order API | January 2016

271

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

processorID

Value that identifies the processor/acquirer to

use for the transaction. This value is supported
only for CyberSource through VisaNet. Contact
CyberSource Customer Support to get the
value for this field.

ccAuthService (O)

String (3)

Additional amount. This field is supported only

for American Express Direct. See "Additional
Amounts," page 99.

ccCaptureService (O)

Additional amount type. This field is supported

only for American Express Direct. See
"Additional Amounts," page 99, for a
description of this feature. For the possible
values for this field, see Appendix C,
"Additional Amount Types," on page 351.

ccCaptureService (O)

purchaseTotals_
additionalAmount0
purchaseTotals_
additionalAmount1

ccCreditService (O for
stand-alone credits;
otherwise, not used.)
String (12)

ccCreditService (O)

purchaseTotals_
additionalAmount2
purchaseTotals_
additionalAmount3
purchaseTotals_
additionalAmount4
purchaseTotals_
additionalAmountType0
purchaseTotals_
additionalAmountType1
purchaseTotals_
additionalAmountType2

String (3)

ccCreditService (O)

purchaseTotals_
additionalAmountType3
purchaseTotals_
additionalAmountType4
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

272

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

purchaseTotals_
currency

Currency used for the order. Use the threecharacter ISO Standard Currency Codes.

ccAuthService (R)

String (5)

For ccAuthReversalService and

ccCaptureService, you must use the same
currency that you used in your request for
ccAuthService.

purchaseTotals_
exchangeRate

ccAuthReversal
Service (R)
ccCaptureService (R)
ccCreditService (R)

DCC for First Data

Your local currency. See "Dynamic Currency
Conversion for First Data," page 114.

ccDCCService (R)

DCC for First Data

Exchange rate returned by the DCC service.
Includes a decimal point and a maximum of 4
decimal places. For details, see "Dynamic
Currency Conversion for First Data," page 114.

DCC for First Data

ccAuthService (R for
DCC transactions)

DCC for First

Data:
String (13)

ccCaptureService (R for
DCC transactions)
ccCreditService (R for
DCC transactions)

purchaseTotals_
exchangeRateTime
Stamp

purchaseTotals_
foreignAmount

DCC for First Data

Time stamp for the exchange rate. This value
is returned by the DCC service.

DCC for First Data

ccAuthService (R for
DCC transactions)

Format: YYYYMMDD~HH:MM
where ~ denotes a space.

ccCaptureService (R for
DCC transactions)

For details, see "Dynamic Currency

Conversion for First Data," page 114.

ccCreditService (R for
DCC transactions)

DCC for First Data

Converted amount returned by the DCC
service. For details, see "Dynamic Currency
Conversion for First Data," page 114.

DCC for First Data

ccAuthService (R for
DCC transactions)

String (14)

String (15)

ccCaptureService (R for
DCC transactions)
ccCreditService (R for
DCC transactions)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

273

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

purchaseTotals_
foreignCurrency

DCC for First Data

Billing currency returned by the DCC service.
For the possible values, see the ISO Standard
Currency Codes. For details about DCC, see
"Dynamic Currency Conversion for First Data,"
page 114.

DCC for First Data

ccAuthService (R for
DCC transactions)

String (5)

ccCaptureService (R for
DCC transactions)
ccCreditService (R for
DCC transactions)

purchaseTotals_
grandTotalAmount

ccAuthService3

Grand total for the order. This value cannot be

negative. You can include a decimal point (.),
but you cannot include any other special
characters. CyberSource truncates the amount
to the correct number of decimal places.

ccAuthReversal
Service3

Important Some processors have specific

ccCreditService3

String (15)

ccCaptureService3

requirements and limitations, such as

maximum amounts and maximum field
lengths. This information is covered in:

Table 10, "Authorization Information for

Specific Processors," on page 35

Table 12, "Capture Information for Specific

Processors," on page 52

Table 14, "Credit Information for Specific

Processors," on page 67

If your processor supports zero amount

authorizations, you can set this field to 0 for
the authorization to check if the card is lost or
stolen. See "Zero Amount Authorizations,"
page 209.
DCC for First Data
Not used.
FDMS South
If you accept IDR or CLP currencies, see the
entry for FDMS South in Table 10,
"Authorization Information for Specific
Processors," on page 35.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

274

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

recipient_accountID

Identifier for the recipients account. Use the

first six digits and last four digits of the
recipients account number.

ccAuthService
(Required in recipient
transactions; otherwise,
not used)

String with
numbers
only (10)

This field is a pass-through, which means that

CyberSource does not verify the value or
modify it in any way before sending it to the
processor. If the field is not required for the
transaction, CyberSource does not forward it
to the processor. See "Recipients," page 187.
recipient_dateOfBirth

Recipients date of birth. Format: YYYYMMDD.

This field is a pass-through, which means that
CyberSource ensures that the value is eight
numeric characters but otherwise does not
verify the value or modify it in any way before
sending it to the processor. If the field is not
required for the transaction, CyberSource does
not forward it to the processor. See
"Recipients," page 187.

ccAuthService
(Required in recipient
transactions; otherwise,
not used)

String with
numbers
only (8)

recipient_lastName

Recipients last name. This field is a passthrough, which means that CyberSource does
not verify the value or modify it in any way
before sending it to the processor. If the field is
not required for the transaction, CyberSource
does not forward it to the processor. See
"Recipients," page 187.

ccAuthService
(Required in recipient
transactions; otherwise,
not used)

String with
letters and
numbers
only (6)

recipient_postalCode

Partial postal code for the recipients address.

For example, if the postal code is NN5 7SG,
the value for this field should be the first part of
the postal code: NN5.

ccAuthService
(Required in recipient
transactions; otherwise,
not used)

String with
letters and
numbers
only (6)

This field is a pass-through, which means that

CyberSource does not verify the value or
modify it in any way before sending it to the
processor. If the field is not required for the
transaction, CyberSource does not forward it
to the processor. See "Recipients," page 187.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

275

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

recurringSubscription
Info_subscriptionID

When you use Payment Tokenization or

Recurring Billing and you include this value in
your request, many of the fields that are
normally required for an authorization or credit
become optional. See "Payment Tokenization,"
page 185, and "Recurring Billing," page 188.

ccAuthService (O)

String (26)

reportGroup

Attribute that lets you define custom grouping

for your processor reports. This field is
supported only for Litle. See "Report Groups,"
page 197.

ccAuthService (O)

ccCreditService (O)

String (25)

ccAuthReversal
Service (O)
ccCaptureService (O)
ccCreditService (O)

shipFrom_postalCode

Postal code for the address from which the

goods are shipped, which is used to establish
nexus. The default is the postal code
associated with your CyberSource account.
The postal code must consist of 5 to 9 digits.

ccCaptureService (O)

String (10)

ccCreditService (O)

When the billing country is the U.S., the 9-digit

postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
When the billing country is Canada, the 6-digit
postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3
This field is frequently used for Level II and
Level III transactions. See Level II and Level III
Processing Using the Simple Order API.
American Express Direct
Before sending the postal code to the
processor, CyberSource removes all nonalphanumeric characters and, if the remaining
value is longer than nine characters, truncates
the value starting from the right side.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

276

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

shipTo_city

City to ship the product to.

ccAuthService

String (50)

Required if any shipping

address information is
included in the request
and shipping to the U.S.
or Canada; otherwise,
optional.
shipTo_country

Country to ship the product to. Use the twocharacter ISO Standard Country Codes.

ccAuthService

String (2)

ccCaptureService
ccCreditService
Required if any shipping
address information is
included in the request;
otherwise, optional.

shipTo_firstName

First name of the person receiving the product.

ccAuthService (O)

Litle:
String (25)
All other
processors:
String (60)

shipTo_lastName

Last name of the person receiving the product.

ccAuthService (O)

Litle:
String (25)
All other
processors:
String (60)

shipTo_phoneNumber

Phone number for the shipping address.

ccAuthService (O)

String (15)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

277

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

shipTo_postalCode

Postal code for the shipping address. The

postal code must consist of 5 to 9 digits.

ccAuthService

String (10)

When the shipping country is the U.S., the 9digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
When the shipping country is Canada, the 6digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: A1B 2C3

ccCaptureService
ccCreditService
Required if any shipping
address information is
included in the request
and shipping to the U.S.
or Canada; otherwise,
optional.

American Express Direct

Before sending the postal code to the
processor, CyberSource removes all nonalphanumeric characters and, if the remaining
value is longer than nine characters, truncates
the value starting from the right side.
shipTo_shippingMethod

Shipping method for the product. Possible

values:

sameday: Courier or same-day service

oneday: Next day or overnight service

twoday: Two-day service

threeday: Three-day service

lowcost: Lowest-cost service

pickup: Store pick-up

other: Other shipping method

none: No shipping method because

product is a service or subscription

ccAuthService (O)

String (10)

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

278

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

shipTo_state

State or province of the address to ship the

product to. Use the State, Province, and
Territory Codes for the United States and
Canada.

ccAuthService

String (2)

First line of the address to ship the product to.

ccAuthService

shipTo_street1

Required if any shipping

address information is
included in the request
and shipping to the U.S.
or Canada; otherwise,
optional.
String (60)

Required if any shipping

address information is
included in the request;
otherwise, optional.
shipTo_street2

Second line of the address to ship the product

to.

ccAuthService (O)

String (60)

surchargeAmount

The surcharge amount is included in the total

transaction amount but is passed in a separate
field to the issuer and acquirer for tracking. The
issuer can provide information about the
surcharge amount to the customer. This field is
supported only for CyberSource through
VisaNet.

ccAuthService (O)

String (15)

surchargeSign

Sign for the surcharge amount. Possible

values:

ccAuthService (O)

String (1)

C: The surcharge amount will be credited to

the customers account.

D: The surcharge amount will be debited

from the customers account.

This field is supported only for CyberSource

through VisaNet.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

279

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

transactionLocalDate
Time

Local date and time at your physical location.

Include both the date and time in this field or
leave it blank. This field is supported only for
CyberSource through VisaNet.

ccAuthService (O)

String (14)

Format: YYYYMMDDhhmmss
where:

YYYY = year

MM = month

DD = day

hh = hour

mm = minutes

ss = seconds

ucaf_
authenticationData

Universal cardholder authentication field

(UCAF) data. For the description and
requirements, see "Payer Authentication,"
page 171.

ccAuthService

String (32)

ucaf_collectionIndicator

Universal cardholder authentication field

(UCAF) collection indicator. For the description
and requirements, see "Payer Authentication,"
page 171.

ccAuthService

String with
numbers
only (1)

ccAuthService4

String (48)

CyberSource through VisaNet

The value for this field corresponds to the
following data in the TC 33 capture file5:

vc_orderID

Record: CP01 TCR7

Position: 5

Field: MasterCard Electronic Commerce

IndicatorsUCAF Collection Indicator

Identifier for the Visa Checkout order. Obtain

this value from the callID field from Visa
Checkout.

ccAuthReversal
Service4
ccCaptureService4
ccCreditService4

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

280

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

voidService_run

Whether to include voidService in your

request. Possible values:

voidService (R)

String (5)

true: Include the service in your request.

false (default): Do not include the service

in your request.

voidService_
voidRequestID

Request ID of the capture or credit you want to

void.

voidService (R)

String (26)

voidService_
voidRequestToken

Value of the request token returned from a

previous request for a service that you want to
void.

voidService (Required
for Atos; otherwise,
optional.)

String (256)

The field is an encoded string that contains no

confidential information, such as an account
number or card verification number. The string
can contain a maximum of 256 characters.

1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.

2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

281

Appendix A

Table 58

API Fields

Request Fields (Continued)

Field

Description

Used By:
Required (R)
or Optional (O)

Data Type
& Length

wallet_type

Type of wallet. For possible values, see

Appendix Q, "Values for the Wallet Type Field,"
on page 389.

MasterPass (101 and

102)
ccAuthService (O)

String (5)

This field is a passthrough; therefore,

CyberSource does not verify the value or
modify it in any way before sending it to the
processor.

ccCreditService (O on
Chase Paymentech
Solutions and
CyberSource through
VisaNet. Not used for
credits on OmniPay
Direct.)

Payment card companies can introduce new

values without notice. Your order management
system should be able to process new values
without problems.
CyberSource through VisaNet
This field is supported only for authorizations.
It is not supported for credits.
When the value for this field is 101 or 102, it
corresponds to the following data in the TC 33
capture file5:

Record: CP01 TCR6

Position: 88-90

Field: MasterCard Wallet Identifier

Staged Digital Wallet

(SDW)
ccAuthService (O)
ccCreditService (O)
Visa Checkout
(VCIND)
ccAuthService (R)
ccCreditService (O for
stand-alone credits. Not
used for follow-on
credits.)

When the value for this field is VCIND, it

corresponds to the following data in the TC 33
capture file5:

Record: CP01 TCR8

Position: 72-76

Field: Agent Unique ID

MasterPass (101 and 102)

The MasterPass platform generates the wallet
type value and passes it to you along with the
customers checkout information.
1 Optional for a follow-on credit request, which must include ccCreditService_captureRequestID.
2 For this card type, you must include the card_cardType field in your request for an authorization or a stand-alone credit.
3 You must include either item_#_unitPrice or purchaseTotals_grandTotalAmount in your request. For information about items
and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API.
4 Required for Visa Checkout transactions. Otherwise, not used.
5 The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource.
CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchants acquirer, who uses
this information to facilitate end-of-day clearing processing with payment networks.
6 This field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See
"Relaxed Requirements for Address Data and Expiration Date," page 75. Important It is your responsibility to determine whether a
field is required for the transaction you are requesting.

Credit Card Services Using the Simple Order API | January 2016

282

Appendix A

API Fields

Reply Fields
Table 59

Reply Fields

Field

Description

Returned By

Data Type
& Length

additionalData

This field might contain information about a

decline. This field is supported only for
CyberSource through VisaNet.

ccAuthReply

String (255)

additionalProcessor
Response

Processor-defined response category code. The

associated detail error code is in the
ccAuthReply_processorResponse field or the
ccAuthReversalReply_processorResponse
field depending on which service you requested.

ccAuthReply

Integer (3)

ccAuthReversal
Reply

This field is supported only for:

Japanese issuers

Domestic transactions in Japan

ccAuthReply_
accountBalance

Remaining balance on the account. See "Balance

Responses," page 94, and "Balance Inquiries,"
page 110.

ccAuthReply

String (12)

ccAuthReply_
accountBalanceCurrency

Currency of the remaining balance on the account.

For the possible values, see the ISO Standard
Currency Codes. Also see "Balance Responses,"
page 94 and "Balance Inquiries," page 110.

ccAuthReply

String (5)

ccAuthReply_
accountBalanceSign

Sign for the remaining balance on the account.

Returned only when the processor returns this
value. See "Balance Inquiries," page 110.

ccAuthReply

String (8)

ccAuthReply

String (2)

Possible values:

ccAuthReply_
accountType

positive

negative

Type of account. This value is returned only if you

requested a balance inquiry. See "Balance
Inquiries," page 110.
Possible values:

00: Not applicable or not specified

10: Savings account

20: Checking account

30: Credit card account

40: Universal account

Credit Card Services Using the Simple Order API | January 2016

283

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
affluenceIndicator

Chase Paymentech Solutions

Indicates whether a customer has high credit
limits. This information enables you to market high
cost items to these customers and to understand
the kinds of cards that high income customers are
using.

ccAuthReply

Chase
Paymentech
Solution:
String (1)
Litle:
String (13)

This field is supported for Visa, MasterCard,

Discover, and Diners Club.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

Litle
Flag that indicates that a Visa cardholder or
MasterCard cardholder is in one of the affluent
categories. Possible values:

AFFLUENT: High income customer with high

spending pattern (>100k USD annual income
and >40k USD annual card usage).

MASS AFFLUENT: High income customer

(>100k USD annual income).

ccAuthReply_amount

Amount that was authorized.

ccAuthReply

String (15)

FDMS South
If you accept IDR or CLP currencies on FDMS
South, see the entry for FDMS South in Table 10,
"Authorization Information for Specific
Processors," on page 35.

Credit Card Services Using the Simple Order API | January 2016

284

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
amountType

Type of amount. This value is returned only if you

requested a balance inquiry. The issuer
determines the value that is returned. See
"Balance Inquiries," page 110.

ccAuthReply

String (2)

ccAuthReply

String (7 or
more)

Possible values for deposit accounts:

01: Current ledger (posted) balance.

02: Current available balance, which is typically

the ledger balance less outstanding
authorizations. Some depository institutions
also include pending deposits and the credit or
overdraft line associated with the account.

Possible values for credit card accounts:

ccAuthReply_
authorizationCode

01: Credit amount remaining for customer

(open to buy).

02: Credit limit.

Authorization code. Returned only when the

processor returns this value.
Elavon Encrypted Account Number Program
The returned value is OFFLINE. See "Encoded
Account Numbers," page 119.

The length of
this value
depends on
your
processor.

TSYS Acquiring Solutions

The returned value for a successful zero amount
authorization is 000000. See "Zero Amount
Authorizations," page 209.
ccAuthReply_
authorizedDateTime

Time of authorization.

ccAuthReply

String (20)

Format: YYYY-MM-DDThh:mm:ssZ
Example: 2012-08-11T22:47:57Z is equal to
August 11, 2012, at 10:47:57 P.M. The T separates
the date and the time. The Z indicates UTC.

ccAuthReply_avsCode

AVS results. See "Address Verification System

(AVS)," page 72, for a description of AVS. See
Appendix E, "AVS Codes," on page 355, for the list
of AVS codes.

ccAuthReply

String (1)

ccAuthReply_
avsCodeRaw

AVS result code sent directly from the processor.

Returned only when the processor returns this
value.

ccAuthReply

String (10)

Important Do not use this field to evaluate the

result of AVS. Use for debugging purposes only.

Credit Card Services Using the Simple Order API | January 2016

285

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
cardCategory

CyberSource through VisaNet

Visa product ID. For the possible values, see "Visa
Product IDs," page 379.

ccAuthReply

CyberSource
through
VisaNet:
String (3)

GPN
Visa or MasterCard product ID. For the possible
values, see Appendix N, "Product IDs," on
page 379.

GPN:
String (3)
Litle:
String (7)

Litle
Type of card used in the transaction. The only
possible value is:

RBS
WorldPay
Atlanta:
String (1)

PREPAID: Prepaid Card

RBS WorldPay Atlanta

Type of card used in the transaction. Possible
values:

ccAuthReply_
cardCommercial

B: Business Card

O: Noncommercial Card

R: Corporate Card

S: Purchase Card

Blank: Purchase card not supported

Indicates whether the card is a commercial card,

which enables you to include Level II data in your
transaction requests.

ccAuthReply

String (1)

ccAuthReply

String (1)

This field is supported for Visa and MasterCard on

Chase Paymentech Solutions.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

ccAuthReply_
cardGroup

Type of commercial card. This field is supported

only for CyberSource through VisaNet. Possible
values:

B: Business card

R: Corporate card

S: Purchasing card

0: Noncommercial card

Credit Card Services Using the Simple Order API | January 2016

286

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
cardHealthcare

Indicates whether the card is a healthcare card.

ccAuthReply

String (1)

ccAuthReply

String (3)

ccAuthReply

String (1)

ccAuthReply

String (1)

This field is supported for Visa and MasterCard on

Chase Paymentech Solutions.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

ccAuthReply_
cardIssuerCountry

Country in which the card was issued. This

information enables you to determine whether the
card was issued domestically or internationally.
Use the two-character ISO Standard Country
Codes.
This field is supported for Visa, MasterCard,
Discover, Diners Club, JCB, and Maestro
(International) on Chase Paymentech Solutions.
See "Card Type Indicators (CTIs)," page 112.

ccAuthReply_
cardLevel3Eligible

Indicates whether the card is eligible for Level III

interchange fees, which enables you to include
Level III data in your transaction requests.
This field is supported for Visa and MasterCard on
Chase Paymentech Solutions.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

ccAuthReply_
cardPayroll

Indicates whether the card is a payroll card.

This field is supported for Visa, Discover, Diners
Club, and JCB on Chase Paymentech Solutions.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

Credit Card Services Using the Simple Order API | January 2016

287

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
cardPINlessDebit

Indicates whether the card is a PINless debit card.

ccAuthReply

String (1)

ccAuthReply

String (1)

ccAuthReply

String (1)

This field is supported for Visa and MasterCard on

Chase Paymentech Solutions.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

ccAuthReply_
cardPrepaid

Indicates whether the card is a prepaid card. This

information enables you to determine when a gift
card or prepaid card is presented for use when
establishing a new recurring, installment, or
deferred billing relationship.
This field is supported for Visa, MasterCard,
Discover, Diners Club, and JCB on Chase
Paymentech Solutions.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

ccAuthReply_
cardRegulated

Indicates whether the card is regulated according

to the Durbin Amendment. If the card is regulated,
the card issuer is subject to price caps and
interchange rules.
This field is supported for Visa, MasterCard,
Discover, Diners Club, and JCB on Chase
Paymentech Solutions.
Possible values:

Y: Yes (assets greater than $10B)

N: No (assets less than $10B)

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

Credit Card Services Using the Simple Order API | January 2016

288

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
cardSignatureDebit

Indicates whether the card is a signature debit

card. This information enables you to alter the way
an order is processed. For example, you might not
want to reauthorize a transaction for a signature
debit card, or you might want to perform reversals
promptly for a signature debit card.

ccAuthReply

String (1)

ccAuthReply

String (3)

ccAuthReply

String (3)

This field is supported for Visa, MasterCard, and

Maestro (International) on Chase Paymentech
Solutions.
Possible values:

Y: Yes

N: No

X: Not applicable / Unknown

See "Card Type Indicators (CTIs)," page 112.

ccAuthReply_
cavvResponseCode

ccAuthReply_
cavvResponseCode
Raw

Mapped response code for Verified by Visa and

American Express SafeKey:

See "Verified by Visa," page 171, and

Appendix P, "Verified by Visa
Response Codes," on page 388.

See "American Express SafeKey," page 183,

and Appendix D, "American Express SafeKey
Response Codes," on page 354.

Raw response code sent directly from the

processor for Verified by Visa and American
Express SafeKey:

See "Verified by Visa," page 171.

See "American Express SafeKey," page 183.

ccAuthReply_cvCode

CVN result code. See "Card Verification Numbers

(CVNs)," page 80, for a description of the card
verification check. See Appendix G, "CVN Codes,"
on page 360, for the list of CVN codes.

ccAuthReply

String (1)

ccAuthReply_
cvCodeRaw

CVN result code sent directly from the processor.

Returned only when the processor returns this
value.

ccAuthReply

String (10)

ccAuthReply

String (1)

Important Do not use this field to evaluate the

result of card verification. Use for debugging
purposes only.
ccAuthReply_evEmail

Mapped Electronic Verification response code for

the customers email address. See Appendix I,
"Electronic Verification Response Codes," on
page 365.

Credit Card Services Using the Simple Order API | January 2016

289

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
evEmailRaw

Raw Electronic Verification response code from

the processor for the customers email address.

ccAuthReply

String (1)

ccAuthReply_evName

Mapped Electronic Verification response code for

the customers name. See Appendix I, "Electronic
Verification Response Codes," on page 365.

ccAuthReply

String (1)

ccAuthReply_
evNameRaw

Raw Electronic Verification response code from

the processor for the customers last name.

ccAuthReply

String (1)

ccAuthReply_
evPhoneNumber

Mapped Electronic Verification response code for

the customers phone number. See Appendix I,
"Electronic Verification Response Codes," on
page 365.

ccAuthReply

String (1)

ccAuthReply_
evPhoneNumberRaw

Raw Electronic Verification response code from

the processor for the customers phone number.

ccAuthReply

String (1)

ccAuthReply_
evPostalCode

Mapped Electronic Verification response code for

the customers postal code. See Appendix I,
"Electronic Verification Response Codes," on
page 365.

ccAuthReply

String (1)

ccAuthReply_
evPostalCodeRaw

Raw Electronic Verification response code from

the processor for the customers postal code.

ccAuthReply

String (1)

ccAuthReply_evStreet

Mapped Electronic Verification response code for

the customers street address. See Appendix I,
"Electronic Verification Response Codes," on
page 365.

ccAuthReply

String (1)

ccAuthReply_
evStreetRaw

Raw Electronic Verification response code from

the processor for the customers street address.

ccAuthReply

String (1)

ccAuthReply_
forwardCode

Name of the Japanese acquirer that processed the

transaction. Returned only for CCS (CAFIS) and
JCN Gateway. Please contact the CyberSource
Japan Support Group for more information.

ccAuthReply

String (32)

Credit Card Services Using the Simple Order API | January 2016

290

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
merchantAdviceCode

Reason the recurring payment transaction was

declined. For some processors, this field is used
only for MasterCard. For other processors, this
field is used for Visa and MasterCard. And for
other processors, this field is not implemented.
Possible values:

ccAuthReply

String (2)

00: Response not provided.

01: New account information is available.

Obtain the new information.

02: Try again later.

03: Do not try again. Obtain another type of

payment from the customer.

21: Recurring payment cancellation service.

99: An unknown value was returned from the

processor.

ccAuthReply_
merchantAdviceCode
Raw

Raw merchant advice code sent directly from the

processor. This field is used only for MasterCard.

ccAuthReply

String (2)

ccAuthReply_
ownerMerchantID

Merchant ID that was used to create the

subscription or customer profile for which the
service was requested.

ccAuthReply

String (30)

Payment Tokenization
When your account is enabled for Payment
Tokenization, this field is returned only when you
use profile sharing and when your merchant ID is
in the same merchant ID pool as the owner
merchant ID. See the profile sharing information in
Payment Tokenization Using the Simple Order
API.
Recurring Billing
When your account is enabled for Recurring
Billing, this field is returned only when you use
subscription sharing and when your merchant ID is
in the same merchant ID pool as the owner
merchant ID. See the subscription sharing
information in Recurring Billing Using the Simple
Order API.

Credit Card Services Using the Simple Order API | January 2016

291

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
paymentNetwork
TransactionID

Network transaction identifier (TID). You can use

this value to identify a specific transaction when
you are discussing the transaction with your
processor. Not all processors provide this value.

ccAuthReply

String (15)

ccAuthReply

String (1)

Cielo
For Cielo, this value is the non-sequential unit
(NSU) and is supported for all transactions. The
value is generated by Cielo or the issuing bank.
CyberSource through VisaNet and GPN
For details about this value for CyberSource
through VisaNet and GPN, see Appendix L,
"Network Transaction Identifiers," on page 376.
ccAuthReply_
personalIDCode

Personal identifier result. This field is supported

only for Redecard in Brazil for CyberSource Latin
American Processing. If you included billTo_
personalID in the request, this value indicates
whether or not billTo_personalID matched a
value in a record on file. Returned only when the
personal ID result is returned by the processor.
Possible values:

Y: Match

N: No match

K: Not supported

U: Unknown

Z: No response returned

Note CyberSource Latin American Processing is

the CyberSource name for Braspag. CyberSource
provides two processors for Latin America:
CyberSource Latin American Processing
(Braspag), which is supported in multiple Latin
American countries, and Cielo, which is supported
in Brazil only. The information in this field
description applies only to CyberSource Latin
American Processing (Braspag).

Credit Card Services Using the Simple Order API | January 2016

292

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_posData

Point-of-sale details for the transaction. This value

is returned only for American Express Direct.

ccAuthReply

String (12)

ccAuthReply

JCN
Gateway:
String (3)

CyberSource generates this value, which consists

of a series of codes that identify terminal
capability, security data, and specific conditions
present at the time the transaction occurred. To
comply with the CAPN requirements, this value
must be included in all subsequent follow-on
requests, such as captures and follow-on credits.
When you perform authorizations, captures, and
credits through CyberSource, CyberSource
passes this value from the authorization service to
the subsequent services for you. However, when
you perform authorizations through CyberSource
and perform subsequent services through other
financial institutions, you must ensure that your
requests for captures and credits include this
value. See "Authorization Only," page 110.
ccAuthReply_
processorResponse

For most processors, this is the error message

sent directly from the bank. Returned only when
the processor returns this value.

Important Do not use this field to evaluate the

result of the authorization.
AIBMS
If this value is 08, you can accept the transaction if
the customer provides you with identification.

All other
processors:
String (10)

Atos
This value is the response code sent from Atos
and it might also include the response code from
the bank.
Format: aa,bb with the two values separated by a
comma and where:

aa is the two-digit error message from Atos.

bb is the optional two-digit error message from

the bank.

JCN Gateway
Processor-defined detail error code. The
associated response category code is in the
additionalProcessorResponse field.

Credit Card Services Using the Simple Order API | January 2016

293

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
processorTransactionID

Processor transaction ID.

ccAuthReply

Cielo and
CyberSource
Latin
American
Processing:
String (50)

Cielo and CyberSource Latin American

Processing
This value is a unique identifier for the transaction.
Moneris
This value identifies the transaction on a host
system. It contains the following information:

Terminal used to process the transaction

Shift during which the transaction took place

Batch number

Transaction number within the batch

Moneris:
Positive
Integer (18)

You must store this value. If you give the customer

a receipt, display this value on the receipt.
Example: For the value 66012345001069003:

Terminal ID = 66012345

Shift number = 001

Batch number = 069

Transaction number = 003

ccAuthReply_
reasonCode

Numeric value corresponding to the result of the

credit card authorization request. See Appendix O,
"Reason Codes," on page 384.

ccAuthReply

Integer (5)

ccAuthReply_
reconciliationID

Reference number for the transaction. This value

is not returned for all processors. See Table 7,
"Fields for Reconciliation IDs," on page 26 for the
list of processors for which this value is returned.
See Getting Started with CyberSource Advanced
for the Simple Order API for information about
order tracking and reconciliation.

ccAuthReply

Atos:
Integer (6)

ccAuthReply_
referralResponse
Number

Referral response number for a verbal

authorization with FDMS Nashville when using an
American Express card. Give this number to
American Express when you call them for the
verbal authorization.

ccAuthReply

String (6)

ccAuthReply_
requestAmount

Amount you requested to be authorized. This

value is returned for partial authorizations as
described in "Partial Authorizations," page 88.

ccAuthReply

String (15)

ccAuthReply_
requestCurrency

Currency for the amount you requested to be

authorized. This value is returned for partial
authorizations as described in "Partial
Authorizations," page 88. For the possible values,
see the ISO Standard Currency Codes.

ccAuthReply

String (5)

Credit Card Services Using the Simple Order API | January 2016

All other
processors:
String (60)

294

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReply_
transactionID

Transaction identification (TID) that is used to

identify and track a transaction throughout its life
cycle. This value is returned only for American
Express Direct.

ccAuthReply

String (15)

American Express generates this value. To comply

with the CAPN requirements, this value must be
included in all subsequent follow-on requests,
such as captures and follow-on credits.
When you perform authorizations, captures, and
credits through CyberSource, CyberSource
passes this value from the authorization service to
the subsequent services for you. However, when
you perform authorizations through CyberSource
and perform subsequent services through other
financial institutions, you must ensure that your
requests for captures and credits include this
value. See "Authorization Only," page 110.
ccAuthReversalReply_
amount

Amount that was reversed.

ccAuthReversal
Reply

String (15)

ccAuthReversalReply_
authorizationCode

Authorization code. Returned only when the

authorization code is returned by the processor.

ccAuthReversal
Reply

String (6)

ccAuthReversalReply_
forwardCode

Name of the Japanese acquirer that processed the

transaction. Returned only for CCS (CAFIS) and
JCN Gateway. Please contact the CyberSource
Japan Support Group for more information.

ccAuthReversal
Reply

String (32)

ccAuthReversalReply_
processorResponse

Processor response code.

ccAuthReversal
Reply

JCN
Gateway:
String (3)

JCN Gateway
Processor-defined detail error code. The
associated response category code is in the
additionalProcessorResponse field.

Credit Card Services Using the Simple Order API | January 2016

All other
processors:
String (10)

295

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccAuthReversalReply_
processorTransactionID

Processor transaction ID. This field is supported

only for Moneris.

ccAuthReversal
Reply

Positive
Integer (18)

This value identifies the transaction on a host

system. It contains the following information:

Terminal used to process the transaction

Shift during which the transaction took place

Batch number

Transaction number within the batch

You must store this value. If you give the customer

a receipt, display this value on the receipt.
Example: For the value 66012345001069003:

Terminal ID = 66012345

Shift number = 001

Batch number = 069

Transaction number = 003

ccAuthReversalReply_
reasonCode

Numeric value corresponding to the result of the

full authorization reversal request. See
Appendix O, "Reason Codes," on page 384.

ccAuthReversal
Reply

Integer (5)

ccAuthReversalReply_
reconciliationID

Reference number for the transaction. This value

is not returned for all processors. See Table 7,
"Fields for Reconciliation IDs," on page 26 for the
list of processors for which this value is returned.
See Getting Started with CyberSource Advanced
for the Simple Order API for information about
order tracking and reconciliation.

ccAuthReversal
Reply

String (60)

ccAuthReversalReply_
requestDateTime

Date and time at which the service was requested.

ccAuthReversal
Reply

String (20)

ccCaptureReply

String (15)

Format: YYYY-MM-DDThh:mm:ssZ
Example: 2016-08-11T22:47:57Z is equal to
August 11, 2016, at 10:47:57 P.M. The T separates
the date and the time. The Z indicates UTC.

ccCaptureReply_
amount

Amount that was captured.

Credit Card Services Using the Simple Order API | January 2016

296

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccCaptureReply_
processorTransactionID

Processor transaction ID. This value identifies the

transaction on a host system. This value is
supported only for Moneris. It contains this
information:

ccCaptureReply

Positive
Integer (18)

Terminal used to process the transaction

Shift during which the transaction took place

Batch number

Transaction number within the batch

You must store this value. If you give the customer

a receipt, display this value on the receipt.
Example: For the value 66012345001069003:

Terminal ID = 66012345

Shift number = 001

Batch number = 069

Transaction number = 003

ccCaptureReply_
reasonCode

Numeric value corresponding to the result of the

capture request. See Appendix O, "Reason
Codes," on page 384.

ccCaptureReply

Integer (5)

ccCaptureReply_
reconciliationID

Reference number that you use to reconcile your

CyberSource reports with your processor reports.
See Getting Started with CyberSource Advanced
for the Simple Order API for information about
order tracking and reconciliation.

ccCaptureReply

Atos:
Integer (6)
FDC
Nashville
Global:
String (8)
All other
processors:
String (60)

ccCaptureReply_
requestDateTime

Date and time at which the service was requested.

ccCaptureReply

String (20)

Format: YYYY-MM-DDThh:mm:ssZ
Example: 2016-08-11T22:47:57Z is equal to
August 11, 2016, at 10:47:57 P.M. The T separates
the date and the time. The Z indicates UTC.

ccCreditReply_amount

Amount that was credited.

ccCreditReply

String (15)

ccCreditReply_
forwardCode

Name of the Japanese acquirer that processed the

transaction. Returned only for CCS (CAFIS) and
JCN Gateway. Please contact the CyberSource
Japan Support Group for more information.

ccCreditReply

String (32)

Credit Card Services Using the Simple Order API | January 2016

297

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccCreditReply_
ownerMerchantID

Merchant ID that was used to create the

subscription or customer profile for which the
service was requested.

ccCreditReply

String (30)

ccCreditReply

Positive
Integer (18)

ccCreditReply

Integer (5)

Payment Tokenization
When your account is enabled for Payment
Tokenization, this field is returned only when you
use profile sharing and when your merchant ID is
in the same merchant ID pool as the owner
merchant ID. See the profile sharing information in
Payment Tokenization Using the Simple Order
API.
Recurring Billing
When your account is enabled for Recurring
Billing, this field is returned only when you use
subscription sharing and when your merchant ID is
in the same merchant ID pool as the owner
merchant ID. See the subscription sharing
information in Recurring Billing Using the Simple
Order API.
ccCreditReply_
processorTransactionID

Processor transaction ID. This value identifies the

transaction on a host system. This value is
supported only for Moneris. It contains this
information:

Terminal used to process the transaction

Shift during which the transaction took place

Batch number

Transaction number within the batch

You must store this value. If you give the customer

a receipt, display this value on the receipt.
Example: For the value 66012345001069003:

ccCreditReply_
reasonCode

Terminal ID = 66012345

Shift number = 001

Batch number = 069

Transaction number = 003

Numeric value corresponding to the result of the

credit request. See Appendix O, "Reason Codes,"
on page 384.

Credit Card Services Using the Simple Order API | January 2016

298

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

ccCreditReply_
reconciliationID

Reference number that you use to reconcile your

CyberSource reports with your processor reports.
See Getting Started with CyberSource Advanced
for the Simple Order API for information about
order tracking and reconciliation.

ccCreditReply

Atos:
Integer (6)
FDC
Nashville
Global:
String (8)
All other
processors:
String (60)

ccCreditReply_
requestDateTime

Date and time at which the service was requested.

ccCreditReply

String (20)

ccDCCReply

String (5)

Format: YYYY-MM-DDThh:mm:ssZ
Example: 2016-08-11T22:47:57Z is equal to
August 11, 2016, at 10:47:57 P.M. The T separates
the date and the time. The Z indicates UTC.

ccDCCReply_
dccSupported

DCC for First Data

Flag that indicates whether DCC can be used for
the transaction. Possible values:

TRUE: DCC can be used.

FALSE: DCC cannot be used.

ccDCCReply_
marginRate
Percentage

DCC for First Data

Exchange rate surcharge that is applied to the
wholesale exchange rate. Includes a decimal point
and 4 decimal places. For details, see "Dynamic
Currency Conversion for First Data," page 114.

ccDCCReply

String (7)

ccDCCReply_
reasonCode

DCC for First Data

Numeric value corresponding to the result of the
DCC request. See Appendix O, "Reason Codes,"
on page 384.

ccDCCReply

Integer (5)

decision

Summarizes the result of the overall request.

Possible values:

All credit card

services

String (6)

ACCEPT

ERROR

REJECT

REVIEW: Returned only when you use

CyberSource Decision Manager.

For details about these values, see the information

about handling replies in Getting Started with
CyberSource Advanced for the Simple Order API.

Credit Card Services Using the Simple Order API | January 2016

299

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

invalidField_0...N

Fields in the request that have invalid data. For

information about missing or invalid fields, see
Getting Started with CyberSource Advanced for
the Simple Order API.

All credit card

services

String (100)

All credit card

services

String (50)

All credit card

services

String (100)

ccAuthReversal
Reply

String (15)

Note These fields are included as an aid to

software developers only. Do not use these fields
to interact with your customers.
merchantReference
Code

Order reference or tracking number that you

provided in the request. If you included multi-byte
characters in this field in the request, the returned
value might include corrupted characters.
FDC Nashville Global
There are some special circumstances in which
the processor truncates this value to 15 or 17
characters for Level II and Level III processing.
This can cause a discrepancy between the value
you submit and the value included in some
processor reports.

missingField_0...N

Required fields that were missing from the

request. For information about missing or invalid
fields, see Getting Started with CyberSource
Advanced for the Simple Order API.

Note These fields are included as an aid to

software developers only. Do not use these fields
to interact with your customers.

originalTransaction_
amount

Amount of the original transaction. See "MerchantInitiated Reversals and Voids," page 168.

voidReply
originalTransaction_
reasonCode

purchaseTotals_
currency

Reason code for the original transaction. See

"Merchant-Initiated Reversals and Voids,"
page 168.

ccAuthReversal
Reply

Currency used for the order. For the possible

values, see the ISO Standard Currency Codes.

ccAuthReply

DCC for First Data

Your local currency. For details, see "Dynamic
Currency Conversion for First Data," page 114.

String (50)

voidReply
String (5)

ccAuthReversal
Reply
ccCaptureReply
ccCreditReply
ccDCCReply

Credit Card Services Using the Simple Order API | January 2016

300

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

purchaseTotals_
exchangeRate

DCC for First Data

Exchange rate. Includes a decimal point and a
maximum of 4 decimal places. For details, see
"Dynamic Currency Conversion for First Data,"
page 114.

ccDCCReply

String (13)

purchaseTotals_
exchangeRateTime
Stamp

DCC for First Data

Time stamp for the exchange rate. For details, see
"Dynamic Currency Conversion for First Data,"
page 114.

ccDCCReply

String (14)

Format: YYYYMMDD~HH:MM
where ~ denotes a space.
purchaseTotals_
foreignAmount

DCC for First Data

Converted amount. For details, see "Dynamic
Currency Conversion for First Data," page 114.

ccDCCReply

String (15)

purchaseTotals_
foreignCurrency

DCC for First Data

Billing currency. For the possible values, see the
ISO Standard Currency Codes. For details about
DCC, see "Dynamic Currency Conversion for First
Data," page 114.

ccDCCReply

String (5)

reasonCode

Numeric value corresponding to the result of the

overall request. See Appendix O, "Reason
Codes," on page 384.

All credit card

services

Integer (5)

receiptNumber

This field is returned only for American Express

Direct and CyberSource through VisaNet.

ccAuthReply

String (6)

American Express Direct

System trace audit number (STAN). This value
identifies the transaction and is useful when
investigating a chargeback dispute.
CyberSource through VisaNet
System trace number that must be printed on the
customers receipt.
requestID

Identifier for the request.

All credit card

services

String (26)

requestToken

Request token data created by CyberSource for

each reply. The field is an encoded string that
contains no confidential information such as an
account or card verification number. The string can
contain a maximum of 256 characters.

All credit card

services

String (256)

When you request the authorization and capture

services together, the request token is for the
capture reply only.

Note If Atos is your processor, you must store the

contents of this field so that you can retrieve and
send it in follow-on requests.

Credit Card Services Using the Simple Order API | January 2016

301

Appendix A

Table 59

API Fields

Reply Fields (Continued)

Field

Description

Returned By

Data Type
& Length

voidReply_amount

Amount that was voided.

voidReply

String (15)

voidReply_currency

Currency used for the order. For the possible

values, see the ISO Standard Currency Codes.

voidReply

String (5)

voidReply_reasonCode

Numeric value corresponding to the result of the

void request. See Appendix O, "Reason Codes,"
on page 384.

voidReply

Integer (5)

voidReply_
requestDateTime

Date and time at which the service was requested.

voidReply

String (20)

Format: YYYY-MM-DDThh:mm:ssZ
Example: 2016-08-11T22:47:57Z is equal to
August 11, 2016, at 10:47:57 P.M. The T separates
the date and the time. The Z indicates UTC.

Credit Card Services Using the Simple Order API | January 2016

302

APPENDIX

Examples

Name-Value Pair Examples

Basic Credit Card Examples
Example 3

Credit Card Authorization Request

ccAuthService_run=true
merchantID=infodev
merchantReferenceCode=482046C3A7E94F5
billTo_firstName=John
billTo_lastName=Doe
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_postalCode=94043
billTo_country=US
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD
card_expirationMonth=12
card_expirationYear=2015
card_accountNumber=4111111111111111
card_cardType=001

Credit Card Services Using the Simple Order API | January 2016

303

Appendix B

Example 4

Examples

Credit Card Authorization Reply

requestID=0305782650000167905080
decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5
purchaseTotals_currency=USD
ccAuthReply_reasonCode=100
ccAuthReply_amount=49.95
ccAuthReply_accountBalance=50.05
ccAuthReply_authorizationCode=123456
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_processorResponse=A

Example 5

Credit Card Capture Request

ccCaptureService_authRequestID=0305782650000167905080
merchantID=infodev
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
ccCaptureService_run=true
item_0_unitPrice=49.95
purchaseTotals_currency=USD

Example 6

Credit Card Capture Reply

requestID=1019827520348290570293
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
decision=ACCEPT
reasonCode=100
ccCaptureReply_amount=49.95
purchaseTotals_currency=USD
ccCaptureReply_reasonCode=100
ccCaptureReply_reconciliationID=1094820975023470

Credit Card Services Using the Simple Order API | January 2016

304

Appendix B

Examples

Apple Pay Examples

Do not include the e-commerce indicator in your authorization request.
Important

Example 7

Credit Card Authorization Request

merchantID=Foster_City_Flowers
merchantReferenceCode=123456
billTo_city=Foster City
billTo_country=US
billTo_email=flowers@example.com
billTo_firstName=Jane
billTo_lastName=Smith
billTo_postalCode=94404
billTo_state=CA
billTo_street1=100 Main Street
purchaseTotals_grandTotalAmount=99.99
encryptedPayment_descriptor=RklEPUNPTU1PTi5BUFBMRS5JTkFQUC5QQVlNRU5U
encryptedPayment_data=encrypted payment data
encryptedPayment_encoding=Base64
paymentSolution=001
ccAuthService_run=true

Example 8

Credit Card Authorization Reply

merchantReferenceCode=123456
requestID=0305782650000167905080
decision=ACCEPT
reasonCode=100
purchaseTotals_currency=USD
ccAuthReply_reasonCode=100
ccAuthReply_amount=5.00
ccAuthReply_authorizationCode=888888
ccAuthReply_avsCode=X
ccAuthReply_avsCodeRaw=I1
ccAuthReply_processorResponse=100

Credit Card Services Using the Simple Order API | January 2016

305

Appendix B

Examples

Asia, Middle East, and Africa Gateway

Examples
Example 9

Credit Card Authorization Request with Payer Authentication Data

shipTo_firstName=Jane
shipTo_lastName=Smith
shipTo_street1=1234 ABCD Street
shipTo_city=Mountain View
shipTo_state=CA
shipTo_country=US
shipTo_postalCode=94043
billTo_firstName=John
billTo_lastName=Doe
billTo_street1=1295 Charleston Road
billTo_city=Mountain View
billTo_state=CA
billTo_country=US
billTo_postalCode=94043
billTo_ipAddress=10.7.7.7
billTo_email=jdoe@example.com
billTo_phoneNumber=650-965-6000
merchantReferenceCode=0123456789
purchaseTotals_currency=USD
card_accountNumber=4111111111111111
card_expirationMonth=12
card_expirationYear=2020
card_cardType=001
ccAuthService_commerceIndicator=vbv
ccAuthService_xid=WhPlErd9WE2pb12345HlewUIQwQ
ccAuthService_veresEnrolled=Y
ccAuthService_paresStatus=Y
ccAuthService_cavv=PpmBUYXt2uyt12345mAb8XgnOk
ccAuthService_run=true
item_0_unitPrice=12.34
item_1_unitPrice=56.78

Example 10

Credit Card Authorization Reply

ccAuthReply_avsCode=2
ccAuthReply_amount=69.12
ccAuthReply_reasonCode=100
ccAuthReply_reconciliationID=19119123440
ccAuthReply_processorResponse=0
ccAuthReply_authorizationCode=ABC12345
requestID=1921371701234567904567
reasonCode=100
decision=ACCEPT
merchantReferenceCode=0123456789
purchaseTotals_currency=USD

Credit Card Services Using the Simple Order API | January 2016

306

Appendix B

Examples

Cielo Examples
Example 11

Auto Capture Request with Elo

merchantID=merchant_cielo_1
merchantReferenceCode=Transaction-Cielo-NTA-3
billTo_firstName=Jlia
billTo_lastName=Fernndez
billTo_buildingNumber=1024
billTo_street1=R. August
billTo_street2=Bloco 01
billTo_city=So Paulo
billTo_district=Bela Vista
billTo_state=SP
billTo_postalCode=01310-000
billTo_country=BR
billTo_phoneNumber=999-999-9999
billTo_email=jfernandez@example.com
purchaseTotals_currency=usd
purchaseTotals_grandTotalAmount=104.00
card_accountNumber=1234567812345678
card_expirationMonth=03
card_expirationYear=2031
card_cardType=054
ccAuthService_run=true
ccAuthService_authType=AUTOCAPTURE
ccCaptureService_run=true

Example 12

Auto Capture Reply with Elo

merchantReferenceCode=Transaction-Cielo-NTA-3
requestID=4231489930765000001540
decision=ACCEPT
reasonCode=100
purchaseTotals_currency=usd
ccAuthReply_reasonCode=100
ccAuthReply_amount=104.00
ccAuthReply_authorizationCode=123456
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=CC
ccAuthReply_processorResponse=00
ccAuthReply_reconciliationID=Auth12345678
ccAuthReply_paymentNetworkTransactionID=333138
ccAuthReply_processorTransactionID=00142308609746028231
ccCaptureReply_reasonCode=100
ccCaptureReply_amount=104.00
ccCaptureReply_reconciliationID=Auth12345678

Credit Card Services Using the Simple Order API | January 2016

307

Appendix B

Example 13

Examples

Debit Card Request with Maestro (International)

merchantID=merchant_cielo_1
merchantReferenceCode=Transaction-Cielo-NTA-4
billTo_firstName=Jlia
billTo_lastName=Fernndez
billTo_buildingNumber=1024
billTo_street1=R. August
billTo_street2=Bloco 01
billTo_city=So Paulo
billTo_district=Bela Vista
billTo_state=SP
billTo_postalCode=01310-000
billTo_country=BR
billTo_phoneNumber=999-999-9999
billTo_email=jfernandez@example.com
purchaseTotals_currency=brl
purchaseTotals_grandTotalAmount=106.00
card_accountNumber=123456781234567812
card_expirationMonth=03
card_expirationYear=2031
card_cvIndicator=1
card_cvNumber=123
card_cardType=042
ucaf_authenticationData=WhPlErd9WE2pb1yFjFHlewUIQwQ=
ucaf_collectionIndicator=2
ccAuthService_run=true
ccAuthService_commerceIndicator=spa
ccAuthService_xid=lEmYpm61EduaVZjPG1/HsgkAAQc=
ccAuthService_overridePaymentMethod=DB
ccCaptureService_run=true

Example 14

Debit Card Reply with Maestro (International)

merchantReferenceCode=Transaction-Cielo-NTA-4
requestID=4231489990775000001540
decision=ACCEPT
reasonCode=100
purchaseTotals_currency=brl
ccAuthReply_reasonCode=100
ccAuthReply_amount=106.00
ccAuthReply_authorizationCode=123456
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=CC
ccAuthReply_processorResponse=00
ccAuthReply_reconciliationID=Auth12345678
ccAuthReply_paymentNetworkTransactionID=333138
ccAuthReply_processorTransactionID=00142308609746028231
ccCaptureReply_reasonCode=100
ccCaptureReply_amount=106.00
ccCaptureReply_reconciliationID=Auth12345678

Credit Card Services Using the Simple Order API | January 2016

308

Appendix B

Example 15

Examples

Installment Request with Visa

merchantID=merchant_cielo_1
merchantReferenceCode=Transaction-Cielo-NTA-1
billTo_firstName=Jlia
billTo_lastName=Fernndez
billTo_buildingNumber=1024
billTo_street1=R. August
billTo_street2=Bloco 01
billTo_city=So Paulo
billTo_district=Bela Vista
billTo_state=SP
billTo_postalCode=01310-000
billTo_country=BR
billTo_phoneNumber=999-999-9999
billTo_email=jfernandez@example.com
item_0_unitPrice=51025.00
item_0_quantity=1
purchaseTotals_currency=brl
installment_totalCount=4
installment_planType=1
card_accountNumber=4111111111111111
card_expirationMonth=12
card_expirationYear=2018
card_cardType=001
ccAuthService_run=true

Example 16

Installment Reply with Visa

merchantReferenceCode=Transaction-Cielo-NTA-1
requestID=4231493140785000001540
decision=ACCEPT
reasonCode=100
purchaseTotals_currency=brl
ccAuthReply_reasonCode=100
ccAuthReply_amount=51025.00
ccAuthReply_authorizationCode=123456
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=CC
ccAuthReply_processorResponse=00
ccAuthReply_reconciliationID=Auth12345678
ccAuthReply_paymentNetworkTransactionID=333138
ccAuthReply_processorTransactionID=00142308609746028231

Credit Card Services Using the Simple Order API | January 2016

309

Appendix B

Examples

CyberSource Latin American Processing

Examples
Note

CyberSource Latin American Processing is the CyberSource name for

Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil only.
These examples apply only to CyberSource Latin American Processing
(Braspag).

Example 17

Credit Card Authorization Request for Redecard in Brazil with AVS

ccAuthService_run=true
merchantID=okgo
merchantReferenceCode=1234567890
billTo_firstName=Adriana
billTo_lastName=Tavares da Silva
billTo_street1=Rua da Quitanda 187
billTo_buildingNumber=187
billTo_city=Rio de Janeiro
billTo_postalCode=20091-005
billTo_country=BR
billTo_phoneNumber=+552121114700
billTo_email=asilva@example.com
billTo_personalID=987654321
item_0_quantity=1
item_0_unitPrice=49.95
purchaseTotals_currency=BRL
card_cardType=052
card_accountNumber=5432543254325432
card_expirationMonth=12
card_expirationYear=2015

Example 18

Credit Card Authorization Reply

decision=ACCEPT
reasonCode=100
requestID=12345678901234567890
merchantReferenceCode=1234567
purchaseTotals_currency=BRL
ccAuthReply_reasonCode=100
ccAuthReply_personalIDCode=Y
ccAuthReply_amount=49.95
ccAuthReply_authorizationCode=123456
ccAuthReply_reconciliationID=1911912456
ccAuthReply_avsCode=V

Credit Card Services Using the Simple Order API | January 2016

310

Appendix B

Examples

Partial Authorization Examples

Fully Approved Request
The following two examples consist of an authorization request that is fully approved and
the subsequent authorization reply, which includes balance information:

Original request amount: 1500.00 USD

Approved amount: 1500.00 USD

Balance amount: 23.62 USD positive

Example 19

Fully Approved Authorization Request

ccAuthService_run=true
merchantID=OkGo
merchantReferenceCode=AB1234.1-1
billTo_firstName=John
billTo_lastName=Smith
billTo_street1=201 S. Division St.
billTo_street2=Suite 500
billTo_city=Ann Arbor
billTo_state=MI
billTo_country=US
billTo_postalCode=48104-2201
billTo_email=okgo@example.com
billTo_phoneNumber=123-456-7890
card_accountNumber=4111111111111111
card_cardType=001
card_cvNumber=xxx
card_expirationMonth=12
card_expirationYear=2015
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=1500.00

Credit Card Services Using the Simple Order API | January 2016

311

Appendix B

Example 20

Examples

Fully Approved Authorization Reply

merchantReferenceCode=AB1234.1-1
requestID=2688497722340000852964
decision=ACCEPT
reasonCode=100
ccAuthReply_reasonCode=100
ccAuthReply_amount=1500.00
ccAuthReply_avsCode=A
ccAuthReply_avsCodeRaw=A
ccAuthReply_authorizationCode=831000
ccAuthReply_processorResponse=000
ccAuthReply_accountBalance=23.62
ccAuthReply_accountBalanceCurrency=USD
ccAuthReply_accountBalanceSign=positive
ccAuthReply_cardCategory=J1
ccAuthReply_cvCode=3
ccAuthReply_merchantAdviceCode=00
purchaseTotals_currency=USD

Partially Approved Request

The following two examples consist of an authorization request that is partially approved
and the subsequent authorization reply:

Original request amount: 1401.00 USD

Approved amount: 500.00 USD

Example 21

Partially Approved Authorization Request

ccAuthService_run=true
merchantID=OkGo
merchantReferenceCode=AB1234.1-1
billTo_firstName=John
billTo_lastName=Smith
billTo_street1=201 S. Division St.
billTo_street2=Suite 500
billTo_city=Ann Arbor
billTo_state=MI
billTo_country=US
billTo_postalCode=48104-2201
billTo_email=okgo@example.com
billTo_phoneNumber=123-456-7890
card_accountNumber=4111111111111111
card_cardType=001
card_cvNumber=xxx
card_expirationMonth=12
card_expirationYear=2015
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=1401.00

Credit Card Services Using the Simple Order API | January 2016

312

Appendix B

Example 22

Examples

Partially Approved Authorization Reply

merchantReferenceCode=AB1234.1-1
requestID=2688497722340000852964
decision=REJECT
reasonCode=110
ccAuthReply_reasonCode=110
ccAuthReply_amount=500.00
ccAuthReply_avsCode=A
ccAuthReply_avsCodeRaw=A
ccAuthReply_authorizationCode=831000
ccAuthReply_processorResponse=010
ccAuthReply_requestAmount=1401.00
ccAuthReply_requestCurrency=USD
ccAuthReply_cardCategory=J1
ccAuthReply_cvCode=3
ccAuthReply_merchantAdviceCode=00
purchaseTotals_currency=USD

Split Shipment Examples

One Authorization and One Sale
Example 23

Credit Card Authorization Request

ccAuthService_run=true
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
billTo_firstName=John
billTo_lastName=Doe
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_country=US
billTo_postalCode=94043
card_expirationMonth=12
card_expirationYear=2015
card_accountNumber=4111111111111111
card_cardType=001
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD

Credit Card Services Using the Simple Order API | January 2016

313

Appendix B

Example 24

Examples

Credit Card Authorization Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=0305782650000167905080
ccAuthReply_reasonCode=100
ccAuthReply_amount=49.95
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_authorizationCode=123456
ccAuthReply_processorResponse=A
purchaseTotals_currency=USD

Example 25

Sale Request

ccAuthService_run=true
ccCaptureService_run=true
linkToRequest=0305782650000167905080
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
billTo_firstName=John
billTo_lastName=Doe
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_country=US
billTo_postalCode=94043
card_expirationMonth=12
card_expirationYear=2015
card_accountNumber=4111111111111111
card_cardType=001
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD

Credit Card Services Using the Simple Order API | January 2016

314

Appendix B

Example 26

Examples

Sale Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=1416783769994859
ccAuthReply_reasonCode=100
ccAuthReply_amount=49.95
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_authorizationCode=123456
ccAuthReply_processorResponse=A
purchaseTotals_currency=USD
ccCaptureReply_reasonCode=100
ccCaptureReply_amount=49.95
ccCaptureReply_reconciliationID=02850840187309570

One Authorization and Two Captures

Example 27

Credit Card Authorization Request

ccAuthService_run=true
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
billTo_firstName=John
billTo_lastName=Doe
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_country=US
billTo_postalCode=94043
card_expirationMonth=12
card_expirationYear=2015
card_accountNumber=4111111111111111
card_cardType=001
item_0_unitPrice=52.00
item_0_quantity=1
item_1_unitPrice=16.00
item_1_quantity=1
purchaseTotals_currency=USD

Credit Card Services Using the Simple Order API | January 2016

315

Appendix B

Example 28

Examples

Credit Card Authorization Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=0305782650000167905080
ccAuthReply_reasonCode=100
ccAuthReply_amount=68.00
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_authorizationCode=123456
ccAuthReply_processorResponse=A
purchaseTotals_currency=USD

Example 29

First Credit Card Capture Request

ccCaptureService_run=true
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
ccCaptureService_authRequestID=0305782650000167905080
item_0_unitPrice=52.00
item_0_quantity=1
purchaseTotals_currency=USD

Example 30

First Credit Card Capture Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=1019827520348290570293
ccCaptureReply_reasonCode=100
ccCaptureReply_amount=52.00
ccCaptureReply_reconciliationID=02850840187309570
purchaseTotals_currency=USD

Example 31

Second Credit Card Capture Request

ccCaptureService_run=true
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
ccCaptureService_authRequestID=0305782650000167905080
item_0_unitPrice=16.00
item_0_quantity=1
purchaseTotals_currency=USD

Credit Card Services Using the Simple Order API | January 2016

316

Appendix B

Example 32

Examples

Second Credit Card Capture Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=49601835arbl569cj
ccCaptureReply_reasonCode=100
ccCaptureReply_amount=16.00
ccCaptureReply_reconciliationID=sl59vu2nh4ek9lq
purchaseTotals_currency=USD

Two Authorizations and One Capture

Example 33

First Credit Card Authorization Request

ccAuthService_run=true
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
billTo_firstName=John
billTo_lastName=Doe
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_country=US
billTo_postalCode=94043
card_expirationMonth=12
card_expirationYear=2015
card_accountNumber=4111111111111111
card_cardType=001
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD

Example 34

First Credit Card Authorization Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=0305782650000167905080
ccAuthReply_reasonCode=100
ccAuthReply_amount=49.95
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_authorizationCode=123456
ccAuthReply_processorResponse=A
purchaseTotals_currency=USD

Credit Card Services Using the Simple Order API | January 2016

317

Appendix B

Example 35

Examples

Second Credit Card Authorization Request

ccAuthService_run=true
linkToRequest=0305782650000167905080
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
billTo_firstName=John
billTo_lastName=Doe
billTo_phoneNumber=650-965-6000
billTo_email=jdoe@example.com
billTo_street1=1295 Charleston Rd.
billTo_city=Mountain View
billTo_state=CA
billTo_country=US
billTo_postalCode=94043
card_expirationMonth=12
card_expirationYear=2015
card_accountNumber=4111111111111111
card_cardType=001
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD

Example 36

Second Credit Card Authorization Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=1416783769994859
ccAuthReply_reasonCode=100
ccAuthReply_amount=49.95
ccAuthReply_avsCode=Y
ccAuthReply_avsCodeRaw=YYY
ccAuthReply_authorizationCode=123456
ccAuthReply_processorResponse=A
purchaseTotals_currency=USD

Example 37

Credit Card Capture Request

ccCaptureService_run=true
merchantID=my_store
merchantReferenceCode=482046C3A7E94F5BD1
ccCaptureService_authRequestID=1416783769994859
item_0_unitPrice=49.95
item_0_quantity=1
purchaseTotals_currency=USD

Credit Card Services Using the Simple Order API | January 2016

318

Appendix B

Example 38

Examples

Credit Card Capture Reply

decision=ACCEPT
reasonCode=100
merchantReferenceCode=482046C3A7E94F5BD1
requestID=1019827520348290570293
ccCaptureReply_reasonCode=100
ccCaptureReply_amount=49.95
ccCaptureReply_reconciliationID=02850840187309570
purchaseTotals_currency=USD

Visa Checkout Examples

Example 39

Credit Card Authorization Request

ccAuthService_run=true
merchantID=Foster_City_Flowers
merchantReferenceCode=123456
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=25.00
paymentSolution=visacheckout
encryptedPayment_data=binary large object (blob) of encrypted data
encryptedPayment_wrappedKey=RNNRasaeG9QrPl+uJ1DQm0j03ne+Iw4clHLyzwE
vc_orderID=335161017227386762

Example 40

Credit Card Authorization Reply

ccAuthReply_amount=25.00
ccAuthReply_avsCode=Y
ccAuthReply_authorizationCode=831000
ccAuthReply_processorResponse=00
ccAuthReply_avsCodeRaw=Y
ccAuthReply_reasonCode=100
purchaseTotals_currency=USD
decision=ACCEPT
reasonCode=100
merchantReferenceCode=123456
requestID=4068437426340172492292

Credit Card Services Using the Simple Order API | January 2016

319

Appendix B

Examples

XML Examples
Basic Credit Card Examples
Example 41

Credit Card Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23">
<merchantID>infodev</merchantID>
<merchantReferenceCode>482046C3A7E94F5</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295 Charleston Rd.</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>650-965-6000</phoneNumber>
<email>jdoe@example.com</email>
</billTo>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cardType>001</cardType>
</card>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

320

Appendix B

Example 42

Examples

Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23">
<c:merchantReferenceCode>482046C3A7E94F5</c:merchantReferenceCode>
<c:requestID>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>YYY</c:avsCodeRaw>
<c:processorResponse>A</c:processorResponse>
<c:accountBalance>50.05</c:accountBalance>
</c:ccAuthReply>
</c:replyMessage>

Example 43

Credit Card Capture Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.37">
<merchantID>infodev</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<ccCaptureService run="true">
<authRequestID>0305782650000167905080</authRequestID>
</ccCaptureService>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

321

Appendix B

Example 44

Examples

Credit Card Capture Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.37">
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>1019827520348290570293</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:reconciliationID>1094820975023470</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

322

Appendix B

Examples

Apple Pay Examples

Do not include the e-commerce indicator in your authorization request.
Important

Example 45

Credit Card Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.104">
<merchantID>Foster_City_Flowers</merchantID>
<merchantReferenceCode>123456</merchantReferenceCode>
<billTo>
<firstName>Jane</firstName>
<lastName>Smith</lastName>
<street1>100 Main Street</street1>
<city>Foster City</city>
<state>CA</state>
<postalCode>94404</postalCode>
<country>US</country>
<email>flowers@example.com</email>
</billTo>
<purchaseTotals>
<grandTotalAmount>99.99</grandTotalAmount>
</purchaseTotals>
<encryptedPayment>
<descriptor>RklEPUNPTU1PTi5BUFBMRS5JTkFQUC5QQVlNRU5U</descriptor>
<data>encrypted payment data</data>
<encoding>Base64</encoding>
</encryptedPayment>
<paymentSolution>001</paymentSolution>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

323

Appendix B

Example 46

Examples

Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.104">
<c:merchantReferenceCode>123456</c:merchantReferenceCode>
<c:requestID>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals><c:currency>USD</c:currency></c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>5.00</c:amount>
<c:authorizationCode>888888</c:authorizationCode>
<c:avsCode>X</c:avsCode>
<c:avsCodeRaw>I1</c:avsCodeRaw>
<c:processorResponse>100</c:processorResponse>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

324

Appendix B

Examples

Asia, Middle East, and Africa Gateway

Examples
Example 47

Credit Card Authorization Request with Payer Authentication Data

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.32">
<merchantID>okgo</merchantID>
<merchantReferenceCode>0123456789</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295 Charleston Road</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>650-965-6000</phoneNumber>
<email>jdoe@example.com</email>
<ipAddress>10.7.7.7</ipAddress>
</billTo>
<shipTo>
<firstName>Jane</firstName>
<lastName>Smith</lastName>
<street1>1234 ABCD Street</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
</shipTo>
<item id="0">
<unitPrice>12.34</unitPrice>
</item>
<item id="1">
<unitPrice>56.78</unitPrice>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2020</expirationYear>
<cvNumber>1234</cvNumber>
<cardType>001</cardType>
</card>
<ccAuthService run="true">
<cavv>PpmBUYXt2uytV6p12345KuImAb8XgnOk</cavv>
<commerceIndicator>vbv</commerceIndicator>
<xid>WhPlErd9WE1234562pb1yFjFHlewUIQwQ</xid>
<veresEnrolled>Y</veresEnrolled>
<paresStatus>Y</paresStatus>
</ccAuthService>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

325

Appendix B

Example 48

Examples

Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.32">
<c:merchantReferenceCode>0123456789</c:merchantReferenceCode>
<c:requestID>1921312345620167904567</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>69.12</c:amount>
<c:authorizationCode>ABC12345</c:authorizationCode>
<c:avsCode>2</c:avsCode>
<c:cvCode>2</c:cvCode>
<c:cvCodeRaw>Q</c:cvCodeRaw>
<c:processorResponse>0</c:processorResponse>
<c:reconciliationID>19119123438</c:reconciliationID>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

326

Appendix B

Examples

Cielo Examples
Example 49

Auto Capture Request with Elo

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.111">
<merchantID>merchant_cielo_1</merchantID>
<merchantReferenceCode>Transaction-Cielo-NTA-3</merchantReferenceCode>
<billTo>
<firstName>Jlia</firstName>
<lastName>Fernndez</lastName>
<buildingNumber>1024</buildingNumber>
<street1>R. August</street1>
<street2>Bloco 01</street2>
<city>So Paulo</city>
<district>Bela Vista</district>
<state>SP</state>
<postalCode>01310-000</postalCode>
<country>BR</country>
<phoneNumber>999-999-9999</phoneNumber>
<email>jfernandez@example.com</email>
</billTo>
<purchaseTotals>
<currency>usd</currency>
<grandTotalAmount>104.00</grandTotalAmount>
</purchaseTotals>
<card>
<accountNumber>1234567812345678</accountNumber>
<expirationMonth>03</expirationMonth>
<expirationYear>2031</expirationYear>
<cardType>054</cardType>
</card>
<ccAuthService run="true">
<authType>AUTOCAPTURE</authType>
</ccAuthService>
<ccCaptureService run="true"></ccCaptureService>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

327

Appendix B

Example 50

Examples

Auto Capture Reply with Elo

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.111">
<c:merchantReferenceCode>Transaction-Cielo-NTA-3</c:merchantReferenceCode>
<c:requestID>4231489930765000001540</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>usd</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>104.00</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>CC</c:avsCodeRaw>
<c:processorResponse>00</c:processorResponse>
<c:reconciliationID>Auth12345678</c:reconciliationID>
<c:paymentNetworkTransactionID>333138</c:paymentNetworkTransactionID>
<c:processorTransactionID>00142308609746028231</c:processorTransactionID>
</c:ccAuthReply>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>104.00</c:amount>
<c:reconciliationID>Auth12345678</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

328

Appendix B

Example 51

Examples

Debit Card Request with Maestro (International)

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.111">
<merchantID>merchant_cielo_1</merchantID>
<merchantReferenceCode>Transaction-Cielo-NTA-4</merchantReferenceCode>
<billTo>
<firstName>Jlia</firstName>
<lastName>Fernndez</lastName>
<buildingNumber>1024</buildingNumber>
<street1>R. August</street1>
<street2>Bloco 01</street2>
<city>So Paulo</city>
<district>Bela Vista</district>
<state>SP</state>
<postalCode>01310-000</postalCode>
<country>BR</country>
<phoneNumber>999-999-9999</phoneNumber>
<email>jfernandez@example.com</email>
</billTo>
<purchaseTotals>
<currency>brl</currency>
<grandTotalAmount>106.00</grandTotalAmount>
</purchaseTotals>
<card>
<accountNumber>123456781234567812</accountNumber>
<expirationMonth>03</expirationMonth>
<expirationYear>2031</expirationYear>
<cvIndicator>1</cvIndicator>
<cvNumber>123</cvNumber>
<cardType>042</cardType>
</card>
<ucaf>
<authenticationData>WhPlErd9WE2pb1yFjFHlewUIQwQ=</authenticationData>
<collectionIndicator>2</collectionIndicator>
</ucaf>
<ccAuthService run="true">
<commerceIndicator>spa</commerceIndicator>
<xid>lEmYpm61EduaVZjPG1/HsgkAAQc=</xid>
<overridePaymentMethod>DB</overridePaymentMethod>
</ccAuthService>
<ccCaptureService run="true"></ccCaptureService>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

329

Appendix B

Example 52

Examples

Debit Card Reply with Maestro (International)

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.111">
<c:merchantReferenceCode>Transaction-Cielo-NTA-4</c:merchantReferenceCode>
<c:requestID>4231489990775000001540</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>brl</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>106.00</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>CC</c:avsCodeRaw>
<c:processorResponse>00</c:processorResponse>
<c:reconciliationID>Auth12345678</c:reconciliationID>
<c:paymentNetworkTransactionID>333138</c:paymentNetworkTransactionID>
<c:processorTransactionID>00142308609746028231</c:processorTransactionID>
</c:ccAuthReply>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>106.00</c:amount>
<c:reconciliationID>Auth12345678</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

330

Appendix B

Example 53

Examples

Installment Request with Visa

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.111">
<merchantID>merchant_cielo_1</merchantID>
<merchantReferenceCode>Transaction-Cielo-NTA-1</merchantReferenceCode>
<billTo>
<firstName>Jlia</firstName>
<lastName>Fernndez</lastName>
<buildingNumber>1024</buildingNumber>
<street1>R. August</street1>
<street2>Bloco 01</street2>
<city>So Paulo</city>
<district>Bela Vista</district>
<state>SP</state>
<postalCode>01310-000</postalCode>
<country>BR</country>
<phoneNumber>999-999-9999</phoneNumber>
<email>jfernandez@example.com</email>
</billTo>
<item id="0">
<unitPrice>51025.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>brl</currency>
</purchaseTotals>
<installment>
<totalCount>4</totalCount>
<planType>1</planType>
</installment>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2018</expirationYear>
<cardType>001</cardType>
</card>
<ccAuthService run="true"></ccAuthService>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

331

Appendix B

Example 54

Examples

Installment Reply with Visa

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.111">
<c:merchantReferenceCode>Transaction-Cielo-NTA-1</c:merchantReferenceCode>
<c:requestID>4231493140785000001540</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>brl</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>51025.00</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>CC</c:avsCodeRaw>
<c:processorResponse>00</c:processorResponse>
<c:reconciliationID>Auth12345678</c:reconciliationID>
<c:paymentNetworkTransactionID>333138</c:paymentNetworkTransactionID>
<c:processorTransactionID>00142308609746028231</c:processorTransactionID>
</c:ccAuthReply>
</c:replyMessage>

CyberSource Latin American Processing

Examples
Note

CyberSource Latin American Processing is the CyberSource name for

Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil only.
These examples apply only to CyberSource Latin American Processing
(Braspag).

Credit Card Services Using the Simple Order API | January 2016

332

Appendix B

Example 55

Examples

Credit Card Authorization Request for Redecard in Brazil with AVS

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.41">
<merchantID>okgo</merchantID>
<merchantReferenceCode>1234567890</merchantReferenceCode>
<billTo>
<firstName>Adriana</firstName>
<lastName>Tavares da Silva</lastName>
<street1>Rua da Quitanda 187</street1>
<city>Rio de Janeiro</city>
<postalCode>20091-005</postalCode>
<country>BR</country>
<phoneNumber>+552121114700</phoneNumber>
<email>asilva@example.com</email>
<personalID>987654321</personalID>
<buildingNumber>187</buildingNumber>
</billTo>
<item id="0"><unitPrice>49.95</unitPrice></item>
<purchaseTotals><currency>BRL</currency></purchaseTotals>
<card>
<accountNumber>5432543254325432</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cardType>052</cardType>
</card>
<ccAuthService run="true"/>
</requestMessage>

Example 56

Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.41">
<c:merchantReferenceCode>1234567</c:merchantReferenceCode>
<c:requestID>12345678901234567890</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals><c:currency>BRL</c:currency></c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>V</c:avsCode>
<c:personalIDCode>Y</c:personalIDCode>
<c:reconciliationID>19119123456</c:reconciliationID>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

333

Appendix B

Examples

Partial Authorization Examples

Fully Approved Request
The following two examples consist of an authorization request that is fully approved and
the subsequent authorization reply, which includes balance information:

Example 57

Original request amount: 1500.00 USD

Approved amount: 1500.00 USD

Balance amount: 23.62 USD positive

Fully Approved Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.52">
<merchantID>OkGo</merchantID>
<merchantReferenceCode>AB1234.1-1</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Smith</lastName>
<street1>201 S. Division St.</street1>
<street2>Suite 500</street2>
<city>Ann Arbor</city>
<state>MI</state>
<postalCode>48104-2201</postalCode>
<country>US</country>
<phoneNumber>123-456-7890</phoneNumber>
<email>okgo@example.com</email>
</billTo>
<purchaseTotals>
<currency>USD</currency>
<grandTotalAmount>1500.00</grandTotalAmount>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cvNumber>xxx</cvNumber>
<cardType>001</cardType>
</card>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

334

Appendix B

Example 58

Examples

Fully Approved Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.52">
<c:merchantReferenceCode>AB1234.1-1</c:merchantReferenceCode>
<c:requestID>2688497722340000852964</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals><c:currency>USD</c:currency></c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>1500.00</c:amount>
<c:authorizationCode>831000</c:authorizationCode>
<c:avsCode>A</c:avsCode>
<c:avsCodeRaw>A</c:avsCodeRaw>
<c:cvCode>3</c:cvCode>
<c:processorResponse>000</c:processorResponse>
<c:merchantAdviceCode>00</c:merchantAdviceCode>
<c:accountBalance>23.62</c:accountBalance>
<c:cardCategory>J1</c:cardCategory>
<c:accountBalanceCurrency>USD</c:accountBalanceCurrency>
<c:accountBalanceSign>positive</c:accountBalanceSign>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

335

Appendix B

Examples

Partially Approved Request

The following two examples consist of an authorization request that is partially approved
and the subsequent authorization reply:

Example 59

Original request amount: 1401.00 USD

Approved amount: 500.00 USD

Partially Approved Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.52">
<merchantID>OkGo</merchantID>
<merchantReferenceCode>AB1234.1-1</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Smith</lastName>
<street1>201 S. Division St.</street1>
<street2>Suite 500</street2>
<city>Ann Arbor</city>
<state>MI</state>
<postalCode>48104-2201</postalCode>
<country>US</country>
<phoneNumber>123-456-7890</phoneNumber>
<email>okgo@example.com</email>
</billTo>
<purchaseTotals>
<currency>USD</currency>
<grandTotalAmount>1401.00</grandTotalAmount>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cvNumber>xxx</cvNumber>
<cardType>001</cardType>

</card>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

336

Appendix B

Example 60

Examples

Partially Approved Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.52">
<c:merchantReferenceCode>AB1234.1-1</c:merchantReferenceCode>
<c:requestID>2688497722340000852964</c:requestID>
<c:decision>REJECT</c:decision>
<c:reasonCode>110</c:reasonCode>
<c:purchaseTotals><c:currency>USD</c:currency></c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>110</c:reasonCode>
<c:amount>500.00</c:amount>
<c:authorizationCode>831000</c:authorizationCode>
<c:avsCode>A</c:avsCode>
<c:avsCodeRaw>A</c:avsCodeRaw>
<c:cvCode>3</c:cvCode>
<c:processorResponse>010</c:processorResponse>
<c:merchantAdviceCode>00</c:merchantAdviceCode>
<c:cardCategory>J1</c:cardCategory>
<c:requestAmount>1401.00</c:requestAmount>
<c:requestCurrency>USD</c:requestCurrency>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

337

Appendix B

Examples

Split Shipment Examples

One Authorization and One Sale
Example 61

Credit Card Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295 Charleston Rd.</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>650-965-6000</phoneNumber>
<email>jdoe@example.com</email>
</billTo>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cardType>001</cardType>
</card>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

338

Appendix B

Example 62

Examples

Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>YYY</c:avsCodeRaw>
<c:processorResponse>A</c:processorResponse>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

339

Appendix B

Example 63

Examples

Sale Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295 Charleston Rd.</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>650-965-6000</phoneNumber>
<email>jdoe@example.com</email>
</billTo>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cardType>001</cardType>
</card>
<linkToRequest>0305782650000167905080</linkToRequest>
<ccAuthService run="true"/>
<ccCaptureService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

340

Appendix B

Example 64

Examples

Sale Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>YYY</c:avsCodeRaw>
<c:processorResponse>A</c:processorResponse>
</c:ccAuthReply>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:reconciliationID>02850840187309570</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

341

Appendix B

Examples

One Authorization and Two Captures

Example 65

Credit Card Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295 Charleston Rd.</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>650-965-6000</phoneNumber>
<email>jdoe@example.com</email>
</billTo>
<item id="0">
<unitPrice>52.00</unitPrice>
<quantity>1</quantity>
</item>
<item id="1">
<unitPrice>16.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cardType>001</cardType>
</card>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

342

Appendix B

Example 66

Examples

Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>68.00</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>YYY</c:avsCodeRaw>
<c:processorResponse>A</c:processorResponse>
</c:ccAuthReply>
</c:replyMessage>

Example 67

First Credit Card Capture Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<item id="0">
<unitPrice>52.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<ccCaptureService run="true">
<authRequestID>0305782650000167905080</authRequestID>
</ccCaptureService>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

343

Appendix B

Example 68

Examples

First Credit Card Capture Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>1019827520348290570293</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>52.00</c:amount>
<c:reconciliationID>02850840187309570</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Example 69

Second Credit Card Capture Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<item id="0">
<unitPrice>16.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<ccCaptureService run="true">
<authRequestID>0305782650000167905080</authRequestID>
</ccCaptureService>
</requestMessage>

Example 70

Second Credit Card Capture Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>1019827520348290570293</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>16.00</c:amount>
<c:reconciliationID>sl59vu2nh4ek9lq</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

344

Appendix B

Examples

Two Authorizations and One Capture

Example 71

First Credit Card Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295 Charleston Rd.</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>650-965-6000</phoneNumber>
<email>jdoe@example.com</email>
</billTo>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cardType>001</cardType>
</card>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

345

Appendix B

Example 72

Examples

First Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>YYY</c:avsCodeRaw>
<c:processorResponse>A</c:processorResponse>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

346

Appendix B

Example 73

Examples

Second Credit Card Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<lastName>Doe</lastName>
<street1>1295 Charleston Rd.</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<phoneNumber>650-965-6000</phoneNumber>
<email>jdoe@example.com</email>
</billTo>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>12</expirationMonth>
<expirationYear>2015</expirationYear>
<cardType>001</cardType>
</card>
<linkToRequest>0305782650000167905080</linkToRequest>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

347

Appendix B

Example 74

Examples

Second Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>1416783769994859</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:authorizationCode>123456</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>YYY</c:avsCodeRaw>
<c:processorResponse>A</c:processorResponse>
</c:ccAuthReply>
</c:replyMessage>

Example 75

Credit Card Capture Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.40">
<merchantID>my_store</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1</merchantReferenceCode>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
<ccCaptureService run="true">
<authRequestID>1416783769994859</authRequestID>
</ccCaptureService>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

348

Appendix B

Example 76

Examples

Credit Card Capture Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.40">
<c:merchantReferenceCode>482046C3A7E94F5BD1</c:merchantReferenceCode>
<c:requestID>1019827520348290570293</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:reconciliationID>02850840187309570</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Visa Checkout Examples

Example 77

Credit Card Authorization Request

<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.105">
<merchantID>Foster_City_Flowers</merchantID>
<merchantReferenceCode>123456</merchantReferenceCode>
<purchaseTotals>
<currency>USD</currency>
<grandTotalAmount>25.00</grandTotalAmount>
</purchaseTotals>
<encryptedPayment>
<data>binary large object (blob) of encrypted data</data>
<wrappedKey>RNNRasaeG9QrPl+uJ1DQm0j03ne+Iw4clHLyzwE</wrappedKey>
</encryptedPayment>
<ccAuthService_run="true"/>
<paymentSolution>visacheckout</paymentSolution>
<vc><orderID>335161017227386762</orderID></vc>
</requestMessage>

Credit Card Services Using the Simple Order API | January 2016

349

Appendix B

Example 78

Examples

Credit Card Authorization Reply

<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.105">
<c:merchantReferenceCode>123456</c:merchantReferenceCode>
<c:requestID>4068437426340172492292</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>25.00</c:amount>
<c:authorizationCode>831000</c:authorizationCode>
<c:avsCode>Y</c:avsCode>
<c:avsCodeRaw>Y</c:avsCodeRaw>
<c:processorResponse>00</c:processorResponse>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Using the Simple Order API | January 2016

350

APPENDIX

Additional Amount Types

Additional amount types are used with additional amounts, which are described in
"Additional Amounts," page 99.
Table 60

Additional Amount Types for Goods and Services

Goods and Services

Code

Bar

019

Bar/Mini-Bar

023

Barber/Beauty Salon

028

Beverage

017

Business Center

036

Catering Charges

022

Convention Fees

037

Food

016

Food/Beverage

018

Gift Shop

030

Health & Fitness

029

Internet Service

025

Insurance Purchased

052

Laundry/Dry-Cleaning

027

Lodging

020

Movies/Pay-Per-View

026

Pet Fees

033

Phone

024

Pro Shop

031

Restaurant/Room Service

021

Reward Program Transaction

047

Tip/Gratuity

058

Credit Card Services Using the Simple Order API | January 2016

351

Appendix C

Table 61

Additional Amount Types

Additional Amount Types for Charges and Fees

Charges and Fees

Code

Additional Miles/Kilometers/Distance

062

Auto Rental Adjustment

060

Cancellation Adjustment

065

Charges Added After Check-Out/Departure

041

Convenience Charge

050

Delivery Charge

051

Discount

053

Equipment Rental

035

Express Service Charge

040

Freight/Shipping/Handling

055

Fuel Charge

061

Late Return

063

Meeting/Conference Charges

038

Misc Charges/Fees

042

No Show Charge

039

Order Processing Charge

049

Parking Fee

032

Policy Adjustment

066

Repairs

064

Surcharge

048

Tickets/Violations

054

Tours

034

Table 62

Additional Amount Types for Taxes

Taxes

Code

Goods and Services Tax CODE (GST)

001

Consumption Tax

002

Provincial Sales Tax (PST)

003

Quebec Sales Tax (QST)

004

Harmonized Sales Tax (HST)

005

Insurance Premium Tax (IPT)

006

Circulation of Merchandise and Service Tax (ICMS)

007

Industrialized Products Federal Tributary Tax (IPI Federal Tributary)

008

Credit Card Services Using the Simple Order API | January 2016

352

Appendix C

Table 62

Additional Amount Types

Additional Amount Types for Taxes (Continued)

Taxes

Code

Inland Revenue Income Tax (IR Income Tax)

009

International Students and Scholars Income Tax (ISS Income Tax)

010

Income Security and Reform Tax (ISR Income Tax)

011

Occupancy Tax

012

Room Tax

013

Surcharge Tax

014

Airport Tax

015

Ticket Tax

043

Miscellaneous Tax

046

Sales Tax

056

Stamp Duty

067

Value Added Tax (VAT)

057

Exempt - No GST charged

068

Credit Card Services Using the Simple Order API | January 2016

353

APPENDIX

American Express SafeKey

Response Codes

The American Express SafeKey response code is returned in ccAuthReply_

cavvResponseCode in the reply message for an authorization request. See "American
Express SafeKey," page 183, for a description of American Express SafeKey.
Table 63

American Express SafeKey Response Codes

Response
Code

Description

CAVV failed validation and authentication.

CAVV passed validation and authentication.

CAVV passed the validation attempt.

CAVV failed the validation attempt.

CAVV failed the validation attempt and the issuer is available.

CAVV passed the validation attempt and the issuer is available.

CAVV failed the validation attempt and the issuer is not available.

CAVV passed the validation attempt and the issuer is not available.

Issuer does not participate or 3-D secure data was not used.

99

An unknown value was returned from the processor.

Credit Card Services Using the Simple Order API | January 2016

354

APPENDIX

AVS Codes

The AVS code is returned in ccAuthReply_avsCode in the authorization reply message.

See "Address Verification System (AVS)," page 72, for a description of AVS.

AVS Codes for CyberSource Latin

American Processing
CyberSource Latin American Processing is the CyberSource name for
Braspag. CyberSource provides two processors for Latin America:
CyberSource Latin American Processing (Braspag), which is supported in
multiple Latin American countries, and Cielo, which is supported in Brazil only.
The information in this section applies only to CyberSource Latin American
Processing (Braspag).

Note

Table 64

AVS Codes for CyberSource Latin American Processing

Code

Description

Partial match: postal code and address match.

Not supported: AVS is not supported for this card type.

or
Invalid: the acquirer returned an unrecognized value for the AVS response.

Partial match: postal code matches, but CPF and address do not match. 1

Not supported: AVS not supported or not verified.

No match: AVS information is not available.

Partial match: CPF matches, but postal code and address do not match. 1

Partial match: postal code and CPF match, but address does not match. 1

No match: postal code, CPF, and address do not match. 1

1 CPF (Cadastro de Pessoas Fisicas) is required only for Redecard in Brazil.

Credit Card Services Using the Simple Order API | January 2016

355

Appendix E

Table 64

AVS Codes

AVS Codes for CyberSource Latin American Processing (Continued)

Code

Description

Partial match: CPF and address match, but postal code does not match. 1

Not supported: your implementation does not support AVS.

or
System unavailable.

Partial match: address matches, but postal code and CPF do not match. 1

Match: postal code, CPF, and address match. 1

1 CPF (Cadastro de Pessoas Fisicas) is required only for Redecard in Brazil.

AVS Codes for All Other

Processors
Table 65

Types of AVS Codes

Type of Codes

Codes

Description

Codes for American

Express Cards

F, H, K, L, O, T,
V

For American Express cards only. For American

Express cards, you can receive Visa and CyberSource
AVS codes in addition to the American Express AVS
codes.

Note For CyberSource through VisaNet, the

American Express AVS codes are converted to Visa
AVS codes before they are returned to you. As a result,
you will not receive American Express AVS codes for
the American Express card type.

Credit Card Services Using the Simple Order API | January 2016

356

Appendix E

Table 65

AVS Codes

Types of AVS Codes (Continued)

Type of Codes

Codes

Description

International Visa
Codes

B, C, D, G, I,
M, P

Domestic Visa
Codes

A, E, N, R, S,
U, W, X, Y, Z

The international and domestic alphabetic AVS codes

are the Visa standard AVS codes. CyberSource maps
the standard AVS return codes for other types of credit
cards, including American Express cards, to the Visa
standard AVS codes.
AVS is considered either domestic or international,
depending on the location of the bank that issued the
customers credit card:

When the bank is in the U.S., the AVS is domestic.

When the bank is outside the U.S., the AVS is

international.

You should be prepared to handle both domestic and

international AVS result codes:

CyberSource Codes

Table 66

1, 2, 3, 4

For international cards, you can receive domestic

AVS codes in addition to the international AVS
codes.

For domestic cards, you can receive international

AVS codes in addition to the domestic AVS codes.

The numeric AVS codes are created by CyberSource

and are not standard Visa codes. These AVS codes
can be returned for any card type.

AVS Codes

Code

Description

Partial match: street address matches, but 5-digit and 9-digit postal codes do not match.

Partial match: street address matches, but postal code is not verified. Returned only for
Visa cards not issued in the U.S.

No match: street address and postal code do not match. Returned only for Visa cards
not issued in the U.S.

D&M

Match: street address and postal code match. Returned only for Visa cards not issued in
the U.S.

Invalid: AVS data is invalid or AVS is not allowed for this card type.

Partial match: card members name does not match, but billing postal code matches.
Returned only for the American Express card type.

Not supported: issuing bank outside the U.S. does not support AVS.

Partial match: card members name does not match, but street address and postal code
match. Returned only for the American Express card type.

No match: address not verified. Returned only for Visa cards not issued in the U.S.

Partial match: card members name matches, but billing address and billing postal code
do not match. Returned only for the American Express card type.

Credit Card Services Using the Simple Order API | January 2016

357

Appendix E

Table 66

AVS Codes

AVS Codes (Continued)

Code

Description

Partial match: card members name and billing postal code match, but billing address
does not match. Returned only for the American Express card type.

See the entry for D & M.

No match: one of the following:

Street address and postal code do not match.

Card members name, street address, and postal code do not match. Returned only
for the American Express card type.

Partial match: card members name and billing address match, but billing postal code
does not match. Returned only for the American Express card type.

Partial match: postal code matches, but street address not verified. Returned only for
Visa cards not issued in the U.S.

System unavailable.

Not supported: issuing bank in the U.S. does not support AVS.

Partial match: card members name does not match, but street address matches.
Returned only for the American Express card type.

System unavailable: address information unavailable for one of these reasons:

The U.S. bank does not support AVS outside the U.S.

The AVS in a U.S. bank is not functioning properly.

Match: card members name, billing address, and billing postal code match. Returned
only for the American Express card type.

Partial match: street address does not match, but 9-digit postal code matches.

Match: street address and 9-digit postal code match.

Match: street address and 5-digit postal code match.

Partial match: street address does not match, but 5-digit postal code matches.

Not supported: one of the following:

AVS is not supported for this processor or card type.

AVS is disabled for your CyberSource account. To enable AVS, contact CyberSource
Customer Support.

Unrecognized: the processor returned an unrecognized value for the AVS response.

Match: address is confirmed. Returned only for PayPal Express Checkout.

No match: address is not confirmed. Returned only for PayPal Express Checkout.

No match: no AVS code was returned by the processor.

Credit Card Services Using the Simple Order API | January 2016

358

APPENDIX

Commerce Indicators

The commerce indicator is a request value that you send in the ccAuthService_
commerceIndicator and ccCreditService_commerceIndicator fields. This appendix
describes the commerce indicators for transactions that are not for payer authentication.
For the commerce indicators for payer authentication transactions, see "Payer
Authentication," page 171.
Table 67

Commerce Indicators for Non-Payer-Authentication Transactions

Values

Description

install

Payments will be made in installments. See "Installment Payments,"

page 123.

and

install_
internet
internet

E-commerce order placed using a web site. On Global Collect,

(default)

internet is supported only for Carte Bleue transactions.

moto

Mail order or telephone order. Not supported on Cielo or UATP or for any
Bill Me Later processors. On Global Collect, moto is supported only for
Carte Bleue transactions.

moto_cc

Mail order or telephone order from a call center. This value is available
only on the Asia, Middle East, and Africa Gateway.

recurring

Recurring payments. See "Recurring Payments," page 189, for a list of

processors that support these values.

and

recurring_
internet

recurringU.S. transaction or non-U.S. mail order / telephone

order (MOTO) transaction

recurring_internetnon-U.S. e-commerce (internet)

transaction

Credit Card Services Using the Simple Order API | January 2016

359

APPENDIX

CVN Codes

The CVN code is returned in ccAuthReply_cvCode in the authorization reply message.

See "Card Verification Numbers (CVNs)," page 80, for a description of CVN.
Table 68

CVN Codes

Code

Description

The transaction was determined to be suspicious by the issuing bank.

The CVN failed the processor's data validation check.

The CVN matched.

The CVN did not match.

The CVN was not processed by the processor for an unspecified reason.

The CVN is on the card but was not included in the request.

Card verification is not supported by the issuing bank.

Card verification is not supported by the payment card company.

Card verification is not supported for this processor or card type.

An unrecognized result code was returned by the processor for the card
verification response.

No result code was returned by the processor.

Credit Card Services Using the Simple Order API | January 2016

360

APPENDIX

CyberSource through
VisaNet Acquirers

The Visa Electron card type is processed the same way that the Visa debit card
is processed. Use card type value 001 (Visa) for Visa Electron.
Note

The following acquirers are supported for CyberSource through VisaNet:

Absa Bank: Visa, MasterCard, JCB, Diners Club

Agricultural Bank of China (ABC): Visa, MasterCard, American Express, JCB, Diners
Club

Note

CyberSource through VisaNet cannot process domestic transactions in

China. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction is a transaction for which the
credit card is issued in another country and accepted by a merchant in
China.

Arab African International Bank (AAIB): Visa, MasterCard, JCB

Asia Commercial Bank (ACB): Visa, MasterCard, JCB

Auckland Savings Bank (ASB): Visa, MasterCard

Australia and New Zealand Banking Group Limited (ANZ): Visa, MasterCard

Axis Bank Ltd of India: Visa, MasterCard, Diners Club

Banco Nacional de Mxico (Banamex): Visa, MasterCard, American Express,

Discover, JCB, Diners Club

Bank Muscat of Oman: Visa, MasterCard, American Express, Diners Club

Bank of Ayudhya (BAY): Visa, MasterCard, JCB

Bank of China (BOC): Visa, MasterCard

Credit Card Services Using the Simple Order API | January 2016

361

Appendix H

CyberSource through VisaNet Acquirers

Bank of Communications: Visa, MasterCard

Note

CyberSource through VisaNet cannot process domestic transactions in

China. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction is a transaction for which the
credit card is issued in another country and accepted by a merchant in
China.

Banque Pour Le Commerce Exterieur Lao (BCEL): Visa, MasterCard, American

Express, JCB

Barclays Bank Botswana: Visa, MasterCard, American Express

Barclays Bank Mauritius Limited: Visa, MasterCard, American Express

Barclays Bank of Ghana Limited, Barclays Bank of Tanzania Limited, and Barclays
Bank of Uganda Limited: Visa, MasterCard, American Express

Barclays Bank of Kenya: Visa, MasterCard, American Express

Barclays Bank of Zambia: Visa, MasterCard, American Express

Barclays Bank Seychelles: Visa, MasterCard, American Express

BLOM Bank: Visa, MasterCard

CitiBank Singapore LTD: Visa, MasterCard, JCB

Commercial Bank of Qatar: Visa, MasterCard, American Express, JCB, Diners Club

CrediMax (Bahrain): Visa, MasterCard, American Express, JCB, Diners Club

CTBC Bank Ltd.: Visa, MasterCard, JCB

FirstRand Bank: Visa, MasterCard, American Express, Diners Club

Global Payment Asia Pacific: Visa, MasterCard, JCB

Note

In India, the only supported card types are Visa and MasterCard. All three
card types (Visa, MasterCard, JCB) are supported in all other countries
that Global Payment Asia Pacific covers.

Habib Bank Ltd (HBL): Visa, MasterCard, American Express, JCB, Diners Club

HDFC Bank Ltd of India: Visa, MasterCard, Diners Club

I&M Bank: Visa, MasterCard

Credit Card Services Using the Simple Order API | January 2016

362

Appendix H

CyberSource through VisaNet Acquirers

ICICI of India: Visa, MasterCard

Korea Exchange Bank (KEB): Visa, MasterCard, JCB

Note

CyberSource through VisaNet cannot process domestic transactions in

Korea. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction is a transaction for which the
credit card is issued in another country and accepted by a merchant in
Korea.

Mashreq: Visa, MasterCard, American Express, JCB, Diners Club

Maybank: Visa, MasterCard, American Express, JCB

National Bank of Abu Dhabi (NBAD): Visa, MasterCard, JCB, Diners Club

National Bank of Kuwait (NBK): Visa, MasterCard, Diners Club

National Commercial Bank: Visa, MasterCard

Network International: Visa, MasterCard, JCB, Diners Club

Overseas Chinese Banking Corp (OCBC): Visa, MasterCard

PT Bank Negara Indonesia: Visa, MasterCard

Qatar National Bank (QNB Group): Visa, MasterCard, American Express, JCB, Diners
Club

QIWI Bank: Visa

Note

CyberSource through VisaNet cannot process domestic transactions in

Russia. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction in Russia is a transaction for
which the merchant, acquirer, or issuer is not in Russia.

Raiffeisenbank: Visa, MasterCard

Rosbank: Visa, MasterCard, JCB

Note

CyberSource through VisaNet cannot process domestic transactions in

Russia. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction in Russia is a transaction for
which the merchant, acquirer, or issuer is not in Russia.

Credit Card Services Using the Simple Order API | January 2016

363

Appendix H

CyberSource through VisaNet Acquirers

Russian Standard Bank: Visa, MasterCard, American Express, JCB, Diners Club

Note

CyberSource through VisaNet cannot process domestic transactions in

Russia. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction in Russia is a transaction for
which the merchant, acquirer, or issuer is not in Russia.

Sacombank: Visa, MasterCard, JCB

Sberbank: Visa

Note

CyberSource through VisaNet cannot process domestic transactions in

Russia. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction in Russia is a transaction for
which the merchant, acquirer, or issuer is not in Russia.

Vantiv: Visa, MasterCard, American Express, Discover, JCB, Diners Club

Vietcombank: Visa, MasterCard, American Express, JCB, Diners Club

VietinBank: Visa, MasterCard, JCB, Diners Club

Visa Guatemala: Visa

VisaNet Uruguay: Visa

VTB24: Visa, MasterCard

Note

CyberSource through VisaNet cannot process domestic transactions in

Russia. CyberSource through VisaNet can process only cross-border
transactions. A cross-border transaction in Russia is a transaction for
which the merchant, acquirer, or issuer is not in Russia.

Westpac: Visa, MasterCard

Wing Hang Bank: Visa, MasterCard

Wing Lung Bank: Visa, MasterCard

Credit Card Services Using the Simple Order API | January 2016

364

APPENDIX

Electronic Verification
Response Codes

See "Electronic Verification (EV)," page 78, for a list of the fields in which the Electronic
Verification response codes are returned. The following table describes the mapped
response codes.
Table 69

Electronic Verification Mapped Response Codes

Response
Code

Description

First name matches; last name does not match.

Last name matches; first name does not match.

First name and last name match.

No, the data does not match.

The processor did not return verification information.

The system is unavailable, so retry.

The verification service is not available.

Verification information is not available.

Yes, the data matches.

Electronic verification did not generate a response.

The processor returned an unrecognized value.

Credit Card Services Using the Simple Order API | January 2016

365

APPENDIX

Frequently Asked Questions

What kind of bank account do I need to accept credit card payments?

You need a merchant bank account that is configured to process card-not-present or mail
order/telephone order (MOTO) transactions. See "Acquiring (Merchant) Banks," page 22.

What types of credit cards can my customers use?

CyberSource can accept payments made with numerous types of credit cards, including
Visa, MasterCard, Discover, and American Express. In addition, CyberSource can accept
most offline debit cards, which are also known as check cards, many private label cards,
and Level II purchasing cards. Your payment processor can limit the types of cards that
you can accept. See "Payment Processors," page 27, or contact your CyberSource
account representative.

Do I need to sign agreements with the payment card companies?

Some credit card companies, such as American Express and Discover, require you to sign
agreements with them. For other card types, such as Visa and MasterCard, you can
usually sign a single contract with your acquiring bank or payment processor. Your
acquiring bank can help ensure that you sign all of the necessary agreements.

Can I use more than one payment processor or merchant account

provider?
Yes. CyberSource can provide you with multiple CyberSource merchant IDs and configure
each one to use a different payment processor or merchant account provider.

What happens when my customers commit fraud?

You could be liable for fraudulent transactions. When customers complain that you
charged their accounts improperly, you might be required to return their money at your
expense; this is known as a chargeback. If you receive a large number of chargebacks, or
if a large number of your customers commit fraud, your acquiring bank might raise your
fees or revoke your merchant bank account. Contact your CyberSource account
representative for information about CyberSource products that can help prevent fraud.

When do authorizations expire?

Most authorizations expire within five to seven days, but the bank or company that issued
the card decides how long an authorization lasts.

Credit Card Services Using the Simple Order API | January 2016

366

Appendix J

Frequently Asked Questions

When an authorization expires, will I be able to charge my customer?

Yes. CyberSource is not notified when an authorization expires, so it is possible to capture
an expired authorization. However, the capture might be downgraded, which would
increase your fees for the transaction. Additionally, the payment card company can decide
not to capture expired authorizations.
If you believe that an authorization expired, you can request a new authorization, then
capture the new authorization. However, the new authorization could be denied if the
customers credit limit has been exceeded, if the card has expired, or if the card has been
cancelled.

Can I reverse an authorization?

Yes. Some processors allow you to reverse an authorization, which releases the hold that
the authorization placed on the customers credit card funds. For the list of processors that
allow you to reverse an authorization, see "Reversing an Authorization," page 39.
If your processor does not support authorization reversals and you need to reverse an
authorization, contact the customers issuing bank or wait for the authorization to expire.

Can I cancel a capture or credit?

Yes. For some processors, you can use the void service to cancel a capture or credit that
you have previously requested. You must request the void before CyberSource submits
the capture or credit request to your payment processor. See "Voiding a Capture or
Credit," page 70.

How can I prevent my customers from clicking the Buy button more
than once?
Use one or more of these options:

After a customer clicks the Buy button, send the customer to a new web page

After a customer clicks the Buy button, hide or disable the button

The Support Center provides sample JavaScript code to disable the Buy button after a
customer clicks it. The code is available at:
http://www.cybersource.com/support_center/implementation/best_practices/
view.xml?page_id=415

Can I change the company name and phone number that appears on
my customers credit card statements?
CyberSource permits you to change these values, which are called merchant descriptors,
when you use a payment processor that supports this feature. After your processor
configures the merchant descriptors for your account, you can choose which merchant
descriptor to use every time you request a transaction. You must also contact
CyberSource and your processor to specify default merchant descriptors for your account.
See "Merchant Descriptors," page 131.

Credit Card Services Using the Simple Order API | January 2016

367

Appendix J

Frequently Asked Questions

When do my capture and credit transactions appear on my

CyberSource reports?
Capture and credit transactions usually appear on your reports two calendar days after
you request them. However, it might take longer for funds to be transferred.

When are funds transferred between my customers bank account

and my companys bank account?
Funds are usually transferred within two to three days after you request a capture or
credit.

Credit Card Services Using the Simple Order API | January 2016

368

APPENDIX

Global Collect Credit Card

Reversals

Credit card reversals and requests for information, which are also called retrieval
requests, are business transactions initiated by your customers through their banks. You
can learn more about credit card disputes at Visa USAs web site:
http://usa.visa.com/merchants/operations/chargebacks_dispute_resolution/
The information in this section is generally applicable to all card types and all operating
regions although certain details can vary.

Requests for Information

Credit card reversals and requests for information involve communication:

Between your customer and the acquiring bank

Between you and Global Collect

Between Global Collect and the acquiring bank

The process is:

1

The acquiring bank notifies Global Collect of your customers request for information.

Global Collect searches for refunds already processed for the transaction identified by
your customer.

Global Collect responds to the acquiring bank stating already refunded. Global
Collect does not take any further action because the information request has been
satisfied. Requests for information are not documented within any report.

If Global Collects research determines that a refund for the inquiry has not been
initiated, Global Collect forwards the retrieval request to you. All requests received
before midnight PT (Pacific Time) are forwarded to you by 0800 PT by email with a
request for additional information. See "Request for Information Example," page 374.

A request for information is an impending chargeback. If Global Collect does not

receive your answer by midnight PT before the fifth day, your customers bank initiates
a chargeback.

Credit Card Services Using the Simple Order API | January 2016

369

Appendix K

Global Collect Credit Card Reversals

When you receive a request for information, you must respond promptly and with as much
detail as possible:
1

Respond to your customers request for information:

Address your email to Dispute.management@globalcollect.com.

There is no standard format to follow. However, you should provide as much

information as you have. You should provide scanned copies of delivery receipts
or official banking information with bank letterheads, bank logos, or other official
bank insignia.

Global Collect forwards your response by email to the acquiring bank which then
communicates with your customers issuing bank.

If the information in the response is sufficient in the judgment of the issuing bank or
customer in accordance with MasterCard/Visa/American Express rules, the
chargeback is not executed. The dispute is dropped without further notification to the
acquirer, Global Collect, or you.

Chargebacks
If one of the following situations occurs, then the issuing bank sends a chargeback
(refund) to the customers card and debits your account.:

You do not send your response in a timely manner

The information does not satisfy the reasons defined by the card type

Your customer submits a valid claim for refund

If the information you provided in response to the request for information is not satisfactory
or if your customer decides to charge the item back for any reason as defined by the
specific card types, the issuing bank executes a chargeback. This adverse movement of
funds is unavoidable, but can be reversed in some cases. See "Representments,"
page 371.
If Global Collect receives a chargeback by 0800 PT, the amount of the chargeback is
deducted from your account the next business day and is reflected in:

The Transaction Search in the Business Center

The Payment Events Report for that processing day

The chargeback entry includes the reason code for the chargeback. The card types do not
circulate lists of reason codes to merchants. However, notable merchant banks freely
provide detailed explanations of chargeback reason codes on their web sites. This
document provides:

"Chargeback Reason Codes for Visa," page 372

"Chargeback Reason Codes for MasterCard," page 373

Credit Card Services Using the Simple Order API | January 2016

370

Appendix K

Global Collect Credit Card Reversals

Additionally, you can search the Internet for these phrases:

MasterCard chargeback reason code

Visa chargeback reason code

Whenever you receive a chargeback, your account is debited by the full or partial
transaction amount associated with the chargeback. Chargebacks are deducted from the
funding you would normally receive.

Representments
When you or Global Collect disputes the legitimacy of a chargeback, a representment
case is initiated:
1

Global Collect automatically initiates a representment case if your customer initiates a

chargeback for a transaction that has already been refunded by you.
As in all representment cases, there is no assurance that the issuing bank will reverse
the chargeback even in the face of the evidence. However, the chances of success
are excellent. Submitting a representment case does not automatically result in the
debiting of your customers account and the crediting of yours.

If you want to challenge a chargeback, in other words represent it, then you must do
so very quickly. To optimize your chances for success, you must document your facts
and submit them to Global Collect in five or fewer days after receiving notification of
the chargeback.
For a description of the best practices for avoiding chargebacks and challenging
specious chargebacks, see the Visa web site:
http://usa.visa.com/merchants/operations/chargebacks_dispute_resolution/
Additionally, you can search the Internet for these phrases:

fight chargebacks

representment

If your representment case is approved by your customers issuing bank, the bank
notifies you by refunding your account for amount of the chargeback. Although it is
inconvenient, the payment card companies and issuing banks do not provide any
other method of notification.
The notification appears as a chargeback withdrawal that is noted in the Payment
Events Report. This event generally takes place 11 to 15 business days after you
submit the representment case information to Global Collect. A chargeback
withdrawal credits the financial status and the subsequent funding event.

Credit Card Services Using the Simple Order API | January 2016

371

Appendix K

Global Collect Credit Card Reversals

Chargeback Reason Codes

for Visa
Reason
Code

Description

30

Services Not Provided or Merchandise Not Received

31

Error in Addition

41

Cancelled Recurring Transaction

50

Credit Posted as Purchase

53

Not as Described

56

Defective Merchandise

60

Requested Copy Illegible

61

Fraudulent Mail/Phone Order Transaction

71

Authorization Request Declined / Authorization Declined

72

No Authorization / Transaction Exceeds Floor Limit

74

Late Presentment

75

Cardholder Does Not Recognize the Transaction

79

Requested Transaction Information Not Received

82

Duplicate Processing

83

Nonpossession of Card

85

Credit Not Processed

86

Paid by Other Means

90

Nonreceipt of Merchandise

Credit Card Services Using the Simple Order API | January 2016

372

Appendix K

Global Collect Credit Card Reversals

Chargeback Reason Codes

for MasterCard
Reason
Code

Description

01

Requested Transaction Data Not Received

02

Requested Item Illegible

08

Requested / Required Authorization Not Obtained

12

Account Number Not on File

31

Transaction Amount Differs

34

Duplicate Processing

35

Card Not Valid or Expired

37

Fraudulent Mail/Phone Order Transaction

41

Cancelled Recurring Transaction

42

Late Presentment

47

Exceeds Floor Limit, Not Authorized, and Fraudulent Transactions

50

Credit Posted as a Debit

53

Cardholder Dispute Defective / Not as Described

54

Cardholder Dispute-Not Elsewhere (U.S. only)

55

Nonreceipt of Merchandise

59

Services Not Rendered

60

Credit Not Processed

63

Cardholder Does Not Recognize - Potential Fraud

Credit Card Services Using the Simple Order API | January 2016

373

Appendix K

Global Collect Credit Card Reversals

Request for Information Example

This example illustrates an email you might receive from Global Collect requesting
information. In this example, the Xs represent values for the request.
Dear Sir/Madam,
With regards to the transactions below, we have been requested by the cardholders/
cardholders banks to provide photocopies of the transaction receipts.
Please reply within 5 days from the date of this e-mail with:
- legible copies of the transaction receipts;
- a manually imprinted & signed voucher in the case of a hand keyed transaction;
- signed delivery information;
- any other relevant documentation to support these charges;
- or any information regarding a possible refund;
- together with a copy of this e-mail.
Global Collect Call-ID

: XXXXX

Bank Case ID

: XXXXXXXXX

Credit Card Number

: ***********XXXX

External Order Number

: XXXXXXXXXXX

Merchant Reference

Merchant Number

: XXXXXXXXXXXX

Contract-ID

: XXXX

Transaction history
Transaction

Curr

Amount

Date

-------------------------------------------------------------Original order amount

USD

XX.XX

DD-MM-YYYY

-------------------------------------------------------------Total

USD

XX.XX

Amount currently in question

USD

XX.XX

Credit Card Services Using the Simple Order API | January 2016

374

Appendix K

Global Collect Credit Card Reversals

Visa and MasterCard International Rules and Regulations specify that Global Collect's
bank must provide a copy of a sales voucher when requested by a cardholder or bank.
Under these regulations, failure to provide a fully legible transaction receipt will result in
the item being returned unpaid to you. In the event that this transaction was hand keyed
into your terminal, you must also supply us with a copy of the manual imprinted voucher
you took, to prove the presence of the card.
Remember to keep all original vouchers for 12 months as per your merchant
agreement.
Kind regards,
Dispute Management
GlobalCollect BV
P.O. Box 2001
2130 GE Hoofddorp
The Netherlands
Fax: +31 23 554 8663
Email: dispute.management@globalcollect.com

Credit Card Services Using the Simple Order API | January 2016

375

APPENDIX

Network Transaction
Identifiers

The network transaction identifier is returned in ccAuthReply_

paymentNetworkTransactionID in the authorization reply message.

CyberSource through VisaNet

For CyberSource through VisaNet, the following values are returned for each card type:

American Express: American Express generates this value. It is included in all replies
from the American Express Global Network (AEGN).

MasterCard: This value is the qualification information for the MasterCard Interchange
Compliance (MIC) program. It is used for all MasterCard responses coming from
Banknet through Visa to certified acquirers. Format:
Bits 1-4: Banknet date
Bits 5-7: MasterCard product ID. See "MasterCard Product IDs," page 380.
Bits 8-13: Banknet reference number generated by MasterCard for each transaction
Bits 14-15: Spaces

Visa and Other Card Types: The payment card company generates this value. It is
unique for each original authorization and identifies a transaction throughout its life
cycle.

GPN
For GPN, the following values are returned for each card type:

American Express: The payment card company generates this value. CyberSource
saves this value and sends it to the processor in all subsequent capture requests.

Discover: The payment card company generates this value. CyberSource saves this
value and sends it to the processor in all subsequent requests for full authorization
reversals and captures.

MasterCard: The payment card company generates this value. CyberSource saves it
and sends it to the processor in all subsequent requests for full authorization reversals
and captures. Format:
Bits 1-9: Banknet reference number generated by MasterCard for each transaction
Bits 10-13: Banknet date
Bits 14-15: Spaces

Credit Card Services Using the Simple Order API | January 2016

376

Appendix L

Network Transaction Identifiers

Visa: The payment card company generates this value. CyberSource saves it and
sends it to the processor in all subsequent requests for full authorization reversals and
captures.

Other Card Types: Not used.

Credit Card Services Using the Simple Order API | January 2016

377

APPENDIX

Product Codes

The following table lists the values you can use for the product code in the item_#_
productCode request field.
Table 70

Product Codes

Product Code

Definition

adult_content

Adult content.

coupon

Coupon applied to the entire order.

default

Default value for the product code. CyberSource uses

default when a request message does not include a
value for the product code.

electronic_good

Electronic product other than software.

electronic_software

Software distributed electronically rather than on disks or

other media.

gift_certificate

Gift certificate.

handling_only

Fee that you charge your customer to cover your

administrative selling costs.

service

Service that you perform for your customer.

shipping_and_handling

The shipping portion is the charge for shipping the product to

your customer. The handling portion is the fee you charge
your customer to cover your administrative selling costs.

shipping_only

Charge for transporting tangible personal property from your

location to your customer. You must maintain documentation
that clearly establishes the location where the title to the
property passed from you to your customer.

subscription

Subscription to a web site or other content.

Credit Card Services Using the Simple Order API | January 2016

378

APPENDIX

Product IDs

The Visa or MasterCard product ID is returned in ccAuthReply_cardCategory in the

authorization reply message for all processors except CyberSource through VisaNet.
For CyberSource through VisaNet:

The Visa product ID is returned in ccAuthReply_cardCategory in the authorization

reply message.

The MasterCard product ID is returned in ccAuthReply_paymentNetwork

TransactionID in the authorization reply message.

Visa Product IDs

You will probably not receive all the codes in the following table.
Note

In the following table, the carat character ( ^ ) indicates a space.

Table 71

Visa Product IDs

Value

Description

Value

Description

A^

Visa Traditional

L^

Electron

AX

American Express

M^

MasterCard/Eurocard and Diners

B^

Visa Traditional Rewards

N^

Visa Platinum

C^

Visa Signature

N1

Visa Rewards

D^

Visa Signature Preferred

N2

Visa Select

DI

Discover

P^

Visa Gold

DN

Diners Club International

Q^

Private Label

E^

Reserved

Q1

Private Label Prepaid

F^

Visa Classic

Q2

Private Label Basic

G^

Visa Business

Q3

Private Label Standard

Credit Card Services Using the Simple Order API | January 2016

379

Appendix N

Table 71

Product IDs

Visa Product IDs (Continued)

G1

Visa Signature Business

Q4

Private Label Enhanced

G2

Visa Business Check Card

Q5

Private Label Specialized

G3

Visa Business Enhanced

Q6

Private Label Premium

G4

Visa Infinite Business

R^

Proprietary

H^

Visa Check Card

S^

Visa Purchasing

I^

Visa Infinite

S1

Visa Purchasing with Fleet

I1

Visa Infinite Privilege

S2

Visa GSA Purchasing

I2

Visa Ultra High Net Worth

S3

Visa GSA Purchasing with Fleet

J^

Reserved

S4

Government Services Loan

J1

Visa General Prepaid

S5

Commercial Transport EBT

J2

Visa Prepaid Gift

S6

Business Loan

J3

Visa Prepaid Healthcare

T^

Reserved/Interlink

J4

Visa Prepaid Commercial

U^

Visa TravelMoney

JC

JCB

V^

V Pay

K^

Visa Corporate T&E

W^ Z^

Reserved

K1

Visa GSA Corporate T&E

0^ 9^

Reserved

MasterCard Product IDs

Note

Table 72

MasterCard can introduce new values for this field without advance notice. See
the MasterCard technical documentation for additional information.
CyberSource through VisaNet does not edit or validate field content.

MasterCard Product IDs

Value

Description

Value

Description

CBL

Carte Blanche

MNF

MasterCard Public Sector

Commercial Card

DAG

Gold Debit MasterCard Salary

MOC

Standard Maestro Social

DAP

Platinum Debit MasterCard Salary

MPA

Prepaid MasterCard Payroll Card

DAS

Standard Debit MasterCard Salary

MPB

MasterCard Preferred BusinessCard

DCC

Diners Club

MPC

MasterCard Professional Card

DOS

Standard Debit MasterCard Social

MPF

Prepaid MasterCard Gift Card

JCB

Japanese Credit Bureau

MPG

Prepaid MasterCard Consumer

Reloadable Card

Credit Card Services Using the Simple Order API | January 2016

380

Appendix N

Table 72

Product IDs

MasterCard Product IDs (Continued)

Value

Description

Value

Description

MAB

World Elite MasterCard for Business

MPJ

Prepaid Debit MasterCard Card Gold

MAC

MasterCard Corporate World Elite

MPK

Prepaid MasterCard Government

Commercial Card

MAP

MasterCard Commercial Payments

Account product

MPL

Platinum MasterCard Card

MAQ

MasterCard Prepaid Commercial

Payments Account

MPM

Prepaid MasterCard Consumer

Promotion Card

MAV

MasterCard Activation Verification

MPN

Prepaid MasterCard Insurance Card

MBB

MasterCard Prepaid Consumer

MPO

Prepaid MasterCard Other Card

MBC

MasterCard Prepaid Voucher

MPR

Prepaid MasterCard Travel Card

MBD

Deferred Debit MasterCard

BusinessCard Card

MPT

Prepaid MasterCard Teen Card

MBE

MasterCard Electronic Business

Card

MPV

Prepaid MasterCard Government

Benefit Card

MBP

MasterCard Corporate Prepaid

MPW

Prepaid MasterCard Corporate Card

MBT

MasterCard Corporate Prepaid

Travel

MPX

Prepaid MasterCard Flex Benefit

Card

MCB

MasterCard BusinessCard Card/

MasterCard Corporate Card

MPY

Prepaid MasterCard Employee

Incentive Card

MCC

MasterCard Card

MPZ

Prepaid MasterCard Emergency

Assistance Card

MCE

MasterCard Electronic Card

MRB

Prepaid MasterCard Electronic

BusinessCard

MCF

MasterCard Electronic Fleet Card

MRC

Prepaid MasterCard Electronic Card

MCG

Gold MasterCard Card

MRG

Prepaid MasterCard Card Outside

U.S.

MCM

MasterCard Corporate Meeting Card

MRH

MasterCard Platinum Prepaid Travel

Card

MCO

MasterCard Corporate

MRJ

Prepaid MasterCard Gold Card

MCP

MasterCard Corporate Purchasing

Card

MRK

Prepaid MasterCard Electronic

Commercial

MCS

MasterCard Standard Card

MRL

Prepaid MasterCard Electronic

Commercial

MCW

World MasterCard Card

MRS

Prepaid MasterCard ISIC Student

Card

MCX

MasterCard Card
(international use)

MRW

Prepaid MasterCard BusinessCard

Credit Outside U.S.

MDB

Debit MasterCard BusinessCard

Card

MSI

Maestro point-of-sale debit program

Credit Card Services Using the Simple Order API | January 2016

381

Appendix N

Table 72

Product IDs

MasterCard Product IDs (Continued)

Value

Description

Value

Description

MDG

Debit Gold MasterCard

MTP

MasterCard Platinum Prepaid Travel

Card

MDL

Business Debit Other Embossed

MUS

Prepaid MasterCard Unembossed

U.S.

MDM

Middle Market Fleet Card

MWB

World MasterCard for Business

MDN

Middle Market Purchasing Card

MWE

MasterCard World Elite

MDO

Debit MasterCard Other

MWO

MasterCard Corporate World

MDP

Debit MasterCard Platinum

PRO

Proprietary Card

MDQ

Middle Market Corporate Card

PVL

Private label card

MDS

Debit MasterCard

SAG

Gold MasterCard Salary-Immediate

Debit

MDT

MasterCard Business Debit

SAL

Standard Maestro Salary

MDW

MasterCard Black Debit/World Elite

Debit MasterCard

SAP

Platinum MasterCard SalaryImmediate Debit

MEB

MasterCard Executive BusinessCard

Card

SAS

Standard MasterCard SalaryImmediate Debit

MEC

MasterCard Electronic Commercial

SOS

Standard MasterCard SocialImmediate Debit

MEF

MasterCard Electronic Payment

Account

SUR

Prepaid MasterCard Unembossed

Outside U.S.

MEO

MasterCard Corporate Executive

Card

TBE

Business-Immediate Debit

MET

Titanium Debit MasterCard

TCB

MasterCard Business CardImmediate Debit

MGF

MasterCard Government
Commercial Card

TCF

MasterCard Fleet Card-Immediate

Debit

MHA

MasterCard Healthcare Prepaid

Non-tax

TCO

MasterCard Corporate-Immediate
Debit

MHB

MasterCard HSA Substantiated

TCP

MasterCard Purchasing CardImmediate Debit

MHC

MasterCard Healthcare Credit Nonsubstantiated

TDN

Middle Market MasterCard

Purchasing Card-Immediate Debit

MHH

MasterCard HSA Non-substantiated

TEB

MasterCard Executive BusinessCard

Card-Immediate Debit

MIA

MasterCard Unembossed Prepaid

Student Card

TEC

MasterCard Electronic CommercialImmediate Debit

MIK

MasterCard Electronic Consumer

Prepaid Non U.S. Student Card

TEO

MasterCard Corporate Executive

Card-Immediate Debit

MIL

MasterCard Unembossed Prepaid

Non U.S. Student Card

TLA

MasterCard Central Travel Solutions

Air-Immediate Debit

Credit Card Services Using the Simple Order API | January 2016

382

Appendix N

Table 72

Product IDs

MasterCard Product IDs (Continued)

Value

Description

Value

Description

MIP

MasterCard Debit Prepaid Student

Card

TNF

MasterCard Public Sector

Commercial Card-Immediate Debit

MLA

MasterCard Central Travel Solutions

Air

TPB

MasterCard Preferred Business

Card-Immediate Debit

MLC

MasterCard Micro-Business Card

TPC

MasterCard Professional CardImmediate Debit

MLD

MasterCard Distribution Card

WDR

World Debit MasterCard Rewards

MLL

MasterCard Central Travel Solutions

Land

WMR

World MasterCard Rewards

Credit Card Services Using the Simple Order API | January 2016

383

APPENDIX

Reason Codes

The following table describes the reason codes returned by the Simple Order API for the
credit card services. For a description of replies, decisions, and reason codes, see the
information about handling replies in Getting Started with CyberSource Advanced for the
Simple Order API.
Because CyberSource can add reply fields and reason codes at any time:

You must parse the reply data according to the names of the fields
instead of the field order in the reply. For more information about parsing
reply fields, see the documentation for your client.

Your error handler should be able to process new reason codes without
problems.

Your error handler should use the decision field to determine the result if
it receives a reason code that it does not recognize.

Important

Table 73

Reason Codes

Reason
Code

Description

100

Successful transaction.
AIBMS: If ccAuthReply_processorResponse is 08, you can accept the
transaction if the customer provides you with identification.

101

The request is missing one or more required fields.

Possible action: see the reply fields missingField_0...N for which fields are
missing. Resend the request with the complete information. For information about
missing or invalid fields, see Getting Started with CyberSource Advanced for the
Simple Order API.

102

One or more fields in the request contains invalid data.

Possible action: see the reply fields invalidField_0...N for which fields are invalid.
Resend the request with the correct information. For information about missing or
invalid fields, see Getting Started with CyberSource Advanced for the Simple
Order API.

Credit Card Services Using the Simple Order API | January 2016

384

Appendix O

Table 73

Reason Codes

Reason Codes (Continued)

Reason
Code

Description

104

The merchant reference code for this authorization request matches the merchant
reference code of another authorization request that you sent within the past 15
minutes.
Possible action: Resend the request with a unique merchant reference code.

110

Only a partial amount was approved.

Possible action: see "Partial Authorizations," page 88.

150

General system failure.

See the documentation for your CyberSource client for information about handling
retries in the case of system errors.

151

The request was received but there was a server timeout. This error does not
include timeouts between the client and the server.
Possible action: To avoid duplicating the transaction, do not resend the request
until you have reviewed the transaction status in the Business Center. See the
documentation for your CyberSource client for information about handling retries in
the case of system errors.

152

The request was received, but a service did not finish running in time.
Possible action: To avoid duplicating the transaction, do not resend the request
until you have reviewed the transaction status in the Business Center. See the
documentation for your CyberSource client for information about handling retries in
the case of system errors.

200

The authorization request was approved by the issuing bank but declined by
CyberSource because it did not pass the Address Verification System (AVS)
check.
Possible action: You can capture the authorization, but consider reviewing the
order for the possibility of fraud.

201

The issuing bank has questions about the request. You do not receive an
authorization code programmatically, but you might receive one verbally by calling
the processor.
Possible action: Call your processor to possibly receive a verbal authorization. For
contact phone numbers, refer to your merchant bank information.

202

Expired card. You might also receive this value if the expiration date you provided
does not match the date the issuing bank has on file.
Possible action: Request a different card or other form of payment.

203

General decline of the card. No other information was provided by the issuing
bank.
Possible action: Request a different card or other form of payment.

204

Insufficient funds in the account.

Possible action: Request a different card or other form of payment.

Credit Card Services Using the Simple Order API | January 2016

385

Appendix O

Table 73

Reason Codes

Reason Codes (Continued)

Reason
Code

Description

205

Stolen or lost card.

Possible action: Review this transaction manually to ensure that you submitted the
correct information.

207

Issuing bank unavailable.

Possible action: Wait a few minutes and resend the request.

208

Inactive card or card not authorized for card-not-present transactions.

Possible action: Request a different card or other form of payment.

209

CVN did not match.

Possible action: Request a different card or other form of payment.

210

The card has reached the credit limit.

Possible action: Request a different card or other form of payment.

211

Invalid CVN.
Possible action: Request a different card or other form of payment.

221

The customer matched an entry on the processors negative file.

Possible action: Review the order and contact the payment processor.

230

The authorization request was approved by the issuing bank but declined by
CyberSource because it did not pass the CVN check.
Possible action: You can capture the authorization, but consider reviewing the
order for the possibility of fraud.

231

Invalid account number.

Possible action: Request a different card or other form of payment.

232

The card type is not accepted by the payment processor.

Possible action: Contact your merchant bank to confirm that your account is set up
to receive the card in question.

233

General decline by the processor.

Possible action: Request a different card or other form of payment.

234

There is a problem with the information in your CyberSource account.

Possible action: Do not resend the request. Contact CyberSource Customer
Support to correct the information in your account.

235

The requested capture amount exceeds the originally authorized amount.

Possible action: Issue a new authorization and capture request for the new
amount.

236

Processor failure.
Possible action: Wait a few minutes and resend the request.

237

The authorization has already been reversed.

Possible action: No action required.

Credit Card Services Using the Simple Order API | January 2016

386

Appendix O

Table 73

Reason Codes

Reason Codes (Continued)

Reason
Code

Description

238

The authorization has already been captured.

Possible action: No action required.

239

The requested transaction amount must match the previous transaction amount.
Possible action: Correct the amount and resend the request.

240

The card type sent is invalid or does not correlate with the credit card number.
Possible action: Confirm that the card type correlates with the credit card number
specified in the request, then resend the request.

241

The request ID is invalid.

Possible action: Request a new authorization, and if successful, proceed with the
capture.

242

You requested a capture, but there is no corresponding, unused authorization

record. Occurs if there was not a previously successful authorization request or if
the previously successful authorization has already been used by another capture
request.
Possible action: Request a new authorization, and if successful, proceed with the
capture.

243

The transaction has already been settled or reversed.

Possible action: No action required.

246

One of the following:

The capture or credit is not voidable because the capture or credit information
has already been submitted to your processor.

- or

You requested a void for a type of transaction that cannot be voided.

Possible action: No action required.

247

You requested a credit for a capture that was previously voided.

Possible action: No action required.

250

The request was received, but there was a timeout at the payment processor.
Possible action: To avoid duplicating the transaction, do not resend the request
until you have reviewed the transaction status in the Business Center.

254

Stand-alone credits are not allowed.

Possible action: Submit a follow-on credit by including a request ID in the credit
request. A follow-on credit must be requested within 60 days of the authorization.
To process stand-alone credits, contact your CyberSource account representative
to find out if your processor supports stand-alone credits.

Credit Card Services Using the Simple Order API | January 2016

387

APPENDIX

Verified by Visa
Response Codes

The Verified by Visa response code is returned in ccAuthReply_cavvResponseCode in

the reply message for an authorization request. See "Verified by Visa," page 171, for a
description of Verified by Visa.
Table 74

Verified by Visa Response Codes

Response
Code

Description

CAVV not validated because erroneous data was submitted.

CAVV failed validation and authentication.

CAVV passed validation and authentication.

CAVV passed the validation attempt.

CAVV failed the validation attempt.

CAVV not validated because the issuer does not participate.

CAVV failed the validation attempt and the issuer is available.

CAVV passed the validation attempt and the issuer is available.

CAVV failed the validation attempt and the issuer is not available.

CAVV passed the validation attempt and the issuer is not available.

CAVV passed the validation with information only; no liability shift.

CAVV attempted but not validated; issuer did not return CAVV code.

CAVV not validated or authenticated; issuer did not return CAVV code.

Invalid security data.

Issuer does not participate or 3-D secure data was not used.

99

An unknown value was returned from the processor.

Credit Card Services Using the Simple Order API | January 2016

388

APPENDIX

Values for the Wallet Type

Field

The wallet type is sent in the wallet_type field in authorization requests and credit
requests. Possible value are:

101: MasterPass remote payment. The cardholder created the wallet by manually
interacting with a customer-controlled device such as a computer, tablet, or phone.
This value is supported only for MasterPass transactions on Chase Paymentech
Solutions and CyberSource through VisaNet.

102: MasterPass remote near field communication (NFC) payment. The cardholder
created the wallet by tapping a PayPass card or consumer-controlled device at a
contactless card reader. This value is supported only for card-present MasterPass
transactions on CyberSource through VisaNet.

SDW: Staged digital wallet. An issuer or operator created the wallet. This value is
supported only for MasterPass transactions on Chase Paymentech Solutions.

VCIND: Visa Checkout payment. This value is supported only on CyberSource

through VisaNet.

For additional information about the wallet_type field, see Appendix A, "API Fields," on
page 216.

Credit Card Services Using the Simple Order API | January 2016

389

INDEX

Index
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A
AAV 177
AAV+ 77
account authentication values 177
account balances 94
acquirers 27
acquiring banks 22
additional amounts 99
Address Verification System
AAV+ 77
codes 355
described 72
Enhanced 77
and recurring payments 193
relaxed requirements 75
aggregator 100
aggregator support 100
AIBMS
authorizations 31
AVS 72
captures 49
card types 28
credits 64
CVNs 80
forced captures 121
full authorization reversals 40
MasterCard SecureCode 177
merchant descriptors 132
multiple partial captures 52
recurring payments 189
verbal authorizations 84
Verified by Visa 171
voids 70
airline data 106

Credit Card Services Using the Simple Order API | January 2016

American Express Brighton

authorizations 31
AVS 72
captures 49
card types 28
credits 64
CVNs 80
recurring payments 189
verbal authorizations 84
voids 70
American Express Direct
AAV+ 77
additional amounts 99
American Express SafeKey 183
Apple Pay 106
authorization only 110
authorizations 31
AVS 72
AVS, enhanced 77
balance responses 95
captures 49
card types 28
credits 64
CVNs 80
Electronic Verification 78
forced captures 121
full authorization reversals 40
merchant descriptors 133
partial authorizations 89
recurring payments 189
relaxed requirements 75
verbal authorizations 84
voids 70
zero amount authorizations 209
American Express installment payments 123
American Express SafeKey
described 171
response codes 354

390

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Apple Pay 106

automatic authorization reversals 61

Asia, Middle East, and Africa Gateway

authorizations 31
captures 49
card types 28
credits 64
CVNs 80
examples, name-value pairs 306
examples, XML 325
forced captures 121
MasterCard SecureCode 177
multiple partial captures 52
recurring payments 189
verbal authorizations 84
Verified by Visa 171
voids 70

automatic interchange optimization 62

Atos
authorization refresh 63
authorizations 31
AVS 72
captures 49
card types 28
credits 64
CVN 80
MasterCard SecureCode 177
quasi-cash 186
recurring payments 189
Verified by Visa 171
authorization only 110
authorization refresh 63
authorization reversals
alternate methods 367
full 39
partial 61
authorizations
described 31
examples, name-value pairs 303
examples, XML 320
expiration of 366
for zero amounts 209
partial 88
verbal 84
See also ccAuthService

Credit Card Services Using the Simple Order API | January 2016

AVS
AAV+ 77
codes 355
described 72
Enhanced 77
and recurring payments 193
relaxed requirements 75
AVS only 209

B
balance inquiries 110
balance responses 94
Barclays
authorizations 31
AVS 72
captures 49
card types 28
cash advances 113
credits 64
CVNs 80
final authorization indicator 120
full authorization reversals 41
MasterCard SecureCode 177
multiple partial captures 53
recipients 187
recurring payments 189
verbal authorizations 84
Verified by Visa 171
voids 70
zero amount authorizations 209
Bill Me Later 111
Bill Payment program (Visa) 207
business cards 130
business rules 76

391

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

C
captures
after void 71
described 49
examples, name-value pairs 303
examples, XML 320
multiple 52
See also ccCaptureService

ccCaptureService
described 49
requesting 50
required fields 51
ccCreditService
described 64
requesting 65
required fields 65, 66

card-not-present transactions 20

CCS (CAFIS)
authorizations 31
captures 49
card types 28
credits 64
CVNs 80
forced captures 121
full authorization reversals 41
Japanese payment options 128
JCB J/Secure 177
MasterCard SecureCode 177
multiple partial captures 53
verbal authorizations 84
Verified by Visa 171
voids 70

card-present data 111

characters, special 216

card-present transactions 20

chargebacks
described 23
fees 23
for Global Collect 369
reason codes for MasterCard 373
reason codes for Visa 372

card associations 24
card identification digits. See CVNs
card type indicators 112
Card Validation Code. See CVNs
card validation code. See CVNs
card verification numbers. See CVNs
cardholder authentication verification values
API fields 238
for American Express SafeKey 184
for JCB J/Secure 173
for Verified by Visa 173
Cardnet. See LloydsTSB Cardnet

cash advances 113

CAVV
API fields 238
for American Express SafeKey 184
for JCB J/Secure 173
for Verified by Visa 173
ccAuthReversalService
described 39
requesting 48
required fields 48
ccAuthService
described 31
requesting 33
required fields 34

Credit Card Services Using the Simple Order API | January 2016

392

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Chase Paymentech Solutions

Apple Pay 106
authorizations 31
automatic authorization reversals 61
AVS 72
balance responses 95
captures 49
card type indicators (CTIs) 112
card types 28
credits 64
CVNs 80
encoded account numbers 119
final authorization indicator 120
full authorization reversals 41
installment payments 123
MasterCard SecureCode 177
MasterPass 130
merchant descriptors 136
merchant-initiated reversals 168
multi-currency 170
multiple partial captures 53
partial authorizations 89
recurring payments 189
relaxed requirements 75
verbal authorizations 84
Verified by Visa 171
Visa Bill Payments 207
voids 70
zero amount authorizations 209
China processing 30
CID. See CVNs

Cielo
authorizations 31
AVS 73
captures 49
card types 28
credits 64
CVNs 80
examples, name-value pairs 307
examples, XML 327
full authorization reversals 41
installment payments 123
MasterCard SecureCode 177
merchant descriptors 139
recurring payments 189
Verified by Visa 171
voids 70
Citibank India 28
commerce indicators
API fields 239
for American Express SafeKey 184
for JCB J/Secure 174
for MasterCard SecureCode 180
for Verified by Visa 174
values 359
consumer banks 23
corporate cards 130
credit card associations 24
credit card encryption 119
credit card numbers for testing 214
credits
described 64
See also ccCreditService
CTIs 112
customer profiles 185
CVC2. See CVNs
CVNs
and recurring payments 189
codes 360
described 80
CVV2. See CVNs

Credit Card Services Using the Simple Order API | January 2016

393

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

CyberSource Latin American Processing

installment payments 123
CyberSource Latin American Processing. See
Latin American Processing
CyberSource through VisaNet
American Express SafeKey 183
automatic authorization reversals 61
AVS 73
balance responses 95
card types 29
CVNs 81
final authorization indicator 120
forced captures 121
full authorization reversals 42
installment payments 124
interchange optimization 62
JCB J/Secure 177
MasterCard SecureCode 178
MasterPass 130
merchant descriptors 140
partial authorizations 89
recurring payments 190
relaxed requirements 75
split shipments 199
verbal authorizations 84
Verified by Visa 172
zero amount authorizations 209

D
data types 216

E
E4X 170
ECI
API fields 239
for American Express SafeKey 184
for JCB J/Secure 174
for MasterCard SecureCode 180
for Verified by Visa 174
values 359
Elavon
AVS 73
card types 29
CVNs 81
final authorization indicator 120
full authorization reversals 42
MasterCard SecureCode 178
merchant descriptors 146
recipients 187
recurring payments 190
relaxed requirements 75
verbal authorizations 84
Verified by Visa 172
zero amount authorizations 210
electronic commerce indicators
API fields 239
for American Express SafeKey 184
for JCB J/Secure 174
for MasterCard SecureCode 180
for Verified by Visa 174

debit cards 88

Electronic Verification
described 78
response codes 365

Debt Repayment program (Visa) 208

encoded account numbers 119

descriptors 131

encryption 119

digital wallets 389

Enhanced AVS 77

Diners Club installment payments 123

errors
reason codes 384
simulating during testing 214

date and time formats 285

Discover installment payments 123

dynamic currency conversions
First Data, description 114

Credit Card Services Using the Simple Order API | January 2016

EV
described 78
response codes 365

394

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

example code 303

exchange rates 170
expiration dates
for recurring payments 189
relaxed requirements 75
expiration of authorizations 366

F
FAQ 366
FDC Compass
Apple Pay 106
authorizations 31
automatic authorization reversals 61
AVS 74
balance responses 95
captures 49
card types 29
credits 64
CVNs 81
full authorization reversals 42
installment payments 124
MasterCard SecureCode 178
merchant descriptors 147
multiple partial captures 56
partial authorizations 89
recurring payments 191
relaxed requirements 75
verbal authorizations 84
Verified by Visa 172
Visa Bill Payments 207
voids 70
zero amount authorizations 210

Credit Card Services Using the Simple Order API | January 2016

FDC Germany
authorizations 31
AVS 74
captures 49
card types 29
credits 64
CVNs 81
full authorization reversals 43
MasterCard SecureCode 178
recurring payments 191
verbal authorizations 85
Verified by Visa 172
voids 70
FDC Nashville Global
American Express SafeKey 183
Apple Pay 106
authorizations 31
automatic authorization reversals 61
AVS 74
balance responses 95
captures 49
card types 29
credits 64
CVNs 81
dynamic currency conversion 114
Electronic Verification 78
forced captures 121
full authorization reversals 43
installment payments 124
MasterCard SecureCode 178
merchant descriptors 151
merchant-initiated reversals 168
partial authorizations 89
recurring payments 191
relaxed requirements 75
verbal authorizations 85
Verified by Visa 172
Visa Bill Payments 207
Visa Debt Repayments 208
voids 70
zero amount authorizations 210

395

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

FDI Australia
authorizations 31
captures 49
card types 29
credits 64
CVNs 81
MasterCard SecureCode 178
recurring payments 191
relaxed requirements 75
verbal authorizations 85
Verified by Visa 172
voids 70
FDMS Nashville
authorizations 31
automatic authorization reversals 61
AVS 74
balance responses 95
captures 49
card types 29
credits 64
CVNs 81
forced captures 121
full authorization reversals 43
installment payments 124
MasterCard SecureCode 178
partial authorizations 89
recurring payments 191
verbal authorizations 85
Verified by Visa 172
Visa Bill Payments 207
Visa Debt Repayments 208
voids 70
zero amount authorizations 210

Credit Card Services Using the Simple Order API | January 2016

FDMS South
authorizations 31
automatic authorization reversals 61
AVS 74
balance responses 96
captures 49
card types 29
credits 64
CVNs 81
dynamic currency conversion 114
forced captures 122
full authorization reversals 44
installment payments 124
MasterCard SecureCode 178
merchant descriptors 156
partial authorizations 89
recurring payments 191
relaxed requirements 75
verbal authorizations 85
Verified by Visa 172
voids 70
zero amount authorizations 210
follow-on credits 64
forced captures 121
foreign exchange service 170
fraud 366
full authorization reversals
described 39
See also ccAuthReversalService

396

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

G
Global Collect
authorizations 31
captures 49
card types 29
chargebacks 369
credits 64
CVNs 81
JCB J/Secure 177
MasterCard SecureCode 178
merchant descriptors 157
recurring payments 191
relaxed requirements 75
representments 371
requests for information 369
retrieval requests 369
transaction reversals 369
Verified by Visa 172
GMT 285

GPN
Apple Pay 106
authorizations 31
automatic authorization reversals 61
AVS 74
balance responses 96
captures 49
card types 29
credits 64
CVNs 81
forced captures 122
full authorization reversals 44
interchange optimization 62
MasterCard SecureCode 178
merchant descriptors 158
multiple partial captures 57
partial authorizations 89
product IDs 379
quasi-cash 186
recurring payments 191
relaxed requirements 75
split shipments 199
verbal authorizations 85
Verified by Visa 172
Visa Bill Payments 207
Visa Debt Repayments 208
voids 70
zero amount authorizations 210
guaranteed exchange rates 170

Credit Card Services Using the Simple Order API | January 2016

397

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

HBoS
authorizations 31
AVS 74
captures 49
card types 29
credits 64
CVNs 81
final authorization indicator 120
full authorization reversals 45
MasterCard SecureCode 178
recipients 187
recurring payments 191
verbal authorizations 85
Verified by Visa 172
voids 70

J/Secure 171

HSBC
authorizations 31
AVS 74
captures 49
card types 30
credits 64
CVNs 81
final authorization indicator 120
MasterCard SecureCode 178
multiple partial captures 57
recurring payments 191
verbal authorizations 85
Verified by Visa 172
voids 70
zero amount authorizations 211

I
installment payments
American Express 123
Discover Network 123
Visa 123

Japanese payment options 128

JCB installment payments 123
JCB J/Secure 171
JCN Gateway
American Express SafeKey 183
card types 30
CVNs 82
forced captures 122
full authorization reversals 45
Japanese payment options 128
JCB J/Secure 177
MasterCard SecureCode 178
multiple partial captures 58
verbal authorizations 85
Verified by Visa 172
zero amount authorizations 211

L
Latin American Processing
authorizations 31
AVS 73
captures 49
card types 29
credits 64
CVNs 81
examples, name-value pairs 310
examples, XML 333
MasterCard SecureCode 178
Verified by Visa 171
voids 70
Level II 130
Level III 130

interchange fees 22
interchange optimization 62
issuer encryption 119
issuing banks 23

Credit Card Services Using the Simple Order API | January 2016

398

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Litle
authorizations 31
automatic authorization reversals 61
AVS 74
balance responses 96
captures 49
card types 30
credits 64
CVNs 82
Electronic Verification 78
full authorization reversals 45
installment payments 124
MasterCard SecureCode 178
merchant descriptors 159
multiple partial captures 58
partial authorizations 89
recurring payments 191
report groups 197
verbal authorizations 85
Verified by Visa 172
voids 70
zero amount authorizations 211
Lloyds-OmniPay
authorizations 31
AVS 74
captures 49
card types 30
credits 64
CVNs 82
final authorization indicator 120
full authorization reversals 45
recurring payments 191
verbal authorizations 85
voids 70

LloydsTSB Cardnet
authorizations 31
AVS 74
captures 49
card types 30
cash advances 113
credits 64
CVNs 82
final authorization indicator 120
full authorization reversals 45
MasterCard SecureCode 178
recipients 187
recurring payments 191
verbal authorizations 85
Verified by Visa 172
voids 70
Lynk
authorizations 31
AVS 74
captures 49
card types 30
credits 64
CVNs 82
verbal authorizations 85

M
Maestro (UK Domestic) cards 97
MasterCard
MasterPass 389
payment card company 24
PayPass 389
SecureCode 171
MasterPass 130, 389
merchant banks 22
merchant descriptors 131
merchant-initiated reversals 168
micropayments 169

Credit Card Services Using the Simple Order API | January 2016

399

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Moneris
Apple Pay 106
authorizations 31
AVS 74
captures 49
card types 30
credits 64
CVNs 82
full authorization reversals 46
MasterCard SecureCode 178
recurring payments 191
verbal authorizations 85
Verified by Visa 172
voids 70
zero amount authorizations 211
multi-currency 170
multiple captures 52

OmniPay. See Lloyds-OmniPay

OmniPay-Ireland
authorizations 31
automatic authorization reversals 61
AVS 74
captures 49
card types 30
credits 64
CVNs 82
final authorization indicator 120
installment payments 125
MasterCard SecureCode 178
merchant descriptors 164
multiple partial captures 59
recurring payments 191
verbal authorizations 85
Verified by Visa 172
Visa Bill Payments 207
voids 70
zero amount authorizations 211

network tokenization 185

open to buy 31

network transaction identifiers 376

order tracking 25

OmniPay Direct
Apple Pay 106
authorizations 31
AVS 74
captures 49
card types 30
credits 64
CVNs 82
final authorization indicator 120
full authorization reversals 46
MasterCard SecureCode 178
MasterPass 130
merchant descriptors 162
multiple partial captures 59
recurring payments 191
relaxed requirements 75
Verified by Visa 172
voids 70
zero amount authorizations 211

partial authorization reversals 61

Credit Card Services Using the Simple Order API | January 2016

partial authorizations
described 88
examples, name-value pairs 311
examples, XML 334
partial captures 52
partial shipments
described 199
examples, name-value pairs 313
examples, XML 338
PayEase China Processing 30
payer authentication 171
payment aggregator 100
payment card companies 24
payment network tokenization 185
payment network transaction identifiers 376

400

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

payment processors 27

recurring payments 189

payment tokenization 185

recurring profiles 188

Paymentech. See Chase Paymentech Solutions

recurring transactions 189

PayPass 389

refunds
described 64
See also ccCreditService

PINless debit cards 18

POS transactions 111
prepaid cards 88
private label cards 18
processors 27
procurement cards 130
product codes 378
product IDs 379
profiles 185
purchasing cards 130

Repayment program (Visa) 208

replacement dates for recurring payments 189
report groups 197
representments 371
request fields 217
request IDs 25
requests for information 369
retail POS transactions 111
retrieval requests 369

Q
quasi-cash 186

reversals, authorization
alternate methods 367
full 39
partial 61
reversals, merchant-initiated 168

RBS WorldPay Atlanta

authorizations 31
AVS 74
captures 49
card types 30
credits 64
CVNs 82
full authorization reversals 46
MasterCard SecureCode 178
recurring payments 191
verbal authorizations 85
Verified by Visa 172
voids 70
zero amount authorizations 211

reversals, transaction
described 23
fees 23
for Global Collect 369
reason codes for MasterCard 373
reason codes for Visa 372

reason codes 384

secure storage 185

recipients 187

SecureCode 171

reconciliation IDs 25

service fees 199

recurring billing 188

settlements. See captures and credits

recurring indicators 189

soft descriptors 131

Credit Card Services Using the Simple Order API | January 2016

S
SafeKey
described 171
response codes 354
sample code 303
secure data 185

401

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

special characters 216

split dial/route 121
split shipments
described 199
examples, name-value pairs 313
examples. XML 338
stand-alone credits 65
Streamline
authorizations 31
AVS 74
captures 49
card types 30
credits 64
CVNs 82
full authorization reversals 47
MasterCard SecureCode 178
merchant descriptors 166
recipients 187
recurring payments 191
Verified by Visa 172
voids 70
zero amount authorizations 212
subscriptions 188
Switch cards 97

T
TAA fields 131
testing your system 213
time formats 285
tokenization
payment network tokenization 185
payment tokenization 185
Transaction Advice Addendum fields 131
transaction identifiers
API field 242
for American Express SafeKey 184
for MasterCard SecureCode 183
for Verified by Visa 176
JCB J/Secure 176

Credit Card Services Using the Simple Order API | January 2016

transaction reversals
described 23
fees 23
for Global Collect 369
reason codes for MasterCard 373
reason codes for Visa 372
TSYS Acquiring Solutions
Apple Pay 106
authorizations 31
automatic authorization reversals 61
AVS 74
balance responses 96
captures 49
card types 30
credits 64
CVNs 82
Electronic Verification 78
forced captures 122
full authorization reversals 47
installment payments 125
JCB J/Secure 177
MasterCard SecureCode 178
merchant descriptors 167
multiple partial captures 60
partial authorizations 89
quasi-cash 186
recurring payments 191
verbal authorizations 85
Verified by Visa 172
Visa Bill Payments 207
voids 70
zero amount authorizations 212
Type II cards 130

U
UATP
authorizations 31
captures 49
card types 30
credits 64
verbal authorizations 85
voids 70

402

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

UCAF
API fields 280
for MasterCard SecureCode 182
universal cardholder authentication fields
API fields 280
for MasterCard SecureCode 182

W
wallets 389

X
XID
API field 242
for American Express SafeKey 184
for JCB J/Secure 176
for MasterCard SecureCode 183
for Verified by Visa 176

UTC (in authorization reply) 285

V
verbal authorizations 84
Verified by Visa
described 171
response codes 388
Visa
Bill Payment program 207
Debt Repayments 208
installment payments 123
payment card company 24
Verified by Visa response codes 388
Verified by Visa, described 171

Z
zero amount authorizations 209

Visa Checkout 207

Vital. See TSYS Acquiring Solutions
voidService
described 70
requesting 71
required fields 71

Credit Card Services Using the Simple Order API | January 2016

403