You are on page 1of 338

CyberSource Credit Card Services

Implementation Guide

Simple Order API


SCMP API
June 2009
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-965-6000 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.
For Customer Support, see the CyberSource Knowledgebase.

Copyright
© 2009 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 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 CyberSource logo, SmartCert, and PaylinX are registered trademarks of CyberSource
Corporation in the U.S. and other countries. The Power of Payment, CyberSource Payment Manager,
CyberSource Risk Manager, CyberSource Decision Manager, and CyberSource Connect are trademarks and/or
service marks of CyberSource Corporation. All other brands and product names are trademarks or registered
trademarks of their respective owners.

ii CyberSource Corporation
Contents

Documentation Changes and Enhancements xi

Chapter 1
Introduction to the Credit Card Services 1
Overview of Credit Card Services 1
Types of Cards 2
MasterCard and Diners Club Alliance 3
CyberSource Global Payment Service 3
Card-Present and Card-Not-Present Transactions 4
The Payment Industry 4
Acquiring (Merchant) Banks 4
Issuing (Consumer) Banks 5
Credit Card Associations 5
Payment Processors 6
Processing a Credit Card Payment 9
Authorizing a Credit Card Payment 9
Reversing an Authorization 12
Capturing an Authorization 13
Crediting a Payment 17
Voiding a Capture or Credit 20

Chapter 2
Getting Started 21

Credit Card Services Implementation Guide • June 2009 iii


Chapter 3
Basic Credit Card Features 23
Address Verification Service 23
Standard AVS 24
Enhanced AVS 26
Automated Address Verification Plus 26
Extended AVS 26
Additional Information 26
Card Verification Numbers 27
Additional Information 29
Verbal Authorizations 29
Additional Information 31
Reconciliation 31

Chapter 4
Payment Processing with the Simple Order API 33
Introduction to the API 33
Multi-Byte Character Support for the ICS Services 34
Simple Order API Clients 34
Which Version of the API to Use 34
Using Name-Value Pairs 35
Using XML 35
Working with Request Tokens 38
About Requests 40
Using Items or a Grand Total in the Request 40
Requesting a Follow-on Service 42
Handling Replies 43
Tracking Orders 46
Authorizing a Credit Card Payment 47
Address Verification Service 47
Card Verification Numbers 48
Verbal Authorizations: The Authorization 50
Required Fields for Requesting an Authorization 50
Reversing an Authorization 51
Required Fields for Requesting a Full Authorization Reversal 52
Capturing an Authorization 52
Verbal Authorizations: The Capture 53
Reconciliation 54
Required Fields for Requesting a Capture 54
Crediting a Payment 55
Follow-On Credits 55
Stand-Alone Credits 56
Reconciliation 56
Required Fields for Requesting a Credit 56
Voiding a Capture or Credit 57
Required Fields for Requesting a Void 58

iv CyberSource Corporation
Chapter 5
Payment Processing with the SCMP API 59
Introduction to the API 59
Multi-Byte Character Support for the ICS Services 60
SCMP API Clients 60
Working with Request Tokens 60
About Requests 62
Using Offers or a Grand Total in the Request 62
Requesting a Follow-on Service 65
Handling Replies 65
Tracking Orders 67
Authorizing a Credit Card Payment 68
Address Verification Service 69
Card Verification Numbers 70
Verbal Authorizations: The Authorization 71
Required Fields for Requesting an Authorization 71
Reversing an Authorization 72
Required Fields for Requesting a Full Authorization Reversal 73
Capturing an Authorization 73
Verbal Authorizations: The Capture 74
Reconciliation 75
Required Fields for Requesting a Capture 75
Crediting a Payment 76
Follow-On Credits 77
Stand-Alone Credits 77
Reconciliation 77
Required Fields for Requesting a Credit 78
Voiding a Capture or Credit 79
Required Fields for Requesting a Void 79

Chapter 6
Optional Features for the Simple Order API 81
$0 Authorizations 82
Airline Data 82
American Express Prepaid Cards 83
AVS Only 83
Bill Me Later 83
Bill Payments with Visa 84
Cash Advances 85
Coupons 86
How Coupons are Processed 86
Coupon Constraints 87
Customer Profiles 87

Credit Card Services Implementation Guide • June 2009 v


Dynamic Currency Conversion (DCC) 88
Requirements and Limitations 89
Terminology 90
Procedure 91
Additional Information 94
Encoded Account Numbers 95
Forced Captures 95
Gift Cards 96
Guaranteed Exchange Rates 96
Japanese Payment Options 96
JCB J/Secure 97
Level II Data 98
Level III Data 98
Maestro (UK Domestic) and Solo Cards 99
MasterCard SecureCode 99
Merchant Descriptors 100
American Express Direct 101
American Express Phoenix 101
Chase Paymentech Solutions 102
CyberSource Global Payment Service 103
FDI Global 104
FDMS South 105
GPN 105
OmniPay-Ireland 105
Micropayments 106
Multi-Currency Service 106
Payer Authentication 107
Verified by Visa 107
JCB J/Secure 113
MasterCard SecureCode 113
POS Transactions 118
Prepaid Cards 118
Recurring Billing 118
Recurring Payments 119
AVS and Recurring Payments 121
Card Verification Number and Recurring Payments 121
Replacement Expiration Dates for Recurring Payments 121
Recurring Profiles 122
Retail POS Data 123
Secure Data 123
Soft Descriptors 123
Split Dial/Route 123
Subscriptions 123
Switch and Solo Cards 123
Type II Cards 123
Verbal Authorizations 123
Verified by Visa 124

vi CyberSource Corporation
Chapter 7
Optional Features for the SCMP API 125
$0 Authorizations 126
Airline Data 126
American Express Prepaid Cards 127
AVS Only 127
Bill Me Later 127
Bill Payments with Visa 128
Cash Advances 129
Coupons 130
How Coupons are Processed 130
Coupon Constraints 131
Customer Profiles 131
Dynamic Currency Conversion (DCC) 132
Requirements and Limitations 133
Terminology 134
Procedure 135
Additional Information 138
Encoded Account Numbers 138
Forced Captures 139
Gift Cards 139
Guaranteed Exchange Rates 139
Japanese Payment Options 140
JCB J/Secure 141
Level II Data 142
Level III Data 142
Maestro (UK Domestic) and Solo Cards 143
MasterCard SecureCode 143
Merchant Descriptors 144
American Express Direct 145
American Express Phoenix 145
Chase Paymentech Solutions 146
CyberSource Global Payment Service 147
FDI Global 148
FDMS South 149
GPN 149
OmniPay-Ireland 149
Micropayments 150
Multi-Currency Service 150
Payer Authentication 151
Verified by Visa 151
JCB J/Secure 157
MasterCard SecureCode 157
POS Transactions 162
Prepaid Cards 162
Recurring Billing 162

Credit Card Services Implementation Guide • June 2009 vii


Recurring Payments 163
AVS and Recurring Payments 165
Card Verification Number and Recurring Payments 165
Replacement Expiration Dates for Recurring Payments 165
Recurring Profiles 166
Retail POS Data 167
Secure Data 167
Soft Descriptors 167
Split Dial/Route 167
Subscriptions 167
Switch and Solo Cards 167
Type II Cards 167
Verbal Authorizations 167
Verified by Visa 168

Chapter 8
Testing Credit Card Services 169
Requirements for Testing 169
Testing the Services 170
Using Amounts to Simulate Errors 171
Testing American Express Card Verification 171
Going Live 171

Appendix A
Fields for the Simple Order API 173
Formatting Restrictions 173
Data Type Definitions 173
Request Fields 174
Reply Fields 203

Appendix B
Fields for the SCMP API 213
Formatting Restrictions 213
Data Type Definitions 213
Request-Level Fields 214
Offer-Level Fields 237
Reply Fields 240

viii CyberSource Corporation


Appendix C
Examples for the Simple Order API 251
Name-Value Pair Examples 251
Basic Credit Card Examples 251
DCC Examples 253
Asia-Mideast Processing Examples 257
XML Examples 259
Basic Credit Card Examples 259
DCC Examples 262
Asia-Mideast Processing Examples 270

Appendix D
Examples for the SCMP API 273
Basic Credit Card Examples 273
DCC Examples 275
Asia-Mideast Processing Examples 281

Appendix E
Reason Codes for the Simple Order API 283

Appendix F
Reply Flags for the SCMP API 287

Appendix G
Address Verification Service Codes 291

Appendix H
Card Verification Number Codes 295

Appendix I
Product Codes 297

Appendix J
Bank Card Reversals for the Global Payment Service 299
Request for Information 299
Responding to a Request for Information 300
Chargebacks 301
Representments 302
Chargeback Reason Codes for Visa 303
Chargeback Reason Codes for MasterCard 304
Sample Request for Information 305

Credit Card Services Implementation Guide • June 2009 ix


Appendix K
Frequently Asked Questions 307

Index 311

x CyberSource Corporation
Documentation Changes and Enhancements

The following table lists changes made in recent releases of this document.

Month of
Changes
Release

June 2009 Made the following updates for Chase Paymentech Solutions:
• Added support for full authorization reversals: “Reversing an Authorization” on page 12.
• Added support for $0 authorizations: 
- Simple Order API: “$0 Authorizations” on page 82. 
- SCMP API: “$0 Authorizations” on page 126.
May 2009 Added information about a new processor: Atos. See “Payment Processors” on page 6. For information about
which credit card features are supported for this processor:
• Basic features: Chapter 3, “Basic Credit Card Features,” on page 23.
• Optional features for the Simple Order API: Chapter 6, “Optional Features for the Simple Order API,” on
page 81.
• Optional features for the SCMP API: Chapter 7, “Optional Features for the SCMP API,” on page 125.
Updated the list of processors that are supported for forced captures:
• Simple Order API: “Forced Captures” on page 95.
• SCMP API: “Forced Captures” on page 139.

April 2009 Made the following updates for GPN:


• Added support for full authorization reversals: “Reversing an Authorization” on page 12.
• Added support for interchange optimization: “Interchange Optimization” on page 15.
• Added support for the merchant descriptor contact field which enables you to send dynamic telephone
numbers in your requests. 
- Simple Order API: “Merchant Descriptors” on page 100. 
- SCMP API: “Merchant Descriptors” on page 144.
• Added support for a flag that indicates to Visa that the payment is for an existing debt: 
- Simple Order API: The debtIndicator field in Table 33 on page 174. 
- SCMP API: The debt_indicator field in Table 35 on page 214.

Credit Card Services Implementation Guide • June 2009 xi


Month of
Changes
Release

March 2009 Removed Concord EFS because support for that processor has ended.

November 2008 Added support for full authorization reversals for FDMS South: “Reversing an Authorization” on page 12.

September 2008 Added Carte Bleu and Carta Si to the list of supported card types for Chase Paymentech Solutions: Table 1
on page 6.

August 2008 Added Barclays to the list of processors that can perform cash advances:
• Simple Order API: “Cash Advances” on page 85.
• SCMP API: “Cash Advances” on page 129.
Made the following updates for Asia-Mideast Processing:
• Added support for verbal authorizations: “Verbal Authorizations” on page 29.
• Added support for forced captures: 
- Simple Order API: “Forced Captures” on page 95. 
- SCMP API: “Forced Captures” on page 139.
• Added support for stand-alone credits: “Crediting a Payment” on page 17.

July 2008 Corrected the name of the request token document at the end of “Working with Request Tokens” on page 38
for the Simple Order API and at the end of “Working with Request Tokens” on page 60 for the SCMP API.

June 2008 Added information about a new processor: FDC Germany. See “Payment Processors” on page 6. For
information about which credit card features are supported for this processor:
• Basic features: Chapter 3, “Basic Credit Card Features,” on page 23.
• Optional features for the Simple Order API: Chapter 6, “Optional Features for the Simple Order API,” on
page 81.
• Optional features for the SCMP API: Chapter 7, “Optional Features for the SCMP API,” on page 125.
Updated all request token documentation to cover the new request token fields:
• Simple Order API: “Working with Request Tokens” on page 38.
• SCMP API: “Working with Request Tokens” on page 60.

xii CyberSource Corporation


Chapter 1
Introduction to the Credit Card Services

The CyberSource® Internet Commerce SuiteSM (ICS) processes financial transactions. This
document explains how to use the CyberSource APIs to access the CyberSource ICS
Credit Card Services.

Topics:
Overview of Credit Card Services
The Payment Industry
Processing a Credit Card Payment

Overview of Credit Card Services


The CyberSource Credit Card Services do the following:

• Provide your business with secure, reliable, real-time credit card payment processing,
without requiring you to develop and maintain a complex in-house infrastructure
• Accept multiple card types in multiple currencies and allow you to connect with
multiple banks and processors worldwide
• Allow you to easily expand your overall order volume and handle seasonal order
volume peaks
The CyberSource Credit Card Services are part of the Internet Commerce Suite, which
includes electronic payment, fraud management, and verification services. The steps for
using ICS services are:
1 You send a request that includes information about your company, the customer, and
the services you want to use.
2 CyberSource sends you a reply with information about the services you requested.
3 You use the reply information to interpret the results of your request.

Credit Card Services Implementation Guide • June 2009 1


Overview of Credit Card Services

As a user of the CyberSource ICS services, you can use the Business Center, which offers a
graphical interface for various functions, including:

• Processing customers’ payments and credits


• Viewing details about your transactions
• Viewing and downloading reports—See Using the Reporting System on the Support
Center for tutorials and documentation about CyberSource reports
After you register your merchant ID with CyberSource, you can use the test version of the
Business Center at https://ebctest.cybersource.com. After you go live, you can also use
the production version at https://ebc.cybersource.com. The username and password that
you use to log in to either site is your merchant ID and the password you established
when you registered the merchant ID with CyberSource. After you log in to the
production or test version of the Business Center, click the Help button on any page for
context-sensitive help.

Topics:
Types of Cards
MasterCard and Diners Club Alliance
CyberSource Global Payment Service
Card-Present and Card-Not-Present Transactions

Types of Cards
The CyberSource Credit Card Services can process these types of cards:

• Credit cards—CyberSource can accept payments made with numerous types of credit
cards, including Visa®, MasterCard®, Discover®, and American Express®. These
include Visa-branded and MasterCard-branded debit cards, which are processed the
same way as credit cards.
• Private label cards—Private label cards are credit cards that can only be used at the
issuing company’s own stores. If you are interested in using CyberSource to process
transactions for your company’s private label card, contact your CyberSource account
representative for more information.

Note You can process payments with PIN-less debit cards if your business is in one of the
acceptable merchant categories where a card-not-present debit transaction is low risk. The
categories include educational institutions, insurers, and utilities. Processing PIN-less
debit cards is covered in the PIN-less Debit Card Services Implementation Guide.

2 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

MasterCard and Diners Club Alliance


In 2004, MasterCard and Diners Club announced an alliance that allows Diners Club cards
to be processed as MasterCard cards. This alliance enables merchants who accept
MasterCard to automatically accept Diners Club cards.
MasterCard cards have a 16-digit number that begins with 5. Diners Club has two types of
cards:

• Cards issued in North America by Diners Club North America have a 14-digit
number that begins with either 30 or 38
• Cards issued outside of North America by Diners Club International have a 14-digit
number that begins with 36
By mid-2005, the Diners Club cards issued in North America were replaced with
MasterCard cards, which have the 16-digit number starting with 5. If you process a North
American Diners Club card that has a 14-digit number that begins with 30 or 38, the issuer
will decline the authorization.
The Diners Club cards issued outside North America are not being replaced by
MasterCard cards; they will continue to have the 14-digit number that begins with 36. If
you are a merchant outside North America, you should continue to process these cards as
Diners Club cards. However, if you are a North American merchant, you must now
process these cards as MasterCard cards by setting the card type to MasterCard. It is your
responsibility, as the merchant, to determine whether you should process a Diners Club
card as a Diners Club card or as a MasterCard card.
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.
If you are a merchant outside North America, you do not need to change how you process
MasterCard or Diners Club cards.

CyberSource Global Payment Service


The CyberSource Global Payment Service enables you to accept worldwide credit cards,
such as Visa, MasterCard, and Diners Club, as well as certain regional and country-
specific bank cards, such as Carte Bleue, Dankort, and Carta Si. For information about
credit card reversals with the Global Payment Service, see Appendix J, “Bank Card
Reversals for the Global Payment Service,” on page 299.
The CyberSource Global Payment Service also enables you to accept other payment types,
such as bank transfers and direct debits. For information about bank transfers and direct
debits with the Global Payment Service, see the Global Payment Service Planning and User’s
Guide, which is available on the Support Center.

Credit Card Services Implementation Guide • June 2009 3


The Payment Industry

Card-Present and Card-Not-Present Transactions


When a customer uses a credit 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 implementation guide.


• Provide retail data as described in the API for Retail POS Transactions, which is
available on the Support Center.
When a customer provides a credit card number, but you do not have access to the
physical credit 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 implementation guide.
Card-not-present transactions pose an additional level of risk to your business because
you cannot directly verify the customer’s identification. CyberSource offers features in the
Credit Card Services that can reduce that risk by checking the validity of the customer’s
information and notifying you when discrepancies occur.

The Payment Industry


This section describes some of the companies in the payment industry and explains how
to work with them to accept payments.

Topics:
Acquiring (Merchant) Banks
Issuing (Consumer) Banks
Credit Card Associations
Payment Processors

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 card-not-
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” on page 6.

4 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

Expect to be charged these fees:

• Your acquiring bank will charge a fee and collect 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.
• 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.
• If customers dispute charges to their accounts, you can incur chargebacks. A
chargeback occurs when a charge on a customer’s account is reversed. Your merchant
bank will remove the money from your account and could charge you a fee for the
chargeback.
If you have 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 credit card associations to which they belong.

Credit Card Associations


Credit card associations manage communications between acquiring banks and issuing
banks. They also develop industry standards, support their brands, and establish fees for
acquiring banks.
Some credit card associations, such as Visa and MasterCard, are not-for-profit trade
associations. These associations do not issue cards; instead, issuing banks are members of
the 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.

Credit Card Services Implementation Guide • June 2009 5


The Payment Industry

Payment Processors
Payment processors connect CyberSource servers with acquiring banks. Before you can
accept payments, you must sign up 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 implementation guide describes the payment processing features
supported by CyberSource. The beginning of each feature description specifies which
payment processors support the feature.
Your processor will provide you with unique identification numbers for your account.
You must provide these identification numbers to Customer Support.
The following table lists the processors and corresponding card types that CyberSource
supports for credit card transactions.

Note Only the card types explicitly listed here are supported.

Table 1 Payment Processors and Credit Card Types

Payment Processor Supported Credit Card Types & Notes

American Express Brighton American Express

American Express Direct American Express

American Express Phoenix American Express

Asia-Mideast Processing Visa, MasterCard, American Express, Diners Club, JCB

Atos Visa, MasterCard, Diners Club, JCB, Maestro (UK


Domestic), Maestro (UK International), Solo, Carte Bleue

Barclays Visa, MasterCard, JCB, Maestro (International), Maestro (UK


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

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, Carte Bleu, Carta Si, Maestro (UK
Domestic), Solo, private label cards

Citibank For details about the Citibank processors, contact your


CyberSource sales representative.

6 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

Table 1 Payment Processors and Credit Card Types (Continued)

Payment Processor Supported Credit Card Types & Notes

CyberSource Global Payment Visa, MasterCard, American Express, Diners Club, JCB,
Service Maestro (UK Domestic), Solo, Delta, Visa Electron, Dankort,
Laser, Carte Bleue, Carte Si
For credit card processing, the Global Payment Service
processor consists only of Global Collect at this time.

CyberSource Latin American Not all card types are supported in all Latin American
Processing countries. Contact Customer Support for details.
For some countries, you are required to submit the
authorization request and the capture request together in the
same message.

FDC Germany Visa, MasterCard, Maestro (UK Domestic), Solo,


Maestro (International)

FDI Australia Visa, MasterCard, American Express, Diners Club

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


JCB

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


Carte Blanche, JCB

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


Carte Blanche, JCB

GE Capital GE Money UK cards


GBP currency only
Before setting up your system to work with the GE Capital
processor and GE Money UK cards, contact the
CyberSource UK Support Group.
If you are processing with GE Capital, you are required to
pass the Transaction Reference Number. For more
information, contact Customer Support.

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), Solo,


Maestro (International)

HSBC Visa, MasterCard, Maestro (UK Domestic), Solo,


Maestro (International)

Credit Card Services Implementation Guide • June 2009 7


The Payment Industry

Table 1 Payment Processors and Credit Card Types (Continued)

Payment Processor Supported Credit Card Types & Notes

Lloyds-OmniPay Visa, MasterCard, Maestro (UK Domestic), Solo,


Maestro (International)

LloydsTSB Cardnet Visa, MasterCard, Maestro (UK Domestic), Solo

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


Carte Blanche, JCB

OmniPay-Ireland Visa, MasterCard

PayEase China Processing Visa, MasterCard, American Express, JCB


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

Streamline Visa, MasterCard, JCB, Maestro (UK Domestic),


Maestro (International), Solo, Laser
GBP currency only for JCB, Maestro (UK Domestic), and
Solo
SecureCode processing is required to accept
Maestro (International) cards.

TSYS Acquiring Solutions Visa, MasterCard, American Express, Discover, Diners Club,
Carte Blanche, JCB, private label cards

UATP UATP

8 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

Processing a Credit Card Payment


Topics:
Authorizing a Credit Card Payment
Reversing an Authorization
Capturing an Authorization
Crediting a Payment
Voiding a Capture or Credit

Authorizing a Credit Card Payment


CyberSource supports authorizations for all processors.
When a customer places an order, you need to request a credit card authorization. The
bank does not move money into your account until you capture the authorization and the
capture is processed.

Online Authorization
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 customer’s 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 will 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 determines 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 if it has expired with the issuing bank.

If 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 Implementation Guide • June 2009 9


Processing a Credit Card Payment

The following steps take place within seconds when you request an online credit card
authorization:
Figure 1 Processing an Online Authorization

Authorization AVS
Capture
Payment Card Issuing
Secure Internet Credit
Processor Association Bank
Customer Your Connection
Company
CyberSource

1 The customer places an order and provides the credit card number, the card
expiration date, and other information about the card.
2 You send a request for authorization over a secure Internet connection. If the customer
buys a digitally delivered product or service, you can request both the authorization
and the capture at the same time. If the customer buys a physically fulfilled product,
do not request the capture until you ship the product.
3 CyberSource validates the order information, then contacts your payment processor
and requests authorization.
4 The processor sends the transaction to the card association, which routes it to the
issuing bank for the customer’s credit card. Some card companies, including Discover
and American Express, act as their own issuing banks.
5 The issuing bank approves or declines the request. Depending on the card type, the
bank could also use the Address Verification Service (AVS) to determine whether the
customer provided the correct billing address. For information about AVS, see
“Address Verification Service” on page 23.
6 CyberSource runs its own tests, then tells you if the authorization succeeded.

Offline Authorization
Offline authorization means that when you submit an order using a credit card, you will not
know if the funds are available until you capture the order and receive confirmation of
payment. You typically will not ship the goods until you receive this payment
confirmation.
Most of the credit cards processed with CyberSource are online cards; a few of the cards
processed through the Global Payment Service are processed offline. For more
information about these offline cards, see the Global Payment Service Planning and User’s
Guide, which is available on the Support Center
For offline credit cards, it will take typically five days longer to receive payment
confirmation than for online cards.

10 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

Authorization Information for Specific Processors


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

Table 2 Authorization Information for Specific Processors

Payment Processor Authorization Information

American Express Direct American Express Direct limits authorization and capture
amounts to $9,999,999.00 USD.

American Express Phoenix American Express Phoenix limits authorization and capture
amounts to seven digits, which is $99,999.99 USD.

Asia-Mideast Processing Asia-Mideast Processing limits authorization and capture


amounts to four bytes, which is 2147483647.
Certain acquirers that are connected to Asia-Mideast
Processing require that an authorization be auto-captured.
This means that an authorization will always result in a
capture if the authorization is approved. If you use any of
these acquirers, you still need to send CyberSource a
capture request. Please check with your Customer Support
representative to determine whether your acquirer uses
delayed capture or auto capture.

Atos Atos limits authorization, capture, and credit amounts to


999999999999, which is 12 digits.
Important Authorizations time out after six days. If you
need to capture after six days, you must reauthorize.

CyberSource Latin American If you are processing with CyberSource Latin American
Processing 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
Customer Support for each country’s requirements.

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


10 digits.

TSYS Acquiring Solutions TSYS Acquiring Solutions limits authorization and capture
amounts to $99,999.99. If you want to process an amount
greater than this, contact TSYS Acquiring Solutions.

Additional Information
See “Authorizing a Credit Card Payment” on page 47 for the Simple Order API or
“Authorizing a Credit Card Payment” on page 68 for the SCMP API.

Credit Card Services Implementation Guide • June 2009 11


Processing a Credit Card Payment

Reversing an Authorization
CyberSource supports full authorization reversals for these processors:

• American Express Direct


• American Express Phoenix
• Barclays—You are responsible for complying with the processor’s specific
requirements for full authorization reversals. Contact the processor for more
information.
• CCS (CAFIS)
• Chase Paymentech Solutions—Full authorization reversals:
- Are supported only for Visa, MasterCard, Discover, and Diners Club.
- Must take place within three days of the authorization.
• CyberSource Latin American Processing—Full authorization reversals:
- Are supported only for Visa and MasterCard.
- Must take place within 24 hours of the authorization.
- Are not guaranteed: CyberSource’s acceptance of your full authorization reversal
request does not guarantee that CyberSource Latin American Processing will perform
the reversal.
• FDC Germany—You are responsible for complying with the processor’s specific
requirements for full authorization reversals. Contact the processor for more
information.
• FDMS Nashville—Visa only
• FDMS South—Full authorization reversals are supported only for transactions that do
not go through a currency conversion. The types of merchants and currencies that are
supported are:
- Merchants located in the United States 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.
• GE Capital—You are responsible for complying with the processor’s specific
requirements for full authorization reversals. Contact the processor for more
information.
• GPN
• HBoS—You are responsible for complying with the processor’s specific requirements
for full authorization reversals. Contact the processor for more information.

12 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

• Lloyds-OmniPay—You are responsible for complying with the processor’s specific


requirements for full authorization reversals. Contact the processor for more
information.
• LloydsTSB Cardnet—You are responsible for complying with the processor’s specific
requirements for full authorization reversals. Contact the processor for more
information.
• Streamline—You are responsible for complying with the processor’s specific
requirements for full authorization reversals. Contact the processor for more
information.
• TSYS Acquiring Solutions—Visa and MasterCard
The full authorization reversal service releases the hold that the authorization placed on
the customer’s credit card funds. Use this service in exceptional situations to reverse an
unnecessary or undesired authorization. You can use full authorization reversal only for
an authorization that has not been captured and settled. The amount of the reversal must
be the same as the amount of the authorization.

Note Each issuing bank has its own rules that determine whether a full authorization
reversal succeeds. If your reversal fails, contact the issuing bank to determine if it is
possible to perform the reversal by alternate means.

Additional Information
See “Reversing an Authorization” on page 51 for the Simple Order API or “Reversing an
Authorization” on page 72 for the SCMP API.

Capturing an Authorization
CyberSource supports captures for all processors.
When you are ready to fulfill a customer’s order and transfer funds from the customer’s
bank to your bank, capture the authorization for that order.
If you can fulfill only part of a customer’s 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.
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.

Credit Card Services Implementation Guide • June 2009 13


Processing a Credit Card Payment

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 if it has expired with the issuing bank.

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.
See Figure 2 on page 17 for more information about processing a capture.

Automatic Partial Authorization Reversals


CyberSource supports automatic partial authorization reversals for these processors and
card types:

Table 3 Processors That Support Automatic Partial Authorization Reversals

Processor Card Types

FDI Global Visa

FDMS Nashville Visa, MasterCard, Discover

GPN Note For GPN, automatic partial


authorization reversal is performed as
part of interchange optimization. See
“Interchange Optimization” on page 15.

OmniPay-Ireland Visa

TSYS Acquiring Solutions Visa, MasterCard

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 credit card
association.
• The hold on the unused credit card funds might be released. It is up to the issuing
bank to release the hold on unused funds.

Note Not all issuers act on a request for a partial authorization reversal. Therefore
CyberSource cannot guarantee that the funds will be released.

The automatic partial authorization feature can be enabled or disabled at your request. To
do this, contact Customer Support.

14 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

Interchange Optimization
CyberSource offers automatic interchange optimization to GPN acquiring merchants for
Visa transactions. This feature helps you reduce your interchange fees. Interchange
optimization consists of:

• Automatic authorization refresh—If the capture request occurs six days or more 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.
To enable interchange optimization, call Customer Support to have your account
configured for this feature.

Capture Information for Specific Processors


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

Table 4 Capture Information for Specific Processors

Payment Processor Capture Information

American Express Direct American Express Direct limits authorization and capture
amounts to $9,999,999.00 USD.

American Express Phoenix American Express Phoenix limits authorization and capture
amounts to seven digits, which is $99,999.99 USD.

Asia-Mideast Processing If you are using Asia-Mideast Processing as your payment


processor, you can request multiple partial captures against
the same authorization. You must make sure that the total
amount for all the captures does not exceed the authorization
amount.
Asia-Mideast Processing limits authorization and capture
amounts to four bytes, which is 2147483647.
Certain acquirers that are connected to Asia-Mideast
Processing require that an authorization be auto-captured.
This means that an authorization will always result in a
capture if the authorization is approved. If you use any of
these acquirers, you still need to send CyberSource a
capture request. Please check with your Customer Support
representative to determine whether your acquirer uses
delayed capture or auto capture.

Credit Card Services Implementation Guide • June 2009 15


Processing a Credit Card Payment

Table 4 Capture Information for Specific Processors (Continued)

Payment Processor Capture Information

Atos Atos limits authorization, capture, and credit amounts to


999999999999, which is 12 digits.
Important Authorizations time out after six days. If you
need to capture after six days, you must reauthorize.

Chase Paymentech Solutions If you are using Chase Paymentech Solutions as your
payment processor, you can request multiple partial captures
against the same authorization. You must make sure that the
total amount for all the captures does not exceed the
authorization amount.

CyberSource Global Payment Captures for cards using the Global Payment Service are not
Service batched. CyberSource submits these captures immediately
to the Global Payment Service processor when they are
received.

CyberSource Latin American Card association rules generally specify that you must not
Processing capture a payment until you have shipped the products to the
customer. However, if you are processing 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 Customer Support for each country’s
requirements. With CyberSource Latin American Processing,
it takes 31 days for the funds to be deposited in your
merchant bank account.

FDI Global CyberSource always provides merchant descriptor


information to the processor for you for all capture and credit
transactions. For more information, see “Merchant
Descriptors” on page 100 for the Simple Order API or
“Merchant Descriptors” on page 144 for the SCMP API.

GE Capital If you are processing with GE Capital, you are required to


pass the Transaction Reference Number. For more
information, contact Customer Support.

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


10 digits.

TSYS Acquiring Solutions TSYS Acquiring Solutions limits authorization and capture
amounts to $99,999.99. If you want to process an amount
greater than this, contact TSYS Acquiring Solutions.

16 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

Additional Information
See “Capturing an Authorization” on page 52 for the Simple Order API or “Capturing an
Authorization” on page 73 for the SCMP API.

Crediting a Payment
CyberSource supports credits for all processors.
Request a credit when you need to give the customer a refund. 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.

You can perform two types of credits:

• Follow-on: A follow-on credit is linked to the original charge in the CyberSource


system. You can request multiple follow-on credits against a single charge. You must
request all follow-on credits within 60 days of the original charge.
• Stand-alone: A stand-alone credit does not link the credit to a previous charge. There
is no time limit for submitting stand-alone credits.
Credit requests are batched in the same manner as captures.
The following steps take place when you request a capture or credit:
Figure 2 Processing a Capture or Credit

Authorization
after within 96
Capture midnight hours
Issuing
Secure Internet Credit Bank
Company Connection
Representative Payment
Batch File
CyberSource Processor Capture Credit

Acquiring
Bank

Credit Card Services Implementation Guide • June 2009 17


Processing a Credit Card Payment

1 You send a request for capture or credit over a secure Internet connection.
2 CyberSource validates the order information, then stores the capture or credit request
in a batch file.
3 After midnight, CyberSource sends the batch file to your payment processor.
4 The processor settles the capture or credit request and transfers funds to the
appropriate bank account.

Note The processor does not notify CyberSource if a transaction is declined. To make
sure all captures and credits are processed, reconcile your system’s reports with the
reports from your processor. See “Reconciliation” on page 31 for more information.

Credit Information for Specific Processors


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

Table 5 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, which means the maximum amount is 999999999999.
The credit cannot be processed on the same day as the
capture. You must wait at least one 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.

18 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services

Table 5 Credit Information for Specific Processors (Continued)

Payment Processor Credit Information

CyberSource Global Payment If you are using the Global Payment Service, you can
Service process only one follow-on credit against a specific captured
authorization each day. For example, if you want to first
process a follow-on credit of $15 against an original capture
of $50, and then later you want to process a follow-on credit
of $35 against the same capture, you must request the two
credits on two separate days.
You cannot automatically do stand-alone credits for cards
processed through the CyberSource Global Payment
Service. Contact Customer Support if you want to do stand-
alone credits with the Global Payment Service.
Credits for cards using the Global Payment Service are not
batched. CyberSource submits these captures immediately
to the Global Payment Service processor when they are
received.

CyberSource Latin American CyberSource Latin American Processing supports only


Processing 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.

FDI Global CyberSource always provides merchant descriptor


information to the processor for you for all capture and credit
transactions. For more information, see “Merchant
Descriptors” on page 100 for the Simple Order API or
“Merchant Descriptors” on page 144 for the SCMP API.

GE Capital If you are processing with GE Capital, you are required to


pass the Transaction Reference Number. For more
information, contact Customer Support.

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


10 digits.

Additional Information
See “Crediting a Payment” on page 55 for the Simple Order API or “Crediting a Payment”
on page 76 for the SCMP API.

Credit Card Services Implementation Guide • June 2009 19


Processing a Credit Card Payment

Voiding a Capture or Credit


CyberSource supports voids for all processors except:

• CyberSource Global Payment Service


• Lynk
Request a void when you want to cancel a capture or credit request that you have
submitted to CyberSource. A transaction can be voided only if CyberSource has not
already submitted the capture or credit information to your processor. Usually
CyberSource submits that type of information to your processor once a day, so your
window for successfully performing a void is small. CyberSource will decline your void
request if the capture or credit information has already been sent to the processor.
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. You cannot perform a follow-on credit for
a transaction that has been voided.
You cannot undo a void.

Additional Information
See “Voiding a Capture or Credit” on page 57 for the Simple Order API or “Voiding a
Capture or Credit” on page 79 for the SCMP API.

20 CyberSource Corporation
Chapter 2
Getting Started

Follow these steps to start using the CyberSource Credit Card Services:
1 Set up your banking relationships.
Choose a merchant bank and payment processor based on your business needs. See
“Payment Processors” on page 6. CyberSource supports different features, currencies,
and types of credit cards for each processor. Make sure the processor you choose
accepts customers in your country.
• Establish an account with your merchant bank.
• Choose which credit cards to accept. Most processors support the most widely
used credit card types. If you need to support other card types, contact your
payment processor for more information.
• Decide which currencies to accept. Some processors do not support multiple
currencies.
• Consider implementing fraud prevention features. Your fraud rate could affect
the fees you pay to your merchant bank or payment processor. If your fraud rate
is extremely high, you might lose your merchant bank account. Contact your
CyberSource account representative for information about preventing fraud.
• Consider any legal requirements related to accepting credit card payments.
Contact your legal counsel to discuss these requirements.
2 Get your CyberSource test account.
If you have not done so already, contact Customer Support to get your test account
and CyberSource merchant ID. Customer Support can also help you subscribe to
some CyberSource reports. You will receive a login and password for the Business
Center, which is a Web portal that allows you to:
• Manage your CyberSource transactions.
• Download CyberSource reports.
The test version of the Business Center is at https://ebctest.cybersource.com.
The production version of the Business Center is at https://ebc.cybersource.com.

Credit Card Services Implementation Guide • June 2009 21


3 Install your client SDK.
If you have not integrated with CyberSource before, you will be using the
CyberSource Simple Order API. The other CyberSource API is the SCMP API, which
is an older, legacy API. Both APIs are covered in this guide.
Go to the Technical Resources page to select and download a Simple Order API client
(SDK). After reading the client documentation, install and test the client.
The documentation for the CyberSource client you choose describes how to use the
client to request the CyberSource ICS services. The documentation is available when
you download the SDK. The Support Center has a Web page for the Simple Order API
SDKs and a Web page for the SCMP API SDKs.
4 Implement your system.
Write code that:
• Creates requests.
• Uses the client SDK to send the requests to and receive replies from the Credit
Card Services.
• Handles the replies.

5 Test your system.


Send test transactions to the CyberSource test server. See Chapter 8, “Testing Credit
Card Services,” on page 169. Search for and view your test transactions in the test
version of the Business Center at https://ebctest.cybersource.com.
6 Go live.
When you have tested your system and are ready to accept production transactions,
you can go live with electronic check transactions. If you have not already gone live
with CyberSource for another payment type, such as credit cards, see “Going Live” on
page 171.
Your production transactions will be available in the production version of the
Business Center at https://ebc.cybersource.com.

22 CyberSource Corporation
Chapter 3
Basic Credit Card Features

This chapter explains the basic credit card features, which are authorization features. You
need to support the authorization features that your processor supports. For optional
features that you can use, see Chapter 6, “Optional Features for the Simple Order API,” on
page 81 or Chapter 7, “Optional Features for the SCMP API,” on page 125.

Important For details about the Citibank processors, contact your CyberSource sales
representative.

Topics:
Address Verification Service
Card Verification Numbers
Verbal Authorizations
Reconciliation

Address Verification Service


Depending on which processor you use, you have different levels of the Address
Verification Service (AVS) available to you.

Topics:
Standard AVS
Enhanced AVS
Automated Address Verification Plus
Extended AVS

Credit Card Services Implementation Guide • June 2009 23


Address Verification Service

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

Table 6 Processors That Support Standard AVS

Processors Credit Card Types

American Express Brighton American Express


You must contact Customer Support to
activate standard AVS for American
Express Brighton.

American Express Direct American Express


You must contact Customer Support to
activate standard AVS for American
Express Direct.

American Express Phoenix American Express


You must contact Customer Support to
activate standard AVS for American
Express Phoenix.

Atos Visa (UK only), MasterCard (UK only)

Barclays Visa, MasterCard, Maestro (UK Domestic)/Solo

Chase Paymentech Solutions Visa: Billing country must be the U.S., Canada, or
Great Britain
American Express: Billing country must be the U.S.
or Canada
MasterCard, Discover, Diners Club: Billing country
must be the U.S.

CyberSource Global Payment Service Visa, MasterCard


processor
The billing country must be U.S. or Great Britain.

CyberSource Latin American Processing Visa, MasterCard, American Express, Diners Club

FDC Germany Visa, MasterCard

FDI Global Visa, MasterCard, American Express, Discover,


Diners Club, JCB

FDMS Nashville Visa, MasterCard, American Express, Discover

FDMS South Visa, MasterCard, American Express, Discover,


Diners Club

24 CyberSource Corporation
Chapter 3 Basic Credit Card Features

Table 6 Processors That Support Standard AVS (Continued)

Processors Credit Card Types

GE Capital GE Money UK card


GBP currency only

GPN Visa, MasterCard, American Express, Discover,


Diners Club, JCB

HBoS Visa, MasterCard

HSBC Visa, MasterCard, Maestro (UK Domestic)/Solo

Lloyds-OmniPay Visa, MasterCard

LloydsTSB Cardnet Visa, MasterCard

Lynk Visa, MasterCard, American Express, Discover,


Diners Club

OmniPay-Ireland Visa, MasterCard

Streamline Visa, MasterCard, Maestro (UK Domestic)/Solo

TSYS Acquiring Solutions Visa, MasterCard, American Express, Diners Club


The billing country must be the U.S.

For supported processors and card types, the issuing bank uses AVS to confirm that the
customer has provided the correct billing address. If the customer provides incorrect
information, the transaction might be fraudulent. AVS occurs automatically with every
authorization request. In the reply, you receive an AVS code that describes the result of the
AVS check.
AVS can be considered either domestic or international, depending on the location of the
bank that issued the customer’s credit card. If the bank is in the U.S., the AVS is domestic.
If the bank is outside the U.S., the AVS is international. Certain AVS codes are returned
only for international AVS on Visa cards.

Note You should be prepared to handle both domestic and international AVS result codes.
You can receive international AVS codes even if the customer has a U.S. billing address.
Conversely, you can receive domestic AVS codes even if the customer has a non-U.S.
billing address. See Appendix G, “Address Verification Service Codes,” on page 291 for a
list of the AVS codes.

Credit Card Services Implementation Guide • June 2009 25


Address Verification Service

If 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, consider reviewing these orders to make sure 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.

Enhanced AVS
Note You must contact Customer Support and American Express to sign up for Enhanced
AVS.

CyberSource returns Enhanced AVS results for American Express cards for the American
Express Phoenix processor. Enhanced AVS includes the standard AVS capability and adds
verification of the customer’s last name.

Automated Address Verification Plus


Note You must contact Customer Support and American Express to sign up for AAV+.

CyberSource returns AAV+ results for the American Express Phoenix processor, which
handles only American Express cards. Automated Address Verification Plus (AAV+)
includes both the standard and Enhanced AVS capability and adds verification of the
ship-to address. This service is intended for merchants who deliver physical goods to a
different address than the billing address. AAV+ verifies the ship-to address only if the
standard and Enhanced AVS tests first pass.

Extended AVS
Extended AVS is a CAPN feature. CyberSource returns Extended AVS results for
American Express cards if this features is supported by the processor.
There are two levels of Extended AVS:
1 Standard AVS + verification of the customer’s last name.
2 Standard AVS + verification of the customer’s last name + verification of the ship-to
address. This level of verification is intended for merchants who deliver physical
goods to a different address than the billing address.

Additional Information
See “Address Verification Service” on page 47 for the Simple Order API or “Address
Verification Service” on page 69 for the SCMP API.

26 CyberSource Corporation
Chapter 3 Basic Credit Card Features

Card Verification Numbers


The following table lists the processors and card types for which CyberSource supports
card verification numbers (CVNs).

Table 7 Processors That Support CVN

Processors Credit Card Types

American Express Brighton American Express

American Express Direct American Express

American Express Phoenix American Express

Asia-Mideast Processing Visa, MasterCard, American Express, Diners


Club

Atos Visa, MasterCard, Carte Bleue

Barclays Visa, MasterCard, Maestro (UK Domestic)/Solo

CCS (CAFIS) Visa, MasterCard, American Express, Diners


Club, JCB

Chase Paymentech Solutions Visa, MasterCard, American Express, Discover

CyberSource Global Payment Service Visa, MasterCard


Note Do not include the card verification number
in the request if you are processing a recurring
payment. See “Recurring Payments” on
page 119.

CyberSource Latin American Processing Visa, MasterCard, American Express

FDC Germany Visa, MasterCard

FDI Australia Visa, MasterCard, American Express, Diners


Club

FDI Global Visa, MasterCard, American Express, Diners


Club
Note Do not include the card verification number
in the request if you are performing a $0
authorization. See “$0 Authorizations” on
page 82.

FDMS Nashville Visa, MasterCard, American Express, Discover

Credit Card Services Implementation Guide • June 2009 27


Card Verification Numbers

Table 7 Processors That Support CVN (Continued)

Processors Credit Card Types

FDMS South Visa, MasterCard, American Express, Discover


Note Do not include the card verification number
in the request if you are performing a $0
authorization. See “$0 Authorizations” on
page 82.

GE Capital GE Money UK card


GBP currency only

GPN Visa, MasterCard, American Express, Discover,


Diners Club

HBoS Visa, MasterCard

HSBC Visa, MasterCard

Lloyds-Omnipay Visa, MasterCard

LloydsTSB Cardnet Visa, MasterCard

Lynk Visa, MasterCard, American Express, Discover,


Diners Club

OmniPay-Ireland Visa, MasterCard

Streamline Visa, MasterCard, Maestro (UK Domestic)/Solo

TSYS Acquiring Solutions Visa, MasterCard, American Express, Discover,


Diners Club

Many credit cards have a card verification number printed, not embossed, on the card.
Figure 3 Example of a Visa Card Verification Number

1234567890123456 789

Card verification number

28 CyberSource Corporation
Chapter 3 Basic Credit Card Features

You can include the card verification number in the request to reduce the risk of fraud.
This number is never transferred during card swipes and should be known only by the
cardholder. Each card association has its own name for this number:

• Visa calls it the Card Verification Value (CVV2).


• MasterCard calls it the Card Validation Code (CVC2).
• American Express and Discover call it the Card Identification Digits (CID).
Visa and MasterCard print the number on the back of the card.
Even if the card verification number does not match the expected value, the issuing bank
might still authorize the transaction. You will receive a card verification decline from
CyberSource, but you can still capture the transaction because it has been authorized by
the bank. However, consider reviewing the order to make sure it is legitimate.
Settling authorizations that fail the card verification 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.

Note The American Express card verification number is available only to large companies
with high transaction volumes. If you want to use the American Express card verification
number, first complete the setup of this program with your American Express
representative. Then send a request to Customer Support to enable the feature for your
CyberSource merchant ID. See “Testing American Express Card Verification” on
page 171.

Additional Information
See “Card Verification Numbers” on page 48 for the Simple Order API or “Card
Verification Numbers” on page 70 for the SCMP API.

Verbal Authorizations
CyberSource supports verbal authorizations for these processors:

• American Express Brighton


• American Express Direct
• American Express Phoenix
• Asia-Mideast Processing
• Barclays
• CCS (CAFIS)
• Chase Paymentech Solutions

Credit Card Services Implementation Guide • June 2009 29


Verbal Authorizations

• CyberSource Latin American Processing—Banorte only


• FDC Germany
• FDI Australia
• FDI Global
• FDMS Nashville
• FDMS South
• GE Capital
• GPN
• HBoS
• HSBC
• Lloyds-OmniPay
• LloydsTSB Cardnet
• Lynk

• Streamline
• TSYS Acquiring Solutions
• UATP

Important Do not use Dynamic Currency Conversion for a verbal authorization.

When you request an authorization through CyberSource, the issuing bank might ask that
you call the payment processor to answer questions about the transaction. If this happens,
the processor will give you a verbal authorization code for the transaction. You can
capture verbally authorized transactions by sending the verbal authorization code as part
of the capture request.
Make sure your customer service and point-of-sale staff can enter verbal authorization
codes into your system.

Important Do not confuse the verbal authorization discussed here with a forced capture.
With a verbal authorization, you get 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 performing
an authorization outside of CyberSource. In both cases, you follow up with a capture that
uses the CyberSource system. For information about processing forced captures, see
“Forced Captures” on page 95 for the Simple Order API or “Forced Captures” on
page 139 for the SCMP API.

30 CyberSource Corporation
Chapter 3 Basic Credit Card Features

Using verbal authorization, you can request to capture an authorization that was declined
for any of these reasons:

• Verbal authorization required


• Card expired
• Card refused
• Invalid card

Additional Information
See “Verbal Authorizations: The Authorization” on page 50 for the Simple Order API or
“Verbal Authorizations: The Authorization” on page 71 for the SCMP API.

Reconciliation
CyberSource supports reconciliation for all processors except CCS (CAFIS).
When you use Credit Card Services with a supported processor to capture an
authorization or issue a credit, CyberSource returns a unique transaction reference
number that you can use to reconcile the transaction with your account statement. Both
the payment processor and CyberSource include this number on reports.
The transaction reference number is also called a reconciliation ID.
You can use CyberSource reports to reconcile your credit card transactions with the
payment processor’s transactions. The reports that are the most useful for reconciliation
are:

• Payment Batch Detail Report—This report provides summary information about


credit card transactions that were submitted to the processor on the previous day. You
can compare the Payment Batch Detail Report to the processor’s report to determine if
each transaction you submitted was processed.
• Payment Submission Detail Report—This report is the same as the Payment Batch
Detail Report except that it includes a column for the payment processor, which is
useful if you use more than one payment processor.
• Payment Events Report—This report provides information about events that
occurred on the previous day for transactions you submitted. Use this report to
confirm payments and credits. This report is particularly important for reconciling
offline credit card transactions.
These reports area available through the Business Center. For information about the
formats of the reports and how to download them, see the Reporting Developer’s Guide,
which is available on the Support Center.

Credit Card Services Implementation Guide • June 2009 31


Reconciliation

For the following processors, the transaction reference number is included in the
authorization reply message.

• Asia-Mideast Processing
• Atos
• BML Direct
• Chase Paymentech Solutions
If you perform multiple partial captures against an authorization for the following
processors, you receive a different transaction reference number in the reply for each
capture request:

• Asia-Mideast Processing
• Chase Paymentech Solutions

32 CyberSource Corporation
Chapter 4
Payment Processing with the Simple Order API

Topics:
Introduction to the API
Authorizing a Credit Card Payment
Reversing an Authorization
Capturing an Authorization
Crediting a Payment
Voiding a Capture or Credit

Introduction to the API


The CyberSource Simple Order API enables you to access ICS services using either name-
value pairs or XML. Depending on the platform you are using and your experience, you
might be able to use the SOAP interface instead. For more information about the SOAP
interface, contact Customer Support.
The name-value pair interface is based on the XML schema. This guide uses the name-
value pairs when discussing the interface. If you plan to use XML, you can easily translate
the name-value pairs in this guide to the corresponding XML elements. See “Correlating
Schema and Name-Value Pair Fields Names” on page 36.
To guarantee the integrity and privacy of the messages that you use to access the ICS
services, CyberSource requires that all messages be digitally signed according to the WS-
Security standard. CyberSource clients handle this requirement for you.

Credit Card Services Implementation Guide • June 2009 33


Introduction to the API

Topics:
Multi-Byte Character Support for the ICS Services
Simple Order API Clients
Which Version of the API to Use
Using Name-Value Pairs
Using XML
Working with Request Tokens
About Requests
Using Items or a Grand Total in the Request
Requesting a Follow-on Service
Handling Replies
Tracking Orders

Multi-Byte Character Support for the ICS Services


CyberSource supports multi-byte characters for all ICS services except Delivery Address
Verification, Stored Value, and Customer Profiles.Before implementing any of these
services, contact Customer Support to clarify any questions you have about multi-byte
character support. See the Support Center for documentation about these services.
All of the Simple Order API clients (SDKs) support UTF-8.

Simple Order API Clients


The Simple Order API clients contain these components:

• Client libraries used to communicate with CyberSource and access the ICS services
• Security libraries used to digitally sign the messages
• For SOAP users, the SOAP proxy classes
• Sample code for digitally signing the messages and using the client libraries
For the latest list of available Simple Order API clients and related documentation, see the
Downloads page at the Support Center.

Which Version of the API to Use


CyberSource updates the Simple Order API on a regular basis to introduce new API fields
and functionality. With each update, the API receives a new version number. For example,
1.22. To determine the latest version of the API, go to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/.

34 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

You should use the latest version to take advantage of the full functionality of the ICS
services. For information about changes to the API, see the Simple Order API Release Notes,
which are available at the Support Center.
When configuring your Simple Order API client, indicate which version of the API you
want to use. See the documentation for your client for instructions on how to do this.

Important When using the request token functionality as described in “Working with
Request Tokens” on page 38 with the Simple Order API in XML format, you must use
version 1.37 or higher of the XML schema located at https://ics2ws.ic3.com/commerce/
1.x/transactionProcessor.

Using Name-Value Pairs


If you use name-value pairs, your requests include the required name-value pairs for the
services you are requesting. The client digitally signs and sends your request. You only
need to create the request message and parse the reply message, which also contains
name-value pairs. See Appendix C, “Examples for the Simple Order API,” on page 251 for
example name-value pair requests and replies.

Using XML
If you use XML, your requests are XML messages that contain the required information
for the services you are requesting. The client digitally signs and sends your request. You
only need to create the request XML message and parse the XML reply message. See
Appendix C, “Examples for the Simple Order API,” on page 251 for example XML
requests and replies.

Constructing Requests
The XML schema is located at
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor.
The schema’s structure is separated into a request message and a reply message. Inside
the request message are elements for the basic invoice information, tender information,
and service-specific information. For example, the information specific to a credit card
authorization is in the <ccAuthService> element.
To indicate in the request that you want to run a service, set the run attribute for the
service’s element to "true". For example, to request credit card authorization, set the run
attribute for the <ccAuthService> element to "true".
You can send either live or test transactions. For live transactions, send your request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor where the XML schema is
located. For test transactions, send your requests to https://ics2wstest.ic3.com/
commerce/1.x/transactionProcessor.

Credit Card Services Implementation Guide • June 2009 35


Introduction to the API

Parsing Replies
The reply message includes general information for the entire request as well as
information for each service in the request. For example, the reply information relevant to
the credit card authorization is in the <ccAuthReply> element. For more information
about interpreting the reply, see “Handling Replies” on page 43.
XML replies from CyberSource always contain the namespace prefix c:. You need to use
an XML parser that supports namespaces.

Important Because CyberSource could add reply fields and reason codes at any time, do
the following:
- Parse the reply data according to the names of the fields instead of their order in the
reply. For more information about parsing reply fields, see the documentation for your
client.
- Program your error handler to use the decision field to determine the result if it receives
a reason code that it does not recognize.

Correlating Schema and Name-Value Pair Fields Names


This guide discusses the API using name-value pairs and not the element names in the
XML schema. You can easily translate between the name-value pair field name and the
corresponding XML element name.
The relationship between the XML element names and the name-value pair field names is
as follows:

• Each name-value pair field name matches the corresponding XML element name.
• The XML schema shows hierarchy with an underscore ( _ ) separating the name of the
parent element from the name of the child element.
For example, the XML schema has a <card> element with several child elements. The
following table shows the <card> child element names in the XML schema, and the
corresponding name-value pair field names.

Table 8 Example of Schema Names and Name-Value Pair Field Names

Schema Names Corresponding Name-Value Pair Field Names

<card>
<accountNumber> card_accountNumber
<expirationMonth> card_expirationMonth
<expirationYear> card_expirationYear
</card>

The same convention is used for reply fields.

36 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

Note If you are using SOAP, the complex types in the XML schema translate to classes of
the same name. For example, the <Card> complex type in the schema translates to a Card
class in the SOAP client.

The XML schema also includes several numbered types and elements. These are complex
types or elements that you can include more than once in a request. For example, if a
customer’s order includes more than one item, you need to include multiple <item>
elements in your request. Each item is numbered, starting with 0.
The XML schema uses an id attribute in the item’s opening tag to indicate the number.
For example:
<item id="0">
For the name-value field names, this is represented as item_0. In this situation, the
underscore before the number does not indicate hierarchy in the XML schema. The item
fields are generically referred to as item_#_<element name> in the documentation.
The following table shows an example of the numbered <item> element and the
corresponding name-value pair field names. If you are using SOAP, the client contains a
corresponding Item class.

Table 9 Example of Numbered Schema Names and Name-Value Pair Field Names

Schema Names Corresponding Name-Value Pair Field Names

<item id="0">
<unitPrice> item_0_unitPrice
<quantity> item_0_quantity
</item>

<item id="1">
<unitPrice> item_1_unitPrice
<quantity> item_1_quantity
</item>

Credit Card Services Implementation Guide • June 2009 37


Introduction to the API

Working with Request Tokens


The requestToken is a unique identifier that CyberSource assigns to each request and
returns to you in each reply. This field is an encoded string that does not contain any
confidential information, such as account numbers or card verification numbers. You need
to store this value, which is a string that can contain up to 256 characters. Depending on
how you process follow-on requests, you might need to retrieve the request token value
and send it in the orderRequestToken field in your follow-on service requests:

• If you process primary requests with an API, but process follow-on requests through
the Business Center, you do not need to change how you use the Business Center or
provide the request token data at this time.
• If you process primary and follow-on requests with an API, you need to retrieve the
request token from the primary reply message and include the request token in the
follow-on request message:
Primary Reply Message: requestToken=AA4JUrWguaMUGwxSWVdPS5IM
Follow-on Request: orderRequestToken=AA4JUrWguaMUGwxSWVdPS5IM

Existing Merchants Who Have Not Implemented Request Tokens


If you were a CyberSource merchant before July 2008 and never implemented request
tokens, you have these choices:

• You can implement the request token as described in this document. CyberSource
recommends that you use this option.
• You can let CyberSource store the request token data for you and retrieve it for you as
necessary when you send follow-on requests.

38 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

Existing Merchants Who Have Implemented Request Tokens


If you were a CyberSource merchant before July 2008 and implemented request tokens,
your implementation uses a different field name for the request token that is sent to each
different follow-on service. With the new implementation, you would use the
orderRequestToken field for all follow-on services. This approach makes it easier to
manage the request token values. It also reduces the likelihood of submitting a duplicate
request by accidentally sending in the wrong request token value. You have these choices:

• You can continue to use your current implementation at this time. It is still supported,
but CyberSource recommends that you update your implementation to use the
orderRequestToken field.
• You can update your implementation to store the latest request token for a transaction
in one database field to return with all follow-on services for the transaction:
Figure 4

• You can update your implementation without changing your database. Store the
latest request token for a transaction in all of your existing request token database
fields so that any follow-on request for the transaction will return the latest request
token value:

Note The following figure uses the request field names for the Credit Card services. If
you are using a different set of services, such as PayPal services, Electronic Check
services, or Global Payment services, substitute the request field names for the
services you are using.

Figure 5

For more information about request tokens, see the Request Token Planning Guide.

Credit Card Services Implementation Guide • June 2009 39


Introduction to the API

About Requests
A request for ICS services contains general information and information specific to the
services you are requesting. General information includes information about you, the
merchant; about the customer and their form of payment; and about the items the
customer is buying.

Using Items or a Grand Total in the Request


For some services, you must specify the amount of the transaction. You can provide either
the individual products the consumer is purchasing or a grand total for the transaction.

Note If you are using Decision Manager, CyberSource recommends that you provide
individual item information instead of a grand total for the order. Decision Manager can
be configured to use the individual item information to assess the risk of the order and
determine if the purchaser is following your business rules. For more information about
Decision Manager, see the Decision Manager Developer’s Guide.

Using Items
Items are the products that the consumer purchases from you. When you send a request
for a service that requires an amount, you can send item-specific information, such as the
quantity of each item ordered and the unit price for each item. The items are referred to as
item_0, item_1, item_2, and so on. CyberSource uses the information you provide for each
item to calculate the grand total for the order.
The values for the item_#_ fields must not contain carets (^) or colons (:) because these
characters are reserved for use by the ICS services.
Required Item-Level Fields
If you are using the item-level fields, which fields are required depends on the value you
use for item_#_productCode. If item_#_productCode is one of the following values:

• default
• stored_value
• a value related to shipping and handling
or if you omit item_#_productCode, which causes it to default to the value default, then
the only required field is item_#_unitPrice. If you do not set item_#_quantity, it defaults
to 1.

40 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

If you do not set item_#_productCode to one of the values in the previous list, the
following fields are required:

• item_#_unitPrice
• item_#_quantity
• item_#_productName
• item_#_productSKU
The item_#_taxAmount field is always optional.
Specifying Tax
To include tax for an item, use the item_#_taxAmount field. This value is the total tax for
the entire quantity of that item. In other words, the value is not multiplied by item_#_
quantity. For example:

item_0_unitPrice=10.00
item_0_quantity=5
item_0_taxAmount=4.00

The grand total for this transaction is (10.00 * 5) + 4.00 = 54.00.


Specifying Freight Charges
To include a shipping and handling charge for the order, you must include an additional
item with item_#_productCode set to one of the following values:

• shipping_only
• handling_only
• shipping_and_handling

For example:

item_0_unitPrice=10.00
item_0_quantity=5
item_0_taxAmount=4.00
item_1_unitPrice=4.95
item_1_quantity=1
item_1_productCode=shipping_only

The grand total for this transaction is (10.00 * 5) + 4.00 + (4.95 * 1) = 58.95.

Credit Card Services Implementation Guide • June 2009 41


Introduction to the API

Using a Grand Total


Instead of using items, you can send a grand total for the order in the purchaseTotals_
grandTotalAmount field. This field is useful if you do not have information for each item
or do not care about the information for each item and simply want to use a transaction
total. If you include purchaseTotals_grandTotalAmount in your request, CyberSource
uses this value and does not use item-level information to calculate the transaction’s
grand total. If you provide item-level information in addition to the grand total, the item-
level information is displayed on the Transaction Detail page in the Business Center.

Important If you include purchaseTotals_grandTotalAmount in your request, you cannot


include the Tax Calculation service as part of the request. See the Tax Calculation
Implementation Guide.

Requesting a Follow-on Service

A request for a follow-on service must include a request ID and a request token:
1 Save the request ID and request token from the reply for the primary service. Here is
an example of the fields you will receive in the reply message:
requestID=0305782650000167905080
requestToken=AA4JUrWguaMUGwxSWVdPS5IM
2 Send those values in the follow-on request. For the request token, use the following
field:
orderRequestToken=AA4JUrWguaMUGwxSWVdPS5IM
For the request ID, the field name depends on the names of the primary service and
follow-on service. For more information, see the description of the follow-on service
or the tables of field descriptions.
Follow-on services covered in this guide:

• ccCaptureService
• ccCreditService
• ccAuthReversalService
• voidService
For more information, see “Working with Request Tokens” on page 38.

42 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

Handling Replies
The reply provides you with the results of your request. To use the reply information, you
must integrate it into your system and any other system that uses that data. This includes
storing the data and passing it to any other systems that need the information.
Write an error handler to interpret the information that you receive. Do not show the reply
information directly to customers. Instead, present an appropriate response that tells
customers the result.

Important Because CyberSource could add reply fields and reason codes at any time, do
the following:
- Parse the reply data according to the names of the fields instead of their order in the
reply. For more information about parsing reply fields, see the documentation for your
client.
- Program your error handler to use the decision field to determine the result if it receives
a reason code that it does not recognize.

Decisions
The reply includes the decision field, which summarizes the results for the entire request.
Look at this field first to determine your course of action. The following table describes
the possible values for decision.

Table 10 Possible Values for the decision Field

Value of decision Description

ACCEPT The request succeeded

ERROR There was a system error

REJECT One or more of the services was declined

REVIEW CyberSource Decision Manager flagged the order for review. See
“Reviews” on page 44.

Errors are due to system issues usually unrelated to the content of the request itself. You
must design your transaction management system to include a way to correctly handle
CyberSource system errors. Depending on which payment processor is handling the
transaction, the error could indicate a valid CyberSource system error, or it could indicate
a processor rejection because of some type of invalid data. In either case, CyberSource
recommends that you do not design your system to endlessly retry sending a transaction
in the case of a system error. See the documentation for the CyberSource client (SDK) you
are using for more information about how to handle system errors and retries.

Credit Card Services Implementation Guide • June 2009 43


Introduction to the API

Requests can be rejected by CyberSource, the payment processor, or the issuing bank. For
example, CyberSource will reject a request if required data is missing or invalid. Also, the
issuing bank will reject a request if the card limit has been reached and funds are not
available. To determine the reason for the reject decision, use the reasonCode field.
You are charged for all accepted, rejected, and reviewed requests. You are not charged for
requests that result in errors.

Reason Codes
After looking at the decision field, use the reasonCode field to determine the reason for
the decision and decide if you want to take further action.
If the decision was ERROR, the reasonCode specifies what type of error occurred.
If the decision was REJECT, the reasonCode specifies the reason for the rejection and
whether you can take action that might result in a successful order. For descriptions of the
reason codes for the Credit Card Services, see Appendix E, “Reason Codes for the Simple
Order API,” on page 283.
The <service>_reasonCode fields specifies the result for each individual service in the
request. For example, if you request a credit card authorization, you receive
ccAuthReply_reasonCode in the reply. These fields are useful for debugging your system.

Note CyberSource reserves the right to add new reason codes at any time. If your error
handler receives a reason code that it does not recognize, it should use the decision field
to determine the result.

Reviews
If you use Decision Manager, you can receive the REVIEW value for the decision field. A
REVIEW means that Decision Manager has flagged the order for review based on how you
configured the Decision Manager rules.
If you set up your system to use the CyberSource ICS services and then subsequently
decide to use Decision Manager, you must determine how to handle the new decision
value of REVIEW. CyberSource recommends that you update your order management
system to recognize the REVIEW response and handle it according to your business rules.
If you cannot update your system to handle the REVIEW response, CyberSource
recommends that you implement one of the following options:

• Treat the REVIEW response like a REJECT response by rejecting orders that are flagged
for review. This might be appropriate if the product you sell is a software download
or access to a Web site and if you authorize and capture the credit card payment at the
same time. You might also want to perform an authorization reversal for the order if
authorization reversals are supported by your processor.
• If you approve the order after reviewing it, convert the order status to ACCEPT in your
order management system. Here you can simply request credit card capture without
requesting a new authorization.

44 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

• If you approve the order after reviewing it but cannot convert the order status to
ACCEPT in your system, request a new authorization for the order. You must disable
Decision Manager when processing this new authorization or the order will be
flagged for review again. See the Decision Manager Developer’s Guide for details about
the API field that disables Decision Manager.
Alternately, you can specify a custom business rule in Decision Manager so that
authorizations originating from a particular internal IP address at your company are
automatically accepted.
You might want to perform an authorization reversal for the original authorization if
authorization reversals are supported by your processor.

Missing or Invalid Fields


You are responsible for ensuring that the data that you send to CyberSource is complete
(no missing fields) and correct (no invalid data). To do this, verify the data entered on
your Web sites and point-of-sale applications before sending the information to
CyberSource.
If you send a request with missing or invalid information, the reply message will include
the appropriate reason codes and one or more reply fields, invalidField_0...N or
missingField_0…N, which list the fields that you need to correct. The services that were
requested and the nature of the missing or invalid information will be used to determine
the number and the content of the reply fields. For example, if three required fields are
missing from the request, the reply will include at least one and up to three reply fields
named missingField_0, missingField_1, and missingField_2. You should correct these
fields and resubmit the request.
Because the API behavior pertaining to these reply fields is always subject to change, do
not use these fields to communicate with customers.

Note For XML, the <missingField> and <invalidField> elements are not numbered.
Instead, the reply includes multiple <missingField> or <invalidField> elements.

If you are using SOAP, you receive an array of the missing fields and an array of the
invalid fields.

Credit Card Services Implementation Guide • June 2009 45


Introduction to the API

Request IDs and Request Tokens

Request IDs and request tokens are identifiers that CyberSource returns in the replies for
all services. You need to store the contents of the request ID and request token fields
because you need these values when you send a request for a follow-on service.

Important Although the names of the request ID and request token fields that you receive
are the same in each reply, the contents of the fields are different. Therefore, you must save
each request ID and request token that you receive.

For more information, see “Working with Request Tokens” on page 38.

Tracking Orders
The API provides different fields that act as identifiers for tracking orders. You can use
the merchant reference code and the reconciliation ID to track your orders.

Merchant Reference Code


The merchantReferenceCode is an order tracking number that you generate and send in
requests so that you can track orders as they move through the different phases of
processing with CyberSource.
CyberSource recommends that you use a unique merchant reference code for each order
and use the same merchant reference code for all the requests associated with the order.
This enables you to efficiently track the order in the CyberSource reports and on the
Transaction Search screens.

Reconciliation ID
Every reply message includes a unique reconciliation ID This value is assigned by
CyberSource. You can use it to reconcile the transactions in your CyberSource reports with
the transactions in your processor reports.
This value is returned in one of these fields, depending on the service you requested:

• ccAuthReply_reconciliationID—This value is returned for only a few processors. See


the description of ccAuthReply_reconciliationID in Table 34 on page 203 for a list of
these processors.
• ccCaptureReply_reconciliationID
• ccCreditReply_reconciliationID

46 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

Authorizing a Credit Card Payment


This section describes how to use the Simple Order API to process credit card
authorizations. The sub-sections listed below describe how to use the basic credit card
features associated with an authorization. See Chapter 3, “Basic Credit Card Features,” on
page 23 to determine if a particular feature is supported for the payment processor you
are using. For API information about optional credit card features, see Chapter 6,
“Optional Features for the Simple Order API,” on page 81.

Topics:
Address Verification Service
Card Verification Numbers
Verbal Authorizations: The Authorization
Reconciliation
Required Fields for Requesting an Authorization

To request a credit card authorization, set the ccAuthService_run field to true. See
“Required Fields for Requesting an Authorization” on page 50 for a list of the fields to use
when requesting the service.
When requesting authorization, do not request any of these other services:

• Full authorization reversal or credit (ccAuthReversalService or ccCreditService)


• Electronic check debit or credit (ecDebitService or ecCreditService)
• Bank transfer or bank transfer refund (bankTransferService or
bankTransferRefundService)
• Direct debit or direct debit refund (directDebitService or directDebitRefundService)
• PayPal® payment or credit (payPalPaymentService or payPalCreditService)

Address Verification Service


AVS verifies that the customer has provided the correct billing address. See “Address
Verification Service” on page 23 for a description of this feature and whether it is
supported for the processor you are using.
AVS does not require you to send extra fields in the request.
The 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 “Address Verification Service Codes” on
page 291 for a list of the codes.

Credit Card Services Implementation Guide • June 2009 47


Authorizing a Credit Card Payment

If the authorization is approved by the issuing bank, but AVS cannot match the street
address or postal code, CyberSource declines the request and returns the AVS code N in
the field ccAuthReply_avsCode. You can still capture the transaction. However, consider
reviewing these orders to make sure they are legitimate.

Note CyberSource, not the issuing bank, assigns the AVS decline to the authorization. You
can capture any authorization that has a valid authorization code from the issuing bank,
even if CyberSource declines the request for AVS reasons.

By default, only the AVS code N results in an AVS decline. You can change this behavior by
using the request-level field businessRules_declineAVSFlags to specify a list of AVS
codes that should result in an AVS decline.

Important If you use the field businessRules_declineAVSFlags, make sure that you
include the value N in the list if you want to receive declines for the AVS code N.

If the request includes the field businessRules_ignoreAVSResult with a value of true,


then you will receive no AVS declines, even if you are using the field businessRules_
declineAVSFlags. 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.

Enhanced AVS and AAV+


If you use American Express Phoenix as your processor and are signed up for Enhanced
AVS or AAV+, you can use the request-level field ccAuthService_avsLevel to specify the
level of AVS to use for the request. This field’s value overrides the default level your
CyberSource merchant ID is configured to use.
There are reply AVS codes that are specific to Enhanced AVS and AAV+. See “Address
Verification Service Codes” on page 291 for a list of the codes.

Card Verification Numbers


The card verification number (CVN), found on the back of the card, can be sent with the
request and verified to help reduce the risk of fraud. See “Card Verification Numbers” on
page 27 for a description of this feature and whether it is supported for the processor you
are using. To use the card verification feature, include the card_cvNumber field in the
request along with the customer’s card verification number.

Result Codes for Card Verification Numbers


See “Address Verification Service Codes” on page 291 for a list of the possible results of
the card verification check. A result of D or N will cause CyberSource to decline the
request with reason code 230.

48 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

If a request includes both ccAuthService and ccCaptureService, and if you receive a card
verification decline for ccAuthService, CyberSource does not process the
ccCaptureService request unless you have set the request field businessRules_
ignoreCVResult to true.

Visa and MasterCard Card Verification Results


The result code is in the ccAuthReply_cvCode field in the reply message. The reply also
includes the ccAuthReply_cvCodeRaw field, which contains the raw card verification
information sent directly from the processor. Do not use this field to handle the card
verification response. Use the value only for debugging purposes.
If the authorization is approved by the issuing bank, but the card verification result is D or
N, CyberSource declines the request and with reason code 230. You can still capture the
transaction. However, consider reviewing these orders to make sure they are legitimate.

Note CyberSource, not the issuing bank, assigns the card verification decline to the
authorization. You can capture any authorization that has a valid authorization code from
the issuing bank, even if the request receives a card verification decline.

If the issuing bank does not authorize the transaction, and the card verification number
does not match, the request is declined because the card is refused. You cannot capture the
transaction.

American Express Card Verification Results


If the card verification number does not match, American Express refuses the card and the
request is declined.
If the ccAuthReply_cvCode value is 1, CyberSource has not yet configured your account
to accept card verification numbers. Contact Customer Support to enable the card
verification feature for your account.
If you want to use the card verification number with American Express, see “Testing
American Express Card Verification” on page 171.

Discover Card Verification Results


If the card verification number does not match, Discover refuses the card and the request
is declined. The reply message will not include a ccAuthReply_cvCode field indicating
that the card verification check failed.

Credit Card Services Implementation Guide • June 2009 49


Authorizing a Credit Card Payment

Verbal Authorizations: The Authorization


A verbal authorization lets you capture a questionable authorization by using an
authorization code that you obtain verbally from the payment processor. See “Verbal
Authorizations” on page 29 for a general description of this feature and whether it is
supported for the processor you are using.

Important Do not use Dynamic Currency Conversion for a verbal authorization.

The authorization part of 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.
2 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.
3 You call the processor to answer questions about the transaction.
4 If the processor verbally authorizes the transaction, you are given a verbal
authorization code.
5 You include the verbal authorization code in your capture request. See “Verbal
Authorizations: The Capture” on page 53.

Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 95.

Required Fields for Requesting an Authorization


The required fields for requesting ccAuthService are:

• billTo_city
• billTo_country
• billTo_email
• billTo_firstName
• billTo_lastName
• billTo_postalCode—required under certain conditions
• billTo_state—required under certain conditions
• billTo_street1
• card_accountNumber

50 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

• 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
• card_expirationYear
• ccAuthService_run
• merchantID
• merchantReferenceCode
• purchaseTotals_currency
• purchaseTotals_grandTotalAmount—either this field or item_#_unitPrice must be
included in the request
See Appendix A, “Fields for the Simple Order API,” on page 173 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

Reversing an Authorization
To request a full authorization reversal, set the ccAuthReversalService_run field to true.
A full authorization reversal is a follow-on transaction that uses the requestID and
requestToken returned from a previous ccAuthService request. These values link the full
authorization reversal to the authorization. Send the request ID value in the
ccAuthReversalService_authRequestID field and send the request token value in the
orderRequestToken field. CyberSource uses these values to look up the customer’s billing
and account information from the original authorization, so you are not required to
include those fields in the ccAuthReversalService request. For information about the
request token, see “Working with Request Tokens” on page 38. See “Reversing an
Authorization” on page 12 for more information about the service and whether it is
supported for the processor you are using.
Do not include any other ICS services in a request for a full authorization reversal. You
cannot partially reverse an authorization; you can reverse an authorization only for its full
amount.

Note Each issuing bank has its own rules that determine whether a full authorization
reversal succeeds. If a reversal request fails, contact the issuing bank to determine if it is
possible to perform the reversal by alternate means.

Credit Card Services Implementation Guide • June 2009 51


Capturing an Authorization

Required Fields for Requesting a Full Authorization Reversal


The required fields for requesting ccAuthReversalService are:

• ccAuthReversalService_run
• ccAuthReversalService_authRequestID
• orderRequestToken
• merchantID
• merchantReferenceCode
• purchaseTotals_currency
• purchaseTotals_grandTotalAmount—either this field or item_#_unitPrice must be
included in the request
See Appendix A, “Fields for the Simple Order API,” on page 173 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

Capturing an Authorization
See Chapter 3, “Basic Credit Card Features,” on page 23 to determine if a particular
authorization feature is supported for the payment processor you are using.

Topics:
Verbal Authorizations: The Capture
Reconciliation
Required Fields for Requesting a Capture

To request the capture of a credit card authorization, set the ccCaptureService_run field to
true. A capture uses the requestID and requestToken returned from a previous
ccAuthService request to link the capture to the authorization. Send the request ID value
in the ccCaptureService_authRequestID field and send the request token value in the
orderRequestToken field. CyberSource uses these values to look up the customer’s billing
and account information from the original authorization, which means you are not
required to supply those fields in the ccCaptureService request. For information about the
request token, see “Working with Request Tokens” on page 38. See “Required Fields for
Requesting a Capture” on page 54 for a list of the fields used when requesting the service.

Note For Carte Bleue cards, your capture request cannot be for less than 0.99 euros.

52 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

When you request a capture, do not request any of these other services at the same time:

• Full authorization reversal or credit (ccAuthReversalService or ccCreditService)


• Electronic check debit or credit (ecDebitService or ecCreditService)
• Bank transfer or bank transfer refund (bankTransferService or
bankTransferRefundService)
• Direct debit or direct debit refund (directDebitService or directDebitRefundService)
• PayPal payment or credit (payPalPaymentService or payPalCreditService)

Note You cannot include a request for Advanced Fraud Screen (afsService) in a follow-on
request for ccCaptureService. For information about the service, see the Decision Manager
Developer’s Guide, which is available at the Support Center.

Verbal Authorizations: The Capture


A verbal authorization enables you to capture a questionable authorization by using an
authorization code that you obtain verbally from the payment processor. See “Verbal
Authorizations” on page 29 for a general description of this feature and whether it is
supported for the processor you are using.

Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 95.

The authorization part of a verbal authorization is described in “Verbal Authorizations:


The Authorization” on page 50. The capture part of a verbal authorization works as
follows:

• Send the verbal authorization code in the ccCaptureService_verbalAuthCode request


field.
• Send the word verbal in the ccCaptureService_authType field.

Note You must set the ccCaptureService_authType field to verbal or else the
ccCaptureService_verbalAuthCode field will be ignored.

• For the American Express card type on FDMS South, the ccCaptureService_posData
and ccCaptureService_transactionID fields are required to support the CAPN
requirements.
When you perform 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 zero-fills the transaction ID. American
Express has indicated that capture requests submitted without a valid transaction ID,

Credit Card Services Implementation Guide • June 2009 53


Capturing an Authorization

including transactions that originated as verbal authorizations, may incur additional


transaction charges. Check with your American Express account representative to
determine if your processing may be impacted by these additional transaction
charges.

Reconciliation
Reconciliation allows you to verify that your transaction records are consistent with your
payment processor’s statement. See “Reconciliation” on page 31 for a description of this
feature and whether it is supported for the processor you are using.
The unique reference number that you use to reconcile the transaction is in the
ccCaptureReply_reconciliationID reply field.

Note If you perform multiple partial captures against an authorization, each reply
includes a different reference number in ccCaptureReply_reconciliationID for each
capture request. Table 4 on page 15 indicates which payment processors support multiple
partial captures.

Required Fields for Requesting a Capture


The required fields for requesting ccCaptureService are:

• ccCaptureService_run
• ccCaptureService_authRequestID—optional if ccAuthService and ccCaptureService
are in the same request
• orderRequestToken—optional if ccAuthService and ccCaptureService are in the
same request
• merchantID
• merchantReferenceCode
• purchaseTotals_currency
• purchaseTotals_grandTotalAmount—either this field or item_#_unitPrice must be
included in the request
See Appendix A, “Fields for the Simple Order API,” on page 173 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

54 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

Crediting a Payment
To request a credit card credit, set the ccCreditService_run field to true. When you
request a credit, do not request any of these other services at the same time:

• Any other credit card services (ccAuthService, ccAuthReversalService, or


ccCaptureService)
• Electronic check debit or credit (ecDebitService or ecCreditService)
• Bank transfer or bank transfer refund (bankTransferService or
bankTransferRefundService)
• Direct debit or direct debit refund (directDebitService or directDebitRefundService)
• PayPal payment or credit (payPalPaymentService or payPalCreditService)

Follow-On Credits
A follow-on credit uses the requestID and requestToken returned from a previous
ccCaptureService request to link the credit to the capture. Send the request ID value in the
ccCreditService_captureRequestID field and send the request token value in the
orderRequestToken field. CyberSource uses these values to look up the customer’s billing
and account information from the original authorization, which means that you are not
required to include those fields in the ccCreditService request. For information about the
request token, see “Working with Request Tokens” on page 38.

Important If you combine a request for a follow-on credit with a request for another
service, such as Tax Calculation, you must supply the customer’s billing and account
information.

You can do multiple partial follow-on credits. Send the same ccCreditService_
captureRequestID and the same orderRequestToken in each follow-on ccCreditService
request.

Note If you are using the Global Payment Service, you can process only one follow-on
credit against a specific captured authorization each day. For example, if you want to first
process a follow-on credit of $15 against an original capture of $50, and then later that day
you want to process a follow-on credit of $35 against the same capture, you must request
the two credits on two separate days.

Credit Card Services Implementation Guide • June 2009 55


Crediting a Payment

Stand-Alone Credits
A stand-alone credit does not link the credit to a previous request for ccCaptureService.
Instead of sending the ccCreditService_captureRequestID and orderRequestToken
fields in the credit request, the request must include the fields for the customer’s billing
and account information.

Note You cannot automatically do stand-alone credits for cards processed through the
CyberSource Global Payment Service. Contact Customer Support if you want to do stand-
alone credits with the Global Payment Service.

Reconciliation
Reconciliation enables you to verify that your transaction records are consistent with your
payment processor’s statement. See “Reconciliation” on page 31 for a description of this
feature and whether it is supported for the processor you are using. The unique reference
number for reconciling the transaction is in the ccCreditReply_reconciliationID reply
field.

Required Fields for Requesting a Credit


The required fields for requesting ccCreditService are:

• ccCreditService_run
• ccCreditService_captureRequestID—required only for follow-on credits
• orderRequestToken —required only for follow-on credits
• merchantID
• merchantReferenceCode
• purchaseTotals_currency
• purchaseTotals_grandTotalAmount—either this field or item_#_unitPrice must be
included in the request
• billTo_city—required only for stand-alone credits
• billTo_country—required only for stand-alone credits
• billTo_email—required only for stand-alone credits
• billTo_firstName—required only for stand-alone credits
• billTo_lastName—required only for stand-alone credits
• billTo_postalCode—required under certain conditions
• billTo_state—required under certain conditions

56 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API

• card_accountNumber—required only for stand-alone credits


• 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—required only for stand-alone credits and only for processors
not listed in the following note
• card_expirationYear—required only for stand-alone credits and only for processors
not listed in the following note

Note The expiration month and expiration year are not required for the following
processors:
- American Express Direct
- American Express Phoenix
- Chase Paymentech Solutions
- FDI Global
- FDMS Nashville
- FDMS South
- TSYS Acquiring Solutions

See Appendix A, “Fields for the Simple Order API,” on page 173 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

Voiding a Capture or Credit


This section describes how to use the Simple Order API to void captures and credits. See
“Voiding a Capture or Credit” on page 20 for important information about when you
should use the service, and to determine if the service is supported for your payment
processor.
To request a void, set the voidService_run field to true. A void uses the requestID and
requestToken returned from a previous service request to link the void to the service.
Send the request ID value in the voidService_voidRequestID field and send the request
token value in the orderRequestToken field. CyberSource uses these values to look up the
customer’s billing and account information from the previous request or service, which
means that you are required to include those fields in the voidService request. For
information about the request token, see “Working with Request Tokens” on page 38.
When you request a void, do not request any other ICS services at the same time.

Credit Card Services Implementation Guide • June 2009 57


Voiding a Capture or Credit

Required Fields for Requesting a Void


The required fields for requesting voidService are:

• voidService_run
• voidService_voidRequestID
• orderRequestToken
• merchantID
• merchantReferenceCode
See Appendix A, “Fields for the Simple Order API,” on page 173 for:

• Detailed descriptions of these required request fields


• Reply fields

58 CyberSource Corporation
Chapter 5
Payment Processing with the SCMP API

The SCMP API is CyberSource’s older, legacy API. If you are starting your first
implementation with CyberSource, you need to use the Simple Order API instead of the
SCMP API.

Topics:
Introduction to the API
Authorizing a Credit Card Payment
Reversing an Authorization
Capturing an Authorization
Crediting a Payment
Voiding a Capture or Credit

Introduction to the API


The Simple Commerce Messaging Protocol (SCMP) API uses industry-standard Triple
DES encryption to secure messages between your company and CyberSource. With this
API, you use name-value pairs to access the ICS services.

Topics:
Multi-Byte Character Support for the ICS Services
SCMP API Clients
Working with Request Tokens
About Requests
Using Offers or a Grand Total in the Request
Requesting a Follow-on Service
Handling Replies
Tracking Orders

Credit Card Services Implementation Guide • June 2009 59


Introduction to the API

Multi-Byte Character Support for the ICS Services


CyberSource supports multi-byte characters for all ICS services except Delivery Address
Verification, Stored Value, and Customer Profiles, which was previously called the
Subscription Payment Services. Before implementing any of these particular services,
contact Customer Support to clarify any questions you have about multi-byte character
support. See the Support Center for documentation about these services.
For the SCMP API, the Java client (version 3.7.7 or newer) and the .NET client support
UTF-8. All of the other clients support ISO-8859-1.

SCMP API Clients


To use the SCMP API, you must first choose a client integration or development kit. The
SCMP API clients contain the following:

• Client libraries used to communicate with CyberSource and access the ICS services
• Security libraries used to digitally sign the messages
• Sample code for digitally signing the messages and using the client libraries
For the latest list of available SCMP API clients and related documentation, go to the
SCMP Clients portion of the Downloads page on the CyberSource Support Center.

Working with Request Tokens


The request_token is a unique identifier that CyberSource assigns to each request and
returns to you in each reply. This field is an encoded string that does not contain any
confidential information, such as account numbers or card verification numbers. You need
to store this value, which is a string that can contain up to 256 characters. Depending on
how you process follow-on requests, you might need to retrieve the request token value
and send it in the order_request_token field in your follow-on service requests:

• If you process primary requests with an API, but process follow-on requests through
the Business Center, you do not need to change how you use the Business Center or
provide the request token data at this time.
• If you process primary and follow-on requests with an API, you need to retrieve the
request token from the primary reply message and include the request token in the
follow-on request message:
Primary Reply Message: request_token=AA4JUrWguaMUGwxSWVdPS5IM
Follow-on Request: order_request_token=AA4JUrWguaMUGwxSWVdPS5IM

60 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

Existing Merchants Who Have Not Implemented Request Tokens


If you were a CyberSource merchant before July 2008 and never implemented request
tokens, you have these choices:

• You can implement the request token as described in this document. CyberSource
recommends that you use this option.
• You can let CyberSource store the request token data for you and retrieve it for you as
necessary when you send follow-on requests.

Existing Merchants Who Have Implemented Request Tokens


If you were a CyberSource merchant before July 2008 and implemented request tokens,
your implementation uses a different field name for the request token that is sent to each
different follow-on service. With the new implementation, you would use the order_
request_token field for all follow-on services. This approach makes it easier to manage
the request token values. It also reduces the likelihood of submitting a duplicate request
by accidentally sending in the wrong request token value. You have these choices:

• You can continue to use your current implementation at this time. It is still supported,
but CyberSource recommends that you update your implementation to use the order_
request_token field.
• You can update your implementation to store the latest request token for a transaction
in one database field to return with all follow-on services for the transaction:
Figure 6

Credit Card Services Implementation Guide • June 2009 61


Introduction to the API

• You can update your implementation without changing your database. Store the
latest request token for a transaction in all of your existing request token database
fields so that any follow-on request for the transaction will return the latest request
token value:

Note The following figure uses the request field names for the Credit Card services. If
you are using a different set of services, such as PayPal services, Electronic Check
services, or Global Payment services, substitute the request field names for the
services you are using.

Figure 7

For more information about request tokens, see the Request Token Planning Guide.

About Requests
The Simple Commerce Messaging Protocol (SCMP) uses industry-standard Triple DES
encryption to secure messages between your company and CyberSource. A request for
ICS services contains general information and information specific to the services you are
requesting. General information includes information about you, the merchant; about the
customer and their form of payment; and about the items the customer is buying.

Using Offers or a Grand Total in the Request


For some services, you must specify the amount of the transaction. You can provide either
the individual products the consumer is purchasing or a grand total for the transaction.

62 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

Note If you are using Decision Manager, CyberSource recommends that you provide
individual item information instead of a grand total for the order. Decision Manager can
be configured to use the individual item information to assess the risk of the order and
determine if the purchaser is following your business rules. For more information about
Decision Manager, see the Decision Manager Developer’s Guide.

Using Offers
Offers are the products that the customer purchases from you. When you send a request
for a service that requires an amount, you can send offer-specific information, such as the
quantity of each product ordered and the unit price for each product. The offers are
referred to as offer0, offer1, offer2, and so on. CyberSource uses the information you
provide for each offer to calculate the grand total for the order.
Each offer line contains one or more offer-level fields that describe the product. The offer-
level fields are quantity, amount, product_code, product_name, merchant_product_sku,
and tax_amount. Offer-level field names and values are separated by colons (:) and carets
(^) in the following format:
offerN=<field name>:<field value>^<field name>:<field value>^...
The values of the offer-level fields cannot contain carets (^) or colons (:) because these
characters indicate the start of the next field name or field value.
Required Offer-Level Fields
If you are using the offer-level fields, which fields are required depends on the value you
use for product_code. If product_code is one of the following values:

• default
• stored_value
• a value related to shipping and handling
or if you omit product_code, which causes it to default to the value default, then the
only required field is amount. If you do not set quantity, it defaults to 1.
If you do not set product_code to one of the values in the previous list, the following
fields are required:

• amount
• quantity
• product_name
• merchant_product_sku
The tax_amount field is always optional.

Credit Card Services Implementation Guide • June 2009 63


Introduction to the API

Specifying Tax
To include tax for an offer, use the tax_amount field. This value is the total tax for the
entire quantity of that product. In other words, the value is not multiplied by quantity. For
example:

offer0=amount:10.00^quantity:5^tax_amount:4.00

The grand total for this transaction is (10.00 * 5) + 4.00 = 54.00.


Specifying Freight Charges
To include a shipping and handling charge for the order, you must include an additional
offer with product_code set to one of the following values:

• shipping_only
• handling_only
• shipping_and_handling

For example:

offer0=amount:10.00^quantity:5^tax_amount:4.00
offer1=amount:4.95^quantity:1^product_code:shipping_only

The grand total for this transaction is (10.00 * 5) + 4.00 + (4.95 * 1) = 58.95.

Using a Grand Total


Instead of using offers, you can send a grand total for the order in the grand_total_
amount field. This field is useful if you do not have information for each offer or do not
care about the information for each offer and simply want to use a transaction total. If you
include grand_total_amount in your request, CyberSource uses this value and does not
use offer-level information to calculate the transaction’s grand total. If you provide offer-
level information in addition to the grand total, the offer-level information is displayed on
the Transaction Detail page in the Business Center.

Important If you include grand_total_amount in your request, you cannot include the Tax
Calculation service as part of the request. See the Tax Calculation Implementation Guide.

64 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

Requesting a Follow-on Service

A request for a follow-on service must include a request ID and a request token:
1 Save the request ID and request token from the reply for the primary service. Here is
an example of the fields you will receive in the reply message:
request_id=0305782650000167905080
request_token=AA4JUrWguaMUGwxSWVdPS5IM
2 Send those values in the follow-on request. For the request token, use the following
field:
order_request_token=AA4JUrWguaMUGwxSWVdPS5IM
For the request ID, the field name depends on the names of the primary service and
follow-on service. For more information, see the description of the follow-on service
or the tables of field descriptions.
Follow-on services covered in this guide:

• ics_bill
• ics_credit
• ics_auth_reversal
• ics_void
For more information, see “Working with Request Tokens” on page 60.

Handling Replies
The reply contains the result of the request, which can be one of the following:

• Success
• Decline
• Error
Requests can be declined by CyberSource, the payment processor, or the issuing bank. For
example, CyberSource will decline a request if required data is missing or invalid. Also,
the issuing bank will decline a request if the card limit has been reached and funds are not
available. You are charged for all transactions that result in declines.
Errors are due to system issues unrelated to the content of the request itself. You are not
charged for transactions that result in errors.
Like SCMP requests, SCMP replies include fields that contain name-value pairs. Several
fields summarize the results for the entire request and additional fields provide the results
for each service in the request. For the overall request, they are ics_rcode, ics_rflag, and
ics_rmsg. For the individual services, they are <service>_rcode, <service>_rflag, and

Credit Card Services Implementation Guide • June 2009 65


Introduction to the API

<service>_rmsg, where <service> represents the service. For example, if you request ics_
auth, you receive auth_rcode, auth_rflag, and auth_rmsg in the reply. See “Authorizing a
Credit Card Payment” on page 68 for an example reply.

Important Because CyberSource can add reply fields, reply codes, and reply flags at any
time, do the following:
- Parse the reply data according to the names of the fields instead of their order in the
reply. For more information about parsing reply fields, see the documentation for your
client.
- Program your error handler to process these new reply flags without problems.

The reply code, or rcode, contains a one-digit number that indicates whether the request
resulted in a success, a decline, or an error:

• Success: 1
• Decline: 0
• Error: -1
The reply flag, or rflag, contains a one-word value that gives more information about the
result:

• Success: SOK
• Decline: A value starting with D, for example, DMISSINGFIELD
• Error: A value starting with E, for example, ESYSTEM. See the documentation for
your CyberSource client (SDK) for important information about how to handle
system errors and retries.

Note If you receive the ESYSTEM flag in your reply along with the following error
message, your system’s clock is incorrect. You must adjust your system’s clock for
your time zone; otherwise your transactions will be rejected.

Error message: The request ID generated by your client is incorrect because your
system's clock does not match your local time. Please adjust your system's clock to
your local time, and resend your request.

See Appendix F, “Reply Flags for the SCMP API,” on page 287 for a list of possible reply
flags.
The reply message, or rmsg, contains more detailed information about the result of the
request. Do not code to the reply message, as the messages can change without notice.
Write an error handler to interpret the reply codes and reply flags in the reply messages.
Do not show the reply information or error messages directly to customers. Instead,

66 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

present an appropriate response that tells customers the result. See the documentation for
your CyberSource software developer kit for details on how to handle the replies.
To use the reply information, you must integrate it into your system and any other system
that uses that data. This includes storing the data and passing it to any other systems that
need the information.

Note CyberSource reserves the right to add new reply flags and codes at any time. Write
your error handler so that it can process these new reply flags without problems.

Request IDs and Request Tokens

Request IDs and request tokens are identifiers that CyberSource returns in the replies for
all services. You need to store the contents of the request ID and request token fields
because you need these values when you send a request for a follow-on service.

Important Although the names of the request ID and request token fields that you receive
are the same in each reply, the contents of the fields are different. Therefore, you must save
each request ID and request token that you receive.

For more information, see “Working with Request Tokens” on page 60.

Tracking Orders
The API provides different fields that act as identifiers for tracking orders. You can use
the merchant reference number and the transaction reference number to track your
orders.

Merchant Reference Number


The merchant_ref_number is an order tracking number that you generate and send in
requests so that you can track orders as they move through the different phases of
processing with CyberSource.
CyberSource recommends that you use a unique merchant reference number for each
order and use the same merchant reference number for all the requests associated with the
order. This enables you to efficiently track the order in the CyberSource reports and on the
Transaction Search screens.

Credit Card Services Implementation Guide • June 2009 67


Authorizing a Credit Card Payment

Transaction Reference Number


Every reply message includes a unique transaction reference number. This value is
assigned by CyberSource. You can use it to reconcile the transactions in your CyberSource
reports with the transactions in your processor reports.
This value is returned in one of these fields, depending on the service you requested:

• auth_trans_ref_no—This value is returned for only a few processors. See the


description of auth_trans_ref_no in Table 37 on page 240 for a list of these processors.
• bill_trans_ref_no
• credit_trans_ref_no

Authorizing a Credit Card Payment


This section describes how to use the SCMP API to process credit card authorizations. The
various sub-sections describe how to use the credit card features associated with an
authorization. See Chapter 3, “Basic Credit Card Features,” on page 23 to determine if a
particular feature is supported for the payment processor you are using.

Topics:
Address Verification Service
Card Verification Numbers
Verbal Authorizations: The Authorization
Reconciliation
Required Fields for Requesting an Authorization

Use the ics_auth service to request credit card authorization. See “Required Fields for
Requesting an Authorization” on page 71 for a list of the ics_auth fields.
When requesting authorization, do not request any of these other services:

• Full authorization reversal or credit (ics_auth_reversal or ics_credit)


• Electronic check debit or credit (ics_ecp_debit or ics_ecp_credit)
• Bank transfer or bank transfer refund (ics_bank_transfer or
ics_bank_transfer_refund)
• Direct debit or direct debit refund (ics_direct_debit or ics_direct_debit_refund)
• PayPal payment or credit (ics_paypal_payment or ics_paypal_credit)
• Risk update (ics_risk_update)
For more information, see the Decision Manager Implementation Guide, which is
available at the Support Center.

68 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

Address Verification Service


AVS verifies that the customer has provided the correct billing address. See “Address
Verification Service” on page 23 for a description of this feature and whether it is
supported for the processor you are using.
AVS does not require you to send extra fields in your request.
The reply includes the auth_auth_avs 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 “Address Verification Service Codes” on page 291 for a list of
the codes.
If the authorization is approved by the issuing bank, but AVS cannot match the street
address or postal code, CyberSource declines the request and returns an AVS decline reply
flag (auth_rflag = DAVSNO) and the AVS code N. You can still capture the transaction.
However, consider reviewing these orders to make sure they are legitimate.

Note CyberSource, not the issuing bank, assigns the DAVSNO decline to the
authorization. You can capture any authorization that has a valid authorization code from
the issuing bank, even if the request receives the DAVSNO reply flag.

By default, only the AVS code N results in an AVS decline. You can change this behavior by
using the request-level field decline_avs_flags to specify a comma-separated list of AVS
codes that should result in an AVS decline.

Important If you use the decline_avs_flags field, make sure that you include the value N
in the comma-separated list if you want to receive declines for the AVS code N.

If the request includes the ignore_avs field with a value of yes, then you will receive no
AVS declines, even if you are using the decline_avs_flags field.
The auth_avs_raw 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.

Enhanced AVS and AAV+


If you use American Express Phoenix as your processor and are signed up for Enhanced
AVS or AAV+, you can use the request-level field avs_level to specify the level of AVS to
use for the request. This field’s value overrides the default level your CyberSource
merchant ID is configured to use.
There are reply AVS codes that are specific to Enhanced AVS and AAV+. See “Address
Verification Service Codes” on page 291 for a list of the codes.

Credit Card Services Implementation Guide • June 2009 69


Authorizing a Credit Card Payment

Card Verification Numbers


The card verification number, found on the back of the card, can be sent with the request
and verified to help reduce the risk of fraud. See “Card Verification Numbers” on page 27
for a description of this feature and whether it is supported for the processor you are
using. To use the card verification feature, include the customer_cc_cv_number field in
the request along with the customer’s card verification number.

Result Codes for Card Verification Numbers


See Appendix H, “Card Verification Number Codes,” on page 295 for a list of the possible
results of the card verification check. A result of D or N will cause CyberSource to decline
the request with reply flag DCV.
If a request includes both ics_auth and ics_bill, and if you receive a card verification
decline for ics_auth, CyberSource does not process the ics_bill unless you set the request
field ignore_bad_cv to yes.

Visa and MasterCard Card Verification Results


The result code is in the auth_cv_result field in the reply message. The reply also includes
the auth_cv_result_raw field, which contains the raw card verification information sent
directly from the processor. Do not use this field to handle the card verification response.
Use the value only for debugging purposes.
If the authorization is approved by the issuing bank, but the card verification result is D or
N, CyberSource declines the request and returns the DCV reply flag. You can still capture
the transaction. However, consider reviewing these orders to make sure they are
legitimate.

Note CyberSource, not the issuing bank, assigns the DCV decline to the authorization.
You can capture any authorization that has a valid authorization code from the issuing
bank, even if the request receives the DCV reply flag.

If the issuing bank does not authorize the transaction, and the card verification number
does not match, the reply message includes a DCARDREFUSED reply flag. You cannot
capture the transaction.

American Express Card Verification Results


If the card verification number does not match, American Express declines the card and
the reply message includes a DCARDREFUSED reply flag.
If the auth_cv_result value is 1, CyberSource has not yet configured your account to
accept card verification numbers. Contact Customer Support to enable the card
verification feature for your account.
If you want to use the card verification number with American Express, see “Testing
American Express Card Verification” on page 171.

70 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

Discover Card Verification Results


If the card verification number does not match, Discover declines the card and the reply
message includes a DCARDREFUSED reply flag instead of a DCV reply flag. The reply
message will not include a code in the auth_cv_result field indicating that the card
verification check failed.

Verbal Authorizations: The Authorization


A verbal authorization lets you capture a questionable authorization by using an
authorization code that you obtain verbally from the payment processor. See “Verbal
Authorizations” on page 29 for a general description of this feature and whether it is
supported for the processor you are using.

Important Do not use Dynamic Currency Conversion for a verbal authorization.

The authorization part of a verbal authorization works as follows:


1 The authorization reply includes a DCALL reply flag indicating that the issuing bank
is requiring a verbal authorization.
2 For an American Express card with FDMS Nashville, the authorization reply also
includes a referral response number in auth_referral_response_number. You will be
asked for this number, which identifies the failed transaction, when you call American
Express for the verbal authorization.
3 You call the processor to answer questions about the transaction.
4 If the processor verbally authorizes the transaction, you are given a verbal
authorization code.
5 You include the verbal authorization code in your capture request. See “Verbal
Authorizations: The Capture” on page 74.

Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 139.

Required Fields for Requesting an Authorization


The required fields for requesting ics_auth are:

• bill_address1
• bill_city
• bill_country
• bill_state—required under certain conditions
• bill_zip—required under certain conditions

Credit Card Services Implementation Guide • June 2009 71


Reversing an Authorization

• card_type—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.
• currency
• customer_cc_expmo
• customer_cc_expyr
• customer_cc_number
• customer_email
• customer_firstname
• customer_lastname
• grand_total_amount—either this field or offer0 and amount must be included in the
request
• ics_applications
• merchant_id
• merchant_ref_number
See Appendix B, “Fields for the SCMP API,” on page 213 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

Reversing an Authorization
To request a full authorization reversal, call the ics_auth_reversal service. A full
authorization reversal is a follow-on transaction that uses the request_id and request_
token returned from a previous ics_auth request. These values link the full authorization
reversal to the authorization. Send the request ID value in the auth_request_id field and
send the request token value in the order_request_token field. CyberSource uses these
values to look up the customer’s billing and account information from the original
authorization, so you are not required to include those fields in the ics_auth_reversal
request. For information about the request token, see “Working with Request Tokens” on
page 60. See “Reversing an Authorization” on page 12 for more information about the
service and whether it is supported for the processor you are using.
Do not include any other ICS services in a request for a full authorization reversal. You
cannot partially reverse an authorization; you can reverse an authorization only for its full
amount.

72 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

Note Each issuing bank has its own rules that determine whether a full authorization
reversal succeeds. If a reversal request fails, contact the issuing bank to determine if it is
possible to perform the reversal by alternate means.

Required Fields for Requesting a Full Authorization Reversal


The required fields for requesting ics_auth_reversal are:

• ics_applications
• auth_request_id
• order_request_token
• currency
• grand_total_amount—either this field or offer0 and amount must be included in the
request
• merchant_id
• merchant_ref_number
See Appendix B, “Fields for the SCMP API,” on page 213 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

Capturing an Authorization
See Chapter 3, “Basic Credit Card Features,” on page 23 to determine if a particular
feature is supported for the payment processor you are using.

Topics:
Verbal Authorizations: The Capture
Reconciliation
Required Fields for Requesting a Capture

Use the ics_bill service to capture a credit card authorization. A capture uses the request_
id and request_token returned from a previous ics_auth request to link the capture to the
authorization. Send the request ID value in the auth_request_id field and send the request
token value in the order_request_token field. CyberSource uses these values to look up
the customer’s billing and account information from the original authorization, which
means you are not required to supply those fields in the ics_bill request. For information

Credit Card Services Implementation Guide • June 2009 73


Capturing an Authorization

about the request token, see “Working with Request Tokens” on page 60. See “Required
Fields for Requesting a Capture” on page 75 for a list of the ics_bill fields.

Note For Carte Bleue cards, your capture request cannot be for less than 0.99 euros.

When you request a capture, do not request any of these other services at the same time:

• Full authorization reversal or credit (ics_auth_reversal or ics_credit)


• Electronic check debit or credit (ics_ecp_debit or ics_ecp_credit)
• Bank transfer or bank transfer refund (ics_bank_transfer or
ics_bank_transfer_refund)
• Direct debit or direct debit refund (ics_direct_debit or ics_direct_debit_refund)
• PayPal payment or credit (ics_paypal_payment or ics_paypal_credit)
• Risk update (ics_risk_update)
For more information, see the Decision Manager Developer’s Guide, which is available at
the Support Center.

Note You cannot include a request for Advanced Fraud Screen (ics_score) or Digital
Delivery (ics_elc) in a follow-on request for ics_bill. For more information about
these services, see the Decision Manager Developer’s Guide and the Digital Delivery
Implementation Guide, which are available at the Support Center.

Verbal Authorizations: The Capture


A verbal authorization enables you to capture a questionable authorization by using an
authorization code that you obtain verbally from the payment processor. See “Verbal
Authorizations” on page 29 for a general description of this feature and whether it is
supported for the processor you are using.

Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 139.

The authorization part of a verbal authorization is described in “Verbal Authorizations:


The Authorization” on page 71. The capture part of a verbal authorization works as
follows:

• Send the verbal authorization code in the auth_code field in the ics_bill request.
• Send the word verbal in the auth_type field in the ics_bill request.

Note You must set the auth_type field to verbal or else the auth_code field will be
ignored.

74 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

• For the American Express card type on FDMS South, the bill_pos_data and bill_
transaction_id fields are required to support the CAPN requirements.
When you perform 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 zero-fills the transaction ID. American
Express has indicated that capture requests submitted without a valid transaction ID,
including transactions that originated as verbal authorizations, may incur additional
transaction charges. Check with your American Express account representative to
determine if your processing may be impacted by these additional transaction
charges.

Reconciliation
Reconciliation allows you to verify that your transaction records are consistent with your
payment processor’s statement. See “Reconciliation” on page 31 for a description of this
feature and whether it is supported for the processor you are using.
The unique reference number that you use to reconcile the transaction is in the bill_trans_
ref_no reply field.

Note If you perform multiple partial captures against an authorization, each reply
includes a different reference number in bill_trans_ref_no for each capture request.
Table 4 on page 15 indicates which payment processors support multiple partial captures.

Required Fields for Requesting a Capture


The required fields for requesting ics_bill are:

• ics_applications
• auth_request_id—optional if ics_auth and ics_bill are in the same request
• order_request_token—optional if ics_auth and ics_bill are in the same request
• currency
• grand_total_amount—either this field or offer0 and amount must be included in the
request
• merchant_id
• merchant_ref_number

Credit Card Services Implementation Guide • June 2009 75


Crediting a Payment

See Appendix B, “Fields for the SCMP API,” on page 213 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

Crediting a Payment
To request a credit card credit, request the ics_credit service. When you request a credit,
do not request any of these other services at the same time:

• Any other credit card services (ics_auth, ics_auth_reversal, or ics_bill)


• Electronic check debit or credit (ics_ecp_debit or ics_ecp_credit)
• Bank transfer or bank transfer refund (ics_bank_transfer or
ics_bank_transfer_refund)
• Direct debit or direct debit refund (ics_direct_debit or ics_direct_debit_refund)
• PayPal payment or credit (ics_paypal_payment or ics_paypal_credit)
• Risk update (ics_risk_update)—For more information, see the Decision Manager
Developer’s Guide, which is available at the Support Center.
• Stored Value redeem (ics_redeem_isv)—For more information, see the Stored Value
Implementation Guide, which is available at the Support Center.

76 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

Follow-On Credits
A follow-on credit uses the request_id and request_token returned from a previous ics_
bill request to link the credit to the capture. Send the request ID value in the bill_request_
id field and send the request token value in the order_request_token field. CyberSource
uses these values to look up the customer’s billing and account information from the
original authorization, which means that you are not required to include those fields in
the ics_credit request. For information about the request token, see “Working with
Request Tokens” on page 60.

Important If you combine a request for a follow-on credit with a request for another
service, such as ics_tax, you must supply the customer’s billing and account information.

You can do multiple partial follow-on credits. Send the same bill_request_id and the
same order_request_token in each follow-on ics_credit request.

Note If you are using the Global Payment Service, you can process only one follow-on
credit against a specific captured authorization each day. For example, if you want to first
process a follow-on credit of $15 against an original capture of $50, and then later that day
you want to process a follow-on credit of $35 against the same capture, you must request
the two credits on two separate days.

Stand-Alone Credits
A stand-alone credit does not link the credit to a previous request for ics_bill. Instead of
sending the bill_request_id and order_request_token fields, the request must include the
fields for the customer’s billing and account information.

Note You cannot automatically do stand-alone credits for cards processed through the
CyberSource Global Payment Service. Contact Customer Support if you want to do stand-
alone credits with the Global Payment Service.

Reconciliation
Reconciliation enables you to verify that your transaction records are consistent with your
payment processor’s statement. See “Reconciliation” on page 31 for a description of this
feature and whether it is supported for the processor you are using. The unique reference
number for reconciling the transaction is in the credit_trans_ref_no reply field.

Credit Card Services Implementation Guide • June 2009 77


Crediting a Payment

Required Fields for Requesting a Credit


The required fields for requesting ics_credit are:

• ics_applications
• bill_request_id—required only for follow-on credits
• order_request_token—required only for follow-on credits
• merchant_id
• merchant_ref_number
• currency
• grand_total_amount—either this field or offer0 and amount must be included in the
request
• bill_address1—required only for stand-alone credits
• bill_city—required only for stand-alone credits
• bill_country—required only for stand-alone credits
• bill_state—required under certain conditions
• bill_zip—required under certain conditions
• card_type—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.
• customer_cc_expmo—required only for stand-alone credits and only for processors
not listed in the following note
• customer_cc_expyr—required only for stand-alone credits and only for processors
not listed in the following note

Note The expiration month and expiration year are not required for the following
processors:
- American Express Direct
- American Express Phoenix
- Chase Paymentech Solutions
- FDI Global
- FDMS Nashville
- FDMS South
- TSYS Acquiring Solutions

78 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API

• customer_cc_number—required only for stand-alone credits


• customer_email—required only for stand-alone credits
• customer_firstname—required only for stand-alone credits
• customer_lastname—required only for stand-alone credits
See Appendix B, “Fields for the SCMP API,” on page 213 for:

• Detailed descriptions of these required request fields


• Optional request fields
• Reply fields

Voiding a Capture or Credit


This section describes how to use the ics_void service to void captures and credits. See
“Voiding a Capture or Credit” on page 20 for important information about when you
should use the service, and to determine if the service is supported for your payment
processor. A void uses the request_id and request_token returned from a previous
service request to link the void to the service. Send the request ID value in the void_
request_id field and send the request token value in the order_request_token field.
CyberSource uses these values to look up the customer’s billing and account information
from the previous request or service, which means that you are required to include those
fields in the ics_void request. For information about the request token, see“Working with
Request Tokens” on page 60. When you request a void, do not request any other ICS
services at the same time.

Required Fields for Requesting a Void


The required fields for requesting ics_void are:

• ics_applications
• void_request_id
• order_request_token
• merchant_id
• merchant_ref_number
See Appendix B, “Fields for the SCMP API,” on page 213 for:

• Detailed descriptions of these required request fields


• Reply fields

Credit Card Services Implementation Guide • June 2009 79


Voiding a Capture or Credit

80 CyberSource Corporation
Chapter 6
Optional Features for the Simple Order API

This chapter describes the optional features and includes information about
implementing them with the Simple Order API.

Topics:
$0 Authorizations Merchant Descriptors
Airline Data Micropayments
American Express Prepaid Cards Multi-Currency Service
AVS Only Payer Authentication
Bill Me Later POS Transactions
Bill Payments with Visa Prepaid Cards
Cash Advances Recurring Billing
Coupons Recurring Payments
Customer Profiles Recurring Profiles
Dynamic Currency Conversion (DCC) Retail POS Data
Encoded Account Numbers Secure Data
Forced Captures Soft Descriptors
Gift Cards Split Dial/Route
Guaranteed Exchange Rates Subscriptions
Japanese Payment Options Switch and Solo Cards
JCB J/Secure Type II Cards
Level II Data Verbal Authorizations
Level III Data Verified by Visa
Maestro (UK Domestic) and Solo Cards
MasterCard SecureCode

Credit Card Services Implementation Guide • June 2009 81


$0 Authorizations

$0 Authorizations
Applicable services:
• Authorization
Supported processors:
• American Express Direct
• Chase Paymentech Solutions
• FDI Global
• FDMS South
• GPN
• OmniPay-Ireland
• TSYS Acquiring Solutions
By performing an authorization for $0, you can see if a credit card account is valid and
whether the card is lost or stolen. You cannot process a capture for a $0 authorization.

Airline Data
Applicable services:
• Authorization
• Capture
• Credit
For information about airline data, including the list of processors for which CyberSource
supports airline data, see the Airline Data Addendum, which is available at the Support
Center.

82 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

American Express Prepaid Cards


Applicable services:
• Authorization
Supported processors:
• American Express Direct
• FDMS Nashville
• FDMS South
American Express prepaid cards are processed using the same services as credit cards:
authorization, capture, credit, and void. If there is a balance remaining on a prepaid card
after an authorization, the authorization reply includes the balance amount in
ccAuthReply_accountBalance. If there is not enough of a balance on the prepaid card for
the requested transaction, it will be declined.

AVS Only
See “$0 Authorizations” on page 82.

Bill Me Later
Applicable 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, which is available at
the Support Center.

Credit Card Services Implementation Guide • June 2009 83


Bill Payments with Visa

Bill Payments with Visa


Applicable services:
• Authorization
• Credit
Supported processors:
• Chase Paymentech Solutions
• FDI Global
• FDMS Nashville
• GPN
• OmniPay-Ireland
• TSYS Acquiring Solutions
Visa has a special Bill Payment program that allows customers to use their Visa cards to
pay their bills. If you participate in this program, Visa requests that you flag the bill
payments and credits so they can be easily identified. This flag is called the debt indicator
and the field name is debtIndicator.
Although CyberSource accepts the bill payment indicator no matter which processor you
are using, you should not use this indicator if you have not signed up with Visa to take
part in the program.

84 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

Cash Advances
Applicable services:
• Authorization
• Capture
Supported processors:
• Barclays
• LloydsTSB Cardnet
A cash advance allows 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.

Important You must contact the processor to obtain an agreement to process cash advance
transactions.

You must have a separate CyberSource merchant ID that you use only with cash advance
transactions. Contact CyberSource Customer Support to configure your account correctly.

Process a cash advance transaction the same way you process a regular credit card
transaction: with an authorization and a capture. You cannot do the following:

• Reverse a cash advance authorization.


• Process a credit against a cash advance.
• Create a recurring cash advance transaction.
• Process a cash advance and airline data in the same transaction.

Credit Card Services Implementation Guide • June 2009 85


Coupons

Coupons
Applicable services:
• Authorization
Supported processors:
• All payment processors
You can offer customers virtual coupons at your Web store. CyberSource defines a coupon
as a non-taxable, fixed amount deducted from an order total. Some examples of coupons
you might offer are:

• Register now and get $100 off your purchase!


• Spring clearance! Get $10 off any order!
• Thank you for ordering again within 30 days! We’re taking $5 off your order!

How Coupons are Processed


The following steps provide an overview of how CyberSource processes a request that
includes a coupon:
1 All the line items are totaled and then the coupon amounts are deducted, resulting in
an order subtotal.
2 If the request includes the Tax Calculation service, tax is calculated for all taxable line
items to obtain a tax total. The Tax Calculation service ignores coupon line items
because they are not taxable.
3 The order subtotal and tax total are added to obtain an order grand total.
4 The order grand total is used by other CyberSource services you included in the
request, if any.
For example, if the coupon is included in an authorization request, the authorization
service uses the order grand total as the amount to authorize.

86 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

Coupon Constraints
You cannot use coupons to do the following:

• Apply a discount to a specific item in a multi-item order


• Apply a discount to a specific item before tax is calculated (if taxable)
• Apply a percentage discount
Also, the total coupon amount cannot be greater than the order grand total. Precalculate
your order totals before you send your requests to CyberSource so that you do not send
orders with negative subtotals. CyberSource returns an error for orders with negative
subtotals.

Customer Profiles
Applicable services:
• Authorization
• Credit
Supported processors:
• See the Secure Data Suite User’s Guide, which is available at the Support Center.
If you are using Customer Profiles, you can process an authorization, capture, or credit
that uses a profile. CyberSource uses the profile ID to reference the profile information in
the CyberSource database. Instead of providing all the information that is normally
required for a transaction, you only need to provide your merchant ID, an order number,
the amount of the payment or credit, and the profile ID.
When you include recurringSubscriptionInfo_subscriptionID in a request, the only
other fields you must provide in the request are:

• merchantID
• merchantReferenceCode
• item_0_unitPrice or purchaseTotals_grandTotalAmount to indicate the amount of
the payment or credit

Credit Card Services Implementation Guide • June 2009 87


Dynamic Currency Conversion (DCC)

You can also provide one or more of the four optional storage fields. CyberSource
encrypts these fields before storing them in the database:

• merchantSecureData_field1
• merchantSecureData_field2
• merchantSecureData_field3
• merchantSecureData_field4
Most of the information stored in the profile will be used for the payment or credit. This
information includes the required information such as the customer’s name, billing
address, and credit card information, as well as any optional information you stored in
the profile, including the shipping address and whether the transaction is part of Visa’s
Bill Payment program. The only information that is not used for payment or credit is the
information in the four optional storage fields. You can override most of the information
stored in the profile, except the credit card number, by including the relevant API fields in
the request. For example, you could provide a different billing or shipping address with
the request. Additionally, you can use the four optional storage fields as a stand-alone
feature.
For information about Customer Profiles and the different payment methods, see the
Secure Data Suite User’s Guide and the Customer Profiles Developer’s Guide, which are
available at the Support Center.

Dynamic Currency Conversion (DCC)


Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• FDI Global—Visa, MasterCard
• FDMS South—Visa, MasterCard
The DCC service converts a foreign cardholder’s purchase from your local currency to the
cardholder’s billing currency. This service can help you improve or create business
relationships with customers who prefer to make purchases in their own currency.

88 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

Topics:
Requirements and Limitations
Terminology
Procedure
Additional Information

Requirements and Limitations


The requirements for using the DCC service are:

• Your local currency must be USD.


• You must call CyberSource Customer Support to have your account configured to use
DCC.
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.

Credit Card Services Implementation Guide • June 2009 89


Dynamic Currency Conversion (DCC)

Terminology
Table 11 DCC Terminology

Term Definition

Billing currency Cardholder’s currency in which their card is denominated and


or in which transactions are posted to the cardholder’s account.
Cardholder billing currency

Converted amount Amount of the transaction, denominated in the cardholder’s


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 Conversion factor used to convert an original amount to a


or converted amount.
DCC exchange rate

Local currency Your selling currency that you use for pricing your goods and
or in which you usually submit transactions for processing.
Merchant local currency

Original amount Amount of the transaction, denominated in your local


currency.

Prefix First 6 to 10 digits of a Visa or MasterCard credit card number.


or
Account prefix

90 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

Procedure

Step 1. Call the DCC Service


To call the DCC service:
a Include the statement ccDCCService_run=true in your request.
b Include the required DCC fields in your request.
The following two tables list the request fields required for the DCC service and
the fields returned by the DCC service.

Table 12 Fields Required for the DCC Service

Value Field Name

Credit card account number—Set this field to the card_accountNumber


first 6 to 10 digits of the credit card number.

Original amount item_#_unitPrice

Local currency purchaseTotals_currency

Merchant ID merchantID

Merchant reference number merchantReferenceCode

Table 13 Fields Returned by the DCC Service

Value Field Name

DCC supported flag ccDCCReply_dccSupported

Converted amount purchaseTotals_foreignAmount

Converted currency code purchaseTotals_foreignCurrency

Exchange rate purchaseTotals_exchangeRate

Exchange rate timestamp purchaseTotals_exchangeRateTimeStamp

Currency selection fee ccDCCReply_marginRatePercentage

Credit Card Services Implementation Guide • June 2009 91


Dynamic Currency Conversion (DCC)

Step 2. If Necessary: Handle 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.

Step 3. 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.
b Display required DCC data to the customer. Check with your acquirer for data
requirements.
c Ask the customer if they would like to complete the transaction in their billing
currency.

Important 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.

Step 4. If Necessary: Proceed in the Local Currency


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

• 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.

92 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

Step 5. Authorize the Payment


The following table lists the DCC fields required for the authorization, capture, and credit
services.

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

Value Field Name

DCC indicator—If the customer opted in, dcc_dccIndicator


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

Converted amount purchaseTotals_foreignAmount

Converted currency code purchaseTotals_foreignCurrency

Exchange rate purchaseTotals_exchangeRate

Exchange rate timestamp purchaseTotals_exchangeRate


TimeStamp

Step 6. Display DCC Data


If the customer opted in, notify your customer that the transaction was successfully
authorized and display required DCC data 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:

• 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
service with the capture amount and then submit a capture request that includes the
new DCC values.

Credit Card Services Implementation Guide • June 2009 93


Dynamic Currency Conversion (DCC)

Step 8. 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.

Note If the customer did not opt in, use the DCC values you already obtained.

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 information about this report, see the Reporting Developer’s Guide, which is
available on the Support Center.

Important 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
• Fields—For descriptions of the required fields and to see which fields are optional, see
Appendix A, “Fields for the Simple Order API,” on page 173.
• Name-value pair examples—See “DCC Examples” on page 253.
• XML examples—See “DCC Examples” on page 262.

94 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

Encoded Account Numbers


Applicable services:
• Authorization
• Credit
Supported processors:
• Chase Paymentech Solution’s Credit Card Encryption program
Depending on what type of business you are in, 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 data according to the provisions of the Graham Leach Bliley Act.
When processing a payment or credit for one of these customers, you use the encoded
account number instead of the customer’s credit card number. The issuing bank then
matches the encoded account number to the customer’s credit card number when
processing the payment.
You must contact Chase Paymentech Solutions 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.

Forced Captures
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• FDMS South
• GPN
• TSYS Acquiring Solutions

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

Credit Card Services Implementation Guide • June 2009 95


Gift Cards

Gift Cards
See “American Express Prepaid Cards” on page 83.

Guaranteed Exchange Rates


See “Multi-Currency Service” on page 106.

Japanese Payment Options


Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• CCS (CAFIS)
In addition to standard single payments, Japanese acquirers support the following
payment options:

• Single bonus payment


• Installment bonus payment
• Installment payments (2 to 36 payments)
• Revolving repayments
• Combination of bonus payment and installment payments
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.

96 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

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.

The following table lists the Simple Order API fields required for each payment option.

Table 15 Simple Order API Fields for Japanese Payment Options

Payment Option Simple Order API Fields Required

Single bonus payment jpo_paymentMethod

Installment bonus payment jpo_paymentMethod, jpo_bonuses

Installment payments  jpo_paymentMethod, jpo_installments


(2 to 36 payments)

Revolving repayments jpo_paymentMethod

Combination of bonus payment and jpo_paymentMethod, jpo_bonusAmount, 


installment payments jpo_bonuses, jpo_installments

If you omit jpo_paymentMethod from the request, then a single payment is processed.
Combination of Bonus Payment and Installment Payments. When you choose the
combination of bonus payment and installment payments, the way the other request
fields need to be set might vary based on the acquirer. Please contact Customer Support of
CyberSource KK (Japan).
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 needs to include the Japanese payment option fields.
Stand-Alone Credits. If you are performing 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), 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” on page 107.

Credit Card Services Implementation Guide • June 2009 97


Level II Data

Level II Data
Applicable 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 the Level II and Level III Processing Addendum, which is
available at the Support Center.

Level III Data


Applicable 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 the Level II and Level III Processing Addendum, which is
available at the Support Center.

98 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API

Maestro (UK Domestic) and Solo Cards


Applicable services:
• Authorization
• Credit
Supported processors:
• See “Payment Processors” on page 6.

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

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

• Issue number—A Maestro (UK Domestic) or Solo 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.
If a Maestro (UK Domestic) or Solo card has an issue number, you must provide it
when requesting a credit card service for the card. On the other hand, you cannot
provide this API field, even with a blank value, when requesting a credit card service
for another card type.
• Start date—A Maestro (UK Domestic) or Solo card might have a start date embossed
on it. The start date consists of a month and year.
If a Maestro (UK Domestic) or Solo card has a start date, you must provide it when
requesting a credit card service for the card. On the other hand, you cannot provide
these API fields, even with blank values, when requesting a credit card service for
another card type.

MasterCard SecureCode
See “Payer Authentication” on page 107.

Credit Card Services Implementation Guide • June 2009 99


Merchant Descriptors

Merchant Descriptors
Applicable services:
• Capture
• Credit
Supported processors:
• American Express Direct
• American Express Phoenix
• Chase Paymentech Solutions
• CyberSource Global Payment Service
• FDI Global
• FDMS South
• GPN
• OmniPay-Ireland
This feature lets you submit a merchant descriptor that will be displayed on a
cardholder’s statement. Some processors also support a contact field that you can use to
provide a telephone number. Additionally, some processors support TAA fields for
American Express cards.
The merchant descriptor request fields are:

• invoiceHeader_merchantDescriptor—Merchant descriptor
• invoiceHeader_merchantDescriptorContact—Phone number or other contact
information
• invoiceHeader_merchantDescriptorAlternate—Alternate contact information
• invoiceHeader_amexDataTAA1...4—Four Transaction Advice Addendum (TAA)
fields for American Express cards that you can use to further describe a purchase

Important Before using merchant descriptors in your requests, check with your bank to
determine if you need to pre-register the merchant descriptor information with them.

The following sections describe the fields supported by each processor.

100 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

American Express Direct


American Express Direct supports the merchant descriptor field and the merchant
descriptor contact field.

Important Before sending merchant descriptors in your requests, you must first contact
American Express Direct to register to use merchant descriptors. Then, you must call
CyberSource Customer Support so that your account can be configured to use the
descriptors.

The merchant descriptor field must include your merchant DBA name.
The merchant descriptor contact field must contain the following information:

• If you are submitting a retail request: Street address where your store or outlet is
located.
• If you are submitting a non-retail request: Street address where your processing
facility is located or your URL or your email address.

American Express Phoenix


American Express Phoenix supports two types of fields:

• Merchant descriptor fields, which include the descriptor field and the contact field.
The contact field is for telephone or other contact information.
• Transaction Advice Addendum (TAA) fields, which are four fields that further
describe the purchase.
The following table shows which fields you can use depending on whether or not you are
a Level II merchant with American Express Phoenix.

Table 16 American Express Phoenix Merchant Descriptor Field Usage

Type of Merchant Merchant TAA


Merchant Descriptor Descriptor
Contact

Non-Level II Yes Yes Yes

Level II No Yes Yes (TAA1 is required)

For non-Level II transactions, if you provide the contact field you must also provide the
descriptor field. You can provide the descriptor field without the contact field.

Important Contact Customer Support if you want to use any of these fields so that your
account can be configured appropriately.

Credit Card Services Implementation Guide • June 2009 101


Merchant Descriptors

Chase Paymentech Solutions


Chase Paymentech Solutions supports two types of fields:

• Merchant descriptor fields, which include the descriptor field and the contact field.
The contact field is for telephone or other contact information. If you provide one of
the merchant descriptor fields, you must provide both fields.
• Transaction Advice Addendum (TAA) fields, which are four fields that further
describe the purchase. You can use these fields only with American Express cards for
Level II or non-Level II transactions.

Important Chase Paymentech Solutions restricts the number of merchant descriptors you
can use. Before sending merchant descriptors in your requests, contact Chase Paymentech
Solutions for more information and prepare a list of the merchant descriptors you plan to
use. Also contact Chase Paymentech Solutions if you want to use TAA fields.

Characters
In the merchant descriptor fields, question marks will be 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 Simple Order API reason code 233 or
SCMP API reply flag DINVALIDDATA:

• caret (^)
• backslash (\)
• open bracket ([)
• close bracket (])
• tilde (~)
• accent ( ` )

102 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Merchant Descriptor
For an installment transaction, you must use one of the following formats for the
merchant descriptor:

• <12-character merchant name>*PYMT<N>OF<M>


• <7-character merchant name>*PYMT<N>OF<M>
• <3-character merchant name>*PYMT<N>OF<M>

where <N> is the payment number and <M> is the total number of payments. For example,
for the 3rd installment in a series of 7 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 for the
merchant descriptor:

• <12-character merchant name>*<9-character product description>


• <7-character merchant name>*<14-character product description>
• <3-character merchant name>*<18-character product description>

Merchant Descriptor Contact


You must use one of the following formats:

• PCCCCCCCCCCCC
• NNN-NNN-NNNN
• NNN-NNN-NAAA
• NNN-NNN-AAAA
• NNN-AAAAAAA

where:

• A: Alphanumeric (alpha or numeric)

• C: Character (alpha or blank)

• N: Numeric
• P: Alpha

CyberSource Global Payment Service


The CyberSource Global Payment Service supports the merchant descriptor field.

Important Before sending the merchant descriptor in your requests, contact CyberSource
Customer Support so that your CyberSource and processor accounts can be configured to
use the descriptor.

Credit Card Services Implementation Guide • June 2009 103


Merchant Descriptors

FDI Global
FDI Global supports the merchant descriptor field, the merchant descriptor contact field,
and the merchant descriptor alternate contact field. You can send as many or as few of
these fields as you like in an API request: no fields, one field, two fields, or all three fields.

Important Before sending merchant descriptors in your requests, you must first contact
FDI Global to register to use merchant descriptors. Then, you must call CyberSource
Customer Support so that your account can be configured to use the descriptors.

Contents and Formats


The merchant descriptor field must contain the following information:

• Your merchant DBA name.


• If payments are being made in installments, the merchant descriptor field must also
contain installment information such as “1 of 5” or “3 of 7.”
The merchant descriptor contact field must contain the following information:

• If you are submitting a retail request: City in which your store or outlet is located.
• If you are submitting a non-retail request: Your customer service telephone number.
The merchant descriptor alternate contact field must contain alternate contact information
such as a URL or email address.

Default Values
CyberSource always provides merchant descriptor information to the processor for you
for all capture and credit transactions. If you do not include merchant descriptor
information in your requests, CyberSource uses the default values in the merchant
configuration database as follows:

• If you do not include a merchant descriptor in your request, CyberSource uses the
merchant name from the merchant configuration database.
• If you do not include a merchant descriptor contact in your request, the value that
CyberSource uses depends on the type of transaction:
• For retail transactions, CyberSource uses the merchant city from the merchant
configuration database.
• For non-retail transactions, CyberSource uses the merchant phone number from
the merchant configuration database.
• If you do not include a merchant descriptor alternate contact in your request,
CyberSource uses the URL from the merchant configuration database.

104 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

FDMS South
FDMS South supports the merchant descriptor field. FDMS South allows 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.

Important Before sending the merchant descriptor in your requests, you must first contact
FDMS South to register to use merchant descriptors. Then, you must call CyberSource
Customer Support so that your account can be configured to use the descriptor.

GPN
GPN supports a dynamic merchant name descriptor and a dynamic merchant descriptor
contact.

Important Before sending merchant descriptors in your requests, you must first contact
your merchant account provider to register to use merchant descriptors.

OmniPay-Ireland
OmniPay-Ireland supports the merchant descriptor field. For OmniPay-Ireland, you must
use one of the following formats for the merchant descriptor:

• <12-character merchant DBA name>*<10-character product description>


• <7-character merchant DBA name>*<15-character product description>
• <3-character merchant DBA name>*<19-character product description>

Important Before sending the merchant descriptor in your requests, you must first contact
OmniPay-Ireland to register to use merchant descriptors. Then, you must call
CyberSource Customer Support so that your account can be configured to use the
descriptor.

Credit Card Services Implementation Guide • June 2009 105


Micropayments

Micropayments
Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• Most of the card types and processors that are supported by CyberSource
Micropayments are payments for less than one dollar.

Note If you want to process micropayments with the American Express Phoenix
processor, please contact Customer Support so that your account can be configured
correctly. When you request a micropayment with American Express Phoenix,
CyberSource must increase the amount of the authorization to $1 when the request is sent
to American Express Phoenix to accommodate their requirements. CyberSource records
the actual amount that you sent in your request in the CyberSource database. When you
request the subsequent capture or credit for the micropayment, you should make the
request for the actual amount.

Multi-Currency Service
Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• Chase Paymentech Solutions
If you want to sell your products in multiple countries, you might want to list your
product prices in your customers’ local currencies. The CyberSource Multi-Currency
Service lets you obtain current, guaranteed exchange rates. This lets customers pay using
their local currencies, while still allowing you to do business and settle transactions in
your desired currency.
For more information about the CyberSource Multi-Currency Service, see the Multi-
Currency Service Supplement, which is available at the Support Center.

106 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Payer Authentication
Important Before you implement payer authentication, you need to contact Customer
Support to have your account configured for this feature.

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
CyberSource Payer Authentication services to add Verified by Visa, JCB J/Secure™, or
MasterCard® SecureCode™ support to your Web store without running additional
software on your own server. The following table lists the cards supported for each type of
payer authentication.

Table 17 Supported Card Types for Payer Authentication

Type of Payer Card Types


Authentication

Verified by Visa Visa

JCB J/Secure JCB

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

For more information about payer authentication, see the Payer Authentication
Implementation Guide, which is available on the Support Center.

Verified by Visa
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• Atos
• Barclays
• CCS (CAFIS)
• Chase Paymentech Solutions
• 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 Implementation Guide • June 2009 107


Payer Authentication

• FDC Germany
• FDI Australia
• FDI Global
• FDMS Nashville
• FDMS South
• GPN
• HBoS
• HSBC
• OmniPay-Ireland
• 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 customer’s 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 visit http://visa.com/.
To request the authorization of a Verified by Visa transaction, add the fields listed in the
following table to your ccAuthService request. The values for these fields are included in
the reply from the Validate Authentication service payerAuthValidateService. If you
request payerAuthValidateService and ccAuthService together, the data is automatically
passed from one service to the other.

108 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Table 18 Request Fields for Verified by Visa and JCB J/Secure

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

CAVV—Cardholder authentication verification value. ccAuthService_cavv payerAuthValidateReply_


This value is a transaction identifier generated by the cavv
issuing bank during Verified by Visa or JCB J/Secure
payer authentication. Must be 28-character base64
or 40-character hex binary.
• 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.

CAVV Algorithm—Algorithm for generating the ccAuthService_ payerAuthValidateReply_


CAVV. cavvAlgorithm cavvAlgorithm
• Used only for Atos.
• Required when you include the CAVV in your
request.
• You must not include the CAVV algorithm value in
your request if the CAVV is not included in your
request or if you are not using Atos.
• Possible values:
0: HMAC
1: CVV
2: CVV with ATN
3: MasterCard SPA algorithm

Credit Card Services Implementation Guide • June 2009 109


Payer Authentication

Table 18 Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

Commerce Indicator—Type of transaction. ccAuthService_ payerAuthValidateReply_


• Used for all processors that support Verified by commerceIndicator commerceIndicator
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 Raw—Raw electronic commerce indicator. ccAuthService_eciRaw payerAuthValidateReply_


• Used for all processors that support Verified by eciRaw
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
Customer Support for information about your
processor’s requirements.

110 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Table 18 Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

PARes Status—Payer authentication response ccAuthService_ payerAuthValidateReply_


status. paresStatus paresStatus
• Used only for Asia-Mideast Processing and Atos.
• For Atos: Required for a successful Verified by
Visa transaction, which is indicated when the
commerce indicator is vbv.
• For Asia-Mideast Processing: Required unless all
of the following are true:
• You are performing payer authentication and
authorization separately in different 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.
If all the preceding conditions are true, do not
include the PARes status in the authorization
request. If you do, CyberSource will send the
value to the processor without modification.
CyberSource will not decline the transaction;
any decline will be 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 Implementation Guide • June 2009 111


Payer Authentication

Table 18 Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

VERes Enrolled—Verification response enrollment ccAuthService_ payerAuthEnrollReply_


status. veresEnrolled veresEnrolled
• Used only for Asia-Mideast Processing.
• Required for all payer authentication transactions.
• Possible values:
• Y: Authentication available.
• N: Cardholder not participating.
• U: Unable to authenticate regardless of the
reason.

XID—Transaction identifier. Must be 28-character ccAuthService_xid payerAuthValidateReply_


base64 or 40-character hex binary. xid
• 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.

112 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

JCB J/Secure
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• CCS (CAFIS)
• CyberSource Global Payment Service
• GPN
• 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 visit http://www.jcb-global.com/.
To request the authorization of a JCB J/Secure transaction, add the fields listed in the
preceding table to your ccAuthService request. The values for these fields are included in
the reply from the Validate Authentication service payerAuthValidateService. If you
request payerAuthValidateService and ccAuthService together, the data is automatically
passed from one service to the other.

MasterCard SecureCode
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• Atos
• Barclays
• CCS (CAFIS)
• CyberSource Global Payment Service
• 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.
• FDC Germany
• FDI Australia
• FDI Global

Credit Card Services Implementation Guide • June 2009 113


Payer Authentication

• FDMS Nashville
• FDMS South
• GPN
• HBoS
• HSBC
• OmniPay-Ireland
• 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
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 visit http://www.mastercard.com/.
To request the authorization of a MasterCard SecureCode transaction, 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. If you request
payerAuthValidateService and ccAuthService together, the data is automatically passed
from one service to the other.

114 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Table 19 Request Fields for MasterCard SecureCode

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

CAVV Algorithm—Algorithm for generating the ccAuthService_ payerAuthValidateReply_


UCAF authentication data. cavvAlgorithm cavvAlgorithm
• Used only for Atos.
• Required when you include the UCAF
authentication data in your request.
• You must not include the CAVV algorithm value in
your request if the UCAF authentication data is not
included in your request or if you are not using
Atos.
• Possible values:
0: HMAC
1: CVV
2: CVV with ATN
3: MasterCard SPA algorithm

Commerce Indicator—Type of transaction. ccAuthService_ payerAuthValidateReply_


• Used for all processors that support MasterCard commerceIndicator commerceIndicator
SecureCode.
• Always required.
• Possible values for a MasterCard SecureCode
transaction:
• spa: MasterCard SecureCode transaction.
• spa_failure: MasterCard SecureCode
authentication failed. Available only for HSBC
and Streamline.

ECI Raw—Raw electronic commerce indicator. ccAuthService_eciRaw payerAuthValidateReply_


• Used for all processors that support MasterCard eciRaw
SecureCode.
• Required when the payer authentication validation
service returns a raw ECI value.
• Some processors require the raw ECI to
guarantee chargeback protection. Contact
Customer Support for information about your
processor’s requirements.

Credit Card Services Implementation Guide • June 2009 115


Payer Authentication

Table 19 Request Fields for MasterCard SecureCode (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

PARes Status—Payer authentication response ccAuthService_ payerAuthValidateReply_


status. paresStatus paresStatus
• Used only for Asia-Mideast Processing and Atos.
• For Atos: Required for a successful MasterCard
SecureCode transaction, which is indicated when
the UCAF collection indicator is 2.
• For Asia-Mideast Processing: Required unless all
of the following are true:
• You are performing payer authentication and
authorization separately in different 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.
If all the preceding conditions are true, do not
include the PARes status in the authorization
request. If you do, CyberSource will send the
value to the processor without modification.
CyberSource will not decline the transaction;
any decline will be 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.

116 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Table 19 Request Fields for MasterCard SecureCode (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

UCAF Authentication Data—Authentication data for ucaf_ payerAuthValidateReply_


the universal cardholder authentication field. authenticationData ucafAuthenticationData
• Used for all processors that support MasterCard
SecureCode.
• Required when the UCAF collection indicator is 2.
Do not include the UCAF authentication data in the
authorization request if the UCAF collection
indicator is not 2.

UCAF Collection Indicator—Collection indicator for ucaf_ payerAuthValidateReply_


for the universal cardholder authentication field. collectionIndicator ucafCollectionIndicator
• 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, but the UCAF was not populated.
• 2: UCAF collection is supported at your Web
site and the UCAF was populated. This
indicates a successful MasterCard SecureCode
transaction.

Credit Card Services Implementation Guide • June 2009 117


POS Transactions

Table 19 Request Fields for MasterCard SecureCode (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

VERes Enrolled—Verification response enrollment ccAuthService_ payerAuthEnrollReply_


status. veresEnrolled veresEnrolled
• Used only for Asia-Mideast Processing.
• Required for all payer authentication transactions.
• Possible values:
• Y: Authentication available.
• N: Cardholder not participating.
• U: Unable to authenticate regardless of the
reason.

XID—Transaction identifier. Must be 28-character ccAuthService_xid payerAuthValidateReply_


base64 or 40-character hex binary. xid
• 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.

POS Transactions
See “Retail POS Data” on page 123.

Prepaid Cards
See “American Express Prepaid Cards” on page 83.

Recurring Billing
See “Customer Profiles” on page 87.

118 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Recurring Payments
Applicable services:
• Authorization
Supported processors:
• See the following table.

Table 20 Processors That Support Recurring Payments

Processors Credit Card Types

American Express Brighton American Express

American Express Direct American Express

American Express Phoenix American Express

Asia-Mideast Processing Visa, MasterCard, American Express, Diners


Club, JCB

Barclays Visa, MasterCard, JCB

Chase Paymentech Solutions Visa, MasterCard, American Express, Discover

CyberSource Global Payment Service Carte Bleue


processor

FDC Germany Visa, MasterCard

FDI Australia Visa, MasterCard

FDI Global Visa, MasterCard

FDMS South Visa, MasterCard

FDMS Nashville Visa, MasterCard, American Express, Discover

GE Capital GE Money UK cards


GBP currency only

GPN Visa, MasterCard, American Express, Discover,


Diners Club, JCB

HBoS Visa, MasterCard

HSBC
Contact the CyberSource European office if you want to process recurring payments with HSBC.
To get the European office’s phone number, go to the CyberSource Web site at
www.cybersource.com and click the Contact Us link.

Credit Card Services Implementation Guide • June 2009 119


Recurring Payments

Table 20 Processors That Support Recurring Payments

Processors Credit Card Types

Lloyds-OmniPay Visa, MasterCard

LloydsTSB Cardnet Visa, MasterCard

OmniPay-Ireland Visa, MasterCard

Streamline
Contact the CyberSource European office if you want to process recurring payments with
Streamline. To get the European office’s phone number, go to the CyberSource Web site at
www.cybersource.com and click the Contact Us link.

TSYS Acquiring Solutions Visa, MasterCard, American Express, Discover

Note American Express and Discover have programs that you must sign up for if you
want to process recurring payments. Contact American Express and Discover for details
about their programs.

Depending on the type of products or services you sell, you might want to process
recurring payments for a customer. For example, you might want to charge a customer
$19.95 each month to access a service that you offer.

Note A customer’s recurring payment does not have to be for the same amount each time.

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 this clear.
To create a recurring payment:
1 For the first payment, send a regular request for credit card authorization.
Only if the first authorization is successful should you then submit authorizations for
recurring payments for that card.
2 For each subsequent recurring payment, send an authorization request using the
e-commerce indicator to indicate the payment is a recurring payment:
ccAuthService_commerceIndicator=recurring
CyberSource also offers a service that allows you to create a profile for a customer in the
CyberSource system and then use that profile later to manually or automatically bill the
customer. CyberSource’s system eliminates the need for you to handle or store the
customer’s sensitive credit card information or create your own system for billing the
customer on a regular basis. For more information, see the Secure Data Suite User’s Guide,
which is available at the Support Center.

120 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

AVS and Recurring Payments


If the Address Verification Service is supported for your processor and card type, AVS is
run for every authorization request that you submit. For recurring payments, you should
check the AVS result for the first payment to make sure the information is accurate and to
reduce the risk of fraud.
You must decide how to handle the AVS results for the subsequent recurring 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 non-
fraudulent.
If you need to change the credit card number used for a series of recurring payments, treat
the first authorization with the new credit card number as a non-recurring payment and
closely evaluate the AVS results. You could then flag the subsequent payments as
recurring payments and ignore the AVS results.

Card Verification Number and Recurring Payments


If you are using the CyberSource Global Payment Service to process your transactions,
you must not include the card verification number in a recurring payment request. If you
do, CyberSource will reject the request due to invalid data.

Replacement Expiration Dates for Recurring Payments

Applicable service: Authorization

Supported processors See the following table.


and card types:

Table 21 Processors That Support Replacement Expiration Dates for Recurring Payments

Processors Credit Card Types

American Express Brighton American Express


You must contact American Express Brighton to get
approval for using replacement expiration dates
before using this feature.

Chase Paymentech Solutions Visa, MasterCard

FDI Australia Visa, MasterCard

FDMS South Visa, MasterCard

GE Capital GE Money UK card

Credit Card Services Implementation Guide • June 2009 121


Recurring Profiles

Table 21 Processors That Support Replacement Expiration Dates for Recurring Payments

Processors Credit Card Types

HBoS Visa, MasterCard

HSBC Visa, MasterCard, Maestro (International)

Lloyds-OmniPay Visa, MasterCard

LloydsTSB Cardnet Visa, MasterCard

Normally when you request a credit card authorization, you must supply 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 send a replacement expiration date of month=12 and
year=2021.

Important Do not use the replacement expiration date for cards that have not yet expired.
Use the replacement expiration date only for cards that have expired and only for
recurring payments.

Using the replacement expiration date for a recurring payment does not guarantee that
the authorization will be successful. The issuing bank determines if a card is authorized;
some issuing banks will not accept an expiration date that does not match what the
expiration date in the bank’s database.

To process a recurring payment authorization with a credit card that has expired, set these
fields in your authorization request:

• card_expirationMonth = 12
• card_expirationYear = 2021

Recurring Profiles
See “Customer Profiles” on page 87.

122 CyberSource Corporation


Chapter 6 Optional Features for the Simple Order API

Retail POS Data


Applicable services:
• Authorization
For a description of Retail point of sale (POS) data, including the list of processors for
which CyberSource supports retail transactions, see the API for Retail POS Transactions,
which is available at the Support Center.

Secure Data
See “Customer Profiles” on page 87.

Soft Descriptors
See “Merchant Descriptors” on page 100.

Split Dial/Route
See “Forced Captures” on page 95.

Subscriptions
See “Customer Profiles” on page 87.

Switch and Solo Cards


See “Maestro (UK Domestic) and Solo Cards” on page 99.

Type II Cards
See “Level II Data” on page 98.

Verbal Authorizations
See “Verbal Authorizations: The Authorization” on page 50.

Credit Card Services Implementation Guide • June 2009 123


Verified by Visa

Verified by Visa
See “Payer Authentication” on page 107.

124 CyberSource Corporation


Chapter 7
Optional Features for the SCMP API

This chapter describes the optional features and includes information about
implementing them with the SCMP API.

Topics:
$0 Authorizations Merchant Descriptors
Airline Data Micropayments
American Express Prepaid Cards Multi-Currency Service
AVS Only
Bill Me Later Payer Authentication
Bill Payments with Visa POS Transactions
Cash Advances Prepaid Cards
Coupons Recurring Billing
Customer Profiles Recurring Payments
Dynamic Currency Conversion (DCC) Recurring Profiles
Encoded Account Numbers Retail POS Data
Forced Captures Secure Data
Gift Cards Soft Descriptors
Guaranteed Exchange Rates Split Dial/Route
Japanese Payment Options Subscriptions
JCB J/Secure Switch and Solo Cards
Level II Data Type II Cards
Level III Data Verbal Authorizations
Maestro (UK Domestic) and Solo Cards Verified by Visa
MasterCard SecureCode

Credit Card Services Implementation Guide • June 2009 125


$0 Authorizations

$0 Authorizations
Applicable services:
• Authorization
Supported processors:
• American Express Direct
• Chase Paymentech Solutions
• FDI Global
• FDMS South
• GPN
• OmniPay-Ireland
• TSYS Acquiring Solutions
By performing an authorization for $0, you can see if a credit card account is valid and
whether the card is lost or stolen. You cannot process a capture for a $0 authorization.

Airline Data
Applicable services:
• Authorization
• Capture
• Credit
For information about airline data, including the list of processors for which CyberSource
supports airline data, see the Airline Data Addendum, which is available at the Support
Center.

126 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

American Express Prepaid Cards


Applicable services:
• Authorization
Supported processors:
• American Express Direct
• FDMS Nashville
• FDMS South
American Express prepaid cards are processed using the same services as credit cards:
authorization, capture, credit, and void. If there is a balance remaining on a prepaid card
after an authorization, the authorization reply includes the balance amount in auth_
account_balance. If there is not enough of a balance on the prepaid card for the requested
transaction, it will be declined.

AVS Only
See “$0 Authorizations” on page 126.

Bill Me Later
Applicable 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, which is available at
the Support Center.

Credit Card Services Implementation Guide • June 2009 127


Bill Payments with Visa

Bill Payments with Visa


Applicable services:
• Authorization
• Credit
Supported processors:
• Chase Paymentech Solutions
• FDI Global
• FDMS Nashville
• GPN
• OmniPay-Ireland
• TSYS Acquiring Solutions
Visa has a special Bill Payment program that allows customers to use their Visa cards to
pay their bills. If you participate in this program, Visa requests that you flag the bill
payments and credits so they can be easily identified. This flag is called the debt indicator
and the field name is debt_indicator.
Although CyberSource accepts the bill payment indicator no matter which processor you
are using, you should not use this indicator if you have not signed up with Visa to take
part in the program.

128 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Cash Advances
Applicable services:
• Authorization
• Capture
Supported processors:
• Barclays
• LloydsTSB Cardnet
A cash advance allows 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.

Important You must contact the processor to obtain an agreement to process cash advance
transactions.

You must have a separate CyberSource merchant ID that you use only with cash advance
transactions. Contact CyberSource Customer Support to configure your account correctly.

Process a cash advance transaction the same way you process a regular credit card
transaction: with an authorization and a capture. You cannot do the following:

• Reverse a cash advance authorization.


• Process a credit against a cash advance.
• Create a recurring cash advance transaction.
• Process a cash advance and airline data in the same transaction.

Credit Card Services Implementation Guide • June 2009 129


Coupons

Coupons
Applicable services:
• Authorization
Supported processors:
• All payment processors
You can offer customers virtual coupons at your Web store. CyberSource defines a coupon
as a non-taxable, fixed amount deducted from an order total. Some examples of coupons
you might offer are:

• Register now and get $100 off your purchase!


• Spring clearance! Get $10 off any order!
• Thank you for ordering again within 30 days! We’re taking $5 off your order!

How Coupons are Processed


The following steps provide an overview of how CyberSource processes a request that
includes a coupon:
1 All the line items are totaled and then the coupon amounts are deducted, resulting in
an order subtotal.
2 If the request includes the Tax Calculation service, tax is calculated for all taxable line
items to obtain a tax total. The Tax Calculation service ignores coupon line items
because they are not taxable.
3 The order subtotal and tax total are added to obtain an order grand total.
4 The order grand total is used by other CyberSource services you included in the
request, if any.
For example, if the coupon is included in an authorization request, the authorization
service uses the order grand total as the amount to authorize.

130 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Coupon Constraints
You cannot use coupons to do the following:

• Apply a discount to a specific item in a multi-item order


• Apply a discount to a specific item before tax is calculated (if taxable)
• Apply a percentage discount
Also, the total coupon amount cannot be greater than the order grand total. Precalculate
your order totals before you send your requests to CyberSource so that you do not send
orders with negative subtotals. CyberSource returns an error for orders with negative
subtotals.

Customer Profiles
Applicable services:
• Authorization
• Credit
Supported processors:
• See the Secure Data Suite User’s Guide, which is available at the Support Center.
If you are using Customer Profiles, you can process an authorization, capture, or credit
that uses a profile. CyberSource uses the profile ID to reference the profile information in
the CyberSource database. Instead of providing all the information that is normally
required for a transaction, you only need to provide your merchant ID, an order number,
the amount of the payment or credit, and the profile ID.
When you include subscription_id in a request, the only other fields you must provide in
the request are:

• merchant_id
• merchant_ref_number
• offer0 with the offer-level amount field, or the request-level field grand_total_
amount to indicate the amount of the payment or credit

Credit Card Services Implementation Guide • June 2009 131


Dynamic Currency Conversion (DCC)

You can also provide one or more of the four optional storage fields. CyberSource
encrypts these fields before storing them in the database:

• merchant_secure_data1
• merchant_secure_data2
• merchant_secure_data3
• merchant_secure_data4
Most of the information stored in the profile will be used for the payment or credit. This
information includes the required information such as the customer’s name, billing
address, and credit card information, as well as any optional information you stored in
the profile, including the shipping address and whether the transaction is part of Visa’s
Bill Payment program. The only information that is not used for payment or credit is the
information in the four optional storage fields. You can override most of the information
stored in the profile, except the credit card number, by including the relevant API fields in
the request. For example, you could provide a different billing or shipping address with
the request. Additionally, you can use the four optional storage fields as a stand-alone
feature.
For information about Customer Profiles and the different payment methods, see the
Secure Data Suite User’s Guide and the Customer Profiles Developer’s Guide, which are
available at the Support Center.

Dynamic Currency Conversion (DCC)


Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• FDI Global—Visa, MasterCard
• FDMS South—Visa, MasterCard
The DCC service converts a foreign cardholder’s purchase from your local currency to the
cardholder’s billing currency. This service can help you improve or create business
relationships with customers who prefer to make purchases in their own currency.

132 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Topics:
Requirements and Limitations
Terminology
Procedure
Additional Information

Requirements and Limitations


The requirements for using the DCC service are:

• Your local currency must be USD.


• You must call CyberSource Customer Support to have your account configured to use
DCC.
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.

Credit Card Services Implementation Guide • June 2009 133


Dynamic Currency Conversion (DCC)

Terminology
Table 22 DCC Terminology

Term Definition

Billing currency Cardholder’s currency in which their card is denominated and


or in which transactions are posted to the cardholder’s account.
Cardholder billing currency

Converted amount Amount of the transaction, denominated in the cardholder’s


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 Conversion factor used to convert an original amount to a


or converted amount.
DCC exchange rate

Local currency Your selling currency that you use for pricing your goods and
or in which you usually submit transactions for processing.
Merchant local currency

Original amount Amount of the transaction, denominated in your local


currency.

Prefix First 6 to 10 digits of a Visa or MasterCard credit card number.


or
Account prefix

134 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Procedure

Step 1. Call the DCC Service


To call the DCC service:
a Include the statement ics_applications=ics_dcc in your request.
b Include the required DCC fields in your request.
The following two tables list the request fields required for the DCC service and
the fields returned by the DCC service.

Table 23 Fields Required for the DCC Service

Value Field Name

Credit card account number—Set this field to the customer_cc_number


first 6 to 10 digits of the credit card number.

Original amount amount

Local currency currency

Merchant ID merchant_id

Merchant reference number merchant_ref_number

Value Field Name

DCC supported flag dcc_dcc_supported

Converted amount dcc_foreign_amount

Converted currency code dcc_foreign_amount

Exchange rate dcc_exchange_rate

Exchange rate timestamp dcc_exchange_rate_timestamp

Currency selection fee dcc_margin_rate_percentage

Step 2. If Necessary: Handle 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 Implementation Guide • June 2009 135


Dynamic Currency Conversion (DCC)

Step 3. 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.
b Display required DCC data to the customer. Check with your acquirer for data
requirements.
c Ask the customer if they would like to complete the transaction in their billing
currency.

Important 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.

Step 4. If Necessary: Proceed in the Local Currency


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

• 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.

Step 5. Authorize the Payment


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

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

Value Field Name

DCC indicator—If the customer opted in, dcc_indicator


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

Converted amount foreign_amount

Converted currency code foreign_currency

Exchange rate exchange_rate

Exchange rate timestamp exchange_rate_timestamp

136 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Step 6. Display DCC Data


If the customer opted in, notify your customer that the transaction was successfully
authorized and display required DCC data 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:

• 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
service with the capture amount and then submit a capture request that includes the
new DCC values.

Step 8. 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.

Note If the customer did not opt in, use the DCC values you already obtained.

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

Credit Card Services Implementation Guide • June 2009 137


Encoded Account Numbers

You can also see the DCC values in the XML version of the Payment Submission Detail
Report. For information about this report, see the Reporting Developer’s Guide, which is
available on the Support Center.

Important 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
• Fields—For descriptions of the required fields and to see which fields are optional, see
Appendix B, “Fields for the SCMP API,” on page 213.
• Examples—See “DCC Examples” on page 275.

Encoded Account Numbers


Applicable services:
• Authorization
• Credit
Supported processors:
• Chase Paymentech Solution’s Credit Card Encryption program
Depending on what type of business you are in, 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 data according to the provisions of the Graham Leach Bliley Act.
When processing a payment or credit for one of these customers, you use the encoded
account number instead of the customer’s credit card number. The issuing bank then
matches the encoded account number to the customer’s credit card number when
processing the payment.
You must contact Chase Paymentech Solutions 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.

138 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Forced Captures
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• FDMS South
• GPN
• TSYS Acquiring Solutions

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

Gift Cards
See “American Express Prepaid Cards” on page 127.

Guaranteed Exchange Rates


See “Multi-Currency Service” on page 150.

Credit Card Services Implementation Guide • June 2009 139


Japanese Payment Options

Japanese Payment Options


Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• CCS (CAFIS)
In addition to standard single payments, Japanese acquirers support the following
payment options:

• Single bonus payment


• Installment bonus payment
• Installment payments (2 to 36 payments)
• Revolving repayments
• Combination of bonus payment and installment payments
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.

140 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

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

Table 25 SCMP API Fields for Japanese Payment Options

Payment Option SCMP API Fields Required

Single bonus payment jpo_payment_method

Installment bonus payment jpo_payment_method, jpo_bonuses

Installment payments  jpo_payment_method, jpo_installments


(2 to 36 payments)

Revolving repayments jpo_payment_method

Combination of bonus payment and jpo_payment_method, jpo_bonus_amount, 


installment payments jpo_bonuses, jpo_installments

If you omit jpo_payment_method from the request, then a single payment is processed.
Combination of Bonus Payment and Installment Payments. When you choose the
combination of bonus payment and installment payments, the way the other request
fields need to be set might vary based on the acquirer. Please contact Customer Support of
CyberSource KK (Japan).
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 needs to include the Japanese payment option fields.
Stand-Alone Credits. If you are performing 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), 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” on page 151.

Credit Card Services Implementation Guide • June 2009 141


Level II Data

Level II Data
Applicable 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 the Level II and Level III Processing Addendum, which is
available at the Support Center.

Level III Data


Applicable 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 the Level II and Level III Processing Addendum, which is
available at the Support Center.

142 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Maestro (UK Domestic) and Solo Cards


Applicable services:
• Authorization
• Credit
Supported processors:
• See “Payment Processors” on page 6.

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

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

• Issue number—A Maestro (UK Domestic) or Solo 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.
If a Maestro (UK Domestic) or Solo card has an issue number, you must provide it
when requesting a credit card service for the card. On the other hand, you cannot
provide this API field, even with a blank value, when requesting a credit card service
for another card type.
• Start date—A Maestro (UK Domestic) or Solo card might have a start date embossed
on it. The start date consists of a month and year.
If a Maestro (UK Domestic) or Solo card has a start date, you must provide it when
requesting a credit card service for the card. On the other hand, you cannot provide
these API fields, even with blank values, when requesting a credit card service for
another card type.

MasterCard SecureCode
See “Payer Authentication” on page 151.

Credit Card Services Implementation Guide • June 2009 143


Merchant Descriptors

Merchant Descriptors
Applicable services:
• Capture
• Credit
Supported processors:
• American Express Direct
• American Express Phoenix
• Chase Paymentech Solutions
• CyberSource Global Payment Service
• FDI Global
• FDMS South
• GPN
• OmniPay-Ireland
This feature lets you submit a merchant descriptor that will be displayed on a
cardholder’s statement. Some processors also support a contact field that you can use to
provide a telephone number. Additionally, some processors support TAA fields for
American Express cards.
The merchant descriptor request fields are:

• merchant_descriptor—Merchant descriptor
• merchant_descriptor_contact—Phone number or other contact information
• merchant_descriptor_alternate—Alternate contact information
• amexdata_taa1...4—Four Transaction Advice Addendum (TAA) fields for American
Express cards that you can use to further describe a purchase

Important Before using merchant descriptors in your requests, check with your bank to
determine if you need to pre-register the merchant descriptor information with them.

The following sections describe the fields supported by each processor.

144 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

American Express Direct


American Express Direct supports the merchant descriptor field and the merchant
descriptor contact field.

Important Before sending merchant descriptors in your requests, you must first contact
American Express Direct to register to use merchant descriptors. Then, you must call
CyberSource Customer Support so that your account can be configured to use the
descriptors.

The merchant descriptor field must include your merchant DBA name.
The merchant descriptor contact field must contain the following information:

• If you are submitting a retail request: Street address where your store or outlet is
located.
• If you are submitting a non-retail request: Street address where your processing
facility is located or your URL or your email address.

American Express Phoenix


American Express Phoenix supports two types of fields:

• Merchant descriptor fields, which include the descriptor field and the contact field.
The contact field is for telephone or other contact information.
• Transaction Advice Addendum (TAA) fields, which are four fields that further
describe the purchase.
The following table shows which fields you can use depending on whether or not you are
a Level II merchant with American Express Phoenix.

Table 26 American Express Phoenix Merchant Descriptor Field Usage

Type of Merchant Merchant TAA


Merchant Descriptor Descriptor
Contact

Non-Level II Yes Yes Yes

Level II No Yes Yes (TAA1 is required)

For non-Level II transactions, if you provide the contact field you must also provide the
descriptor field. You can provide the descriptor field without the contact field.

Important Contact Customer Support if you want to use any of these fields so that your
account can be configured appropriately.

Credit Card Services Implementation Guide • June 2009 145


Merchant Descriptors

Chase Paymentech Solutions


Chase Paymentech Solutions supports two types of fields:

• Merchant descriptor fields, which include the descriptor field and the contact field.
The contact field is for telephone or other contact information. If you provide one of
the merchant descriptor fields, you must provide both fields.
• Transaction Advice Addendum (TAA) fields, which are four fields that further
describe the purchase. You can use these fields only with American Express cards for
Level II or non-Level II transactions.

Important Chase Paymentech Solutions restricts the number of merchant descriptors you
can use. Before sending merchant descriptors in your requests, contact Chase Paymentech
Solutions for more information and prepare a list of the merchant descriptors you plan to
use. Also contact Chase Paymentech Solutions if you want to use TAA fields.

Characters
In the merchant descriptor fields, question marks will be 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 Simple Order API reason code 233 or
SCMP API reply flag DINVALIDDATA:

• caret (^)
• backslash (\)
• open bracket ([)
• close bracket (])
• tilde (~)
• accent ( ` )

146 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Merchant Descriptor
For an installment transaction, you must use one of the following formats for the
merchant descriptor:

• <12-character merchant name>*PYMT<N>OF<M>


• <7-character merchant name>*PYMT<N>OF<M>
• <3-character merchant name>*PYMT<N>OF<M>

where <N> is the payment number and <M> is the total number of payments. For example,
for the 3rd installment in a series of 7 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 for the
merchant descriptor:

• <12-character merchant name>*<9-character product description>


• <7-character merchant name>*<14-character product description>
• <3-character merchant name>*<18-character product description>

Merchant Descriptor Contact


You must use one of the following formats:

• PCCCCCCCCCCCC
• NNN-NNN-NNNN
• NNN-NNN-NAAA
• NNN-NNN-AAAA
• NNN-AAAAAAA

where:

• A: Alphanumeric (alpha or numeric)

• C: Character (alpha or blank)

• N: Numeric
• P: Alpha

CyberSource Global Payment Service


The CyberSource Global Payment Service supports the merchant descriptor field.

Important Before sending the merchant descriptor in your requests, contact CyberSource
Customer Support so that your CyberSource and processor accounts can be configured to
use the descriptor.

Credit Card Services Implementation Guide • June 2009 147


Merchant Descriptors

FDI Global
FDI Global supports the merchant descriptor field, the merchant descriptor contact field,
and the merchant descriptor alternate contact field. You can send as many or as few of
these fields as you like in an API request: no fields, one field, two fields, or all three fields.

Important Before sending merchant descriptors in your requests, you must first contact
FDI Global to register to use merchant descriptors. Then, you must call CyberSource
Customer Support so that your account can be configured to use the descriptors.

Contents and Formats


The merchant descriptor field must contain the following information:

• Your merchant DBA name.


• If payments are being made in installments, the merchant descriptor field must also
contain installment information such as “1 of 5” or “3 of 7.”
The merchant descriptor contact field must contain the following information:

• If you are submitting a retail request: City in which your store or outlet is located.
• If you are submitting a non-retail request: Your customer service telephone number.
The merchant descriptor alternate contact field must contain alternate contact information
such as a URL or email address.

Default Values
CyberSource always provides merchant descriptor information to the processor for you
for all capture and credit transactions. If you do not include merchant descriptor
information in your requests, CyberSource uses the default values in the merchant
configuration database as follows:

• If you do not include a merchant descriptor in your request, CyberSource uses the
merchant name from the merchant configuration database.
• If you do not include a merchant descriptor contact in your request, the value that
CyberSource uses depends on the type of transaction:
• For retail transactions, CyberSource uses the merchant city from the merchant
configuration database.
• For non-retail transactions, CyberSource uses the merchant phone number from
the merchant configuration database.
• If you do not include a merchant descriptor alternate contact in your request,
CyberSource uses the URL from the merchant configuration database.

148 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

FDMS South
FDMS South supports the merchant descriptor field. FDMS South allows 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.

Important Before sending the merchant descriptor in your requests, you must first contact
FDMS South to register to use merchant descriptors. Then, you must call CyberSource
Customer Support so that your account can be configured to use the descriptor.

GPN
GPN supports a dynamic merchant name descriptor and a dynamic merchant descriptor
contact.

Important Before sending merchant descriptors in your requests, you must first contact
your merchant account provider to register to use merchant descriptors.

OmniPay-Ireland
OmniPay-Ireland supports the merchant descriptor field. For OmniPay-Ireland, you must
use one of the following formats for the merchant descriptor:

• <12-character merchant DBA name>*<10-character product description>


• <7-character merchant DBA name>*<15-character product description>
• <3-character merchant DBA name>*<19-character product description>

Important Before sending the merchant descriptor in your requests, you must first contact
OmniPay-Ireland to register to use merchant descriptors. Then, you must call
CyberSource Customer Support so that your account can be configured to use the
descriptor.

Credit Card Services Implementation Guide • June 2009 149


Micropayments

Micropayments
Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• Most of the card types and processors that are supported by CyberSource
Micropayments are payments for less than one dollar.

Note If you want to process micropayments with the American Express Phoenix
processor, please contact Customer Support so that your account can be configured
correctly. When you request a micropayment with American Express Phoenix,
CyberSource must increase the amount of the authorization to $1 when the request is sent
to American Express Phoenix to accommodate their requirements. CyberSource records
the actual amount that you sent in your request in the CyberSource database. When you
request the subsequent capture or credit for the micropayment, you should make the
request for the actual amount.

Multi-Currency Service
Applicable services:
• Authorization
• Capture
• Credit
Supported processors:
• Chase Paymentech Solutions
If you want to sell your products in multiple countries, you might want to list your
product prices in your customers’ local currencies. The CyberSource Multi-Currency
Service lets you obtain current, guaranteed exchange rates. This lets customers pay using
their local currencies, while still allowing you to do business and settle transactions in
your desired currency.
For more information about the CyberSource Multi-Currency Service, see the Multi-
Currency Service Supplement, which is available at the Support Center.

150 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Payer Authentication
Important Before you implement payer authentication, you need to contact Customer
Support to have your account configured for this feature.

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
CyberSource Payer Authentication services to add Verified by Visa, JCB J/Secure™, or
MasterCard® SecureCode™ support to your Web store without running additional
software on your own server. The following table lists the cards supported for each type of
payer authentication.

Table 27 Supported Card Types for Payer Authentication

Type of Payer Card Types


Authentication

Verified by Visa Visa

JCB J/Secure JCB

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

For more information about payer authentication, see the Payer Authentication
Implementation Guide, which is available on the Support Center.

Verified by Visa
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• Atos
• Barclays
• CCS (CAFIS)
• Chase Paymentech Solutions
• 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 Implementation Guide • June 2009 151


Payer Authentication

• FDC Germany
• FDI Australia
• FDI Global
• FDMS Nashville
• FDMS South
• GPN
• HBoS
• HSBC
• OmniPay-Ireland
• 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 customer’s 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 visit http://visa.com/.
To request the authorization of a Verified by Visa transaction, add the fields listed in the
following table to your ics_auth request. The values for these fields are included in the
reply from the Validate Authentication service ics_pa_validate. If you request ics_pa_
validate and ics_auth together, the data is automatically passed from one service to the
other.

152 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Table 28 Request Fields for Verified by Visa and JCB J/Secure

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

CAVV—Cardholder authentication verification value. cavv pa_validate_cavv


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.
• 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.

CAVV Algorithm—Algorithm for generating the cavv_algorithm pa_validate_cavv_


CAVV. algorithm
• Used only for Atos.
• Required when you include the CAVV in your
request.
• You must not include the CAVV algorithm value in
your request if the CAVV is not included in your
request or if you are not using Atos.
• Possible values:
0: HMAC
1: CVV
2: CVV with ATN
3: MasterCard SPA algorithm

Credit Card Services Implementation Guide • June 2009 153


Payer Authentication

Table 28 Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

Commerce Indicator—Type of transaction. e_commerce_indicator pa_validate_e_commerce_


• Used for all processors that support Verified by indicator
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 Raw—Raw electronic commerce indicator. eci_raw pa_validate_eci_raw


• 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
Customer Support for information about your
processor’s requirements.

154 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Table 28 Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

PARes Status—Payer authentication response pares_status pa_validate_pares_status


status.
• Used only for Asia-Mideast Processing and Atos.
• For Atos: Required for a successful Verified by
Visa transaction, which is indicated when the
commerce indicator is vbv.
• For Asia-Mideast Processing: Required unless all
of the following are true:
• You are performing payer authentication and
authorization separately in different 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.
If all the preceding conditions are true, do not
include the PARes status in the authorization
request. If you do, CyberSource will send the
value to the processor without modification.
CyberSource will not decline the transaction;
any decline will be 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 Implementation Guide • June 2009 155


Payer Authentication

Table 28 Request Fields for Verified by Visa and JCB J/Secure (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

VERes Enrolled—Verification response enrollment veres_enrolled pa_enroll_veres_enrolled


status.
• Used only for Asia-Mideast Processing.
• Required for all payer authentication transactions.
• Possible values:
• Y: Authentication available.
• N: Cardholder not participating.
• U: Unable to authenticate regardless of the
reason.

XID—Transaction identifier. Must be 28-character xid pa_validate_xid


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.

156 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

JCB J/Secure
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• CCS (CAFIS)
• CyberSource Global Payment Service
• GPN
• 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 visit http://www.jcb-global.com/.
To request the authorization of a JCB J/Secure transaction, add the fields listed in the
preceding table to your ics_auth request. The values for these fields are included in the
reply from the Validate Authentication service ics_pa_validate. If you request ics_pa_
validate and ics_auth together, the data is automatically passed from one service to the
other.

MasterCard SecureCode
Applicable services:
• Authorization
Supported processors:
• Asia-Mideast Processing
• Atos
• Barclays
• CCS (CAFIS)
• CyberSource Global Payment Service
• 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.
• FDC Germany
• FDI Australia
• FDI Global

Credit Card Services Implementation Guide • June 2009 157


Payer Authentication

• FDMS Nashville
• FDMS South
• GPN
• HBoS
• HSBC
• OmniPay-Ireland
• 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
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 visit http://www.mastercard.com/.
To request the authorization of a MasterCard SecureCode transaction, add the fields in the
following table to your ics_auth request. The values for these fields are in the reply from
the Validate Authentication service ics_pa_validate. If you request ics_pa_validate and
ics_auth together, the data is automatically passed from one service to the other.

158 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Table 29 Request Fields for MasterCard SecureCode

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

CAVV Algorithm—Algorithm for generating the cavv_algorithm pa_validate_cavv_


UCAF authentication data. algorithm
• Used only for Atos.
• Required when you include the UCAF
authentication data in your request.
• You must not include the CAVV algorithm value in
your request if the UCAF authentication data is not
included in your request or if you are not using
Atos.
• Possible values:
0: HMAC
1: CVV
2: CVV with ATN
3: MasterCard SPA algorithm

Commerce Indicator—Type of transaction. e_commerce_indicator pa_validate_e_commerce_


• Used for all processors that support MasterCard indicator
SecureCode.
• Always required.
• Possible values for a MasterCard SecureCode
transaction:
• spa: MasterCard SecureCode transaction.
• spa_failure: MasterCard SecureCode
authentication failed. Available only for HSBC
and Streamline.

ECI Raw—Raw electronic commerce indicator. eci_raw pa_validate_eci_raw


• 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
Customer Support for information about your
processor’s requirements.

Credit Card Services Implementation Guide • June 2009 159


Payer Authentication

Table 29 Request Fields for MasterCard SecureCode (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

PARes Status—Payer authentication response pares_status pa_validate_pares_status


status.
• Used only for Asia-Mideast Processing and Atos.
• For Atos: Required for a successful MasterCard
SecureCode transaction, which is indicated when
the UCAF collection indicator is 2.
• For Asia-Mideast Processing: Required unless all
of the following are true:
• You are performing payer authentication and
authorization separately in different 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.
If all the preceding conditions are true, do not
include the PARes status in the authorization
request. If you do, CyberSource will send the
value to the processor without modification.
CyberSource will not decline the transaction;
any decline will be 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.

160 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Table 29 Request Fields for MasterCard SecureCode (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

UCAF Authentication Data—Authentication data for ucaf_authentication_ pa_validate_ucaf_


the universal cardholder authentication field. data authentication_data
• Used for all processors that support MasterCard
SecureCode.
• Required when the UCAF collection indicator is 2.
Do not include the UCAF authentication data in the
authorization request if the UCAF collection
indicator is not 2.

UCAF Collection Indicator—Collection indicator for ucaf_collection_ pa_validate_ucaf_


for the universal cardholder authentication field. indicator collection_indicator
• 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, but the UCAF was not populated.
• 2: UCAF collection is supported at your Web
site and the UCAF was populated. This
indicates a successful MasterCard SecureCode
transaction.

Credit Card Services Implementation Guide • June 2009 161


POS Transactions

Table 29 Request Fields for MasterCard SecureCode (Continued)

Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field

VERes Enrolled—Verification response enrollment veres_enrolled pa_enroll_veres_enrolled


status.
• Used only for Asia-Mideast Processing.
• Required for all payer authentication transactions.
• Possible values:
• Y: Authentication available.
• N: Cardholder not participating.
• U: Unable to authenticate regardless of the
reason.

XID—Transaction identifier. Must be 28-character xid pa_validate_xid


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.

POS Transactions
See “Retail POS Data” on page 167.

Prepaid Cards
See “American Express Prepaid Cards” on page 127.

Recurring Billing
See “Customer Profiles” on page 131.

162 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Recurring Payments
Applicable services:
• Authorization
Supported processors:
• See the following table.

Table 30 Processors That Support Recurring Payments

Processors Credit Card Types

American Express Brighton American Express

American Express Direct American Express

American Express Phoenix American Express

Asia-Mideast Processing Visa, MasterCard, American Express, Diners


Club, JCB

Barclays Visa, MasterCard, JCB

Chase Paymentech Solutions Visa, MasterCard, American Express, Discover

CyberSource Global Payment Service Carte Bleue


processor

FDC Germany Visa, MasterCard

FDI Australia Visa, MasterCard

FDI Global Visa, MasterCard

FDMS South Visa, MasterCard

FDMS Nashville Visa, MasterCard, American Express, Discover

GE Capital GE Money UK cards


GBP currency only

GPN Visa, MasterCard, American Express, Discover,


Diners Club, JCB

HBoS Visa, MasterCard

HSBC
Contact the CyberSource European office if you want to process recurring payments with HSBC.
To get the European office’s phone number, go to the CyberSource Web site at
www.cybersource.com and click the Contact Us link.

Credit Card Services Implementation Guide • June 2009 163


Recurring Payments

Table 30 Processors That Support Recurring Payments

Processors Credit Card Types

Lloyds-OmniPay Visa, MasterCard

LloydsTSB Cardnet Visa, MasterCard

OmniPay-Ireland Visa, MasterCard

Streamline
Contact the CyberSource European office if you want to process recurring payments with
Streamline. To get the European office’s phone number, go to the CyberSource Web site at
www.cybersource.com and click the Contact Us link.

TSYS Acquiring Solutions Visa, MasterCard, American Express, Discover

Note American Express and Discover have programs that you must sign up for if you
want to process recurring payments. Contact American Express and Discover for details
about their programs.

Depending on the type of products or services you sell, you might want to process
recurring payments for a customer. For example, you might want to charge a customer
$19.95 each month to access a service that you offer.

Note A customer’s recurring payment does not have to be for the same amount each time.

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 this clear.
To create a recurring payment:
1 For the first payment, send a regular request for credit card authorization.
Only if the first authorization is successful should you then submit authorizations for
recurring payments for that card.
2 For each subsequent recurring payment, send an authorization request using the
e-commerce indicator to indicate the payment is a recurring payment:
e_commerce_indicator=recurring
CyberSource also offers a service that allows you to create a profile for a customer in the
CyberSource system and then use that profile later to manually or automatically bill the
customer. CyberSource’s system eliminates the need for you to handle or store the
customer’s sensitive credit card information or create your own system for billing the
customer on a regular basis. For more information, see the Secure Data Suite User’s Guide,
which is available at the Support Center.

164 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

AVS and Recurring Payments


If the Address Verification Service is supported for your processor and card type, AVS is
run for every authorization request that you submit. For recurring payments, you should
check the AVS result for the first payment to make sure the information is accurate and to
reduce the risk of fraud.
You must decide how to handle the AVS results for the subsequent recurring 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 non-
fraudulent.
If you need to change the credit card number used for a series of recurring payments, treat
the first authorization with the new credit card number as a non-recurring payment and
closely evaluate the AVS results. You could then flag the subsequent payments as
recurring payments and ignore the AVS results.

Card Verification Number and Recurring Payments


If you are using the CyberSource Global Payment Service to process your transactions,
you must not include the card verification number in a recurring payment request. If you
do, CyberSource will reject the request due to invalid data.

Replacement Expiration Dates for Recurring Payments

Applicable service: Authorization

Supported processors See the following table.


and card types:

Table 31 Processors That Support Replacement Expiration Dates for Recurring Payments

Processors Credit Card Types

American Express Brighton American Express


You must contact American Express Brighton to get
approval for using replacement expiration dates
before using this feature.

Chase Paymentech Solutions Visa, MasterCard

FDI Australia Visa, MasterCard

FDMS South Visa, MasterCard

GE Capital GE Money UK card

Credit Card Services Implementation Guide • June 2009 165


Recurring Profiles

Table 31 Processors That Support Replacement Expiration Dates for Recurring Payments

Processors Credit Card Types

HBoS Visa, MasterCard

HSBC Visa, MasterCard, Maestro (International)

Lloyds-OmniPay Visa, MasterCard

LloydsTSB Cardnet Visa, MasterCard

Normally when you request a credit card authorization, you must supply 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 send a replacement expiration date of month=12 and
year=2021.

Important Do not use the replacement expiration date for cards that have not yet expired.
Use the replacement expiration date only for cards that have expired and only for
recurring payments.

Using the replacement expiration date for a recurring payment does not guarantee that
the authorization will be successful. The issuing bank determines if a card is authorized;
some issuing banks will not accept an expiration date that does not match what the
expiration date in the bank’s database.

To process a recurring payment authorization with a credit card that has expired, set these
fields in your authorization request:

• customer_cc_expmo = 12
• customer_cc_expyr = 2021

Recurring Profiles
See “Customer Profiles” on page 131.

166 CyberSource Corporation


Chapter 7 Optional Features for the SCMP API

Retail POS Data


Applicable services:
• Authorization
For a description of Retail point of sale (POS) data, including the list of processors for
which CyberSource supports retail transactions, see the API for Retail POS Transactions,
which is available at the Support Center.

Secure Data
See “Customer Profiles” on page 131.

Soft Descriptors
See “Merchant Descriptors” on page 144.

Split Dial/Route
See “Forced Captures” on page 139.

Subscriptions
See “Customer Profiles” on page 131.

Switch and Solo Cards


See “Maestro (UK Domestic) and Solo Cards” on page 143.

Type II Cards
See “Level II Data” on page 142.

Verbal Authorizations
See “Verbal Authorizations: The Authorization” on page 71.

Credit Card Services Implementation Guide • June 2009 167


Verified by Visa

Verified by Visa
See “Payer Authentication” on page 151.

168 CyberSource Corporation


Chapter 8
Testing Credit Card Services

To make sure that your requests are processed correctly, you need to test the basic success
and error conditions for each ICS service you plan to use.

Topics:
Requirements for Testing
Testing the Services
Going Live

Requirements for Testing


Important Before you can test, you must contact Customer Support to activate 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 to perform testing.


• Unless otherwise specified, use test credit card numbers, not real ones. See Table 32
on page 170.
• Use a real combination for the city, state, and postal code.
• Use a real combination for the area code and telephone number.
• Use a non-existent account and domain name for the customer’s email address.
• When testing a Global Payment Service country-specific bank card, such as Italy’s
Carta Si or Ireland’s Laser card, specify the appropriate country code when sending
the customer’s address and specify the currency used in that country.
• When testing the SCMP API, use the CyberSource test server ics2test.ic3.com.
• When testing the Simple Order API, use the test URL 
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor.

Credit Card Services Implementation Guide • June 2009 169


Testing the Services

Note If you are using the Global Payment Service and are testing captures, make sure to
capture the full amount of the authorization. Although a capture request for a partial
amount will not be rejected during testing, it will be rejected by the processor in
production.

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 card’s bin range. For best results, try each
test with a different ICS service request and with different test credit card numbers.

Table 32 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

Laser 6304 9850 2809 0561 515

Maestro (International) 5033 9619 8909 17


5868 2416 0825 5333 38

Maestro (UK Domestic) Issue number not required: 6759 4111 0000 0008
One-digit issue number required: 6759 5600 4500 5727 054
Two-digit issue number required: 5641 8211 1116 6669

MasterCard 5555 5555 5555 4444

Solo Issue number not required: 6334 5898 9800 0001


One-digit issue number required: 6767 8200 9988 0077 06
Two-digit issue number required: 6334 9711 1111 1114

UATP 1354 1234 5678 911

Visa 4111 1111 1111 1111

170 CyberSource Corporation


Chapter 8 Testing Credit Card Services

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.
To see the list of trigger amounts and responses for each processor, go to the Testing
Information page at the Support Center.

Testing American Express Card Verification


If you want to use card verification with American Express, follow these steps:
1 Contact American Express to register to use the feature.
2 Contact Customer Support after you are confirmed with American Express to use the
feature. Until CyberSource configures your account to use the card verification
number, you will receive a 1 in the reply field ccAuthReply_cvCode for the Simple
Order API, or in the field auth_cv_result for the SCMP API.
3 Test your system in production using a small dollar amount, such as one dollar.
Instead of using the test account numbers, use a real credit card account number, and
send an incorrect card verification number in the request for authorization.
The card should be refused and the request declined. If it is not, contact American
Express to confirm that your account is correctly configured to use the card
verification feature.

Going Live
You must go live with CyberSource before you begin to accept customers. When you go
live, your CyberSource account is updated so that you can send transactions to the
CyberSource production server. If you have not already done so, you will need to provide
your banking information to CyberSource so that your processor can deposit funds to
your merchant bank account.
To go live:
1 Go to the CyberSource Knowledgebase at http://www.cybersource.com/esupport.
2 Submit a question—click the Submit a Question link.
3 Log in with your CyberSource merchant ID and password. Use the same merchant ID
and password that you use to log in to the Business Center.
4 On the Submit a Question page, fill in the contact information.
5 For the General Topic, select Getting Set Up on CyberSource.
6 For the Specific Topic, select Go Live.
7 For the Subject, enter “Go Live”.
8 In the question field, indicate that you would like to go live.

Credit Card Services Implementation Guide • June 2009 171


Going Live

9 If you have not already submitted your banking information to CyberSource, include
the information in the question field and select the check box for This question
contains sensitive banking information.
10 Click Submit question.
You will receive an email with your support ticket number and a CyberSource
representative will contact you to complete the process.
11 After CyberSource has confirmed that you are live, update your system to send
requests to the production server and instead of the test server. See the documentation
for your client SDK for instructions.
After you go live, use real card numbers and other data to test every card type, currency,
and CyberSource application that your integration supports. Because these are real
transactions, use small amounts, such as one dollar, to do the tests. If you have more than
one CyberSource merchant ID, test each one separately. Process an authorization, capture,
and credit for each configuration. Use your bank statements to verify that money is
deposited into and withdrawn from your merchant bank account.

172 CyberSource Corporation


Appendix A
Fields for the Simple Order API

Topics:
Formatting Restrictions
Data Type Definitions
Request Fields
Reply Fields

Formatting Restrictions
Unless otherwise noted, all of the field names listed are case sensitive, and the fields
accept special characters such as @, #, and %.

Note The values of the item_#_ fields must not contain carets (^) or colons (:), because
these characters are reserved for use by the ICS services. The values of all request fields
must not contain newlines or carriage returns. However, they can contain embedded
spaces and any other printable characters. All leading and trailing spaces will be removed.

Data Type Definitions


For more information about these data types, see the World Wide Web Consortium (W3C)
XML Schema Part 2: DataTypes specification.

• Integer—Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}.


• String—Sequence of letters, numbers, spaces, and special characters, such as @ and #.

Credit Card Services Implementation Guide • June 2009 173


Request Fields

Request Fields
See “Correlating Schema and Name-Value Pair Fields Names” on page 36 for information
on how name-value pair names relate to their corresponding XML element names.

Note If you are using Customer Profiles and you provide recurringSubscriptionInfo_
subscriptionID in the request, many of the fields in the following table that are normally
required for authorization or credit become optional. For example, if you include
recurringSubscriptionInfo_subscriptionID and do not provide the normally required
billTo_city field in your authorization request, CyberSource uses the value for billTo_city
that is stored with the Customer Profile. If you include billTo_city in the request,
CyberSource uses the value from the request instead of the value stored in the Customer
Profile. See “Customer Profiles” on page 87.

Table 33 Request Fields for the Simple Order API

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

billTo_city City of the billing address. ccAuthService (R) String (50)

ccCreditService (R) (1)


ccDCCService (O)

billTo_company Name of the customer’s company. ccAuthService (O) String (40)


ccCreditService (O)

billTo_country Country of the billing address. Use the two- ccAuthService (R) String (2)
character country codes. (1)
ccCreditService (R)
ccDCCService (O)

billTo_customerID Your identifier for the customer. When a ccAuthService (O) String 
subscription is being created, the maximum (30 or 50)
ccCaptureService (O)
length for this field is 30. Otherwise, the
maximum length is 50. ccCreditService (O)

billTo_email Customer’s email address, including the full ccAuthService (R) String (255)
domain name. 
Example: jdoe@example.com ccCreditService (R) (1)
ccDCCService (O)

billTo_firstName Customer’s first name.The value should be ccAuthService (R) String (60)
the same as the one that is on the card. (1)
ccCreditService (R)
ccDCCService (O)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

174 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

billTo_hostname DNS resolved hostname from billTo_ ccAuthService (O) String (60)
ipAddress.

billTo_ Customer’s browser as identified from the ccAuthService (O) String (40)
httpBrowserType HTTP header data. For example, Mozilla
is the value that identifies the Netscape
browser.

billTo_ipAddress Customer’s IP address.  ccAuthService (O) String (15)


Example: 10.1.27.63

billTo_lastName Customer’s last name. The value should be ccAuthService (R) String (60)
the same as the one that is on the card. ccCreditService (R) (1)
ccDCCService (O)

billTo_personalID Personal identifier. For CyberSource Latin ccAuthService (See String (26)
American Processing, you can use this field the field description.)
for the Cadastro de Pessoas Fisicas (CPF),
which is required for the MasterCard AVS
check in some countries. Otherwise, it is
optional.

billTo_phoneNumber Customer’s phone number. CyberSource ccAuthService (O) String (15)


recommends that you include the country
ccCreditService (O)
code if the order is from outside the U.S.
ccDCCService (O)

billTo_postalCode Postal code for the billing address. The postal ccAuthService String (10)
code must consist of 5 to 9 digits. (Required when the
For a 9-digit postal code, use this format: billing country is the
[5 digits][dash][4 digits] U.S. or Canada.)
If the value of billTo_country is CA, the ccCreditService
postal code must follow these rules: (Required when the
billing country is the
• If the number of characters is greater than
U.S. or Canada.) (1)
3, the first 3 characters must be in this
format: ccDCCService (O)
[alpha][numeric][alpha].
• If the number of characters is 7, the last 3
characters must be in this format:
[numeric][alpha][numeric].

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 175


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

billTo_state State or province of the billing address. Use ccAuthService String (2)
the two-character codes. (Required when the
billing country is the
U.S. or Canada.)
ccCreditService
(Required when the
billing country is the
U.S. or Canada.) (1)
ccDCCService (O)

billTo_street1 First line of the billing street address as it ccAuthService (R) String (60)
appears on the credit card issuer’s records.
ccCreditService (R) (1)

billTo_street2 Second line of the billing street address. ccAuthService (O) String (60)
Used for additional address information.
ccCreditService (O)
Example:
Attention: Accounts Payable
Used for AVS by Chase Paymentech
Solutions and TSYS Acquiring Solutions.

bml_... The fields for Bill Me Later are described


separately in the Bill Me Later Supplement.

businessRules_ List of AVS flags that cause the request to be ccAuthService (O) String (255)
declineAVSFlags declined for AVS reasons. Use a space to
separate the flags in the list.
Important Make sure that you include the
value N in the list if you want to receive
declines for the AVS code N.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

176 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

businessRules_ Used when calling ccAuthService and ccAuthService (O) String (5)
ignoreAVSResult ccCaptureService together. Enables you to
use ccCaptureService even when the
authorization receives an AVS decline.
Possible values:
• true: Ignore the results of AVS checking
and run the ccCaptureService service.
• false (default): If the authorization
receives an AVS decline, do not run the
ccCaptureService service.
If the value of this field is true, the list in the
businessRules_declineAVSFlags field is
ignored.

businessRules_ Determines whether to allow ccAuthService (O) String (5)


ignoreCVResult ccCaptureService to run if the value of the
reply field ccAuthReply_cvCode is D or N.
Used only when both ccAuthService and
ccCaptureService are requested at the
same time.
Possible values:
• true: If the value of ccAuthReply_
cvCode is D or N, allow
ccCaptureService to run.
• false (default): If the value of
ccAuthReply_cvCode is D or N, return a
card verification decline and do not allow
ccCaptureService to run.

card_ Identifier for the issuing bank that provided ccAuthService String (3)
accountEncoderID the customer’s encoded account number. (Required when
Contact Chase Paymentech Solutions for the processing encoded
bank’s ID. See “Encoded Account Numbers” account numbers.)
on page 95.
ccCreditService
(Required when
processing encoded
account numbers.) (1)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 177


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

card_accountNumber Number given to customer for their account. ccAuthService (R) String with
numbers
When processing encoded account numbers, ccCreditService (R) (1) only (20)
use this field for the encoded account
number. ccDCCService (R)

For the DCC service, 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

178 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

card_cardType Type of card to authorize. To see which cards ccAuthService String (3)
can be handled by each processor, see (Required for the card
“Payment Processors” on page 6. Possible types that have
values: asterisks.)
• 001: Visa ccCreditService
• 002: MasterCard, Eurocard*—European (Required for the card
regional brand of MasterCard types that have
• 003: American Express asterisks.) (1)
• 004: Discover CyberSource strongly
recommends that you
• 005: Diners Club—See “MasterCard and
send the card type even
Diners Club Alliance” on page 3. if it is optional for your
• 006: Carte Blanche* processor and card
• 007: JCB* type. Omitting the card
type can cause the
• 014: EnRoute* transaction to be
• 021: JAL* processed with the
• 024: Maestro (UK Domestic), Solo* wrong card type.

• 031: Delta*—Use this value only for the


CyberSource Global Payment Service. For
other processors, use 001 for all Visa card
types.
• 032: Solo*—Use this value only for the
CyberSource Global Payment Service. For
other processors, use 024 for Solo cards.
• 033: Visa Electron*
• 034: Dankort*
• 035: Laser*
• 036: Carte Bleue*
• 037: Carta Si*
• 039: Encoded account number*
• 040: UATP*
• 042: Maestro (International)*
• 043: GE Money UK card*—Before
setting up your system to work with GE
Money UK cards, contact the CyberSource
UK Support Group.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 179


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

card_cvIndicator Card verification indicator used to indicate if a ccAuthService (O) String with
card verification value was sent. Possible numbers
values: only (1)
• 0 (default): CV number service not
requested. This default is used if you do
not include card_cvNumber in the
request.
• 1 (default): CV number service requested
and supported. This default is used if you
include card_cvNumber in the request.
• 2: CV number on credit card is illegible.
• 9: CV number was not imprinted on credit
card.

card_cvNumber Card verification number. See “Card ccAuthService (O) String with
Verification Numbers” on page 27 for a list of numbers
processors that accept the card verification only (4)
number.
Do not include this field if you are using FDI
Global or FDMS South and performing a $0
authorization.
Do not include this field if you are using the
CyberSource Global Payment Service and
you set ccAuthService_
commerceIndicator=recurring.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

180 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

card_expirationMonth Two-digit month that the credit card expires ccAuthService (R) String (2)
in. Format: MM. 
ccCreditService (See
Possible values: 01 through 12.
description) (1)
For encoded account numbers (card_
ccDCCService (O)
cardType=039), use 12 if there is no
expiration date available.
For credits, the following processors do not
require this field:
• American Express Direct
• American Express Phoenix
• Chase Paymentech Solutions
• FDI Global
• FDMS Nashville
• FDMS South
• TSYS Acquiring Solutions
All other processors require this field for
credits.

card_expirationYear Four-digit year that the credit card expires in. ccAuthService (R) String (4)
Format: YYYY.
ccCreditService (See
For encoded account numbers (card_ description) (1)
cardType=039), if there is no expiration date
ccDCCService (O)
available, use 2021.
For credits, the following processors do not
require this field:
• American Express Direct
• American Express Phoenix
• Chase Paymentech Solutions
• FDI Global
• FDMS Nashville
• FDMS South
• TSYS Acquiring Solutions
All other processors require this field for
credits.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 181


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

card_issueNumber Indicates how many times a Maestro (UK ccAuthService String (5)
Domestic) or Solo card has been issued to (Required if an issue
the account holder. The card might or might number is on the card.)
not have an issue number; the field is
required if the card has an issue number. The ccCreditService (1)
number can consist of one or two digits, and (Required if an issue
the first digit might be a zero. Include exactly number is on the card.)
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) or Solo card.

card_startMonth Month of the start of the Maestro (UK ccAuthService String (2)
Domestic) or Solo card validity period. The (Required if an issue
card might or might not have a start date number is on the card.)
printed on it; the field is required if the card
has a start date. Do not include the field, ccCreditService (1)
even with a blank value, if the card is not a (Required if an issue
Maestro (UK Domestic) or Solo card. number is on the card.)
Format: MM. 
Possible values: 01 through 12.

card_startYear Year of the start of the Maestro (UK ccAuthService String (4)
Domestic) or Solo card validity period. The (Required if an issue
card might or might not have a start date number is on the card.)
printed on it; the field is required if the card
has a start date. Do not include the field, ccCreditService (1)
even with a blank value, if the card is not a (Required if an issue
Maestro (UK Domestic) or Solo card. number is on the card.)
Format: YYYY.

ccAuthReversal The requestID for the authorization that you ccAuthReversal String (26)
Service_ want to reverse. Service (R)
authRequestID

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

182 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ccAuthReversal The requestToken value returned from a ccAuthReversal String (256)


Service_ previous request for ccAuthService. Service (O)
authRequestToken
The field is an encoded string that contains
no confidential information, such as an
account number or card verification number.
The string can contain up to 256 characters.
This field is available only for merchants who
implemented request tokens before July
2008. For new implementations, use the
orderRequestToken field.
For more information, see “Working with
Request Tokens” on page 38.

ccAuthReversal Whether to include ccAuthReversalService ccAuthReversal String (5)


Service_run in your request. Possible values: Service (R)
• true: Include the service in your request.
• false (default): Do not include the
service in your request.

ccAuthService_ Unique alphanumeric value that identifies ccAuthService String (15)


aggregatorID you if you are an aggregator. (Required for
aggregators for the
American Express card
type.)

ccAuthService_ Set this field to verbal to indicate that you ccAuthService String (6)
authType are performing a forced capture, which (Required for a forced
means that you received the authorization capture.)
code outside the CyberSource system. See
“Forced Captures” on page 95.

ccAuthService_ Level of AVS service to use for the request. ccAuthService (O) String (8)
avsLevel Used only for the American Express Phoenix
processor. The field is case sensitive.
Possible values:
• Standard
• Enhanced
• AAVPlus
The AVS level you specify in this field
overrides the default level your merchant ID
is configured to use. See “Address
Verification Service” on page 23.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 183


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ccAuthService_ Indicates that this is a bill the customer is ccAuthService (O) String (1)
billPayment paying with a Visa card. See “Bill Payments
with Visa” on page 84 for a list of processors
that support this feature. Possible values:
• N (default): Not a bill payment
• Y: Bill payment

ccAuthService_cavv Cardholder authentication verification value ccAuthService String (40)


(CAVV). For the description and
requirements, see “Payer Authentication” on
page 107.

ccAuthService_ Algorithm used to generate the CAVV for ccAuthService String (1)
cavvAlgorithm Verified by Visa or the UCAF authentication
data for MasterCard SecureCode. For the
description and requirements, see “Payer
Authentication” on page 107.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

184 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ccAuthService_ Type of transaction. Some card associations ccAuthService String (13)


commerceIndicator use this information when determining (Required for payer
discount rates. For the CyberSource Global authentication
Payment Service, if you omit this field, the transactions.
processor uses the default transaction type Otherwise, optional.)
they have on file for you instead of the default
ccCreditService
value listed here.
(Optional. Only
Payer Authentication Transactions internet, moto, and
For the possible values and requirements, recurring are valid
see “Payer Authentication” on page 107. values.) (1)
Other Types of Transactions
Possible values:
• install: Installment profile: payments
will be made in installments.This value is
valid only for Visa. The installment_
sequence and installment_totalCount
fields are required.
• internet (default): eCommerce order
placed using a Web site. For the
CyberSource Global Payment Service,
internet is supported only for Carte
Bleue transactions.
• moto: Mail order or telephone order. Not
supported for UATP or for any Bill Me
Later gateways. For the CyberSource
Global Payment Service, moto is currently
supported only for Carte Bleue
transactions.
• moto_cc: Mail order or telephone order
from a call center. This value is available
only for Asia-Mideast Processing.
• recurring: Recurring transaction. See
“Recurring Payments” on page 119 for a
list of processors that support this value.

ccAuthService_ Raw electronic commerce indicator (ECI). ccAuthService String (2)


eciRaw For the description and requirements, see
“Payer Authentication” on page 107.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 185


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ccAuthService_ Payer authentication response status. For the ccAuthService String (1)
paresStatus description and requirements, see “Payer
Authentication” on page 107.

ccAuthService_run Whether to include ccAuthService in your ccAuthService (R) String (5)


request. Possible values:
• true: Include the service in your request.
• false (default): Do not include the
service in your request.

ccAuthService_ Authorization code you received from an ccAuthService String (6)


verbalAuthCode authorization that you performed outside the (Required for a forced
CyberSource system. See “Forced Captures” capture.)
on page 95.

ccAuthService_ Verification response enrollment status. For ccAuthService String (1)


veresEnrolled the description and requirements, see “Payer
Authentication” on page 107.

ccAuthService_xid Transaction identifier. For the description and ccAuthService String (40)
requirements, see “Payer Authentication” on
page 107.

ccCaptureService_ Value of requestID returned from a previous ccCaptureService String (26)


authRequestID ccAuthReply. (Required unless
ccAuthService and
ccCaptureService are
both called in the same
request.)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

186 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ccCaptureService_ The requestToken value returned from a ccCaptureService (O) String (256)
authRequestToken previous request for ccAuthService. If you
request the authorization and capture
services together, the capture request does
not require a request token.
The field is an encoded string that contains
no confidential information, such as an
account number or card verification number.
The string can contain up to 256 characters.
This field is available only for merchants who
implemented request tokens before July
2008. For new implementations, use the
orderRequestToken field.
For more information, see “Working with
Request Tokens” on page 38.

ccCaptureService_ If the transaction contains a verbally ccCaptureService (O) String (6)


authType authorized transaction, this field must contain
the value verbal.

ccCaptureService_ This field is required for FDMS South for ccCaptureService String (12)
posData verbal authorizations and forced captures (See the field
with the American Express card type to description.)
support the CAPN requirements:
• For a forced capture, obtain the value for
this field from the authorization response.
• For a verbal authorization, you cannot
obtain a value for this field. Therefore,
CyberSource will use the default value.
Default: Value generated by CyberSource
based on various factors of the transaction
such as retail or internet, card present or not,
and swiped or keyed.

ccCaptureService_run Whether to include ccCaptureService in ccCaptureService (R) String (5)


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

Credit Card Services Implementation Guide • June 2009 187


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ccCaptureService_ This field is required for FDMS South for ccCaptureService String (15)
transactionID verbal authorizations and forced captures (See the field
with the Amercing Express card type to description.)
support the CAPN requirements:
• For a forced capture, obtain the value for
this field from the authorization response.
• For a verbal authorization, you cannot
obtain a value for this field. Therefore,
CyberSource will use the default value.
See “Verbal Authorizations: The Capture”
on page 53 for information about using the
default for this field for verbal
authorizations.
Default: 000000000000000 (15 zeros)

ccCaptureService_ Verbally received authorization code. ccCaptureService (O) String (6)


verbalAuthCode
For CCS
(CAFIS):
String (7)

ccCreditService_ Unique alphanumeric value that identifies ccCreditService String (15)


aggregatorID you if you are an aggregator. (Required for
aggregators for the
American Express card
type.)

ccCreditService_ Indicates that this is a credit for a bill the ccCreditService (O) String (1)
billPayment customer paid with a Visa card. See “Bill
Payments with Visa” on page 84 for a list of
processors that support bill payments with
Visa. Possible values:
• N (default): Not a credit for a bill payment
• Y: Credit for a bill payment.

ccCreditService_ The requestID returned from a previous ccCreditService (O) String (26)
captureRequestID request for capture. Creates a follow-on
credit by linking the credit to the previous
capture. If you send this field, you do not
need to send several other credit request
fields. See “Crediting a Payment” on page 55
for more information about follow-on credits.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

188 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ccCreditService_ The requestToken value returned from a ccCreditService (O) String (256)
captureRequestToken previous request for ccCaptureService. This
field is required only for follow-on credit
requests; it is not required for stand-alone
credit requests.
The field is an encoded string that contains
no confidential information, such as an
account number or card verification number.
The string can contain up to 256 characters.
This field is available only for merchants who
implemented request tokens before July
2008. For new implementations, use the
orderRequestToken field.
For more information, see “Working with
Request Tokens” on page 38.

ccCreditService_ Type of transaction. Use with stand-alone ccCreditService (O) String (13)
commerceIndicator credits. Certain card associations use this
information when determining discount rates.
Possible values:
• internet (default): eCommerce order
placed using a Web site.
• moto: Mail order or telephone order. Not
supported for all Bill Me Later gateways.
• recurring: Recurring mail order or
telephone transaction. See “Recurring
Payments” on page 119 for a list of
processors that support this value.

ccCreditService_run Whether to include ccCreditService in your ccCreditService (R) String (5)


request. Possible values:
• true: Include the service in your request.
• false (default): Do not include the
service in your request.

ccDCCService_run Flag that indicates if ccDCCService needs to ccDCCService (R) String (5)
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

Credit Card Services Implementation Guide • June 2009 189


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

dcc_dccIndicator Flag that indicates if DCC is being used for ccAuthService (See String (1)
the transaction. For details, see“Dynamic description)
Currency Conversion (DCC)” on page 88.
ccCaptureService
Possible values:
(See description)
• 1: Converted—DCC is being used.
ccCreditService (See
• 2: Non-convertible—DCC cannot be description)
used.
• 3: Declined—DCC could be used, but the
customer declined it.
This field is required if you called the DCC
service for the purchase.

debtIndicator Flag that presently applies solely to Visa ccAuthService (O) String (1)
purchase transactions and indicates to Visa
that the purchase is for payment on an
existing debt. Usage of the debt indicator is
limited to specific MCCs; contact your
acquirer to find out if usage of this data
element is applicable. Possible values:
• N: The payment is not for an existing debt.
• Y: The payment is for an existing debt.
For a list of processors that support the debt
indicator, see “Bill Payments with Visa” on
page 84.

fundingTotals_... The fields for the Multi-Currency Service are


listed separately in the Multi-Currency
Service Supplement.

installment_sequence Installment number when making payments ccAuthService Integer (2)


in installments. Used along with installment_ (Optional for Chase
totalCount to keep track of which payment is Paymentech Solutions.
being processed. For example, the 2nd of 5 For all other
payments would be passed to CyberSource processors, required for
as installment_sequence = 2 and installment transactions
installment_totalCount = 5. This field is (ccAuthService_
used only for Visa. commerceIndicator =
For Chase Paymentech Solutions: This field
install).)
is optional because this value is required in
the merchant descriptor. See “Merchant
Descriptors” on page 100.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

190 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

installment_totalCount • Total number of installments when making ccAuthService Integer (2)


payments in installments. Used along with (Optional for Chase
installment_sequence to keep track of Paymentech Solutions.
which payment is being processed. For For all other
example, the 2nd of 5 payments would be processors, required for
passed to CyberSource as installment_ installment transactions
sequence = 2 and installment_ (ccAuthService_
totalCount = 5. This field is used only for commerceIndicator =
Visa. install).)
• For Chase Paymentech Solutions: This
field is optional because this value is
required in the merchant descriptor. See
“Merchant Descriptors” on page 100.

invoiceHeader_ Four Transaction Advice Addendum (TAA) ccCaptureService (O) String (40)
amexDataTAA1 fields. These fields are used to display
ccCreditService (O)
descriptive information about a transaction
invoiceHeader_
on the customer’s American Express card
amexDataTAA2
statement. If you are sending any TAA fields,
invoiceHeader_ start with invoiceHeader_amexDataTAA1,
amexDataTAA3 then ...TAA2, and so on. Skipping a TAA field
invoiceHeader_ causes subsequent TAA fields to be ignored.
amexDataTAA4 Contact Customer Support if you plan to use
these fields so that your account can be
configured appropriately.
For information about merchant descriptors,
including which processors support this field,
see “Merchant Descriptors” on page 100.
These fields are frequently used for Level II
transactions. See the Level II and Level III
Processing Addendum, which is available at
the Support Center.

invoiceHeader_ Merchant description that is displayed on the ccCaptureService String (22)


merchantDescriptor cardholder's statement. For information about
ccCreditService For
merchant descriptors, including which
OmniPay-
processors support this field and special (Optional for FDI
Ireland:
formatting required for some processors, see Global. For all other
String(23)
“Merchant Descriptors” on page 100. processors, required if
invoiceHeader_
If you use more than one consecutive space,
merchantDescriptor
extra spaces will be removed.
Contact is set.)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 191


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

invoiceHeader_ Alternate merchant contact information, such ccCaptureService (O) String (32)
merchantDescriptor as a URL or email address, that is displayed
ccCreditService (O)
Alternate on the cardholder's statement. For
information about merchant descriptors,
including which processors support this field
and special formatting required for some
processors, see “Merchant Descriptors” on
page 100.

invoiceHeader_ Merchant contact information, such as a ccCaptureService String (13)


merchantDescriptor phone number, that is displayed on the
ccCreditService For FDI
Contact cardholder's statement. For information about
Global:
merchant descriptors, including which (Required for Chase
String (11)
processors support this field and special Paymentech Solutions if
formatting required for some processors, see invoiceHeader_
“Merchant Descriptors” on page 100. merchantDescriptor is
set. Optional for all
If you use more than one consecutive space,
other processors.)
extra spaces will be removed.

item_#_productCode Type of product. This value is used to ccAuthService (O) String (30)
determine the category that the product is in:
ccCaptureService (O)
electronic, handling, physical, service, or
shipping. The default value is default. See ccCreditService (O)
Table 43 on page 297 for a list of valid ccDCCService (O)
values.
For ccAuthService, if you set this to a value
other than default, stored_value, or
any of the values related to shipping and/or
handling, the item_#_quantity, item_#_
productName, and item_#_productSKU
fields are required.

item_#_productName Name of the product. For ccAuthService, ccAuthService (See String (30)
required if item_#_productCode is not the field description.)
default, stored_value, or one of the ccCaptureService (O)
values related to shipping and/or handling.
ccDCCService (O)

item_#_productSKU Product’s identifier code. For ccAuthService (See String (30)


ccAuthService, required if item_#_ the field description.)
productCode is not default, stored_
ccCaptureService (O)
value, or one of the values related to
shipping and/or handling. ccDCCService (O)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

192 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

item_#_quantity Quantity of the product being purchased. The ccAuthService (See Integer (10)
default value is 1. For ccAuthService, the field description.)
required if item_#_productCode is not ccAuthReversal
default, stored_value, or one of the Service (O)
values related to shipping and/or handling.
ccCaptureService (O)
ccCreditService (O)
ccDCCService (O)

item_#_taxAmount Total tax to apply to the product. This value ccAuthService (O) String (15)
cannot be negative.
The item_#_taxAmount field is additive. For
example, if you send one item with unitPrice
of $10.00 and taxAmount of $0.80, and you
send another item with unitPrice of $20.00
and taxAmount of $1.60, the total amount
authorized will be for $32.40, not $30.00 with
$2.40 of tax included. The item_#_
taxAmount and the item_#_unitPrice must
be in the same currency.
If you want to include item_#_taxAmount
and also request the taxService service, see
the Tax Calculation Implementation Guide,
which is available at the Support Center.
This field is frequently used for Level II and
Level III transactions. See the Level II and
Level III Processing Addendum, which is
available at the Support Center.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 193


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

item_#_unitPrice Per-item price of the product. You must ccAuthService String (15)
include either this field or purchaseTotals_
ccAuthReversal
grandTotalAmount in your request. See
Service
“Using Items or a Grand Total in the Request”
on page 40. ccCaptureService
Important Some processors have specific ccCreditService
requirements and limitations, such as See the field
maximum amounts and maximum field description.
lengths. This information is covered in:
ccDCCService (R)
• Authorizations—Table 2 on page 11
• Captures—Table 4 on page 15
• Credits—Table 5 on page 18
This value cannot be negative. You can
include a decimal point (.) in this field, but you
cannot include any other special characters.
The amount will be truncated at the request
level to the correct number of decimal places.
If your processor supports $0 authorizations,
you can set this field to 0 for the authorization
to check if the card is lost or stolen. See “$0
Authorizations” on page 82 for the list of
supported processors.
For DCC, this value is the original amount in
your local currency. You must include this
field. You cannot use purchaseTotals_
grandTotalAmount.

jpo_bonusAmount Japanese payment option bonus amount: ccAuthService Non-


Amount of the payment during the bonus negative
ccCaptureService
month. The value must be greater than 0. integer (8)
ccCreditService
Required if jpo_
paymentMethod is 6.
Otherwise, not used.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

194 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

jpo_bonuses Japanese payment option bonuses: Number ccAuthService Integer (2)


of bonus payments.
ccCaptureService
ccCreditService
Required if jpo_
paymentMethod is 3 or
6. Otherwise, not used.

jpo_installments Japanese payment option installments: ccAuthService Integer (2)


Number of installment payments.
ccCaptureService
ccCreditService
Required if jpo_
paymentMethod is 4 or
6. Otherwise, not used.

jpo_paymentMethod Japanese payment option payment method: ccAuthService (O) Integer (1)
type of payment option. Possible values:
ccCaptureService (O)
• 1 (default): Single payment
ccCreditService (O)
• 2: Bonus payment
• 3: Installment bonus payment
• 4: Installment
• 5: Revolving repayment
• 6: Combination of installment and bonus
payment
See “Japanese Payment Options” on
page 96.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 195


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

merchantDefinedData_ Four fields that you can use to store ccAuthService (O) String (64)
field1 information.
ccCaptureService (O)
merchantDefinedData_ Warning Merchant-defined data fields are ccCreditService (O)
field2 not intended to and MUST NOT be used to
merchantDefinedData_ capture personally identifying information.
field3 Accordingly, merchants are prohibited from
capturing, obtaining, and/or transmitting any
merchantDefinedData_ personally identifying information in or via the
field4 merchant-defined data fields. Personally
identifying information includes, but is not
limited to, name, 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 merchant-defined 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.
Note If you are creating a profile based on
an authorization, the merchant-defined data
fields do not get transferred to the new
profile.

merchantID Your CyberSource merchant ID. Use the Required for all Credit String (30)
same merchantID for evaluation, testing, Card Services.
and production.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

196 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

merchantReference Merchant-generated order reference or Required for all Credit Atos:


Code tracking number. CyberSource recommends Card Services. String (32)
that you send a unique value for each
FDI Global:
transaction so that you can perform
Numeric (8)
meaningful searches for the transaction See
“Tracking Orders” on page 46. All other
processors:
For FDI Global: This value must be numeric
String (50)
and must be less than 9 digits. If you do not
send a valid value, CyberSource will create
one for you. However, the value will not be
returned to you so you will not be able to use
the merchant reference code to track the
order.

orderRequestToken The requestToken value returned from a ccAuthReversal String (256)


previous request. This value links the Service (R)
previous request to the current follow-on
ccCaptureService (R)
request. This field is an encoded string that
does not contain any confidential information, ccCreditService (R)
such as account numbers or card verification voidService (R)
numbers. The string can contain up to 256
characters.
For more information, see “Working with
Request Tokens” on page 38.

purchaseTotals_ Currency used for the order. Use the ISO ccAuthService (R) String (5)
currency currency codes.
ccAuthReversal
For ccAuthReversalService and Service (R)
ccCaptureService, you must use the same
ccCaptureService (R)
currency that you used in your request for
ccAuthService. ccCreditService (R)
For DCC, this is your local currency. ccDCCService (R)

purchaseTotals_ Exchange rate returned by the DCC service. ccAuthService (R for String (13)
exchangeRate Includes a decimal point and up to 4 decimal DCC transactions)
places. For details, see “Dynamic Currency
ccCaptureService (R
Conversion (DCC)” on page 88.
for DCC transactions)
ccCreditService (R for
DCC transactions)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 197


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

purchaseTotals_ Time stamp for the exchange rate. This value ccAuthService (R for String (14)
exchangeRateTime is returned by the DCC service. For details, DCC transactions)
Stamp see “Dynamic Currency Conversion (DCC)”
ccCaptureService (R
on page 88.
for DCC transactions)
Format: YYYYMMDD~HH:MM
ccCreditService (R for
where ~ denotes a space. DCC transactions)

purchaseTotals_ Converted amount returned by the DCC ccAuthService (R for String (15)
foreignAmount service. For details, see “Dynamic Currency DCC transactions)
Conversion (DCC)” on page 88.
ccCaptureService (R
for DCC transactions)
ccCreditService (R for
DCC transactions)

purchaseTotals_ Billing currency returned by the DCC service. ccAuthService (R for String (5)
foreignCurrency ISO code for the currency of the converted DCC transactions)
amount. See the Support Center for a list of
ccCaptureService (R
ISO codes. For details about DCC, see
for DCC transactions)
“Dynamic Currency Conversion (DCC)” on
page 88. ccCreditService (R for
DCC transactions)

purchaseTotals_ Grand total for the order. You must include ccAuthService String (15)
grandTotalAmount either this field or item_#_unitPrice in your
ccAuthReversal
request. See “Using Items or a Grand Total in
Service
the Request” on page 40.
ccCaptureService
Important Some processors have specific
requirements and limitations, such as ccCreditService
maximum amounts and maximum field See the field
lengths. This information is covered in: description.
• Authorizations—Table 2 on page 11
• Captures—Table 4 on page 15
• Credits—Table 5 on page 18
If your processor supports $0 authorizations,
you can set this field to 0 for the authorization
to check if the card is lost or stolen. See “$0
Authorizations” on page 82 for the list of
supported processors.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

198 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

recurringSubscription Profile ID. If you are using Customer Profiles, ccAuthService (O) String (26)
Info_subscriptionID you can request an authorization, sale, or
ccCreditService (O)
credit and use a profile ID to reference the
profile information. See “Customer Profiles”
on page 87.

shipFrom_postalCode Postal code for the address from which the ccCaptureService (O) String (10)
goods are shipped, which is used to
ccCreditService (O)
determine nexus. The default is the merchant
postal code stored in the CyberSource
merchant configuration database.
The postal code must consist of 5 to 9 digits.
For a 9-digit postal code, use this format:
[5 digits][dash][4 digits]
If the country from which the goods are being
shipped is Canada, the postal code must
follow these rules:
• If the number of characters is greater than
3, the first 3 characters must be in this
format:
[alpha][numeric][alpha].
• If the number of characters is 7, the last 3
characters must be in this format:
[numeric][alpha][numeric].
This field is frequently used for Level II and
Level III transactions. See the Level II and
Level III Processing Addendum, which is
available at the Support Center.

shipTo_city City to ship the product to. ccAuthService String (50)


(Required when
shipping to the U.S. or
Canada.)

shipTo_country Country to ship the product to. Use the two- ccAuthService String (2)
character country codes. (Required if any
shipping address
information is included.)
ccCaptureService (O)
ccCreditService (O)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 199


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

shipTo_firstName First name of the person receiving the ccAuthService (O) String (60)
product.

shipTo_lastName Last name of the person receiving the ccAuthService (O) String (60)
product.

shipTo_postalCode Postal code for the shipping address. The ccAuthService String (10)
postal code must consist of 5 to 9 digits. (Required when
For a 9-digit postal code, use this format: shipping to the U.S. or
[5 digits][dash][4 digits] Canada.)
If the value of shipTo_country is CA, the ccCaptureService (O)
postal code must follow these rules: ccCreditService (O)
• If the number of characters is greater than
3, the first 3 characters must be in this
format:
[alpha][numeric][alpha].
• If the number of characters is 7, the last 3
characters must be in this format:
[numeric][alpha][numeric].

shipTo_ Shipping method for the product. Possible ccAuthService (O) String (10)
shippingMethod 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

shipTo_state State or province of the address to ship the ccAuthService String (2)
product to. Use the two-character codes. (Required when
shipping to the U.S. or
Canada.)

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

200 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

shipTo_street1 First line of the address to ship the product ccAuthService String (60)
to. (Required if any
shipping address
information is included
in the request.)

shipTo_street2 Second line of the address to ship the ccAuthService (O) String (60)
product to.

ucaf_ Universal cardholder authentication field ccAuthService String (32)


authenticationData (UCAF) data. For the description and
requirements, see “Payer Authentication” on
page 107.

ucaf_ Universal cardholder authentication field ccAuthService String with


collectionIndicator (UCAF) collection indicator. For the numbers
description and requirements, see “Payer only (1)
Authentication” on page 107.

voidService_run Whether to include voidService in your voidService (R) String (5)


request. Possible values:
• true: Include the service in your request.
• false (default): Do not include the
service in your request.

voidService_ The requestID of the capture or credit you voidService (R) String (26)
voidRequestID want to void.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

Credit Card Services Implementation Guide • June 2009 201


Request Fields

Table 33 Request Fields for the Simple Order API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

voidService_ The requestToken value returned from a voidService (O) String (256)
voidRequestToken previous request for a service that you want
to void. You can void captures, credits,
electronic check debits, and Bill Me Later
transactions that have not been batched or
voided before. For example, if you want to
void a capture, set this field to the
requestToken value returned in the reply for
the capture request.
The field is an encoded string that contains
no confidential information, such as an
account number or card verification number.
The string can contain up to 256 characters.
This field is available only for merchants who
implemented request tokens before July
2008. For new implementations, use the
orderRequestToken field.
For more information, see “Working with
Request Tokens” on page 38.

(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID

202 CyberSource Corporation


Appendix A Fields for the Simple Order API

Reply Fields
Table 34 Reply Fields for the Simple Order API

Data Type &


Field Name Description Returned By
Length

ccAuthReply_ Prepaid card balance. If there is a balance ccAuthReply String (12)


accountBalance remaining on a prepaid card after an
authorization, the balance is returned in
this field. See “American Express Prepaid
Cards” on page 83.

ccAuthReply_amount Total amount of the authorization. ccAuthReply String (15)

ccAuthReply_ Authorization code. Returned only if a ccAuthReply String (7)


authorizationCode value is returned by the processor.
For TSYS Acquiring Solutions, the
returned value for a successful $0
authorization is 000000. See “$0
Authorizations” on page 82.
For Citibank’s CitiVendor encrypted
account number program, the returned
value is OFFLINE. See “Encoded
Account Numbers” on page 95.

ccAuthReply_ Time of authorization.  ccAuthReply String (20)


authorizedDateTime Format: YYYY-MM-DDThh:mm:ssZ 
Example: 2005-08-11T22:47:57Z is
equal to August 11, 2005, at 10:47:57 P.M.
The T separates the date and the time.
The Z indicates UTC.

ccAuthReply_avsCode Results of address verification. See ccAuthReply String (1)


“Address Verification Service” on page 47
for information about how AVS works. See
Appendix G, “Address Verification Service
Codes,” on page 291 for a list of possible
values.

ccAuthReply_ AVS result code sent directly from the ccAuthReply String (10)
avsCodeRaw processor. Returned only if a value is
returned by the processor.
Note Do not use this field to interpret the
result of AVS. Use for debugging
purposes only.

Credit Card Services Implementation Guide • June 2009 203


Reply Fields

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

ccAuthReply_ Verified by Visa response code. Possible ccAuthReply String (1) 


cavvResponseCode values: or 
• 0 = CAVV not validated because String (3)
erroneous data was submitted
• 1 = CAVV failed validation and
authentication
• 2 = CAVV passed validation and
authentication
• 3 = CAVV passed the validation
attempt
• 4 = CAVV failed the validation attempt
• 6 = CAVV not validated because the
issuer does not participate
• 7 = CAVV failed the validation attempt
and the issuer is available (U.S.-issued
card / non-U.S. acquirer)
• 8 = CAVV passed the validation
attempt and the issuer is available
(U.S.-issued card / non-U.S. acquirer)
• 9 = CAVV failed the validation attempt
and the issuer is not available (U.S.-
issued card / non-U.S. acquirer)
• 99 = An unknown value was returned
from the processor
• A = CAVV passed the validation
attempt and the issuer is not available
(U.S.-issued card / non-U.S. acquirer)
• B = CAVV passed the validation with
information only; no liability shift
• C = CAVV attempted but not validated;
issuer did not return CAVV code
• D = CAVV not validated or
authenticated; issuer did not return
CAVV code
• I = Invalid security data
• U = Issuer does not participate or 3-D
secure data was not utilized

204 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

ccAuthReply_ Raw Verified by Visa response code sent ccAuthReply String (1) 
cavvResponseCodeRaw directly from the processor. or 
String (3)

ccAuthReply_cvCode Result of processing the card verification ccAuthReply String (1)


number. See “Card Verification Numbers”
on page 48 for information about how the
card verification check works. See
Appendix H, “Card Verification Number
Codes,” on page 295 for a list of the
possible values for this field.

ccAuthReply_ Card verification result code sent directly ccAuthReply String (10)
cvCodeRaw from the processor. Returned only if a
value is returned by the processor.
Note Do not use this field to interpret the
result of card verification. Use for
debugging purposes only.

ccAuthReply_ Name of the Japanese acquirer that ccAuthReply String (32)


forwardCode processed the transaction. Returned only
for CCS (CAFIS). Please contact the
CyberSource Japan Support Group for
more information.

ccAuthReply_ The fields for the Multi-Currency Service


fundingTotals_... are listed separately in the Multi-Currency
Service Supplement.

ccAuthReply_ The fields for the Multi-Currency Service


fxQuote... are listed separately in the Multi-Currency
Service Supplement.

Credit Card Services Implementation Guide • June 2009 205


Reply Fields

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

ccAuthReply_ Code associated with the reason the ccAuthReply String (2)
merchantAdviceCode recurring payment transaction was
declined. This field is used only for
MasterCard. Possible values:
• 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_ Raw merchant advice code sent directly ccAuthReply String (2)
merchantAdviceCode from the processor. This field is used only
Raw for MasterCard.

ccAuthReply_ Personal identifier result. For ccAuthReply String (1)


personalIDCode 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. Possible values:
• Y: Match
• N: No match
• K: Not supported
• U: Unknown
• Z: No response returned

206 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

ccAuthReply_ For most processors, this is the error ccAuthReply String (10)
processorResponse message sent directly from the bank.
Returned only if a value is returned by the
processor.
Note Do not use this field to interpret the
result of the authorization.
For Atos, this is the response code sent
from Atos and it might also include the
response code from the bank. The format
is: 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.

ccAuthReply_ Numeric value corresponding to the result ccAuthReply Integer (5)


reasonCode of the credit card authorization request.
See Appendix E, “Reason Codes for the
Simple Order API,” on page 283.

ccAuthReply_ Reference number for the transaction. ccAuthReply Atos: 


reconciliationID Subsequently returned in Integer (6)
ccCaptureReply_reconciliationID for
All other
the first capture of the authorization.
processors:
Returned only for these processors:
String (60)
• Asia-Mideast Processing
• Atos
• BML Direct
• Chase Paymentech Solutions

ccAuthReply_ Referral response number for a verbal ccAuthReply String (6)


referralResponseNumber authorization with FDMS Nashville when
using an American Express card. Give this
number to American Express when you
call them for the verbal authorization.

ccAuthReversalReply_ Total reversed amount. ccAuthReversal String (15)


amount Reply

ccAuthReversalReply_ Authorization code. Returned only when ccAuthReversal String (6)


authorizationCode the authorization code is returned by the Reply
processor.

Credit Card Services Implementation Guide • June 2009 207


Reply Fields

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

ccAuthReversalReply_ Name of the Japanese acquirer that ccAuthReversal String (32)


forwardCode processed the transaction. Returned only Reply
for CCS (CAFIS). Please contact the
CyberSource Japan Support Group for
more information.

ccAuthReversalReply_ Processor response code. ccAuthReversal String (10)


processorResponse Reply

ccAuthReversalReply_ Numeric value corresponding to the result ccAuthReversal Integer (5)


reasonCode of the full authorization reversal request. Reply
See Appendix E, “Reason Codes for the
Simple Order API,” on page 283.

ccAuthReversalReply_ Time when the full authorization reversal ccAuthReversal String (20)
requestDateTime was requested.  Reply
Format: YYYY-MM-DDThh:mm:ssZ
Example: 2005-08-11T22:47:57Z is
equal to August 11, 2005, at 10:47:57 P.M.
The T separates the date and the time.
The Z indicates UTC.

ccCaptureReply_amount Total amount of the capture. ccCaptureReply String (15)

ccCaptureReply_ The fields for the Multi-Currency Service


fundingTotals_... are listed separately in the Multi-Currency
Service Supplement.

ccCaptureReply_ The fields for the Multi-Currency Service


fx... are listed separately in the Multi-Currency
Service Supplement.

ccCaptureReply_ Numeric value corresponding to the result ccCaptureReply Integer (5)


reasonCode of the capture request. See Appendix E,
“Reason Codes for the Simple Order API,”
on page 283.

ccCaptureReply_ Reference number that you use to ccCaptureReply Atos: 


reconciliationID reconcile your CyberSource reports with Integer (6)
your processor reports.
FDI Global:
String (8)
All other
processors:
String (60)

208 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

ccCaptureReply_ Time when capture is requested.  ccCaptureReply String (20)


requestDateTime Format: YYYY-MM-DDThh:mm:ssZ
Example: 2005-08-11T22:47:57Z is
equal to August 11, 2005, at 10:47:57 P.M.
The T separates the date and the time.
The Z indicates UTC.

ccCreditReply_amount Total amount of the credit. ccCreditReply String (15)

ccCreditReply_ Name of the Japanese acquirer that ccCreditReply String (32)


forwardCode processed the transaction. Returned only
for CCS (CAFIS). Please contact the
CyberSource Japan Support Group for
more information.

ccCreditReply_ Numeric value corresponding to the result ccCreditReply Integer (5)


reasonCode of the credit request. See Appendix E,
“Reason Codes for the Simple Order API,”
on page 283.

ccCreditReply_ Reference number that you use to ccCreditReply Atos: 


reconciliationID reconcile your CyberSource reports with Integer (6)
your processor reports.
FDI Global:
String (8)
All other
processors:
String (60)

ccCreditReply_ Time when credit is requested.  ccCreditReply String (20)


requestDateTime Format: YYYY-MM-DDThh:mm:ssZ
Example: 2005-08-11T22:47:57Z is
equal to August 11, 2005, at 10:47:57 P.M.
The T separates the date and the time.
The Z indicates UTC.

ccDCCReply_ Flag that indicates if DCC can be used for ccDCCService String (5)
dccSupported the transaction. Possible values:
• TRUE: DCC can be used.
• FALSE: DCC cannot be used.

ccDCCReply_ Exchange rate surcharge that is applied to ccDCCService String (7)


marginRatePercentage the wholesale exchange rate. Includes a
decimal point and 4 decimal places. For
details, see “Dynamic Currency
Conversion (DCC)” on page 88.

Credit Card Services Implementation Guide • June 2009 209


Reply Fields

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

ccDCCReply_ Numeric value corresponding to the result ccDCCService Integer (5)


reasonCode of the credit card authorization request.
See Appendix E, “Reason Codes for the
Simple Order API,” on page 283.

decision Summarizes the result of the overall All Services String (6)
request. Possible values:
• ACCEPT
• ERROR
• REJECT
• REVIEW—Returned only if you use
CyberSource Decision Manager. See
“Reviews” on page 44.

fxRatesReply_... The fields for the Multi-Currency Service


are listed separately in the Multi-Currency
Service Supplement.

invalidField_0...N Fields in the request that contained invalid All Credit Card Services String (100)
data. These reply fields are included as an
aid to software developers only. No
attempt should be made to use these
fields for end user interaction. See
“Missing or Invalid Fields” on page 45.

merchantReferenceCode Order reference or tracking number that All Credit Card Services String (50)
you provided in the request. If you
included multi-byte characters in this field
in the request, the returned value might
contain corrupted characters.

missingField_0...N Required fields that were missing from the All Credit Card Services String (100)
request. These reply fields are included as
an aid to software developers only. No
attempt should be made to use these
fields for end user interaction. See
“Missing or Invalid Fields” on page 45.

purchaseTotals_currency Currency used for the order. Formatted ccAuthReply String (5)
using the ISO currency codes.
ccAuthReversalReply
For DCC, this is your local currency.
ccCaptureReply
ccCreditReply
ccDCCService

210 CyberSource Corporation


Appendix A Fields for the Simple Order API

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

purchaseTotals_ Exchange rate. Includes a decimal point ccDCCService String (13)


exchangeRate and up to 4 decimal places. For details,
see “Dynamic Currency Conversion
(DCC)” on page 88.

purchaseTotals_ Time stamp for the exchange rate. For ccDCCService String (14)
exchangeRateTimeStamp details, see “Dynamic Currency
Conversion (DCC)” on page 88.
Format: YYYYMMDD~HH:MM
where ~ denotes a space.

purchaseTotals_ Converted amount. For details, see ccDCCService String (15)


foreignAmount “Dynamic Currency Conversion (DCC)” on
page 88.

purchaseTotals_ Billing currency. ISO code for the currency ccDCCService String (5)
foreignCurrency of the converted amount. See the Support
Center for a list of ISO codes. For details
about DCC, see “Dynamic Currency
Conversion (DCC)” on page 88.

reasonCode Numeric value corresponding to the result All Credit Card Services Integer (5)
of the overall request. See Appendix E,
“Reason Codes for the Simple Order API,”
on page 283.

requestID Identifier for the request. All Credit Card Services String (26)

requestToken Request token data created by All Services String (256)


CyberSource for each reply. You need to
store the contents of this field so that you
can retrieve and send it in follow-on
requests. The field is an encoded string
that contains no confidential information,
such as an account or card verification
number. The string can contain up to 256
characters.
If you request the authorization and
capture services together, the request
token is for the capture reply only.
For more information, see “Working with
Request Tokens” on page 38.

voidReply_amount Total amount of the void. voidReply String (15)

Credit Card Services Implementation Guide • June 2009 211


Reply Fields

Table 34 Reply Fields for the Simple Order API (Continued)

Data Type &


Field Name Description Returned By
Length

voidReply_currency Currency used for the order. Formatted voidReply String (5)
using the ISO currency codes.

voidReply_reasonCode Numeric value corresponding to the result voidReply Integer (5)


of the void request. See Appendix E,
“Reason Codes for the Simple Order API,”
on page 283.

voidReply_ Time when void was requested.  voidReply String (20)


requestDateTime Format: YYYY-MM-DDThh:mm:ssZ
Example: 2005-08-11T22:47:57Z is
equal to August 11, 2005, at 10:47:57 P.M.
The T separates the date and the time.
The Z indicates UTC.

212 CyberSource Corporation


Appendix B
Fields for the SCMP API

Topics:
Formatting Restrictions
Data Type Definitions
Request-Level Fields
Offer-Level Fields
Reply Fields

Formatting Restrictions
Unless otherwise noted, all of the fields listed are order and case insensitive, and the fields
accept special characters, such as @, #, and %.
Request-level and offer-level field names and values must not contain carets (^) or colons
(:). However, they can contain embedded spaces and any other printable characters. If
you use more than one consecutive space, the extra spaces will be removed.

Data Type Definitions


• Date and time—The format is YYYY-MM-DDThhmmssZ. For example, 2002-08-
11T224757Z is equal to August 11, 2002, at 10:47:57 P.M. The T separates the date and
the time. The Z indicates Coordinated Universal Time (UTC), which is also known as
Greenwich Mean Time.
• Decimal—Number that includes a decimal point. Examples: 23.45, - 0.1, 4.0,
90809.0468.
• Integer—Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}.
• Non-negative integer—Whole number greater than or equal to zero {0, 1, 2, 3, ...}.
• Positive integer—Whole number greater than zero {1, 2, 3, ...}.
• String—Sequence of letters, numbers, spaces, and special characters, such as @ and #.

Credit Card Services Implementation Guide • June 2009 213


Request-Level Fields

Request-Level Fields
Note If you are using Customer Profiles and you provide subscription_id in the request,
many of the fields in Table 35 that are normally required for authorization or credit
become optional. For example, if you include subscription_id and do not provide the
normally required bill_city field in your authorization request, CyberSource uses the
value for bill_city that is stored with the Customer Profile. If you include bill_city in the
request, CyberSource uses the value from the request instead of the value stored in the
Customer Profile. See “Customer Profiles” on page 131.

Table 35 Request-Level Fields for the SCMP API

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

account_encoder_id Identifier for the issuing bank that provided ics_auth (Required String (3)
the customer’s encoded account number. when processing
Contact Chase Paymentech Solutions for the encoded account
bank’s ID. See “Encoded Account Numbers” numbers.)
on page 138.
ics_credit (Required
when processing
encoded account
numbers.)

aggregator_id Unique alphanumeric value that identifies ics_auth (Required for String (15)
you if you are an aggregator. aggregators for the
American Express card
type.)
ics_credit (Required
for aggregators for the
American Express card
type.)

(1) Optional for a follow-on credit request, which must include bill_request_id

214 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

amexdata_taa1 Four Transaction Advice Addendum (TAA) ics_bill (O) String (40)
fields. These fields are used to display
amexdata_taa2 ics_credit (O)
descriptive information about a transaction
amexdata_taa3 on the customer’s American Express card
amexdata_taa4 statement. If you are sending any TAA fields,
start with amexdata_taa1, then ...taa2, and
so on. Skipping a TAA field causes
subsequent TAA fields to be ignored.
Contact Customer Support if you plan to use
these fields so that your account can be
configured appropriately.
For information about merchant descriptors,
including which processors support this field,
see “Merchant Descriptors” on page 144.
These fields are frequently used for Level II
transactions. See the Level II and Level III
Processing Addendum, which is available at
the Support Center.

auth_code For a forced capture, use with ics_auth to ics_auth (Required for String (6)
send the authorization code you received a forced capture.)
For CCS
from an authorization that you performed
ics_bill (Required for a (CAFIS):
outside the CyberSource system.
verbal authorization.) String (7)
For a verbal authorization, use with ics_bill
to send the verbally received authorization
code.

auth_request_id Value of request_id returned from a previous ics_auth_reversal (R) String (26)
request for ics_auth.
ics_bill (Required
unless ics_auth and
ics_bill are both called
in the same request.)

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 215


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

auth_request_token The request_token value returned from a ics_auth_reversal (O) String (256)
previous request for ics_auth. If you request
ics_bill (O)
the authorization and capture services
together, the capture request does not
require a request token.
The field is an encoded string that contains
no confidential information, such as an
account number or card verification number.
The string can contain up to 256 characters.
This field is available only for merchants who
implemented request tokens before July
2008. For new implementations, use the
order_request_token field.
For more information, see “Working with
Request Tokens” on page 60.

auth_type For a forced capture, use with ics_auth and ics_auth (Required for String (6)
set this field to verbal to indicate that you a forced capture.)
are performing a forced capture, which ics_bill (Required for a
means that you received the authorization
verbal authorization.)
code outside the CyberSource system.
For a verbal authorization, use with ics_bill
and set this field to verbal to indicate that
this is a verbal authorization.

avs_level Level of AVS service to use for the request. ics_auth (O) String (8)
Used only for the American Express Phoenix
processor. The field is case sensitive.
Possible values:
• Standard
• Enhanced
• AAVPlus
The AVS level you specify in this field
overrides the default level your merchant ID
is configured to use. See “Address
Verification Service” on page 23.

bill_address1 Credit card billing street address as it ics_auth (R) String (60)
appears in the credit card issuer’s records.
ics_credit (R) (1)

(1) Optional for a follow-on credit request, which must include bill_request_id

216 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

bill_address2 Used for additional address information. ics_auth (O) (1) String (60)
Example:
Attention: Accounts Payable
Used for AVS by Chase Paymentech
Solutions and TSYS Acquiring Solutions.

bill_city Credit card billing city. ics_auth (R) String (50)

ics_credit (R) (1)

ics_dcc (O)

bill_country Credit card billing country. Use the two- ics_auth (R) String (2)
character country codes. (1)
ics_credit (R)
ics_dcc (O)

bill_payment Indicates that this is an authorization or a ics_auth (O) String (1)


credit for a bill the customer is paying with a
ics_credit (O)
Visa card. See “Bill Payments with Visa” on
page 128 for a list of processors that support
this feature. Possible values:
• N (default): Not a bill payment
• Y: Bill payment

bill_pos_data This field is required for FDMS South for ics_bill (See the field String (12)
verbal authorizations and forced captures description.)
with the American Express card type to
support the CAPN requirements:
• For a forced capture, obtain the value for
this field from the authorization response.
• For a verbal authorization, you cannot
obtain a value for this field. Therefore,
CyberSource will use the default value.
Default: Value generated by CyberSource
based on various factors of the transaction
such as retail or internet, card present or not,
and swiped or keyed.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 217


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

bill_request_id The request_id returned from a previous ics_credit (O) String (26)
request for ics_bill. Creates a follow-on
credit by linking the credit to the previous
capture. If you send bill_request_id, you do
not need to send several other ics_credit
fields. See “Crediting a Payment” on
page 76.

bill_request_token The request_token value returned from a ics_credit (O) String (256)
previous request for ics_bill. This field is
required only for follow-on credit requests; it
is not required for stand-alone credit
requests.
The field is an encoded string that contains
no confidential information, such as an
account number or card verification number.
The string can contain up to 256 characters.
This field is available only for merchants who
implemented request tokens before July
2008. For new implementations, use the
order_request_token field.
For more information, see “Working with
Request Tokens” on page 60.

bill_state Credit card billing state or province. Use the ics_auth (Required String (2)
two-character codes. when the billing country
is the U.S. or Canada.)
ics_credit (Required
when the billing country
is the U.S. or Canada.)
(1)

ics_dcc (O)

(1) Optional for a follow-on credit request, which must include bill_request_id

218 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

bill_transaction_id This field is required for FDMS South for ics_bill (See the field String (15)
verbal authorizations and forced captures description.)
with the American Express card type to
support the CAPN requirements:
• For a forced capture, obtain the value for
this field from the authorization response.
• For a verbal authorization, you cannot
obtain a value for this field. Therefore,
CyberSource will use the default value.
See “Verbal Authorizations: The Capture”
on page 74 for information about using the
default for this field for verbal
authorizations.
Default: 000000000000000 (15 zeros)

bill_zip Postal code for the billing address. The ics_auth (Required String (10)
postal code must consist of 5 to 9 digits. when the billing country
For a 9-digit postal code, use this format: is the U.S. or Canada.)
[5 digits][dash][4 digits] ics_credit (Required
If the value of bill_country is CA, the postal when the billing country
code must follow these rules: is the U.S. or Canada.)
(1)
• If the number of characters is greater than
3, the first 3 characters must be in this ics_dcc (O)
format:
[alpha][numeric][alpha].
• If the number of characters is 7, the last 3
characters must be in this format:
[numeric][alpha][numeric].

bml_... The fields for Bill Me Later are described


separately in the Bill Me Later Supplement.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 219


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

card_type Type of card to authorize. To see which ics_auth (Required for String (3)
cards can be handled by each processor, the card types that have
see “Payment Processors” on page 6. asterisks.)
Possible values:
ics_credit (Required
• 001: Visa for the card types that
• 002: MasterCard, Eurocard*—European have asterisks.) (1)
regional brand of MasterCard
CyberSource strongly
• 003: American Express recommends that you
• 004: Discover send the card type even
if it is optional for your
• 005: Diners Club—See “MasterCard and
processor and card
Diners Club Alliance” on page 3. type. Omitting the card
• 006: Carte Blanche* type can cause the
• 007: JCB* transaction to be
processed with the
• 014: EnRoute* wrong card type.
• 021: JAL*
• 024: Maestro (UK Domestic), Solo*
• 031: Delta*—Use this value only for the
CyberSource Global Payment Service.
For other processors, use 001 for all Visa
card types.
• 032: Solo*—Use this value only for the
CyberSource Global Payment Service.
For other processors, use 024 for Solo
cards.
• 033: Visa Electron*
• 034: Dankort*
• 035: Laser*
• 036: Carte Bleue*
• 037: Carta Si*
• 039: Encoded account number*
• 040: UATP*
• 042: Maestro (International)*
• 043: GE Money UK card*—Before
setting up your system to work with GE
Money UK cards, contact the
CyberSource UK Support Group.

(1) Optional for a follow-on credit request, which must include bill_request_id

220 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

cavv Cardholder authentication verification value ics_auth String (40)


(CAVV). For the description and
requirements, see “Payer Authentication” on
page 151.

cavv_algorithm Algorithm used to generate the CAVV for ics_auth String (1)
Verified by Visa or the UCAF authentication
data for MasterCard SecureCode. For the
description and requirements, see “Payer
Authentication” on page 151.

company_name Name of the customer’s company. ics_auth (O) String (40)

currency Currency used for the order. See the Support ics_auth (R) String (5)
Center for a list of ISO codes.
ics_auth_reversal (R)
For ics_auth_reversal and ics_bill, you
ics_bill (R)
must use the same currency that you used in
the request for ics_auth. ics_credit (R)
For DCC, this is your local currency. ics_dcc (R)

customer_account_id Your identifier for the customer. When a ics_auth (O) String 
subscription is being created, the maximum (30 or 50)
ics_bill (O)
length for this field is 30. Otherwise, the
maximum length is 50. ics_credit (O)

customer_cc_cv_ Card verification indicator used to indicate if ics_auth (O) Non-


indicator a card verification value was sent. Possible negative
values: integer (1)
• 0 (default): CV number service not
requested. This default is used if you do
not include customer_cc_cv_number in
the request.
• 1 (default): CV number service requested
and supported. This default is used if you
include customer_cc_cv_number in the
request.
• 2: CV number on credit card is illegible.
• 9: CV number was not imprinted on credit
card.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 221


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

customer_cc_cv_ Card verification number. See “Card ics_auth (O) Non-


number Verification Numbers” on page 27 for a list of negative
processors that accept the card verification integer (4)
number.
Do not include this field if you are using FDI
Global or FDMS South and performing a $0
authorization.
Do not include this field if you are using the
CyberSource Global Payment Service and
you set e_commerce_indicator
=recurring.

customer_cc_expmo Two-digit month that the credit card expires ics_auth (R) String (2)
in. Format: MM. 
ics_credit (See
Possible values: 01 through 12.
description) (1)
For encoded account numbers (card_
ics_dcc (O)
type=039), if there is no expiration date on
the card, use 12.
For credits, the following processors do not
require this field:
• American Express Direct
• American Express Phoenix
• Chase Paymentech Solutions
• FDI Global
• FDMS Nashville
• FDMS South
• TSYS Acquiring Solutions
All other processors require this field for
credits.

(1) Optional for a follow-on credit request, which must include bill_request_id

222 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

customer_cc_expyr Four-digit year that the credit card expires in. ics_auth (R) Non-
Format: YYYY. negative
ics_credit (See
integer (4)
For encoded account numbers (card_ description) (1)
type=039), if there is no expiration date on
ics_dcc (O)
the card, use 2021.
For credits, the following processors do not
require this field:
• American Express Direct
• American Express Phoenix
• Chase Paymentech Solutions
• FDI Global
• FDMS Nashville
• FDMS South
• TSYS Acquiring Solutions
All other processors require this field for
credits.

customer_cc_issue_ Indicates how many times a Maestro (UK ics_auth (Required if String (5)
number Domestic) or Solo card has been issued to an issue number is on
the account holder. The card might or might the card.)
not have an issue number; the field is
ics_credit (Required if
required if the card has an issue number. The
an issue number is on
number can consist of one or two digits, and
the first digit might be a zero. Include exactly the card.) (1)
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) or Solo card.

customer_cc_number Number given to customer for their account. ics_auth (R) Non-
negative
When processing encoded account ics_credit (R) (1) integer (20)
numbers, use this field for the encoded
account number. ics_dcc (R)

For the DCC service, 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 bill_request_id

Credit Card Services Implementation Guide • June 2009 223


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

customer_cc_startmo Month of the start of the Maestro (UK ics_auth (Required if a String (2)
Domestic) or Solo card validity period. The start date is on the
card might or might not have a start date card.)
printed on it; the field is required if the card
has a start date. Do not include the field, ics_credit (Required if
even with a blank value, if the card is not a a start date is on the
Maestro (UK Domestic) or Solo card. card.) (1)
Format: MM. 
Possible values: 01 through 12.

customer_cc_startyr Year of the start of the Maestro (UK ics_auth (Required if a Non-
Domestic) or Solo card validity period. The start date is on the negative
card might or might not have a start date card.) integer (4)
printed on it; the field is required if the card
has a start date. Do not include the field, ics_credit (Required if
even with a blank value, if the card is not a a start date is on the
Maestro (UK Domestic) or Solo card. card.) (1)
Format: YYYY.

customer_email Customer’s email address, including the full ics_auth (R) String (255)
domain name. 
Format: name@host.domain  ics_credit (R) (1)
Example: jdoe@example.com ics_dcc (O)

customer_firstname Customer’s first name.The value should be ics_auth (R) String (60)
the same as the one that is on the card.
ics_credit (R) (1)
ics_dcc (O)

customer_hostname DNS resolved hostname from customer_ ics_auth (O) String (60)
ipaddress.

customer_ipaddress IP address of the customer.  ics_auth (O) String (15)


Example: 10.1.27.63

customer_lastname Customer’s last name. The value should be ics_auth (R) String (60)
the same as the one that is on the card.
ics_credit (R) (1)
ics_dcc (O)

customer_phone Customer’s phone number. CyberSource ics_auth (O) String (15)


recommends that you include the country
ics_credit (O)
code if the order is from outside the U.S.
ics_dcc (O)

(1) Optional for a follow-on credit request, which must include bill_request_id

224 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

dcc_indicator Flag that indicates if DCC is being used for ics_auth String (1)
the transaction. For details, see “Dynamic
ics_bill
Currency Conversion (DCC)” on page 132.
Possible values: ics_credit
• 1: Converted—DCC is being used. Required if you called
• 2: Non-convertible—DCC cannot be the DCC service for the
used. purchase.

• 3: Declined—DCC could be used, but the


customer declined it.

debt_indicator Flag that presently applies solely to Visa ccAuthService (O) String (1)
purchase transactions and indicates to Visa
that the purchase is for payment on an
existing debt. Usage of the debt indicator is
limited to specific MCCs; contact your
acquirer to find out if usage of this data
element is applicable. Possible values:
• N: The payment is not for an existing
debt.
• Y: The payment is for an existing debt.
For a list of processors that support the debt
indicator, see “Bill Payments with Visa” on
page 128.

decline_avs_flags Comma-separated list of AVS flags that ics_auth (O) String (255)
cause the reply flag DAVSNO to be returned.
Important Include the value N in the
comma-separated list if you want to receive
declines for the AVS code N.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 225


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

e_commerce_indicator Type of transaction. Some card associations ics_auth (Required for String (13)
use this information when determining payer authentication
discount rates. For the CyberSource Global transactions.
Payment Service, if you omit this field, the Otherwise, optional.)
processor uses the default transaction type
ics_credit (Optional.
they have on file for you instead of the default
Only internet,
value listed here.
moto, and recurring
Payer Authentication Transactions are valid values.) (1)
For the possible values and requirements,
see “Payer Authentication” on page 151.
Other Types of Transactions
Possible values:
• install: Installment profile: payments
will be made in installments.This value is
valid only for Visa. The installment_
sequence and installment_total_count
fields are required.
• internet (default): eCommerce order
placed using a Web site. For the
CyberSource Global Payment Service,
internet is supported only for Carte
Bleue transactions.
• moto: Mail order or telephone order. Not
supported for UATP or for any Bill Me
Later gateways. For the CyberSource
Global Payment Service, moto is
currently supported only for Carte Bleue
transactions.
• moto_cc: Mail order or telephone order
from a call center. This value is available
only for Asia-Mideast Processing.
• recurring: Recurring transaction. See
“Recurring Payments” on page 163 for a
list of processors that support this value.

eci_raw Raw electronic commerce indicator (ECI). ics_auth String (2)


For the description and requirements, see
“Payer Authentication” on page 151.

(1) Optional for a follow-on credit request, which must include bill_request_id

226 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

exchange_rate Exchange rate returned by the DCC service. ics_auth (R for DCC Decimal (13)
Includes a decimal point and up to 4 decimal transactions)
places. For details, see “Dynamic Currency
ics_bill (R for DCC
Conversion (DCC)” on page 132.
transactions)
ics_credit (R for DCC
transactions)

exchange_rate_ Time stamp for the exchange rate. This value ics_auth (R for DCC String (14)
timestamp is returned by the DCC service. For details, transactions)
see “Dynamic Currency Conversion (DCC)”
ics_bill (R for DCC
on page 132.
transactions)
Format: YYYYMMDD~HH:MM
ics_credit (R for DCC
where ~ denotes a space. transactions)

foreign_amount Converted amount returned by the DCC ics_auth (R for DCC Decimal (15)
service. For details, see “Dynamic Currency transactions)
Conversion (DCC)” on page 132.
ics_bill (R for DCC
transactions)
ics_credit (R for DCC
transactions)

foreign_currency Billing currency returned by the DCC service. ics_auth (R for DCC String (5)
ISO code for the currency of the converted transactions)
amount. See the Support Center for a list of
ics_bill (R for DCC
ISO codes. For details about DCC, see
transactions)
“Dynamic Currency Conversion (DCC)” on
page 132. ics_credit (R for DCC
transactions)

fxrates_... The fields for the Multi-Currency Service are


listed separately in the Multi-Currency
Service Supplement.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 227


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

grand_total_amount Grand total for the order. You must include ics_auth Decimal (15)
either this field or offer0 and the offer-level
ics_auth_reversal
field amount. See “Using Offers or a Grand
Total in the Request” on page 62. ics_bill
Important Some processors have specific ics_credit
requirements and limitations, such as See the field
maximum amounts and maximum field description.
lengths. This information is covered in:
• Authorizations—Table 2 on page 11
• Captures—Table 4 on page 15
• Credits—Table 5 on page 18
If your processor supports $0 authorizations,
you can set this field to 0 for the
authorization to check if the card is lost or
stolen. See “$0 Authorizations” on page 126
for the list of supported processors.

http_browser_type Customer’s browser as identified from the ics_auth (O) String (40)
HTTP header data. For example, Mozilla
is the value that identifies the Netscape
browser.

ics_applications ICS services to process for the request. Required for all Credit String (255)
Card Services.
At least one service must be specified in the
request.

ignore_avs Used when calling ics_auth and ics_bill ics_auth (O) String (3)
together. Enables you to use ics_bill when
DAVSNO would have been received.
Possible values:
• yes: Ignore the results of AVS checking
and run the ics_bill service.
• no (default): If the authorization receives
an AVS decline, do not run the ics_bill
service.
If the value of this field is yes, the list in the
decline_avs_flags field is ignored.

(1) Optional for a follow-on credit request, which must include bill_request_id

228 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ignore_bad_cv Determines whether to allow ics_bill to run if ics_auth (O) String (3)
the value of the reply field auth_cv_result is
D or N. Used only when both ics_auth and
ics_bill are requested at the same time.
Possible values:
• Yes: If the value of auth_cv_result is D or
N, allow ics_bill to run.
• No (default): If the value of auth_cv_
result is D or N, return the auth_rflag
DCV and do not allow ics_bill to run.

installment_sequence Installment number when making payments ics_auth (Optional for Decimal (2)
in installments. Used along with installment_ Chase Paymentech
total_count to keep track of which payment Solutions. For all other
is being processed. For example, the 2nd of processors, required for
5 payments would be passed to installment transactions 
CyberSource as installment_sequence = 2 (e_commerce_
and installment_total_count = 5. This field indicator = install).)
is used only for Visa.
For Chase Paymentech Solutions: This field
is optional because this value is required in
the merchant descriptor. See “Merchant
Descriptors” on page 144.

installment_total_ • Total number of installments when making ics_auth (Optional for Decimal (2)
count payments in installments. Used along with Chase Paymentech
installment_sequence to keep track of Solutions. For all other
which payment is being processed. For processors, required for
example, the 2nd of 5 payments would be installment transactions 
passed to CyberSource as installment_ (e_commerce_
sequence = 2 and installment_total_ indicator = install).)
count = 5. This field is used only for Visa.
• For Chase Paymentech Solutions: This
field is optional because this value is
required in the merchant descriptor. See
“Merchant Descriptors” on page 144.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 229


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

jpo_bonus_amount Japanese payment option bonus amount: ics_auth Non-


Amount of the payment during the bonus negative
ics_bill
month. The value must be greater than 0. integer (8)
ics_credit
Required if jpo_
payment_method is 6.
Otherwise, not used.

jpo_bonuses Japanese payment option bonuses: Number ics_auth Integer (2)


of bonus payments.
ics_bill
ics_credit
Required if jpo_
payment_method is 3
or 6. Otherwise, not
used.

jpo_installments Japanese payment option installments: ics_auth Integer (2)


Number of installment payments.
ics_bill
ics_credit
Required if jpo_
payment_method is 4
or 6. Otherwise, not
used.

jpo_payment_method Japanese payment option payment method: ics_auth (O) Integer (1)
type of payment option. Possible values:
ics_bill (O)
• 1 (default): Single payment
ics_credit (O)
• 2: Bonus payment
• 3: Installment bonus payment
• 4: Installment
• 5: Revolving repayment
• 6: Combination of installment and bonus
payment
See “Japanese Payment Options” on
page 140.

(1) Optional for a follow-on credit request, which must include bill_request_id

230 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

merchant_defined_ Four fields that you can use to store ics_auth (O) String (64)
data1 information.
ics_bill (O)
merchant_defined_ Warning Merchant-defined data fields are ics_credit (O)
data2 not intended to and MUST NOT be used to
merchant_defined_ capture personally identifying information.
data3 Accordingly, merchants are prohibited from
capturing, obtaining, and/or transmitting any
merchant_defined_ personally identifying information in or via the
data4 merchant-defined data fields. Personally
identifying information includes, but is not
limited to, name, 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 merchant-defined 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.
Note If you are creating a profile based on
an authorization, the merchant-defined data
fields do not get transferred to the new
profile.

merchant_descriptor Merchant description that is displayed on the ics_bill String (22)


cardholder's statement. For information
ics_credit For
about merchant descriptors, including which
OmniPay-
processors support this field and special Optional for FDI Global.
Ireland:
formatting required for some processors, see For all other
String(23)
“Merchant Descriptors” on page 144. processors, required if
merchant_descriptor_
If you use more than one consecutive space,
contact is set.
extra spaces will be removed.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 231


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

merchant_descriptor_ Alternate merchant contact information, such ics_bill (O) String (32)
alternate as a URL or email address, that is displayed
ics_credit (O)
on the cardholder's statement. For
information about merchant descriptors,
including which processors support this field
and special formatting required for some
processors, see “Merchant Descriptors” on
page 144.

merchant_descriptor_ Merchant contact information, such as a ics_bill String (13)


contact phone number, that is displayed on the
ics_credit For FDI
cardholder's statement. For information
Global:
about merchant descriptors, including which Required for Chase
String (11)
processors support this field and special Paymentech Solutions if
formatting required for some processors, see merchant_descriptor
“Merchant Descriptors” on page 144. is set. Optional for all
other processors.
If you use more than one consecutive space,
extra spaces will be removed.

merchant_id Your CyberSource merchant ID. Use the Required for all Credit String (30)
same merchant_id for evaluation, testing, Card Services.
and production.

merchant_ref_number Merchant-generated order reference or Required for all Credit Atos:


tracking number. CyberSource recommends Card Services. String (32)
that you send a unique value for each
FDI Global:
transaction so that you can perform
Numeric (8)
meaningful searches for the transaction. See
“Tracking Orders” on page 67. All other
processors:
For FDI Global: This value must be numeric
String (50)
and must be less than 9 digits. If you do not
send a valid value, CyberSource will create
one for you. However, the value will not be
returned to you so you will not be able to use
the merchant reference number to track the
order.

(1) Optional for a follow-on credit request, which must include bill_request_id

232 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

offer0...N Offers (line items of the order) for the ics_auth (O) String (50)
request. You must include either offer0 and
ics_auth_reversal (O)
the offer-level field amount, or the request-
level field grand_total_amount in your ics_bill (O)
request. See “Using Offers or a Grand Total ics_credit (O)
in the Request” on page 62.
ics_dcc (R)
For DCC, you must include offer0 and the
offer-level field amount. You cannot use
grand_total_amount.

order_request_token The request_token value returned from a ics_auth_reversal (R) String (256)
previous request. This value links the
ics_bill (R)
previous request to the current follow-on
request. This field is an encoded string that ics_credit (R)
does not contain any confidential information, ics_void (R)
such as account numbers or card verification
numbers. The string can contain up to 256
characters.
For more information, see “Working with
Request Tokens” on page 60.

pares_status Payer authentication response status. For ics_auth String (1)


the description and requirements, see “Payer
Authentication” on page 151.

personal_id Personal identifier. For CyberSource Latin ics_auth (See the field String (26)
American Processing, you can use this field description.)
for the Cadastro de Pessoas Fisicas (CPF),
which is required for the MasterCard AVS
check in some countries. Otherwise, it is
optional.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 233


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ship_from_zip Postal code for the address from which the ics_bill (O) String (10)
goods are shipped, which is used to
ics_credit (O)
determine nexus. The default is the merchant
postal code stored in the CyberSource
merchant configuration database.
The postal code must consist of 5 to 9 digits.
For a 9-digit postal code, use this format:
[5 digits][dash][4 digits]
If the country from which the goods are being
shipped is Canada, the postal code must
follow these rules:
• If the number of characters is greater than
3, the first 3 characters must be in this
format:
[alpha][numeric][alpha].
• If the number of characters is 7, the last 3
characters must be in this format:
[numeric][alpha][numeric].

ship_to_address1 First line of the address to ship the product ics_auth (Required if String (60)
to. any shipping address
information is included
in the request.)

ship_to_address2 Second line of the address to ship the ics_auth (O) String (60)
product to.

ship_to_city City to ship the product to. ics_auth (Required if String (50)
any shipping address
information is included
in the request and
shipping to the U.S. or
Canada.)

ship_to_country Country to ship the product to. Use the two- ics_auth String (2)
character country codes.
ics_bill
ics_credit
Required if any shipping
address information is
included in the request.

ship_to_firstname First name of person receiving the product. ics_auth (O) String (60)

(1) Optional for a follow-on credit request, which must include bill_request_id

234 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

ship_to_lastname Last name of person receiving the product. ics_auth (O) String (60)

ship_to_state State or province to ship the product to. Use ics_auth (Required if String (2)
the two-character codes. any shipping address
information is included
in the request and
shipping to the U.S. or
Canada.)

ship_to_zip Postal code for the shipping address. The ics_auth String (10)
postal code must consist of 5 to 9 digits.
ics_bill
For a 9-digit postal code, use this format:
[5 digits][dash][4 digits] ics_credit

If the value of ship_to_country is CA, the Required if any shipping


postal code must follow these rules: address information is
included in the request
• If the number of characters is greater than and shipping to the U.S.
3, the first 3 characters must be in this or Canada.
format:
[alpha][numeric][alpha].
• If the number of characters is 7, the last 3
characters must be in this format:
[numeric][alpha][numeric].

shipping_method Shipping method for the product. Possible ics_auth (O) String (10)
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

subscription_id Profile ID. If you are using Customer Profiles, ics_auth (O) String (26)
you can request an authorization, sale, or
ics_credit (O)
credit and use a profile ID to reference the
profile information. See “Customer Profiles”
on page 131.

(1) Optional for a follow-on credit request, which must include bill_request_id

Credit Card Services Implementation Guide • June 2009 235


Request-Level Fields

Table 35 Request-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

timeout Number of seconds the system waits before Optional for all Credit Positive
returning a timeout error. The default is 110 Card Services integer (3)
seconds.

ucaf_authentication_ Universal cardholder authentication field ics_auth String (32)


data (UCAF) data. For the description and
requirements, see “Payer Authentication” on
page 151.

ucaf_collection_ Universal cardholder authentication field ics_auth Non-


indicator (UCAF) collection indicator. For the negative
description and requirements, see “Payer integer (1)
Authentication” on page 151.

veres_enrolled Verification response enrollment status. For ics_auth String (1)


the description and requirements, see “Payer
Authentication” on page 151.

void_request_id The request_id of the capture or credit you ics_void (R) String (26)
want to void.

void_request_token The request_token value returned from a ics_void (O) String (256)
previous request for a service that you want
to void. You can void captures, credits,
electronic check debits, and Bill Me Later
transactions that have not been batched or
voided before. For example, if you want to
void a capture, set this field to the request_
token value returned in the reply for the
capture request.
The field is an encoded string that contains
no confidential information, such as an
account number or card verification number.
The string can contain up to 256 characters.
This field is available only for merchants who
implemented request tokens before July
2008. For new implementations, use the
order_request_token field.
For more information, see “Working with
Request Tokens” on page 60.

xid Transaction identifier. For the description and ics_auth String (40)
requirements, see “Payer Authentication” on
page 151.

(1) Optional for a follow-on credit request, which must include bill_request_id

236 CyberSource Corporation


Appendix B Fields for the SCMP API

Offer-Level Fields
Table 36 Offer-Level Fields for the SCMP API

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

amount Per-item price of the product. You must ics_auth (See the field Decimal (15)
include either offer0 and this field, or the description.)
request-level field grand_total_amount in
ics_auth_reversal
your request. See “Using Offers or a
(See the field
Grand Total in the Request” on page 62.
description.)
Important Some processors have ics_bill (See the field
specific requirements and limitations, such description.)
as maximum amounts and maximum field
lengths. This information is covered in: ics_credit (See the
• Authorizations—Table 2 on page 11 field description.)

• Captures—Table 4 on page 15 ics_dcc (R)

• Credits—Table 5 on page 18
This value cannot be negative. You can
include a decimal point (.) in this field, but
you cannot include any other special
characters. The amount will be truncated
at the request level to the correct number
of decimal places.
If your processor supports $0
authorizations, you can set this field to 0
for the authorization to check if the card is
lost or stolen. See “$0 Authorizations” on
page 126 for the list of supported
processors.
For DCC, this value is the original amount
in your local currency. You must include
offer0 and this field. You cannot use
grand_total_amount.

merchant_product_sku Product’s identifier code. For ics_auth, ics_auth (See the field String (30)
required if product_code is not description.)
default, stored_value, or one of the ics_bill (O)
values related to shipping and/or handling.
ics_dcc (O)

Credit Card Services Implementation Guide • June 2009 237


Offer-Level Fields

Table 36 Offer-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

product_code Type of product that the offer contains, ics_auth (O) String (30)
which is used to determine the product’s
ics_bill (O)
category: electronic, handling, physical,
service, or shipping. The default value is ics_credit (O)
default. See Appendix I, “Product ics_dcc (O)
Codes,” on page 297 for a list of valid
values.
For ics_auth, if you set this to a value
other than default, stored_value, or
any of the values related to shipping and/
or handling, the quantity, product_name,
and merchant_product_sku fields are
required. See “Using Offers or a Grand
Total in the Request” on page 62.

product_name Name of the product. For ics_auth, ics_auth (See the field String (30)
required if product_code is not description.)
default, stored_value, or one of the ics_bill (O)
values related to shipping and/or handling.
ics_dcc (O)

quantity Quantity of the product being purchased. ics_auth (See the field Non-
The default value is 1. For ics_auth, description.) negative
required if product_code is not integer (10)
ics_auth_reversal (O)
default, stored_value, or one of the
values related to shipping and/or handling. ics_bill (O)
ics_credit (O)
ics_dcc (O)

238 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 36 Offer-Level Fields for the SCMP API (Continued)

Used By: Required (R) Data Type &


Field Name Description
or Optional (O) Length

tax_amount Total tax to apply to the product. This ics_auth (O) Decimal (15)
value cannot be negative. The tax_
amount field is additive. For example, if
you include these offer lines:
offer0=amount:10.00^quantity:
1^tax_amount:0.80
offer1=amount:20.00^quantity:
1^tax_amount:1.60
the total amount authorized will be for
$32.40, not $30.00 with $2.40 of tax
included. The tax_amount and the
amount must be in the same currency.
If you want to include tax_amount and
also request the ics_tax service, see the
Tax Calculation Implementation Guide,
which is available at the Support Center.
This field is frequently used for Level II
and Level III transactions. See the Level II
and Level III Processing Addendum,
which is available at the Support Center.

Credit Card Services Implementation Guide • June 2009 239


Reply Fields

Reply Fields
Table 37 Reply Fields for the SCMP API

Data Type &


Field Name Description Returned By
Length

auth_account_balance Prepaid card balance. If there is a balance ics_auth Decimal (12)


remaining on a prepaid card after an
authorization, the balance is returned in
this field. See “American Express Prepaid
Cards” on page 127.

auth_auth_amount Total amount of the authorization. ics_auth Decimal (15)

auth_auth_avs Results of address verification. See ics_auth String (1)


“Address Verification Service” on page 69
for information about how AVS works. See
Appendix G, “Address Verification Service
Codes,” on page 291 for a list of possible
values.

auth_auth_code Authorization code. Returned only if a ics_auth String (7)


value is returned by the processor.
For TSYS Acquiring Solutions, the
returned value for a successful $0
authorization is 000000. See “$0
Authorizations” on page 126.
For Citibank’s CitiVendor encrypted
account number program, the returned
value is OFFLINE. See “Encoded
Account Numbers” on page 138.

auth_auth_response For most processors, this is the error ics_auth String (10)
message sent directly from the bank.
Returned only if a value is returned by the
processor.
Note Do not use this field to interpret the
result of the authorization.
For Atos, this is the response code sent
from Atos and it might also include the
response code from the bank. The format
is: 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.

240 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

auth_auth_time Time of authorization in UTC. See “Data ics_auth Date and


Type Definitions” on page 213 for the time (20)
field’s format.

auth_avs_raw AVS result code sent directly from the ics_auth String (10)
processor. Returned only if a value is
returned by the processor.
Note Do not use this field to interpret the
result of AVS. Use for debugging
purposes only.

Credit Card Services Implementation Guide • June 2009 241


Reply Fields

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

auth_cavv_response_ Verified by Visa response code. Possible ics_auth String (1) or


code values: String (3)
• 0 = CAVV not validated because
erroneous data was submitted
• 1 = CAVV failed validation and
authentication
• 2 = CAVV passed validation and
authentication
• 3 = CAVV passed the validation
attempt
• 4 = CAVV failed the validation attempt
• 6 = CAVV not validated because the
issuer does not participate
• 7 = CAVV failed the validation attempt
and the issuer is available
• 8 = CAVV passed the validation
attempt and the issuer is available
• 9 = CAVV failed the validation attempt
and the issuer is not available
• 99 = An unknown value was returned
from the processor
• A = CAVV passed the validation
attempt and the issuer is not available
• B = CAVV passed the validation with
information only; no liability shift
• C = CAVV attempted but not validated;
issuer did not return CAVV code
• D = CAVV not validated or
authenticated; issuer did not return
CAVV code
• I = Invalid security data
• U = Issuer does not participate or 3-D
secure data was not utilized

auth_cavv_response_ Raw Verified by Visa response code sent ics_auth String (1) or
code_raw directly from the processor. String (3)

242 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

auth_cv_result Result of processing the card verification ics_auth String (1)


number. See “Card Verification Numbers”
on page 70 for information about how the
card verification check works. See
Appendix H, “Card Verification Number
Codes,” on page 295 for a list of the
possible values for this field.

auth_cv_result_raw Card verification result code sent directly ics_auth String (10)
from the processor. Returned only if a
value is returned by the processor.
Note Do not use this field to interpret the
result of card verification. Use for
debugging purposes only.

auth_forward Name of the Japanese acquirer that ics_auth String (32)


processed the transaction. Returned only
for CCS (CAFIS). Please contact the
CyberSource Japan Support Group for
more information.

auth_fxrates_... The fields for the Multi-Currency Service


are listed separately in the Multi-Currency
Service Supplement.

auth_merchant_advice_ Code associated with the reason the ics_auth String (2)
code recurring payment transaction was
declined. This field is used only for
MasterCard. Possible values:
• 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.

auth_merchant_advice_ Raw merchant advice code sent directly ics_auth String (2)
code_raw from the processor. This field is used only
for MasterCard.

Credit Card Services Implementation Guide • June 2009 243


Reply Fields

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

auth_personal_id_result Personal identifier result. For ics_auth String (1)


CyberSource Latin American Processing,
if you included personal_id in the
request, this value indicates whether or
not personal_id matched a value in a
record on file. Possible values:
• Y: Match
• N: No match
• K: Not supported
• U: Unknown
• Z: No response returned

auth_rcode One-digit code that indicates whether the ics_auth Integer (1)
ics_auth request was successful.
Possible values:
• -1: An error occurred
• 0: The request was declined
• 1: The request was successful

auth_referral_response_ Referral response number for a verbal ics_auth String (6)


number authorization with FDMS Nashville when
using an American Express card. Give this
number to American Express when you
call them for the verbal authorization.

auth_reversal_amount Total reversed amount. ics_auth_reversal Decimal (15)

auth_reversal_auth_code Authorization code. Returned only when ics_auth_reversal String (6)


the authorization code is returned by the
processor.

auth_reversal_auth_ Error message sent directly from the credit ics_auth_reversal String (10)
response card company.

auth_reversal_forward Name of the Japanese acquirer that ics_auth_reversal String (32)


processed the transaction. Returned only
for CCS (CAFIS). Please contact the
CyberSource Japan Support Group for
more information.

244 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

auth_reversal_rcode One-digit code that indicates the ics_ ics_auth_reversal Integer (1)
auth_reversal result. Possible values:
• -1: An error occurred
• 0: The request was declined
• 1: The request was successful

auth_reversal_request_ Time in UTC when the full authorization ics_auth_reversal Date and
time reversal was requested. See “Data Type time (20)
Definitions” on page 213 for the field’s
format.

auth_reversal_rflag If ics_auth_reversal is unsuccessful, this ics_auth_reversal String (50)


field contains a one-word description of
the error. See Appendix F, “Reply Flags
for the SCMP API,” on page 287.

auth_reversal_rmsg Message explaining the reply code auth_ ics_auth_reversal String (255)
reversal_rcode.

auth_rflag One-word description of the result of the ics_auth String (50)


ics_auth request. See Appendix F, “Reply
Flags for the SCMP API,” on page 287.

auth_rmsg Message that explains the reply flag ics_auth String (255)
auth_rflag. Do not display this message
to the customer, and do not use this field
to write an error handler.

auth_trans_ref_no Reference number for the transaction. ics_auth Atos: 


Subsequently returned by ics_bill in the Positive
bill_trans_ref_no reply field for the first Integer (6)
capture of the authorization. Returned
All other
only for these processors:
processors:
• Asia-Mideast Processing String (60)
• Atos
• BML Direct
• Chase Paymentech Solutions

bill_bill_amount Total amount of the capture. ics_bill Decimal (15)

bill_bill_request_time Time when capture is requested in UTC. ics_bill Date and


See “Data Type Definitions” on page 213 time (20)
for the field’s format.

Credit Card Services Implementation Guide • June 2009 245


Reply Fields

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

bill_fxrates_... The fields for the Multi-Currency Service


are listed separately in the Multi-Currency
Service Supplement.

bill_rcode One-digit code that indicates whether the ics_bill Integer (1)
ics_bill request was successful. Possible
values:
• -1: An error occurred
• 0: The request was declined
• 1: The request was successful

bill_rflag One-word description of the result of the ics_bill String (50)


ics_bill request. See Appendix F, “Reply
Flags for the SCMP API,” on page 287.

bill_rmsg Message that explains the reply flag bill_ ics_bill String (255)
rflag. Do not display this message to the
customer, and do not use this field to write
an error handler.

bill_trans_ref_no Reference number that you use to ics_bill Atos: 


reconcile your CyberSource reports with Positive
your processor reports. Integer (6)
FDI Global:
String (8)
All other
processors:
String (60)

client_lib_version Information about the client library used to All Credit Card Services String (50)
request the transaction.

credit_credit_amount Total amount of the credit. ics_credit Decimal (15)

credit_credit_request_ Time when credit is requested in UTC. ics_credit Date and


time See “Data Type Definitions” on page 213 time (20)
for the field’s format.

credit_forward Name of the Japanese acquirer that ics_credit String (32)


processed the transaction. Returned only
for CCS (CAFIS). Please contact the
CyberSource Japan Support Group for
more information.

246 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

credit_rcode One-digit code that indicates whether the ics_credit Integer (1)
ics_credit request was successful.
Possible values:
• -1: An error occurred
• 0: The request was declined
• 1: The request was successful

credit_rflag One-word description of the result of the ics_credit String (50)


ics_credit request. See Appendix F,
“Reply Flags for the SCMP API,” on page
287.

credit_rmsg Message that explains the reply flag ics_credit String (255)
credit_rflag. Do not display this message
to the customer, and do not use this field
to write an error handler.

credit_trans_ref_no Reference number that you use to ics_credit Atos: 


reconcile your CyberSource reports with Positive
your processor reports. Integer (6)
FDI Global:
String (8)
All other
processors:
String (60)

currency Currency used for the order. Formatted ics_auth String (5)
using the ISO currency codes.
ics_auth_reversal
For DCC, this is your local currency.
ics_bill
ics_credit
ics_dcc

dcc_dcc_supported Flag that indicates if DCC can be used for ics_dcc String (5)
the transaction. Possible values:
• TRUE: DCC can be used.
• FALSE: DCC cannot be used.

dcc_exchange_rate Exchange rate. Includes a decimal point ics_dcc Decimal (13)


and up to 4 decimal places. For details,
see “Dynamic Currency Conversion
(DCC)” on page 132.

Credit Card Services Implementation Guide • June 2009 247


Reply Fields

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

dcc_exchange_rate_ Time stamp for the exchange rate. For ics_dcc String (14)
timestamp details, see “Dynamic Currency
Conversion (DCC)” on page 132.
Format: YYYYMMDD~HH:MM
where ~ denotes a space.

dcc_foreign_amount Converted amount. For details, see ics_dcc String (15)


“Dynamic Currency Conversion (DCC)” on
page 132.

dcc_foreign_currency Billing currency. ISO code for the currency ics_dcc String (5)
of the converted amount. See the Support
Center for a list of ISO codes. For details
about DCC, see “Dynamic Currency
Conversion (DCC)” on page 132.

dcc_margin_rate_ Exchange rate surcharge that is applied to ics_dcc Decimal (7)


percentage the wholesale exchange rate. Includes a
decimal point and 4 decimal places. For
details, see “Dynamic Currency
Conversion (DCC)” on page 132.

dcc_rcode One-digit code that indicates whether the ics_dcc Integer (1)
ics_dcc request was successful. Possible
values:
• -1: An error occurred.
• 0: The request was declined.
• 1: The request was successful.

dcc_rflag One-word description of the result of the ics_dcc String (50)


ics_dcc request. See Appendix F, “Reply
Flags for the SCMP API,” on page 287.

dcc_rmsg Message that explains the reply flag dcc_ ics_dcc String (255)
rflag. Do not display this message to the
customer, and do not use this field to write
an error handler.

fxrates_... The fields for the Multi-Currency Service


are listed separately in the Multi-Currency
Service Supplement.

248 CyberSource Corporation


Appendix B Fields for the SCMP API

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

ics_rcode One-digit code that indicates whether the All Credit Card Services Integer (1)
entire request was successful. Possible
values:
• -1: An error occurred
• 0: The request was declined
• 1: The request was successful

ics_rflag One-word description of the result of the All Credit Card Services String (50)
entire request. See Appendix F, “Reply
Flags for the SCMP API,” on page 287.

ics_rmsg Message that explains the reply flag ics_ All Credit Card Services String (255)
rflag. Do not display this message to the
customer, and do not use this field to write
an error handler.

merchant_ref_number Order reference or tracking number that All Credit Card Services String (50)
you provided in the request. If you
included multi-byte characters in this field
in the request, the returned value might
contain corrupted characters.

request_id Identifier for the request generated by the All Credit Card Services String (26)
client.

request_token Request token data created by All Services String (256)


CyberSource for each reply. You need to
store the contents of this field so that you
can retrieve and send it in follow-on
requests. The field is an encoded string
that contains no confidential information,
such as an account or card verification
number. The string can contain up to 256
characters.
If you request the authorization and
capture services together, the request
token is for the capture reply only.
For more information, see “Working with
Request Tokens” on page 60.

Credit Card Services Implementation Guide • June 2009 249


Reply Fields

Table 37 Reply Fields for the SCMP API (Continued)

Data Type &


Field Name Description Returned By
Length

void_rcode One-digit code that indicates whether the ics_void Integer (1)
ics_void request was successful.
Possible values:
• -1: An error occurred
• 0: The request was declined
• 1: The request was successful

void_rflag One-word description of the result of the ics_void String (50)


ics_void request. See Appendix F, “Reply
Flags for the SCMP API,” on page 287.

void_rmsg Message that explains the reply flag void_ ics_void String (255)
rflag. Do not display this message to the
customer, and do not use this field to write
an error handler.

void_void_amount Total amount of the void. ics_void Decimal (15)

void_void_currency Currency used for the order. Formatted ics_void String (5)
using the ISO currency codes.

void_void_request_time Time when void was requested in UTC. ics_void Date and
See “Data Type Definitions” on page 213 time (20)
for the field’s format.

250 CyberSource Corporation


Appendix C
Examples for the Simple Order API

Name-Value Pair Examples XML Examples


Basic Credit Card Examples Basic Credit Card Examples
DCC Examples DCC Examples
Asia-Mideast Processing Examples Asia-Mideast Processing Examples

Name-Value Pair Examples


Basic Credit Card Examples
Example 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

Credit Card Services Implementation Guide • June 2009 251


Name-Value Pair Examples

Example Credit Card Authorization Reply


requestID=0305782650000167905080
requestToken=AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv
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 Credit Card Capture Request


ccCaptureService_authRequestID=0305782650000167905080
orderRequestToken=AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv
merchantID=infodev
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
ccCaptureService_run=true
item_0_unitPrice=49.95
purchaseTotals_currency=USD

Example Credit Card Capture Reply


requestID=1019827520348290570293
requestToken=rWguaL5IMUwAwxAA4JUS1BIRk2Rk5IMUyCv
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
decision=ACCEPT
reasonCode=100
ccCaptureReply_amount=49.95
purchaseTotals_currency=USD
ccCaptureReply_reasonCode=100
ccCaptureReply_reconciliationID=1094820975023470

252 CyberSource Corporation


Appendix C Examples for the Simple Order API

DCC Examples
Example DCC Request
merchantID=infodev
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
item_0_unitPrice=2.00
item_0_quantity=1
purchaseTotals_currency=USD
purchaseTotals_foreignCurrency=AUD
card_accountNumber=4111111111111111
card_expirationMonth=01
card_expirationYear=2010
ccDCCService_run=true

Example DCC Reply


merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
requestID=190899012345000132406
decision=ACCEPT
reasonCode=100
requestToken=FljH6b02EQFNhXLS75aQIyHGaGTaxw3oV+1ncB8yj7B
purchaseTotals_currency=USD
purchaseTotals_foreignAmount=3.14
purchaseTotals_foreignCurrency=AUD
purchaseTotals_exchangeRate=1.5715
purchaseTotals_exchangeRateTimeStamp=20070826 12:00
ccDCCReply_reasonCode=100
ccDCCReply_marginRatePercentage=03.0000

Credit Card Services Implementation Guide • June 2009 253


Name-Value Pair Examples

Example Credit Card Authorization Request with DCC Data


merchantID=infodev
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
billTo_firstName=Jane
billTo_lastName=Smith
billTo_street1=1295 Charleston Road
billTo_city=Mountain View
billTo_state=CA
billTo_postalCode=94043
billTo_country=US
billTo_email=jsmith@example.com
card_accountNumber=4111111111111111
card_expirationMonth=01
card_expirationYear=2010
purchaseTotals_currency=USD
purchaseTotals_foreignCurrency=AUD
purchaseTotals_exchangeRateTimeStamp=20070826 12:00
purchaseTotals_exchangeRate=1.5715
purchaseTotals_foreignAmount=3.14
dcc_dccIndicator=1
item_0_unitPrice=2.00
item_0_quantity=1
ccAuthService_run=true

254 CyberSource Corporation


Appendix C Examples for the Simple Order API

Example Credit Card Authorization Reply


merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
requestID=190894820000132406
decision=ACCEPT
reasonCode=100
requestToken=qFNlGgfj53v7VIfEqi02AAAA9AsB
purchaseTotals_currency=USD
ccAuthReply_reasonCode=100
ccAuthReply_amount=2.00
ccAuthReply_authorizationCode=888668
ccAuthReply_avsCode=X
ccAuthReply_avsCodeRaw=I1
ccAuthReply_processorResponse=100
ccAuthReply_reconciliationID=RYZPS2F735UJHS

Example Credit Card Capture Request with DCC Data


merchantID=infodev
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
item_0_unitPrice=2.00
item_0_quantity=1
purchaseTotals_currency=USD
purchaseTotals_foreignCurrency=AUD
purchaseTotals_exchangeRateTimeStamp=20070826 12:00
purchaseTotals_exchangeRate=1.5715
purchaseTotals_foreignAmount=3.14
dcc_dccIndicator=1
ccCaptureService_run=true
ccCaptureService_authRequestID=190894820000132406
orderRequestToken=qFNlGgfj53v7VIfEqi02AAAA9AsB

Credit Card Services Implementation Guide • June 2009 255


Name-Value Pair Examples

Example Credit Card Capture Reply


merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
requestID=1019827520348290570293
decision=ACCEPT
reasonCode=100
requestToken=rWguaL5IMUw4JUS1BIRk2Rk5IMUyCv
purchaseTotals_currency=USD
ccCaptureReply_reasonCode=100
ccCaptureReply_amount=2.00
ccCaptureReply_reconciliationID=02850840187309570

Example Credit Card Follow-on Credit Request with DCC Data


merchantID=infodev
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
item_0_unitPrice=2.00
item_0_quantity=1
purchaseTotals_currency=USD
purchaseTotals_foreignCurrency=AUD
purchaseTotals_exchangeRateTimeStamp=20070826 12:00
purchaseTotals_exchangeRate=1.5715
purchaseTotals_foreignAmount=3.14
dcc_dccIndicator=1
ccCreditService_run=true
ccCreditService_captureRequestID=1019827520348290570293
orderRequestToken=rWguaL5IMUw4JUS1BIRk2Rk5IMUyCv

Example Credit Card Follow-on Credit Reply


merchantReferenceCode=482046C3A7E94F5BD1FE3C66C
requestID=1909006968670000132406
decision=ACCEPT
reasonCode=100
requestToken=FNlGbs2tWVIlpsK5aXb8BTYVy0j53v7VIfEqi02AAAA9AsB
purchaseTotals_currency=USD
ccCreditReply_reasonCode=100
ccCreditReply_amount=2.00
ccCreditReply_reconciliationID=02PS2F735UJHK

256 CyberSource Corporation


Appendix C Examples for the Simple Order API

Asia-Mideast Processing Examples


Example 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
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

Credit Card Services Implementation Guide • June 2009 257


Name-Value Pair Examples

Example 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
requestToken=Af/vj6Chjhz12345uWTFm0aME1zEF3nCAprm
reasonCode=100
decision=ACCEPT
merchantReferenceCode=0123456789
purchaseTotals_currency=USD

258 CyberSource Corporation


Appendix C Examples for the Simple Order API

XML Examples

Basic Credit Card Examples


Example 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>
</card>
<ccAuthService run="true"/>
</requestMessage>

Credit Card Services Implementation Guide • June 2009 259


XML Examples

Example 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:requestToken>AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv</c:requestToken>
<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:accountBalance>50.05</c:accountBalance>
<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 Credit Card Capture Request


<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.37">
<merchantID>infodev</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<ccCaptureService run="true">
<authRequestID>0305782650000167905080</authRequestID>
</ccCaptureService>
<orderRequestToken>AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv</orderRequestToken>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
</purchaseTotals>
</requestMessage>

260 CyberSource Corporation


Appendix C Examples for the Simple Order API

Example Credit Card Capture Reply


<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.37">
<c:requestID>1019827520348290570293</c:requestID>
<c:requestToken>rWguaL5IMUwAwxAA4JUS1BIRk2Rk5IMUyCv</c:requestToken>
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>49.95</c:amount>
<c:reconciliationID>1094820975023470</c:reconciliationID>
</c:ccCaptureReply>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
</c:replyMessage>

Credit Card Services Implementation Guide • June 2009 261


XML Examples

DCC Examples
Example DCC Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.32">
<merchantID>infodev</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD13C66C</merchantReferenceCode>
<item id="0">
<unitPrice>2.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
<foreignCurrency>AUD</foreignCurrency>
</purchaseTotals>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>01</expirationMonth>
<expirationYear>2010</expirationYear>
</card>
<ccDCCService run="true"/>
</requestMessage>

262 CyberSource Corporation


Appendix C Examples for the Simple Order API

Example DCC Reply


<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.32">
<c:merchantReferenceCode>482046C3A7E94F5BD1F6C</c:merchantReferenceCode>
<c:requestID>190899012345000132406</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:requestToken>FljH6b02EQFNhXLS75aQIyHGw3oV+1ncB8yj7B</c:requestToken>
<c:purchaseTotals>
<c:currency>USD</c:currency>
<c:foreignAmount>3.14</c:foreignAmount>
<c:foreignCurrency>AUD</c:foreignCurrency>
<c:exchangeRate>1.5715</c:exchangeRate>
<c:exchangeRateTimeStamp>20070826 12:00</c:exchangeRateTimeStamp>
</c:purchaseTotals>
<c:ccDCCReply>
<c:reasonCode>100</c:reasonCode>
<c:marginRatePercentage>03.0000</c:marginRatePercentage>
</c:ccDCCReply>
</c:replyMessage>

Credit Card Services Implementation Guide • June 2009 263


XML Examples

Example Credit Card Authorization Request with DCC Data


<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.32">
<merchantID>infodev</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD166C</merchantReferenceCode>
<billTo>
<firstName>Jane</firstName>
<lastName>Smith</lastName>
<street1>1295 Charleston Road</street1>
<city>Mountain View</city>
<state>CA</state>
<postalCode>94043</postalCode>
<country>US</country>
<email>jsmith@example.com</email>
</billTo>
<item id="0">
<unitPrice>2.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
<foreignAmount>3.14</foreignAmount>
<foreignCurrency>AUD</foreignCurrency>
<exchangeRate>1.5715</exchangeRate>
<exchangeRateTimeStamp>20070826 12:00</exchangeRateTimeStamp>
</purchaseTotals>
<dcc>
<dccIndicator>1</dccIndicator>
</dcc>
<card>
<accountNumber>4111111111111111</accountNumber>
<expirationMonth>01</expirationMonth>
<expirationYear>2010</expirationYear>
</card>
<ccAuthService run="true"/>
</requestMessage>

264 CyberSource Corporation


Appendix C Examples for the Simple Order API

Example Credit Card Authorization Reply


<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.32">
<c:merchantReferenceCode>482046C3A7E94F5BD166C</c:merchantReferenceCode>
<c:requestID>190894820000132406</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:requestToken>Af/vj53v7VIfEqi0202AAAA9AsB</c:requestToken>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccAuthReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>2.00</c:amount>
<c:authorizationCode>888668</c:authorizationCode>
<c:avsCode>X</c:avsCode>
<c:avsCodeRaw>I1</c:avsCodeRaw>
<c:processorResponse>100</c:processorResponse>
<c:reconciliationID>RYZPS2F735UJHD</c:reconciliationID>
</c:ccAuthReply>
</c:replyMessage>

Credit Card Services Implementation Guide • June 2009 265


XML Examples

Example Credit Card Capture Request with DCC Data


<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.37">
<merchantID>infodev</merchantID>
<merchantReferenceCode>482046C3A7E94F5BDC66C</merchantReferenceCode>
<item id="0">
<unitPrice>2.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
<foreignAmount>3.14</foreignAmount>
<foreignCurrency>AUD</foreignCurrency>
<exchangeRate>1.5715</exchangeRate>
<exchangeRateTimeStamp>20070826 12:00</exchangeRateTimeStamp>
</purchaseTotals>
<dcc>
<dccIndicator>1</dccIndicator>
</dcc>
<ccCaptureService run="true">
<authRequestID>190894820000132406</authRequestID>
</ccCaptureService>
<orderRequestToken>Af/vj53v7VIfEqi0202AAAA9AsB</orderRequestToken>
</requestMessage>

266 CyberSource Corporation


Appendix C Examples for the Simple Order API

Example Credit Card Capture Reply


<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.37">
<c:merchantReferenceCode>482046C3A75BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>1019827520348290570293</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:requestToken>rWg4JUS1BIRk2Rk5IMUyCv</c:requestToken>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccCaptureReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>2.00</c:amount>
<c:reconciliationID>02850840187309570</c:reconciliationID>
</c:ccCaptureReply>
</c:replyMessage>

Credit Card Services Implementation Guide • June 2009 267


XML Examples

Example Credit Card Follow-on Credit Request with DCC Data


<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.37">
<merchantID>infodev</merchantID>
<merchantReferenceCode>482047E94F5BD1FE3C66C</merchantReferenceCode>
<item id="0">
<unitPrice>2.00</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>USD</currency>
<foreignAmount>3.14</foreignAmount>
<foreignCurrency>AUD</foreignCurrency>
<exchangeRate>1.5715</exchangeRate>
<exchangeRateTimeStamp>20070826 12:00</exchangeRateTimeStamp>
</purchaseTotals>
<dcc>
<dccIndicator>1</dccIndicator>
</dcc>
<ccCreditService run="true">
<captureRequestID>1019827520348290570293</captureRequestID>
</ccCreditService>
<orderRequestToken>rWg4JUS1BIRk2Rk5IMUyCv</orderRequestToken>
</requestMessage>

268 CyberSource Corporation


Appendix C Examples for the Simple Order API

Example Credit Card Follow-on Credit Reply


<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.37">
<c:merchantReferenceCode>482046C3A7E91FE3C66C</c:merchantReferenceCode>
<c:requestID>1908958128620000132406</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:requestToken>FNlGbs2tWVIlpsK5aX02AAAA9AsB</c:requestToken>
<c:purchaseTotals>
<c:currency>USD</c:currency>
</c:purchaseTotals>
<c:ccCreditReply>
<c:reasonCode>100</c:reasonCode>
<c:amount>2.00</c:amount>
<c:reconciliationID>02PS2F735UJHK</c:reconciliationID>
</c:ccCreditReply>
</c:replyMessage>

Credit Card Services Implementation Guide • June 2009 269


XML Examples

Asia-Mideast Processing Examples


Example 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>
Continued...

270 CyberSource Corporation


Appendix C Examples for the Simple Order API

... continued
<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">
<commerceIndicator>vbv</commerceIndicator>
<cavv>PpmBUYXt2uytV6p12345KuImAb8XgnOk</cavv>
<xid>WhPlErd9WE1234562pb1yFjFHlewUIQwQ</xid>
<veresEnrolled>Y</veresEnrolled>
<paresStatus>Y</paresStatus>
</ccAuthService>
</requestMessage>

Credit Card Services Implementation Guide • June 2009 271


XML Examples

Example 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:requestToken>Af/vj6Cg3pMW6Iz4G</c:requestToken>
<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>

272 CyberSource Corporation


Appendix D
Examples for the SCMP API

This appendix provides example requests and replies for the SCMP API.

Examples
Basic Credit Card Examples
DCC Examples
Asia-Mideast Processing Examples

Basic Credit Card Examples


Example Credit Card Authorization Request
bill_address1=1295 Charleston Rd.
bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=12
customer_cc_expyr=2015
customer_cc_number=4111111111111111
customer_email=jdoe@example.com
customer_firstname=John
customer_lastname=Doe
customer_phone=650-965-6000
ics_applications=ics_auth
merchant_id=infodev
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
offer0=amount:49.95^quantity:1
server_host=ics2test.ic3.com
server_port=80

Credit Card Services Implementation Guide • June 2009 273


Basic Credit Card Examples

Example Credit Card Authorization Reply


auth_auth_amount=49.95
auth_account_balance=50.05
auth_auth_avs=Y
auth_auth_code=123456
auth_auth_response=A
auth_avs_raw=YYY
auth_rcode=1
auth_rflag=SOK
auth_rmsg=Request was processed successfully.
client_lib_version=Perl3.2/MSWin324.0/NT4.0/WIN32/C/3.4.5
currency=USD
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
request_id=0305782650000167905080
request_token=AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv

Example Credit Card Capture Request


auth_request_id=0305782650000167905080
order_request_token=AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
merchant_id=infodev
currency=USD
offer0=amount:49.95
ics_applications=ics_bill

274 CyberSource Corporation


Appendix D Examples for the SCMP API

Example Credit Card Capture Reply.


request_id=1019827520348290570293
request_token=rWguaL5IMUwAwxAA4JUS1BIRk2Rk5IMUyCv
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
bill_trans_ref_no=02850840187309570
bill_bill_amount=49.95
bill_rcode=1
bill_rflag=SOK
bill_rmsg=Request was processed successfully.
currency=USD
client_lib_version=Perl3.2/MSWin324.0/NT4.0/WIN32/C/3.4.5

DCC Examples
Example DCC Request
bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=12
customer_cc_expyr=2015
customer_cc_number=4111111111111111
customer_email=jdoe@example.com
customer_firstname=John
customer_lastname=Doe
customer_phone=650-965-6000
ics_applications=ics_dcc
merchant_id=infodev
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
offer0=product_code:electronic_software^merchant_product_
sku:swl^quantity:1^amount:2^product_name:CyberSoftware^offer_id:0

Credit Card Services Implementation Guide • June 2009 275


DCC Examples

Example DCC Reply


dcc_response_code=0
ics_rcode=1
ics_rmsg=Request was processed successfully.
request_id=19083406433304567
request_token=AfNvj53OL6ElCQFL4N+Hax0gRkOMsMm1WkR370pVID4Lx9m
dcc_dcc_supported=TRUE
dcc_foreign_amount=3.14
dcc_foreign_currency=AUD
dcc_exchange_rate=1.5715
dcc_exchange_rate_timestamp=20071001 12:00
dcc_margin_rate_percentage=03.0000
dcc_rcode=1
currency=USD
ics_rflag=SOK
merchant_ref_number=73557862

276 CyberSource Corporation


Appendix D Examples for the SCMP API

Example Credit Card Authorization Request with DCC Data


bill_address1=1295 Charleston Rd.
bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=12
customer_cc_expyr=2015
customer_cc_number=4111111111111111
customer_email=jdoe@example.com
customer_firstname=John
customer_lastname=Doe
customer_phone=650-965-6000
ics_applications=ics_auth
merchant_id=infodev
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
offer0=product_code:electronic_software^merchant_product_
sku:swl^quantity:1^amount:2^product_name:CyberSoftware^offer_id:0
card_type=001
dcc_indicator=1
foreign_amount=3.14
foreign_currency=AUD
exchange_rate=1.5715
exchange_rate_timestamp=20071001 12:00

Credit Card Services Implementation Guide • June 2009 277


DCC Examples

Example Credit Card Authorization Reply


auth_auth_amount=2.00
auth_auth_avs=Y
auth_auth_code=123456
auth_auth_response=A
auth_avs_raw=YYY
auth_rcode=1
auth_rflag=SOK
auth_rmsg=Request was processed successfully.
currency=USD
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
request_id=0305782650000167905080
request_token=AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv

Example Credit Card Capture Request with DCC Data


auth_request_id=0305782650000167905080
order_request_token=AA4JUrWguaLLQxMUGwxSWVdPS1BIRk5IMUwA2yCv
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
merchant_id=infodev
currency=USD
offer0=amount:2.00
ics_applications=ics_bill
dcc_indicator=1
foreign_amount=3.14
foreign_currency=AUD
exchange_rate=1.5715
exchange_rate_timestamp=20071001 12:00

278 CyberSource Corporation


Appendix D Examples for the SCMP API

Example Credit Card Capture Reply


request_id=1019827520348290570293
request_token=rWguaL5IMUwAwxAA4JUS1BIRk2Rk5IMUyCv
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
bill_trans_ref_no=02850840187309570
bill_bill_amount=2.00
bill_rcode=1
bill_rflag=SOK
bill_rmsg=Request was processed successfully.
currency=USD

Example Credit Card Follow-on Credit Request with DCC Data


bill_request_id=1019827520348290570293
order_request_token=rWguaL5IMUwAwxAA4JUS1BIRk2Rk5IMUyCv
currency=USD
offer0=amount:2.00
ics_applications=ics_credit
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
merchant_id=infodev
dcc_indicator=1
foreign_amount=3.14
foreign_currency=AUD
exchange_rate=1.5715
exchange_rate_timestamp=20071001 12:00

Credit Card Services Implementation Guide • June 2009 279


DCC Examples

Example Credit Card Follow-on Credit Reply


request_id=9827520348290570293101
request_token=IMUwAwxAA4JUS1BIRk2Rk5IMUyCvrWguaL5
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
currency=USD
credit_trans_ref_no=02850840187309570
credit_credit_amount=2.00
credit_rcode=1
credit_rflag=SOK
credit_rmsg=Request was processed successfully.

280 CyberSource Corporation


Appendix D Examples for the SCMP API

Asia-Mideast Processing Examples


Example Credit Card Authorization and Capture Request with Payer Authentication
Data
bill_address1=1295 Charleston Road
bill_city=Mountain View
bill_country=US
bill_state=CA
bill_zip=94043
currency=USD
customer_cc_expmo=03
customer_cc_expyr=09
customer_cc_number=4111111111111111
customer_email=jsmith@example.com
customer_firstname=Jane
customer_lastname=Smith
customer_phone=650-965-6000
ship_to_country=USA
ship_to_state=CA
e_commerce_indicator=VBV
ics_applications=ics_auth,ics_bill
merchant_id=okgo
merchant_ref_number=QQQ123
offer0=amount:100
cavv=Z9Jp7ZJ7hKtD0Z2oyxuDx5N
pares_status=Y
veres_enrolled=Y
xid=Z9Jp7ZJ7hKtDZI0Z2oyxuDx5Nqg

Credit Card Services Implementation Guide • June 2009 281


Asia-Mideast Processing Examples

Example Credit Card Authorization and Capture Reply


auth_auth_amount=100.00
auth_auth_avs=2
auth_auth_code=ABC12345
auth_auth_code_available=true
auth_auth_response=00
auth_rcode=1
auth_rflag=SOK
auth_rmsg=Request was processed successfully.
auth_trans_ref_no=19119123407
bill_bill_amount=100.00
bill_rcode=1
bill_rflag=SOK
bill_rmsg=Request was processed successfully.
bill_trans_ref_no=19119345607
currency=USD
ics_rcode=1
ics_rflag=SOK
ics_rmsg=Request was processed successfully.
merchant_ref_number=QQQ123
request_id=190135790167904567
request_token=AfrlmxlZHSB04g4yQyY9DAdE6HPKbgQxIL

282 CyberSource Corporation


Appendix E
Reason Codes for the Simple Order API

The following table describes the Credit Card Services reason codes returned by the
Simple Order API. See “Handling Replies” on page 43 for a discussion of replies,
decisions, and reason codes.

Important Because CyberSource can add reply fields and reason codes at any time,
proceed as follows:
- You should parse the reply data according to the names of the fields instead of their
order in the reply. For more information about parsing reply fields, see the documentation
for your client.
- Your error handler should use the decision field to determine the result if it receives a
reason code that it does not recognize.

Table 38 Reason Codes

Reason
Description
Code

100 Successful transaction.

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. See “Missing or
Invalid Fields” on page 45.

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. See “Missing or Invalid Fields” on
page 45.

150 Error: General system failure.


See the documentation for your CyberSource client (SDK) for information about
how to handle retries in the case of system errors.

Credit Card Services Implementation Guide • June 2009 283


Table 38 Reason Codes (Continued)

Reason
Description
Code

151 Error: 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 (SDK) for information about how to
handle retries in the case of system errors.

152 Error: 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 (SDK) for information about how to
handle 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 Service (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 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 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.

205 Stolen or lost card.


Possible action: Refer the transaction to your customer support center for manual
review.

207 Issuing bank unavailable.


Possible action: Wait a few minutes and resend the request.

284 CyberSource Corporation


Appendix E Reason Codes for the Simple Order API

Table 38 Reason Codes (Continued)

Reason
Description
Code

208 Inactive card or card not authorized for card-not-present transactions.


Possible action: Request a different card or other form of payment.

209 American Express Card Identification Digits (CID) 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 card verification number.


Possible action: Request a different card or other form of payment.

221 The customer matched an entry on the processor’s 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 card verification (CV) 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 your CyberSource merchant configuration.


Possible action: Do not resend the request. Contact Customer Support to correct
the configuration problem.

235 The requested amount exceeds the originally authorized amount. Occurs, for
example, if you try to capture an amount larger than the original authorization
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.

Credit Card Services Implementation Guide • June 2009 285


Table 38 Reason Codes (Continued)

Reason
Description
Code

237 The authorization has already been reversed.


Possible action: No action required.

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 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 Error: 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.

286 CyberSource Corporation


Appendix F
Reply Flags for the SCMP API

The following table describes the reply flags, which can be associated with a request or a
service:

• Entire request—The flag is in the ics_rflag field with a message in the ics_rmsg field.
• Individual services—The flag is in the <service>_rflag with a message in the
<service>_rmsg field.

Table 39 Reply Flags for the SCMP API

Services That Can


Reply Flag Description
Return This Flag

DAVSNO The credit card was accepted by the bank but ics_auth
refused by CyberSource because it did not pass
the AVS check. AVS result is N.

DCALL Indicates that you must call the issuing bank to ics_auth
proceed with the transaction.

DCARDEXPIRED CyberSource declined the request because the ics_auth


credit card has expired. You might also receive
ics_credit
this if the expiration date you provided does not
match the date the issuing bank has on file.
Note ics_credit does not check the expiration
date; instead, it passes the request to the
payment processor. If the payment processor
allows issuance of credits to expired cards,
CyberSource does not limit this functionality.

DCARDREFUSED The bank declined the transaction. ics_auth


Note This includes declines due to insufficient ics_credit
funds, which cannot be differentiated at
authorization time from other transactions.

Credit Card Services Implementation Guide • June 2009 287


Table 39 Reply Flags for the SCMP API (Continued)

Services That Can


Reply Flag Description
Return This Flag

DCV The credit card was accepted by the bank but ics_auth
refused by CyberSource because it did not pass
the card verification number check. Card
verification result is N.

DINVALIDCARD The credit card number did not pass ics_auth


CyberSource basic checks.
ics_credit

DINVALIDDATA Data provided is not consistent with the request. All Credit Card
For example, you requested a product with Services
negative cost, or you tried to credit a capture
that was previously voided.

DMISSINGFIELD The request is missing a required field. All Credit Card


Services

DNOAUTH A request was made to capture or reverse an ics_auth_reversal


order for which there is no corresponding,
ics_bill
unused authorization record. Occurs if there
was not a previously successful ics_auth
request or if the previously successful
authorization has already been used by another
ics_auth_reversal or ics_bill request.

DNOTVOIDABLE The capture or credit is not voidable because ics_void


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.

ESYSTEM System error. You must design your transaction All Credit Card
management system to include a way to Services
correctly handle CyberSource system errors.
Depending on which payment processor is
handling the transaction, the error might indicate
a valid CyberSource system error, or it might
indicate a processor rejection because of some
type of invalid data. In either case, CyberSource
recommends that you do not design your
system to endlessly retry sending a transaction
in the case of a system error. See the
documentation for the CyberSource client (SDK)
you are using for important information about
how to handle system errors and retries.

288 CyberSource Corporation


Appendix F Reply Flags for the SCMP API

Table 39 Reply Flags for the SCMP API (Continued)

Services That Can


Reply Flag Description
Return This Flag

ETIMEOUT The request timed out. All Credit Card


Services

SOK Transaction was successful. All Credit Card


Services

Credit Card Services Implementation Guide • June 2009 289


290 CyberSource Corporation
Appendix G
Address Verification Service Codes

In the reply message for an authorization request, the address verification service (AVS)
code is returned in:

• ccAuthReply_avsCode for the Simple Order API


• auth_auth_avs for the SCMP API
For additional information, see:

• “Address Verification Service” on page 23 for general information.


• “Address Verification Service” on page 47 for Simple Order API information.
• “Address Verification Service” on page 69 for SCMP API information.

Table 40 Types of AVS Codes

Type of Codes Codes Description

Codes for American F, H, J, K, L, For American Express cards only. For American
Express Cards O, Q, T, V Express cards, you can receive Visa and
CyberSource AVS codes in addition to the
American Express AVS codes.

International Visa Codes B, C, D, G, I, The international and domestic alphabetic AVS


M, P codes are the Visa standard AVS codes.
CyberSource maps the standard AVS return codes
Domestic Visa Codes A, E, N, R, S, for other types of credit cards, including American
U, W, X, Y, Z Express cards, to the Visa standard AVS codes.
For international cards, you can receive domestic
AVS codes in addition to the international AVS
codes.

CyberSource Codes 1, 2, 3, 4 The numeric AVS codes are created by


CyberSource and are not standard Visa codes.
These AVS codes can be returned for any card
type.

Credit Card Services Implementation Guide • June 2009 291


Table 41 AVS Codes

Code Description

A Partial match: Street address matches, but the 5-digit or 9-digit postal code does not
match.

B Partial match: Street address matches, but postal code is not verified. Returned only for
non U.S.-issued Visa cards.

C No match: Street address and postal code do not match. Returned only for non
U.S.-issued Visa cards.

D&M Match: Street address and postal code match. Returned only for non U.S.-issued Visa
cards.

E Invalid: AVS data is invalid or AVS is not allowed for this card type.

F Partial match: Card member’s name does not match, but billing postal code matches.
Returned only for the American Express card type.

G Not supported: Non-U.S. issuing bank does not support AVS.

H Partial match: Card member’s name does not match, but street address and postal
code match. Returned only for the American Express card type.

I No match: Address not verified. Returned only for non U.S.-issued Visa cards.

J Match: Card member’s name, billing address, and postal code match. Shipping
information verified and chargeback protection guaranteed through the Fraud
Protection Program. Returned only if you are signed up to use AAV+ with the American
Express Phoenix processor.

K Partial match: Card member’s name matches, but billing address and billing postal code
do not match. Returned only for the American Express card type.

L Partial match: Card member’s name and billing postal code match, but billing address
does not match. Returned only for the American Express card type.

M See the entry for D & M.

N No match: Street address and postal code do not match.


or
No match: Card member’s name, street address and postal code do not match.
Returned only for the American Express card type.

O Partial match: Card member’s name and billing address match, but billing postal code
does not match. Returned only for the American Express card type.

P Partial match: Postal code matches, but street address not verified. Returned only for
non U.S.-issued Visa cards.

292 CyberSource Corporation


Appendix G Address Verification Service Codes

Table 41 AVS Codes (Continued)

Code Description

Q Match: Card member’s name, billing address, and postal code match. Shipping
information verified but chargeback protection not guaranteed (Standard program).
Returned only if you are signed up to use AAV+ with the American Express Phoenix
processor.

R System unavailable.

S Not supported: U.S.-issuing bank does not support AVS.

T Partial match: Card member’s name does not match, but street address matches.
Returned only for the American Express card type.

U System unavailable: Address information unavailable for one of these reasons:


• The U.S. bank does not support non-U.S. AVS.
• The AVS in a U.S. bank is not functioning properly.

V Match: Card member’s name, billing address, and billing postal code match. Returned
only for the American Express card type.

W Partial match: Street address does not match, but 9-digit postal code matches.

X Match: Street address and 9-digit postal code match.

Y Match: Street address and 5-digit postal code match.

Z Partial match: Street address does not match, but 5-digit postal code matches.

1 Not supported: AVS is not supported for this processor or card type.

2 Invalid: The processor returned an unrecognized value for the AVS response.

3 Match: Address is confirmed. Returned only for PayPal Express Checkout.

4 No match: Address is not confirmed. Returned only for PayPal Express Checkout.

Credit Card Services Implementation Guide • June 2009 293


294 CyberSource Corporation
Appendix H
Card Verification Number Codes

In the reply message for an authorization request, the card verification number (CVN)
code is returned in:

• ccAuthReply_cvCode for the Simple Order API


• auth_cv_result for the SCMP API
For additional information, see:

• “Card Verification Numbers” on page 27 for general information.


• “Card Verification Numbers” on page 48 for Simple Order API information.
• “Card Verification Numbers” on page 70 for SCMP API information.
The following table describes the CVN codes.

Table 42 CVN Codes

Code Description

D The transaction was determined to be suspicious by the issuing bank.

I The CVN failed the processor's data validation check.

M The CVN matched.

N The CVN did not match.

P The CVN was not processed by the processor for an unspecified reason.

S The CVN is on the card but was not included in the request.

U Card verification is not supported by the issuing bank.

X Card verification is not supported by the card association.

1 Card verification is not supported for this processor or card type.

2 An unrecognized result code was returned by the processor for the card
verification response.

3 No result code was returned by the processor.

Credit Card Services Implementation Guide • June 2009 295


296 CyberSource Corporation
Appendix I
Product Codes

The following table lists the values you can use for the product code. For the Simple Order
API, use the item_#_productCode request field to specify the product code. For the SCMP
API, use the product_code offer-level field.

Table 43 Product Code Values

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
provides no value for the product code.
electronic_good Electronic product other than software.
electronic_software Software distributed electronically rather than on tapes, disks, or other media.
gift_certificate Gift certificate not issued with CyberSource Stored Value Services.
handling_only Separate charge that is generally a fee imposed by the seller on the customer.
The fee pays for the seller’s administrative selling costs.
service Service that you perform for the customer.
shipping_and_handling Shipping is a separate charge for shipping the product to the purchaser. Handling
is generally a fee imposed by the seller to pay for administrative selling costs.
shipping_only Charge for transporting tangible personal property from the seller to the
purchaser. Documentation must be maintained that clearly establishes where title
to the tangible personal property passed from the seller to the purchaser.
stored_value Stored Value certificate.
subscription Subscription to a Web site or other content.

Credit Card Services Implementation Guide • June 2009 297


298 CyberSource Corporation
Appendix J
Bank Card Reversals for the Global Payment
Service

Note A bank card is the same as a credit card.

Bank card reversals and requests for information, which are also called retrieval requests,
are business transactions initiated by your customers through their bank. You can learn
more about bank card disputes on Visa USA’s Web site: http://usa.visa.com/merchants/
operations/chargebacks_dispute_resolution/. This information is generally applicable to
all card types and all card type operating regions although certain details can vary.

Topics:
Request for Information
Responding to a Request for Information
Chargebacks
Representments
Chargeback Reason Codes for Visa
Chargeback Reason Codes for MasterCard
Sample Request for Information

Request for Information


Bank card reversals and requests for information involve communication:

• Between your customer and the acquiring bank


• Between you and Global Collect, which is CyberSource’s global partner
• Between Global Collect and the acquiring bank
The process is:
1 Request for information—The acquiring bank notifies Global Collect of your
customer’s request for information.
2 Search for refund—Global Collect searches to determine if there has already been a
refund processed for the transaction identified by your customer.

Credit Card Services Implementation Guide • June 2009 299


Responding to a Request for Information

3 If there has been a refund—Global Collect responds to the acquiring bank stating
“already refunded.” No further action will be taken because the information request
has been satisfied. Requests for information are not documented within any report.
4 If there is not a refund—If Global Collect’s 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 “Sample Request for
Information” on page 305.
5 Impending chargeback—A request for information is an impending chargeback. If
Global Collect does not receive your answer by midnight PT prior to the fifth day,
your customer’s bank will initiate a chargeback.

Responding to a Request for Information


When you receive a request for information, you must respond promptly and with as
much detail as possible:
1 Respond to your customer’s 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.
2 Response goes to bank—Global Collect forwards your response by email to the
acquiring bank which then communicates with your customer’s issuing bank.
3 Sufficient information—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 will not be executed. The dispute will be
dropped without further notification to the acquirer, Global Collect, or you.

300 CyberSource Corporation


Appendix J Bank Card Reversals for the Global Payment Service

Chargebacks
If one of the following occurs:

• 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
then the issuing bank sends a chargeback (refund) to the customer’s card and debits your
account:
1 Unsatisfactory response to the request for information—If the information in 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 always involves the adverse movement of funds.
Adverse movement of funds is unavoidable, but can be reversed in some cases. See
“Representments” on page 302.
2 Chargeback issued—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 CyberSource Business Center
• The Payment Events Report for that processing day
The chargeback entry shows the payment type’s 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.
Additionally, you can search on the Internet for:
MasterCard chargeback reason code
or
Visa chargeback reason code
A summary of MasterCard and Visa reason codes is provided in “Chargeback Reason
Codes for Visa” on page 303.
3 Chargeback received—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.

Credit Card Services Implementation Guide • June 2009 301


Representments

Representments
When you or Global Collect disputes the legitimacy of a chargeback, a representment case
is initiated:
1 Refund orders—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 customer’s account and the crediting of yours. See step 3.
2 Challenge a chargeback—If you want to challenge a chargeback, in other words
represent it, then you must do so in an extremely timely manner. To optimize your
chances for success, you need to rapidly put together your facts and submit them to
Global Collect in five or fewer days after receiving notification of the chargeback.
For sources of best practices to avoid chargebacks and to challenge specious
chargebacks, see the Visa Web site: http://usa.visa.com/merchants/operations/
chargebacks_dispute_resolution/.
Additionally, you can search on the Internet for:
fight chargebacks representment
3 Representment time frames—If your representment case is approved by your
customer’s issuing bank, you will receive notification from Global Collect in the form
of a refund to the chargeback. Although it is inconvenient, the card types provide no
other notification vehicle.
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.

302 CyberSource Corporation


Appendix J Bank Card Reversals for the Global Payment Service

Chargeback Reason Codes for Visa


Reason
Description
Code

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 / Declined Authorization

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 Non-Possession of Card

85 Credit Not Processed

86 Paid by Other Means

90 Non-Receipt of Merchandise

Credit Card Services Implementation Guide • June 2009 303


Chargeback Reason Codes for MasterCard

Chargeback Reason Codes for MasterCard


Reason
Description
Code

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 Non-Receipt of Merchandise

59 Services Not Rendered

60 Credit Not Processed

63 Cardholder Does Not Recognize - Potential Fraud

304 CyberSource Corporation


Appendix J Bank Card Reversals for the Global Payment Service

Sample Request for Information


This sample illustrates the email you might receive from Global Collect requesting
information. See Step 4 under Request for Information. In this sample, the Xs will be
replaced by the 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.

GlobalCollect Call-ID : XXXXX

Bank Case ID : XXXXXXXXX


Creditcard Number : ***********XXXX
External Order Number : XXXXXXXXXXX
Merchant Reference :
Merchant Number : XXXXXXXXXXXX
Contract-ID : XXXX

Credit Card Services Implementation Guide • June 2009 305


Sample Request for Information

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

Visa and MasterCard International Rules and Regulations specify GlobalCollect'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 will also have to 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

306 CyberSource Corporation


Appendix K
Frequently Asked Questions

This appendix provides answers to questions that merchants often ask about Credit Card
Services.

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” on
page 4.
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 “Types of Cards” on page 2, “Payment Processors” on page 6, or
contact your CyberSource account representative.
Do I need to sign agreements with the credit card associations?
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 make sure that you sign all of the necessary agreements.
Can I use more than one payment processor or merchant account provider?
Yes. CyberSource can give you additional CyberSource merchant IDs and configure each
CyberSource merchant ID to use a different payment processor or merchant account
provider.
What happens if my customers commit fraud?
You could be liable for fraudulent transactions. If 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 have 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.

Credit Card Services Implementation Guide • June 2009 307


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 determines the length of the authorization.
If 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; that is, your fees
for the transaction could increase. The card association can also choose not to capture
expired authorizations.
If you believe that an authorization might have expired, you can request a new
authorization, then capture the new authorization. However, if the customer’s credit limit
has been exceeded, if the card has expired, or if the card has been cancelled, the new
authorization could be denied.
Can I reverse an authorization?
Yes. For some processors, you can use the full authorization reversal service to reverse a
previous authorization and release the hold that an authorization placed on credit card
funds.
If you are not using a processor that allows full authorization reversal and you need to
reverse an authorization, you must contact the customer’s issuing bank or wait for the
authorization to expire. For a list of processors that support full authorization reversal for
Credit Card Services, see “Reversing an Authorization” on page 12.
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 information to your payment processor. See “Voiding a Capture or
Credit” on page 20.
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 CyberSource 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 allows you to change this information, known as the merchant descriptor, if
you use a payment processor that supports this feature. After your processor configures

308 CyberSource Corporation


Appendix K Frequently Asked Questions

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 information for your account.
See “Merchant Descriptors” on page 100 for the Simple Order API or “Merchant
Descriptors” on page 144 for the SCMP API.
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 customer’s bank account and my company’s bank
account?
Funds are usually transferred within two to three days after you request a capture or
credit.

Credit Card Services Implementation Guide • June 2009 309


310 CyberSource Corporation
Index

Numerics American Express Brighton, continued


recurring payments
$0 authorizations SCMP API 163
SCMP API 126 Simple Order API 119
Simple Order API 82 verbal authorizations 29
voids 20
A American Express card type 5
American Express Direct
AAV 107 $0 authorizations
AAV+ SCMP API 126
described 26 Simple Order API 82
SCMP API 69 authorizations 9
Simple Order API 48 AVS 24
ACCEPT decision 43 captures 13
Account Authentication Value 107 card types 6
acquiring banks 4 CVNs 27
Address Verification Service. See AVS full authorization reversals 12
airline data merchant descriptors
SCMP API 126 SCMP API 144
Simple Order API 82 Simple Order API 100
American Express Brighton prepaid cards
authorizations 9 SCMP API 127
AVS 24 Simple Order API 83
captures 13 reconciliation 31
card types 6 recurring payments
credits 17 SCMP API 163
CVNs 27 Simple Order API 119
reconciliation 31 verbal authorizations 29
voids 20

Credit Card Services Implementation Guide • June 2009 311


A–A

American Express Phoenix Asia-Mideast Processing


authorizations 9 authorizations 9
AVS, enhanced 26 captures 13
AVS, standard 24 card types 6
captures 13 credits 17
card types 6 CVNs 27
credits 17 examples
CVNs 27 SCMP API 281
full authorization reversals 12 Simple Order API, NVP 257
merchant descriptors Simple Order API, XML 270
SCMP API 144 forced captures
Simple Order API 100 SCMP API 139
reconciliation 31 Simple Order API 95
recurring payments JCB J/Secure
SCMP API 163 SCMP API 151
Simple Order API 119 Simple Order API 107
verbal authorizations 29 MasterCard SecureCode
voids 20 SCMP API 151
American Express prepaid cards Simple Order API 107
SCMP API 127 reconciliation 31
Simple Order API 83 recurring payments
SCMP API 163
Simple Order API 119
verbal authorizations 29
Verified by Visa
SCMP API 151
Simple Order API 107
voids 20

312 CyberSource Corporation


Index

ATM cards 2 AVS, continued


Atos Extended 26
authorizations 9 SCMP API 69
AVS 24 Simple Order API 47
captures 13 AVS only. See $0 authorizations
card types 6
credits 17 B
CVN 27
reconciliation 31 bank card reversals 299
voids 20 banks 21
authorization refresh 15 Barclays
authorization reversals authorizations 9
full 12 AVS 24
partial 14 captures 13
using alternate methods 308 card types 6
authorizations cash advances
described 9 SCMP API 129
examples Simple Order API 85
SCMP API 273 credits 17
Simple Order API, NVP 251 CVNs 27
Simple Order API, XML 259 full authorization reversals 12
expiration of 308 MasterCard SecureCode
for $0 SCMP API 151
SCMP API 126 Simple Order API 107
Simple Order API 82 reconciliation 31
verbal 29 recurring payments
See also ccAuthService SCMP API 163
See also ics_auth Simple Order API 119
automated teller machine cards 2 verbal authorizations 29
automatic authorization refresh 15 Verified by Visa
automatic authorization reversals 14 SCMP API 151
automatic interchange optimization 15 Simple Order API 107
AVS voids 20
AAV+ Bill Me Later
described 26 SCMP API 127
SCMP API 69 Simple Order API 83
Simple Order API 48 bill payments with Visa
and recurring payments SCMP API 128
SCMP API 163 Simple Order API 84
Simple Order API 119 business cards. See Level II cards
described 23 Business Center 21
Enhanced business rules 48
described 26
SCMP API 69
Simple Order API 48

Credit Card Services Implementation Guide • June 2009 313


C–C

C ccCaptureService
captures 13
captures description 52
described 13 requested as a follow-on service 42
examples required fields 54
SCMP API 273 ccCreditService
Simple Order API, NVP 251 credits 17
Simple Order API, XML 259 description 55
See also ccCaptureService requested as a follow-on service 42
See also ics_bill required fields 56
card associations 5 CCS (CAFIS)
Card Identification Digits. See card authorizations 9
verification numbers captures 13
Card Validation Code. See card card types 6
verification numbers credits 17
card verification numbers CVNs 27
and recurring payments full authorization reversals 12
SCMP API 163 Japanese payment options
Simple Order API 119 SCMP API 140
described 27 Simple Order API 96
SCMP API 70 JCB J/Secure
Simple Order API 48 SCMP API 151
Cardnet. See LloydsTSB Cardnet Simple Order API 107
card-not-present transactions 4 MasterCard SecureCode
card-present transactions 4 SCMP API 151
cash advances Simple Order API 107
SCMP API 129 verbal authorizations 29
Simple Order API 85 Verified by Visa
ccAuthReversalService SCMP API 151
description 51 Simple Order API 107
full authorization reversals 12 voids 20
requested as a follow-on service 42 character sets
required fields 52 SCMP API 60
ccAuthService Simple Order API 34
authorizations 9 characters, special
description 47 SCMP API 213
required fields 50 Simple Order API 173
chargebacks 307

314 CyberSource Corporation


Index

Chase Paymentech Solutions credit card encryption


$0 authorizations SCMP API 138
SCMP API 126 Simple Order API 95
Simple Order API 82 credit card numbers for testing 170
authorizations 9 credit card types 2
AVS 24 credits
bill payments with Visa described 17
SCMP API 128 See also ccCreditService
Simple Order API 84 See also ics_credit
captures 13 customer profiles
card types 6 SCMP API 131
credits 17 Simple Order API 87
CVNs 27 CVC2. See card verification numbers
encoded account numbers CVN. See card verification numbers
SCMP API 138 CVV2. See card verification numbers
Simple Order API 95 CyberSource Global Payment Service.
full authorization reversals 12 See Global Payment Service
merchant descriptors CyberSource Latin American
SCMP API 144 Processing. See Latin American
Simple Order API 100 Processing
multi-currency
SCMP API 150 D
Simple Order API 106
reconciliation 31 data types
recurring payments SCMP API 213
SCMP API 163 Simple Order API 173
Simple Order API 119 date and time formats
verbal authorizations 29 SCMP API 213
Verified by Visa Simple Order API 203
SCMP API 151 DCC. See dynamic currency conversion
Simple Order API 107 debit cards 2
voids 20 Decision Manager 44
check cards 2 decisions in Simple Order API 43
China processing 8 declines, described 65
CID. See card verification numbers developer kits. See clients
Citibank 6 Diners Club alliance with MasterCard 3
clients 22 Discover card type 5
SCMP API 60 dynamic currency conversion
Simple Order API 34 described
consumer banks 5 SCMP API 132
corporate cards. See Level II cards Simple Order API 88
coupons examples
SCMP API 130 SCMP API 275
Simple Order API 86 Simple Order API, NVP 253
credit card associations 5 Simple Order API, XML 262

Credit Card Services Implementation Guide • June 2009 315


E–F

E F
E4X FAQ 307
SCMP API 150 FDC Germany
Simple Order API 106 authorizations 9
encoded account numbers AVS 24
SCMP API 138 captures 13
Simple Order API 95 card types 7
encoding types credits 17
SCMP API 60 CVNs 27
Simple Order API 34 full authorization reversals 12
encryption reconciliation 31
SCMP API 138 recurring payments
Simple Order API 95 SCMP API 163
Enhanced AVS Simple Order API 119
described 26 verbal authorizations 30
SCMP API 69 voids 20
Simple Order API 48 FDI Australia
ERROR decision 43 authorizations 9
errors captures 13
described for SCMP API 65 card types 7
described for Simple Order API 43 credits 17
reason codes (Simple Order API) 283 CVNs 27
reply flags (SCMP API) 287 MasterCard SecureCode
simulating during testing 171 SCMP API 151
example code Simple Order API 107
SCMP API 68 reconciliation 31
Simple Order API 251 recurring payments
exchange rates SCMP API 163
SCMP API 150 Simple Order API 119
Simple Order API 106 verbal authorizations 30
expiration dates for recurring payments Verified by Visa
SCMP API 163 SCMP API 151
Simple Order API 119 Simple Order API 107
expiration of authorizations 308 voids 20
Extended AVS 26

316 CyberSource Corporation


Index

FDI Global FDMS Nashville


$0 authorizations authorizations 9
SCMP API 126 automatic authorization reversals 14
Simple Order API 82 AVS 24
authorizations 9 bill payments with Visa
automatic authorization reversals 14 SCMP API 128
AVS 24 Simple Order API 84
bill payments with Visa captures 13
SCMP API 128 card types 7
Simple Order API 84 credits 17
captures 13 CVNs 27
card types 7 full authorization reversals 12
credits 17 MasterCard SecureCode
CVNs 27 SCMP API 151
dynamic currency conversion Simple Order API 107
SCMP API 132 prepaid cards
Simple Order API 88 SCMP API 127
MasterCard SecureCode Simple Order API 83
SCMP API 151 reconciliation 31
Simple Order API 107 recurring payments
merchant descriptors SCMP API 163
SCMP API 144 Simple Order API 119
Simple Order API 100 verbal authorizations 30
reconciliation 31 Verified by Visa
recurring payments SCMP API 151
SCMP API 163 Simple Order API 107
Simple Order API 119 voids 20
verbal authorizations 30
Verified by Visa
SCMP API 151
Simple Order API 107
voids 20

Credit Card Services Implementation Guide • June 2009 317


G–G

FDMS South follow-on credits


$0 authorizations SCMP API 77
SCMP API 126 Simple Order API 55
Simple Order API 82 follow-on services
authorizations 9 requesting with SCMP API 65
AVS 24 requesting with Simple Order API
captures 13 42
card types 7 forced captures
credits 17 SCMP API 139
CVNs 28 Simple Order API 95
dynamic currency conversion foreign exchange service
SCMP API 132 SCMP API 150
Simple Order API 88 Simple Order API 106
forced captures fraudulent transactions 307
SCMP API 139 freight charges
Simple Order API 95 SCMP API 62
full authorization reversals 12 Simple Order API 40
MasterCard SecureCode frequently asked questions 307
SCMP API 151 fresh authorization 15
Simple Order API 107 full authorization reversals
merchant descriptors described 12
SCMP API 144 See also ccAuthReversalService
Simple Order API 100 See also ics_auth_reversal
prepaid cards
SCMP API 127 G
Simple Order API 83
reconciliation 31 GE Capital
recurring payments authorizations 9
SCMP API 163 AVS 25
Simple Order API 119 captures 13
verbal authorizations 30 card types 7
Verified by Visa credits 17
SCMP API 151 CVNs 28
Simple Order API 107 full authorization reversals 12
voids 20 reconciliation 31
fields in the SCMP API recurring payments
offer-level 237 SCMP API 163
replies 240 Simple Order API 119
requests 214 verbal authorizations 30
special characters 213 voids 20
fields in the Simple Order API gift cards
invalid 45 SCMP API 127
missing 45 Simple Order API 83
replies 203
requests 174
special characters 173

318 CyberSource Corporation


Index

Global Payment Service GPN, continued


authorizations 9 interchange optimization 15
AVS 24 JCB J/Secure
bank card reversals 299 SCMP API 151
captures 13 Simple Order API 107
card types 7 MasterCard SecureCode
credits 17 SCMP API 151
CVNs 27 Simple Order API 107
described 3 merchant descriptors
MasterCard SecureCode SCMP API 144
SCMP API 151 Simple Order API 100
Simple Order API 107 reconciliation 31
merchant descriptors recurring payments
SCMP API 144 SCMP API 163
Simple Order API 100 Simple Order API 119
reconciliation 31 verbal authorizations 30
recurring payments Verified by Visa
SCMP API 163 SCMP API 151
Simple Order API 119 Simple Order API 107
Verified by Visa voids 20
SCMP API 151 grand total amounts
Simple Order API 107 SCMP API 62
GMT Simple Order API 40
data type 213 guaranteed exchange rates
Simple Order API 203 SCMP API 150
going live 171 Simple Order API 106
GPN
$0 authorizations H
SCMP API 126
Simple Order API 82 HBoS
authorizations 9 authorizations 9
AVS 25 AVS 25
bill payments with Visa captures 13
SCMP API 128 card types 7
Simple Order API 84 credits 17
captures 13 CVNs 28
card types 7 full authorization reversals 12
credits 17 reconciliation 31
CVNs 28 recurring payments
forced captures SCMP API 163
SCMP API 139 Simple Order API 119
Simple Order API 95 verbal authorizations 30
full authorization reversals 12 voids 20

Credit Card Services Implementation Guide • June 2009 319


I–L

HSBC ics_rmsg reply field


authorizations 9 introduced 65
AVS 25 ics_void
captures 13 described 79
card types 7 requested as a follow-on service 65
credits 17 required fields 79
CVNs 28 voids 20
MasterCard SecureCode identification numbers 6
SCMP API 151 identifiers
Simple Order API 107 SCMP API 67
reconciliation 31 Simple Order API 46
recurring payments interchange fees 5
SCMP API 163 interchange optimization 15
Simple Order API 119 ISO-8859-1 60
verbal authorizations 30 issuer encryption. See encoded account
Verified by Visa numbers
SCMP API 151 issuing banks 5
Simple Order API 107
voids 20 J

I J/Secure
SCMP API 151
ics_auth Simple Order API 107
authorizations 9 Japanese payment options
described 68 SCMP API 140
requesting with ics_bill 70 Simple Order API 96
required fields 71 JCB J/Secure
ics_auth_reversal SCMP API 151
described 72 Simple Order API 107
full authorization reversals 12
requested as a follow-on service 65 L
required fields 73
ics_bill Latin American Processing
captures 13 authorizations 9
described 73 AVS 24
requested as a follow-on service 65 captures 13
requesting with ics_auth 70 card types 7
required fields 75 credits 17
ics_credit CVNs 27
credits 17 full authorization reversals 12
described 76 MasterCard SecureCode
requested as a follow-on service 65 SCMP API 151
required fields 78 Simple Order API 107
ics_rcode reply field reconciliation 31
introduced 65 verbal authorizations 30
ics_rflag reply field
introduced 65

320 CyberSource Corporation


Index

Latin American Processing, continued Lynk


Verified by Visa authorizations 9
SCMP API 151 AVS 25
Simple Order API 107 captures 13
voids 20 card types 8
Latin-1 60 credits 17
Level II CVNs 28
SCMP API 142 reconciliation 31
Simple Order API 98 verbal authorizations 30
Level III
SCMP API 142 M
Simple Order API 98
Lloyds-OmniPay Maestro (UK Domestic) cards
authorizations 9 SCMP API 143
AVS 25 Simple Order API 99
captures 13 mail order/telephone order (MOTO) 4
card types 8 MasterCard
credits 17 alliance with Diners Club 3
CVNs 28 SecureCode
full authorization reversals 13 SCMP API 151
reconciliation 31 Simple Order API 107
recurring payments trade association 5
SCMP API 163 merchant banks 4
Simple Order API 119 merchant descriptors
verbal authorizations 30 SCMP API 144
voids 20 Simple Order API 100
LloydsTSB Cardnet merchant IDs 307
authorizations 9 merchant reference codes
AVS 25 SCMP API 67
captures 13 Simple Order API 46
card types 8 micropayments
cash advances SCMP API 150
SCMP API 129 Simple Order API 106
Simple Order API 85 MOTO 4
credits 17 multi-currency
CVNs 28 SCMP API 150
full authorization reversals 13 Simple Order API 106
reconciliation 31
recurring payments N
SCMP API 163
Simple Order API 119 name-value pairs for the Simple Order
verbal authorizations 30 API 35
voids 20

Credit Card Services Implementation Guide • June 2009 321


O–R

O Payment Submission Detail Report 31


payment types 2
offer-level fields 237 Paymentech. See Chase Paymentech
OmniPay. See Lloyds-OmniPay Solutions
OmniPay-Ireland PIN-less debit cards 2
$0 authorizations POS transactions
SCMP API 126 SCMP API 167
Simple Order API 82 Simple Order API 123
authorizations 9 prepaid cards
automatic authorization reversals 14 SCMP API 127
AVS 25 Simple Order API 83
bill payments with Visa private label cards 2
SCMP API 128 processors 6
Simple Order API 84 procurement cards. See Level II
captures 13 product codes
card types 8 described 297
credits 17 SCMP API 62
CVNs 28 Simple Order API 40
MasterCard SecureCode profile IDs
SCMP API 151 SCMP API 235
Simple Order API 107 Simple Order API 199
merchant descriptors profiles
SCMP API 144 SCMP API 131
Simple Order API 100 Simple Order API 87
reconciliation 31 purchasing cards. See Level II and Level
recurring payments III
SCMP API 163
Simple Order API 119
Verified by Visa
R
SCMP API 151 reason codes (Simple Order API) 283
Simple Order API 107 reconciliation
voids 20 described 31
open to buy 9 for captures
order tracking SCMP API 75
SCMP API 67 Simple Order API 54
Simple Order API 46 for credits
SCMP API 77
P Simple Order API 56
reconciliation IDs 46
partial authorization reversals 14 recurring billing. See customer profiles
partial capture 16 recurring payments
PayEase China Processing 8 SCMP API 163
payer authentication Simple Order API 119
SCMP API 151 recurring profiles. See customer profiles
Simple Order API 107 refunds. See credits
Payment Batch Detail Report 31 REJECT decision 43
Payment Events Report 31
payment processors 6

322 CyberSource Corporation


Index

replacement dates for recurring secure data. See customer profiles


payments SecureCode
SCMP API 163 SCMP API 151
Simple Order API 119 Simple Order API 107
reply fields settlements, described 13
SCMP API 240 shipping and handling
Simple Order API 203 SCMP API 62
reply flags (SCMP API) 287 Simple Order API 40
request fields Simple Order API
SCMP API 214 fields 173
Simple Order API 174 introduction 33
request IDs reason codes 283
and captures requesting transactions with 33
SCMP API 73 SOAP 33
Simple Order API 52 soft descriptors. See merchant
and follow-on credits descriptors
SCMP API 77 software, updating 22
Simple Order API 55 Solo cards
and full authorization reversals SCMP API 143
SCMP API 72 Simple Order API 99
Simple Order API 51 special characters
and voids SCMP API 213
SCMP API 79 Simple Order API 173
Simple Order API 57 split dial/route. See forced captures
request tokens stand-alone credits
SCMP API 60 Simple Order API 56
Simple Order API 38 Stored Value redeem service 76
retail POS transactions Streamline
SCMP API 167 authorizations 9
Simple Order API 123 AVS 25
reversals, bank card 299 captures 13
reversing authorizations 12 card types 8
REVIEW decision 44 credits 17
CVNs 28
S full authorization reversals 13
MasterCard SecureCode
sample code SCMP API 151
SCMP API 68 Simple Order API 107
Simple Order API 251 reconciliation 31
SCMP API recurring payments
fields 213 SCMP API 163
introduction 59 Simple Order API 119
reply flags 287 verbal authorizations 30
requesting transactions with 59 Verified by Visa
SDKs. See clients SCMP API 151
secure data Simple Order API 107
SCMP API 131 voids 20
Simple Order API 87

Credit Card Services Implementation Guide • June 2009 323


T–V

subscription IDs TSYS Acquiring Solutions, continued


SCMP API 235 JCB J/Secure
Simple Order API 199 SCMP API 151
subscriptions Simple Order API 107
SCMP API 131 MasterCard SecureCode
Simple Order API 87 SCMP API 151
Switch cards. See Maestro (UK Simple Order API 107
Domestic) cards reconciliation 31
recurring payments
T SCMP API 163
Simple Order API 119
TAA fields verbal authorizations 30
SCMP API 144 Verified by Visa
Simple Order API 100 SCMP API 151
tax Simple Order API 107
SCMP API 62 voids 20
Simple Order API 40 Type II cards. See Level II
test server 169
testing your system 22 U
procedure 169
time formats UATP
SCMP API 213 authorizations 9
Simple Order API 203 captures 13
tracking orders card types 8
SCMP API 67 credits 17
Simple Order API 46 reconciliation 31
trade associations 5 verbal authorizations 30
Transaction Advice Addendum fields. voids 20
See TAA fields UCAF 107
transaction reference numbers 67 Universal Cardholder Authentication
TSYS Acquiring Solutions Field 107
$0 authorizations updating software 22
SCMP API 126 UTC
Simple Order API 82 data type definition 213
authorizations 9 in authorization reply 203
AVS 25 UTF-8 34
bill payments with Visa
SCMP API 128 V
Simple Order API 84
captures 13 verbal authorizations
card types 8 authorizations
credits 17 SCMP API 71
CVNs 28 Simple Order API 50
forced captures captures
SCMP API 139 SCMP API 74
Simple Order API 95 Simple Order API 53
full authorization reversals 13 described 29

324 CyberSource Corporation


Index

Verified by Visa
SCMP API 151
Simple Order API 107
version of Simple Order API 34
Visa
bill payments
SCMP API 128
Simple Order API 84
trade association 5
Verified by Visa
SCMP API 151
Simple Order API 107
Vital. See TSYS Acquiring Solutions
voids
described 20
See also ics_void
See also voidService
voidService 57
requested as a follow-on service 42
required fields 58
voids 20

W
WS Security 33

X
XML 35

Z
$0 authorizations
SCMP API 126
Simple Order API 82

Credit Card Services Implementation Guide • June 2009 325


326 CyberSource Corporation

You might also like