Requesting Services
Variable Price Mode
In Variable Price Mode, use the ics_fxrates service to obtain current exchange rate quotes. See Multicurrency Service: ics_fxrates for the API information for the service. For each quote, ics_fxrates returns the quote ID and additional information.
In your authorization request:
■
Set fxrates_quote_id to the relevant quote ID.
■
The offer-level amount must be in the customer’s local currency.
■
Set total_funding_amount to the total amount of the authorization in the funding currency.
Use the guidelines in Calculating an Amount when calculating the amounts.
In the authorization reply, CyberSource returns:
■
The quote information in several fields that begin with auth_fxrates_.
■
The total amount of the authorization in both currencies:
●
auth_auth_amount is in the customer’s local currency.
●
auth_total_funding_amount is in your funding currency.
Calculating an Amount
To calculate the product’s amount in the customer’s local currency:
Step 1
Multiply the amount in the funding currency by the exchange rate.
Step 2
Round up.
Round up when converting an amount to the customer’s local currency. Rounding up prevents discrepancies with E4X.
For all the supported currencies except Japanese yen, round to the second digit after the decimal point. For Japanese yen, round to the next whole number.
 
Example
Calculating a Product’s Amount
Given values for the example:
■
The product’s amount in the funding currency (U.S. dollars) = $2.00.
■
The exchange rate (auth_fxrates_quote_rate) = 0.7523 British pound per U.S. dollar.
To calculate the product’s amount in British pounds:
Step 1
Multiply the amount by the exchange rate:
2.00 * 0.7523 = 1.5046 British pounds.
Step 2
Round up:
Round 1.5046 up to 1.51 British pounds.
Calculating the Total Funding Amount
To calculate the total funding amount (total_funding_amount) when you have multiple offers:
Step 1
Convert each offer amount to the customer’s local currency.
Step 2
Sum the amounts of all the offers to get the total amount in the customer’s local currency.
Step 3
Convert the total amount in the customer’s local currency to the total amount in the funding currency.
Step 4
Round down.
Convert each offer amount separately before calculating the sum of the offers. Round down when converting an amount to the funding currency. Rounding down prevents calculation discrepancies with E4X.
 
Example
Calculating the Total Funding Amount
Given values for the example:
■
Offer0 amount in U.S. dollars = $2.00
■
Offer1 amount in U.S. dollars = $9.00
■
The exchange rate (auth_fxrates_quote_rate) = 0.7523 British pound per U.S. dollar.
To calculate the total funding amount:
Step 1
Convert each offer amount to the customer’s local currency:
Offer0: 2.00 * 0.7523 = 1.5046. Round up to 1.51 British pounds.
Offer1: 9.00 * 0.7523 = 6.7707. Round up to 6.78 British pounds.
Step 2
Sum the amounts of all the offers to get the total amount in the customer’s local currency:
1.51 + 6. 78 = 8.29 British pounds.
Step 3
Convert the total amount to the funding currency:
8.29 / 0.7523 = 11.0195 U.S. dollars.
Step 4
Round down to get the total funding amount:
Round 11.0195 down to 11.01 U.S. dollars.
Fixed Price Mode
In Fixed Price Mode, your authorization request does not need to include any new request fields specific to the multicurrency service. In your authorization request:
■
Set currency to the customer’s local currency.
■
The offer-level amount must be in the customer’s local currency.
CyberSource determines the appropriate quote ID based on the funding currency associated with your CyberSource merchant ID. If you are configured with E4X to use more than one funding currency, you can use the fxrates_funding_currency request field to specify a different funding currency for the order.
In the authorization reply, CyberSource returns:
■
The quote information in several fields that begin with auth_fxrates_.
■
The total amount of the authorization in both currencies:
●
auth_auth_amount is in the customer’s local currency.
●
auth_total_funding_amount is in your funding currency.
Captures
To capture an authorization that used the multicurrency service, you do not need to send any additional fields in your capture request. The quote ID for the capture is determined by E4X based on your agreement with them. Typically, a capture that occurs within five to seven days after the authorization will use the same quote ID that was used for the authorization.
In the capture reply, CyberSource returns:
■
The quote information in several fields that begin with bill_fxrates_.
■
The total amount of the authorization in both currencies:
●
bill_bill_amount is in the customer’s local currency.
●
bill_total_funding_amount is in your funding currency.
Credits
For stand-alone credits and follow-on credits, E4X determines the appropriate quote ID based on your agreement with them. The default funding currency is the one associated with your CyberSource merchant ID. If you are configured with E4X to use more than one funding currency, you can use the fxrates_funding_currency request field to specify a different funding currency for the transaction.
In the credit reply, CyberSource returns the credit amount in the customer’s local currency in the credit_credit_amount field. The reply does not include the quote ID information or the credit amount in your funding currency.
API Fields for Authorizations, Captures, and Credits
 
