Professional Documents
Culture Documents
Implementation Guide
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.
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
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
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
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
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
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
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.
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.
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
• 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.
As a user of the CyberSource ICS services, you can use the Business Center, which offers a
graphical interface for various functions, including:
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
• 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.
Topics:
Acquiring (Merchant) Banks
Issuing (Consumer) Banks
Credit Card Associations
Payment Processors
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
• 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.
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.
Chase Paymentech Solutions Visa, MasterCard, American Express, Discover, Diners Club,
JCB, Carte Blanche, Carte Bleu, Carta Si, Maestro (UK
Domestic), Solo, private label cards
6 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services
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.
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
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.
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
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.
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.
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.
Reversing an Authorization
CyberSource supports full authorization reversals for these processors:
12 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services
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.
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.
OmniPay-Ireland Visa
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.
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.
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.
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.
Authorization
after within 96
Capture midnight hours
Issuing
Secure Internet Credit Bank
Company Connection
Representative Payment
Batch File
CyberSource Processor Capture Credit
Acquiring
Bank
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.
18 CyberSource Corporation
Chapter 1 Introduction to the Credit Card Services
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.
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.
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.
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
Topics:
Standard AVS
Enhanced AVS
Automated Address Verification Plus
Extended AVS
Standard AVS
The following table lists the processors and card types for which CyberSource returns
standard AVS results.
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 Latin American Processing Visa, MasterCard, American Express, Diners Club
24 CyberSource Corporation
Chapter 3 Basic Credit Card Features
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.
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.
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
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
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:
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:
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:
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:
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
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
• 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.
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 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.
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.
• 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.
<card>
<accountNumber> card_accountNumber
<expirationMonth> card_expirationMonth
<expirationYear> card_expirationYear
</card>
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
<item id="0">
<unitPrice> item_0_unitPrice
<quantity> item_0_quantity
</item>
<item id="1">
<unitPrice> item_1_unitPrice
<quantity> item_1_quantity
</item>
• 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
• 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
• 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.
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.
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
• 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.
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.
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.
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.
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.
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.
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:
46 CyberSource Corporation
Chapter 4 Payment Processing with the Simple Order API
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:
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.
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.
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.
Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 95.
• 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
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.
• 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:
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:
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.
Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 95.
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,
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.
• 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:
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:
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.
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.
• 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
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:
• voidService_run
• voidService_voidRequestID
• orderRequestToken
• merchantID
• merchantReferenceCode
See Appendix A, “Fields for the Simple Order API,” on page 173 for:
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
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
• 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.
• 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
• 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.
• 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
• 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.
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.
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
• 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.
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
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
<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 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.
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:
68 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API
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.
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.
70 CyberSource Corporation
Chapter 5 Payment Processing with the SCMP API
Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 139.
• bill_address1
• bill_city
• bill_country
• bill_state—required under certain conditions
• bill_zip—required under certain conditions
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.
• 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:
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
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:
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.
Important Do not confuse a verbal authorization with a forced capture. See “Forced
Captures” on page 139.
• 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.
• 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
See Appendix B, “Fields for the SCMP API,” on page 213 for:
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:
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.
• 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
• 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:
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
$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
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.
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:
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:
86 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API
Coupon Constraints
You cannot use coupons to do the following:
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
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.
88 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API
Topics:
Requirements and Limitations
Terminology
Procedure
Additional Information
• Tax calculation
• Authorization
• Capture
• Credit
Do not use Level II or Level III processing with DCC.
Terminology
Table 11 DCC Terminology
Term Definition
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
90 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API
Procedure
Merchant ID merchantID
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.
92 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API
Table 14 DCC Fields Required for the Authorization, Capture, and Credit Services
• 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.
• 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.
• 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
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 83.
96 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API
The following table lists the Simple Order API fields required for each payment option.
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.
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.
98 CyberSource Corporation
Chapter 6 Optional Features for the Simple Order API
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.
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.
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.
• 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.
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.
• 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 ( ` )
Merchant Descriptor
For an installment transaction, you must use one of the following formats for the
merchant descriptor:
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:
• PCCCCCCCCCCCC
• NNN-NNN-NNNN
• NNN-NNN-NAAA
• NNN-NNN-AAAA
• NNN-AAAAAAA
where:
• N: Numeric
• P: Alpha
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.
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.
• 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.
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:
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.
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.
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.
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.
• 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.
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
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
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
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
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
• 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.
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
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.
Recurring Payments
Applicable services:
• Authorization
Supported processors:
• See the following table.
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.
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.
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.
Table 21 Processors That Support Replacement Expiration Dates for Recurring Payments
Table 21 Processors That Support Replacement Expiration Dates for Recurring Payments
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.
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.
Type II Cards
See “Level II Data” on page 98.
Verbal Authorizations
See “Verbal Authorizations: The Authorization” on page 50.
Verified by Visa
See “Payer Authentication” on page 107.
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
$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.
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.
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:
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:
Coupon Constraints
You cannot use coupons to do the following:
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
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.
Topics:
Requirements and Limitations
Terminology
Procedure
Additional Information
• Tax calculation
• Authorization
• Capture
• Credit
Do not use Level II or Level III processing with DCC.
Terminology
Table 22 DCC Terminology
Term Definition
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
Procedure
Merchant ID merchant_id
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.
Table 24 DCC Fields Required for the Authorization, Capture, and Credit Services
• 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.
• 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.
• 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 B, “Fields for the SCMP API,” on page 213.
• Examples—See “DCC Examples” on page 275.
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.
The following table lists the SCMP API fields required for each payment option.
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.
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.
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.
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.
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.
• 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.
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.
• 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 ( ` )
Merchant Descriptor
For an installment transaction, you must use one of the following formats for the
merchant descriptor:
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:
• PCCCCCCCCCCCC
• NNN-NNN-NNNN
• NNN-NNN-NAAA
• NNN-NNN-AAAA
• NNN-AAAAAAA
where:
• N: Numeric
• P: Alpha
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.
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.
• 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.
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:
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.
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.
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.
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.
• 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.
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
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
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
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
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
• 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.
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
Value and Requirements Request Field for the Get the Value from this
Authorization Service Payer Authentication Reply
Field
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.
Recurring Payments
Applicable services:
• Authorization
Supported processors:
• See the following table.
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.
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.
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.
Table 31 Processors That Support Replacement Expiration Dates for Recurring Payments
Table 31 Processors That Support Replacement Expiration Dates for Recurring Payments
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.
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.
Type II Cards
See “Level II Data” on page 142.
Verbal Authorizations
See “Verbal Authorizations: The Authorization” on page 71.
Verified by Visa
See “Payer Authentication” on page 151.
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
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.
Credit Card Type Test Account Number—remove spaces when sending to CyberSource
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
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.
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.
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.
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.
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
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_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_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
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.
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
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.
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
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)
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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.
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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
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
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
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
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_ 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
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
ccAuthService_ Payer authentication response status. For the ccAuthService String (1)
paresStatus 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.
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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_ 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.
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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)
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
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.
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
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.
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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.
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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.
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)
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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
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.
(1) Optional for a follow-on credit request, which must include ccCreditService_captureRequestID
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
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
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
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
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_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
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
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.
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
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
Reply Fields
Table 34 Reply Fields for the Simple Order API
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.
ccAuthReply_ Raw Verified by Visa response code sent ccAuthReply String (1)
cavvResponseCodeRaw directly from the processor. or
String (3)
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_ 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_ 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.
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.
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.
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.
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
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_ 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)
voidReply_currency Currency used for the order. Formatted voidReply String (5)
using the ISO currency codes.
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.
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.
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
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
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
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.
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_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
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
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].
(1) Optional for a follow-on credit request, which must include bill_request_id
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
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.
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)
(1) Optional for a follow-on credit request, which must include bill_request_id
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
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)
(1) Optional for a follow-on credit request, which must include bill_request_id
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_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)
(1) Optional for a follow-on credit request, which must include bill_request_id
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.
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
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.
(1) Optional for a follow-on credit request, which must include bill_request_id
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)
(1) Optional for a follow-on credit request, which must include bill_request_id
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
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
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
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.
(1) Optional for a follow-on credit request, which must include bill_request_id
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_id Your CyberSource merchant ID. Use the Required for all Credit String (30)
same merchant_id for evaluation, testing, Card Services.
and production.
(1) Optional for a follow-on credit request, which must include bill_request_id
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.
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
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
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
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
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.
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
Offer-Level Fields
Table 36 Offer-Level Fields for the SCMP API
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.)
• 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)
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)
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.
Reply Fields
Table 37 Reply Fields for the SCMP API
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.
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.
auth_cavv_response_ Raw Verified by Visa response code sent ics_auth String (1) or
code_raw directly from the processor. String (3)
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_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.
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_reversal_auth_ Error message sent directly from the credit ics_auth_reversal String (10)
response card company.
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_rmsg Message explaining the reply code auth_ ics_auth_reversal String (255)
reversal_rcode.
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.
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_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.
client_lib_version Information about the client library used to All Credit Card Services String (50)
request the transaction.
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_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.
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_ 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_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_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_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.
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.
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_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_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.
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
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>
... 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>
This appendix provides example requests and replies for the SCMP API.
Examples
Basic Credit Card Examples
DCC Examples
Asia-Mideast Processing Examples
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
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.
Reason
Description
Code
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.
Reason
Description
Code
209 American Express Card Identification Digits (CID) did not match.
Possible action: Request a different card or other form of payment.
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.
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.
Reason
Description
Code
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.
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.
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.
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.
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.
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.
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.
In the reply message for an authorization request, the address verification service (AVS)
code is returned in:
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.
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.
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.
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.
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.
T Partial match: Card member’s name does not match, but street address matches.
Returned only for the American Express card type.
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.
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.
4 No match: Address is not confirmed. Returned only for PayPal Express Checkout.
In the reply message for an authorization request, the card verification number (CVN)
code is returned in:
Code Description
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.
2 An unrecognized result code was returned by the processor for the card
verification response.
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.
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
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.
Chargebacks
If one of the following occurs:
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.
31 Error in Addition
53 Not as Described
56 Defective Merchandise
74 Late Presentment
82 Duplicate Processing
83 Non-Possession of Card
90 Non-Receipt of Merchandise
34 Duplicate Processing
42 Late Presentment
55 Non-Receipt of Merchandise
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.
Transaction history
Transaction Curr Amount Date
--------------------------------------------------------------
Original order amount USD XX.XX DD-MM-YYYY
--------------------------------------------------------------
Total 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
This appendix provides answers to questions that merchants often ask about Credit Card
Services.
• 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
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.
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
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
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
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