Chapter 7

Optional Features for the SCMP API

This chapter describes the optional features, including information about implementing them with the SCMP API:

$0 Authorizations

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

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.

American Express Prepaid Cards

American Express prepaid cards are processed using the same services as credit cards: authorization, capture, credit, and void. If there is a balance remaining on a prepaid card after an authorization, the authorization reply includes the balance amount in auth_account_balance. If there is not enough of a balance on the prepaid card for the requested transaction, it will be declined.

AVS Only

See $0 Authorizations .

Bill Me Later

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.

Bill Payments with Visa

Visa has a special Bill Payment program that allows customers to use their Visa cards to pay their bills. If you participate in this program, Visa requests that you flag the bill payments and credits so they can be easily identified. Although CyberSource accepts the bill payment indicator no matter which processor you are using, you should not use this indicator if you have not signed up with Visa to take part in the program.

Cash Advances

A cash advance allows a customer to use a credit card to purchase foreign currency or travelers checks. The currency the customer uses to fund the transactions must be British pounds.

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

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

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

•   Reverse a cash advance authorization.

•   Process a credit against a cash advance.

•   Create a recurring cash advance transaction.

•   Process a cash advance and airline data in the same transaction.

Coupons

You can offer customers virtual coupons at your Web store. CyberSource defines a coupon as a non-taxable, fixed amount deducted from an order total. Some examples of coupons you might offer are:

•   Register now and get $100 off your purchase!

•   Spring clearance! Get $10 off any order!

•   Thank you for ordering again within 30 days! We’re taking $5 off your order!

How Coupons are Processed

The following steps provide an overview of how CyberSource processes a request that includes a coupon:

1   All the line items are totaled and then the coupon amounts are deducted, resulting in an order subtotal.

2   If the request includes the Tax Calculation service, tax is calculated for all taxable line items to obtain a tax total. The Tax Calculation service ignores coupon line items because they are not taxable.

3   The order subtotal and tax total are added to obtain an order grand total.

4   The order grand total is used by other CyberSource services you included in the request, if any.

For example, if the coupon is included in an authorization request, the authorization service uses the order grand total as the amount to authorize.

Coupon Constraints

You cannot use coupons to do the following:

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

•   Apply a discount to a specific item before tax is calculated (if taxable)

•   Apply a percentage discount

Also, the total coupon amount cannot be greater than the order grand total. Precalculate your order totals before you send your requests to CyberSource so that you do not send orders with negative subtotals. CyberSource returns an error for orders with negative subtotals.

Customer Profiles

For the list of processors for which CyberSource supports customer profiles, 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.

Dynamic Currency Conversion (DCC)

The DCC service converts a foreign cardholder’s purchase from your local currency to the cardholder’s billing currency. This service can help you improve or create business relationships with customers who prefer to make purchases in their own currency.

Requirements and Limitations

The requirements for using the DCC service are:

•   Your local currency must be USD.

•   You must call CyberSource Customer Support to have your account configured to use DCC.

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

•   Tax calculation

•   Authorization

•   Capture

•   Credit

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

Terminology

Table 22 defines the DCC terminology.

Procedure

The following steps explain how to use DCC.

Step 1. Call the DCC Service

To call the DCC service, include the statement ics_applications=ics_dcc in your request:

•   Table 23 lists the fields required for the DCC service.

•   Table 24 lists the fields returned by the DCC service.

•   For descriptions of the required fields and to see which fields are optional, see Appendix B, Fields for the SCMP API.

•   Appendix D, Examples for the SCMP API includes examples for the DCC service.

Step 2. If Necessary: Handle Lack of Availability

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

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

•   Do not perform the rest of this procedure.

Step 3. Query the Customer

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

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

b   Display required DCC data to the customer. Check with your acquirer for data requirements.

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

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

Step 4. If Necessary: Proceed in the Local Currency

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

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

•   Continue with this procedure.

Step 5. Authorize the Payment

Table 25 lists the DCC fields required for the authorization, capture, and credit services. Appendix D, Examples for the SCMP API includes examples for these services with the DCC fields.

Note These request field names are not exactly the same as the names of the DCC service reply fields.

Step 6. Display DCC Data

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

Step 7. Capture the Authorization

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

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

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

Step 8. Optional: Credit the Payment

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

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

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

•   If this is a stand-alone credit, call the DCC service with the credit amount and then submit a credit request that includes the new DCC values.

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

Step 9. View the Transaction Results

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

•   Original amount

•   Converted amount

•   Exchange rate

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.

Encoded Account Numbers

Depending on what type of business you are in, you might be eligible to acquire from an issuing bank a list of the customers who have credit cards issued by that bank. The list does not include the customers’ credit card numbers, but instead includes encoded account numbers. Some processors refer to this type of program as issuer encryption and to the numbers as encrypted account numbers. This type of program is designed to protect customer data according to the provisions of the Graham Leach Bliley Act.