* 
When you send an authorization, capture, or credit request with multicurrency or funding data, you must include the basic fields required for every authorization, capture, or credit request. For information about these fields, see Credit Card Services Using the SCMP API.
Request Fields
Table 1
Request Fields for Authorizations, Captures, and Credits 
Field Name
Description
Used By
(Required/Optional)
Data Type & Length
currency
The customer’s local currency.
ics_auth (R)
ics_bill (R)
ics_credit (R)
String (5)
fxrates_funding_currency
Funding currency for the request. Overrides the funding currency that is associated with your CyberSource merchant ID. Use the ISO currency codes.
ics_auth (O)
ics_credit (O)
String (5)
fxrates_quote_id
Exchange rate quote identifier that was returned by the multicurrency service. See Multicurrency Service: ics_fxrates.
ics_auth (O)
String (30)
total_funding_
amount
Total amount of the authorization in the funding currency. See Calculating an Amount for information about calculating this amount.
This field is required if fxrates_quote_id is included in the request.
ics_auth (See description)
Decimal (15)
Reply Fields
Table 2
Reply Fields for Authorizations, Captures, and Credits 
Field Name
Description
Returned By
Data Type & Length
auth_auth_amount
Total amount of the authorization in the customer’s local currency.
ics_auth
Decimal (15)
auth_fxrates_funding_currency
Funding currency used for the authorization.
ics_auth
String (5)
auth_fxrates_
quote_exp
Expiration date and time of the exchange rate quote. The format is YYYY-MM-DDThhmmssZ. For example, 2012-08-11T224757Z is August 11, 2012 at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), which is also known as Greenwich Mean Time.
ics_auth
Date and time (20)
auth_fxrates_
quote_id
Exchange rate quote identifier associated with the authorization. See Multicurrency Service: ics_fxrates for more information.
ics_auth
String (30)
auth_fxrates_
quote_rate
Exchange rate for the quote.
ics_auth
Decimal (30)
auth_fxrates_
quote_type
Type of quote. Indicates a single use or recurring usage for a subscription.
ics_auth
String (10)
auth_total_
funding_amount
Total amount of the authorization in your funding currency.
ics_auth
Decimal (15)
bill_bill_amount
Total amount of the capture in the customer’s local currency.
ics_bill
Decimal (15)
bill_fxrates_
funding_currency
Funding currency used for the capture.
ics_bill
String (5)
bill_fxrates_
quote_exp
Expiration date and time of the exchange rate quote. The format is YYYY-MM-DDThhmmssZ. For example, 2012-08-11T224757Z is August 11, 2012 at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), which is also known as Greenwich Mean Time.
ics_bill
Date and time (20)
bill_fxrates_
quote_id
Exchange rate quote identifier associated with the capture.
ics_bill
String (30)
bill_fxrates_
quote_rate
Exchange rate for the quote.
ics_bill
Decimal (30)
bill_fxrates_
quote_type
Type of quote. Indicates a single use or recurring usage for a subscription.
ics_bill
String (10)
bill_total_
funding_amount
Total amount of the capture in your funding currency.
ics_bill
Decimal (15)
Multicurrency Service: ics_fxrates
Use the ics_fxrates service if you are using the Variable Price Mode. The service returns the current guaranteed exchange rates between your funding currency and other local currencies. Request the service at least once per hour to obtain the latest exchange rate information, which you store locally.
In the multicurrency service reply, CyberSource returns quote information for each currency pair. The quotes are numbered from 0 to N. For example, if the reply returns quote information for three currency pairs, the reply fields for the quote IDs will be fxrates_quote_id0, fxrates_quote_id1, and fxrates_quote_id2.
When a customer places an order, include the relevant quote ID in your authorization request. See Variable Price Mode for additional information about what to include in your authorization request.
In your request for ics_fxrates, do not request any other CyberSource services. There are no offer-level fields for ics_fxrates.
Request-Level Fields for the Multicurrency Service
Table 3
Request-Level Fields for the Multicurrency Service 
Field Name
Description
Required /Optional
Data Type & Length
ics_applications
ICS services to process for the request. To request the multicurrency service, set this value to ics_fxrates.
Required
String (255)
merchant_id
Your CyberSource merchant ID.
Required
String (30)
merchant_
ref_number
Merchant-generated order reference number or tracking number.
Required
String (50)
timeout
Number of seconds the system waits before the transaction times out.
Optional
Positive integer (3)
Reply Fields for the Multicurrency Service
Table 4
Reply Fields for the Multicurrency Service 
Field Name
Description
Data Type & Length
client_lib_version
Information about the client library used to request the transaction.
String (50)
fxrates_count
Number of quotes being returned in the reply.
Integer (5)
fxrates_currency0...N
Consumer’s local currency that was used for the quote.
String (5)
fxrates_funding_currency0...N
Funding currency used for the quote.
String (5)
fxrates_quote_date0...N
Date and time when quote was received. The format is YYYY-MM-DDThhmmssZ. For example, 2012-08-11T224757Z is August 11, 2012 at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), which is also known as Greenwich Mean Time.
Date and time (20)
fxrates_quote_exp0...N
Expiration date and time of the quote. The format is YYYY-MM-DDThhmmssZ. For example, 2012-08-11T224757Z is August 11, 2012 at 10:47:57 P.M. The T separates the date and the time. The Z indicates Coordinated Universal Time (UTC), which is also known as Greenwich Mean Time.
Date and time (20)
fxrates_quote_id0...N
Quote ID for the currency pair.
String (30)
fxrates_quote_rate0...N
Exchange rate between the two currencies.
Decimal (30)
fxrates_quote_type0...N
Type of quote. Indicates a single use or recurring usage for a subscription.
String (10)
fxrates_rcode
One-digit code that indicates the ics_fxrates result. Possible values:
■
-1: An error occurred
■
0: The request was declined
■
1: The request was successful
Integer (1)
fxrates_rflag
One-word description of the ics_fxrates result.
String (50)
fxrates_rmsg
Message that explains the reply flag fxrates_rflag. Do not display this message to your customer and do not use this field to write an error handler.
String (255)
ics_rcode
One-digit code that indicates whether the entire request was successful. Possible values:
■
-1: An error occurred
■
0: The request was declined
■
1: The request was successful
Integer (1)
ics_rflag
One-word description of the result of the entire request.
String (50)
ics_rmsg
Message that explains the reply flag ics_rflag. Do not display this message to your customer and do not use this field to write an error handler.
String (255)
merchant_ref_number
Order reference or tracking number that you provided in the request.
String (50)
request_id
Identifier for the request generated by the client.
String (26)
Reply Flags for the Multicurrency Service
Table 5
Reply Flags for the Multicurrency Service 
Reply Flag
Description
DINVALIDDATA
Data provided is not consistent with the request.
DMISSINGFIELD
The request is missing a required field.
ESYSTEM
System error. See the documentation for your CyberSource client for important information about how to handle system errors and retries.
ETIMEOUT
The request timed out.
SOK
The transaction was successful.