When processing a payment or credit for one of these customers, you use the encoded account number instead of the customer’s credit card number. The issuing bank then matches the encoded account number to the customer’s credit card number when processing the payment.

You must contact Chase Paymentech Solutions to obtain the information required for the Credit Card Encryption program and you must have a relationship with the bank in order to acquire their list of customers.

Forced Captures

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 .

Guaranteed Exchange Rates

See Multi-Currency Service .

Japanese Payment Options

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

•   Single bonus payment

•   Installment bonus payment

•   Installment payments (2 to 36 payments)

•   Revolving repayments

•   Combination of bonus payment and installment payments

Before using one of these payment options, you must sign a contract with your acquirer. Additionally, the funding cycle could differ when using these options. Contact your account provider for details about contracts and funding cycles.

Some acquirers might not support all of these payment options. Additionally, a card holder must sign a contract with an issuing bank before using one of these payment options. Therefore, not all card holders take advantage of these payment options. Confirm payment option availability with your account provider and the card holder before implementing one of these payment options.

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

Table 26 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 .

Level II Data

For a description of Level II data, including the list of processors and card types for which CyberSource supports Level II, see the Level II and Level III Processing Addendum, which is available at the Support Center.

Level III Data

For a description of Level III data, including the list of processors and card types for which CyberSource supports Level III, see the Level II and Level III Processing Addendum, which is available at the Support Center.

Maestro (UK Domestic) and Solo Cards

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 .

Merchant Descriptors

This feature allows you to submit a merchant descriptor that will appear 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

See the field descriptions in Table 36 for field sizes and additional information about these fields.

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

The following sections describe the fields supported by each processor.

American Express Direct

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

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

The merchant descriptor field must include your merchant DBA name.

The merchant descriptor contact field must contain the following information:

•   If you are submitting a retail request: Street address where your store or outlet is located.

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

American Express Phoenix

American Express Phoenix supports two types of fields:

•   Merchant descriptor fields, which include the descriptor field and the contact field. The contact field is for telephone or other contact information.

•   Transaction Advice Addendum (TAA) fields, which are four fields that further describe the purchase.

Table 27 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.

Chase Paymentech Solutions

Chase Paymentech Solutions supports two types of fields:

•   Merchant descriptor fields, which include the descriptor field and the contact field. The contact field is for telephone or other contact information. If you provide one of the merchant descriptor fields, you must provide both fields.

•   Transaction Advice Addendum (TAA) fields, which are four fields that further describe the purchase. You can use these fields only with American Express cards for Level II or non-Level II transactions.

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

Characters

In the merchant descriptor fields, question marks will be replaced with spaces.

Do not use the following punctuation characters in the merchant descriptor fields because they will cause the transaction to be rejected with Simple Order API reason code 233 or SCMP API reply flag DINVALIDDATA:

•   caret (^)

•   backslash (\)

•   open bracket ([)

•   close bracket (])

•   tilde (~)

•   accent ( ~ )

Merchant Descriptor

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

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

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

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

where <N> is the payment number and <M> is the total number of payments. For example, for the 3rd installment in a series of 7 payments, the PYMT<N>OF<M> portion of the merchant descriptor would be PYMT3OF7.

For other types of transactions, you must use one of the following formats for the merchant descriptor:

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

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

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

Merchant Descriptor Contact

You must use one of the following formats:

•   PCCCCCCCCCCCC

•   NNN-NNN-NNNN

•   NNN-NNN-NAAA

•   NNN-NNN-AAAA

•   NNN-AAAAAAA

where:

•   A: Alphanumeric (alpha or numeric)

•   C: Character (alpha or blank)

•   N: Numeric

•   P: Alpha

CyberSource Global Payment Service

The CyberSource Global Payment Service supports the merchant descriptor field.

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

FDI Global

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

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

Contents and Formats

The merchant descriptor field must contain the following information:

•   Your merchant DBA name.

•   If payments are being made in installments, the merchant descriptor field must also contain installment information such as "1 of 5" or "3 of 7."

The merchant descriptor contact field must contain the following information:

•   If you are submitting a retail request: City in which your store or outlet is located.

•   If you are submitting a non-retail request: Your customer service telephone number.

The merchant descriptor alternate contact field must contain alternate contact information such as a URL or email address.

Default Values

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

•   If you do not include a merchant descriptor in your request, CyberSource uses the merchant name from the merchant configuration database.

•   If you do not include a merchant descriptor contact in your request, the value that CyberSource uses depends on the type of transaction:

• For retail transactions, CyberSource uses the merchant city from the merchant configuration database.

• For non-retail transactions, CyberSource uses the merchant phone number from the merchant configuration database.

•   If you do not include a merchant descriptor alternate contact in your request, CyberSource uses the URL from the merchant configuration database.

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.

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

OmniPay-Ireland

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

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

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

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

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

Micropayments

Micropayments are payments for less than one dollar.

Note If you would like 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

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 starting to implement payer authentication, you must contact Customer Support to configure your account.

When you request an authorization using a supported card type and a supported processor, you can include pay