Requesting Services

In Variable Price Mode, use fxRatesService to obtain current exchange rate quotes. See Multicurrency Service: fxRatesService for the API information for the service. For each quote, fxRatesService returns the quote ID and additional information.

In your authorization request:

■	Set ccAuthService_fxQuoteID to the relevant quote ID.

■	The item’s unit price must be in the customer’s local currency.

■	Set fundingTotals_grandTotalAmount to the total amount of the authorization in the funding currency.

Use the guidelines in Calculating a Unit Price when calculating the amounts.

In the authorization reply, CyberSource returns:

■	The quote information in several fields that begin with ccAuthReply_fxQuote.

■	The total amount of the authorization in both currencies:

●	ccAuthReply_amount is in the customer’s local currency.

●	ccAuthReply_fundingTotals_grandTotalAmount is in your funding currency.

Calculating a Unit Price

To calculate the product’s unit price in the customer’s local currency:

Step 1

Multiply the unit price in the funding currency by the exchange rate.

Step 2

Round up.

Round up when converting a unit price 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 Unit Price

Given values for the example:

■	The product’s unit price in the funding currency (U.S. dollars) = $2.00.

■	The exchange rate (ccAuthReply_fxQuoteRate) = 0.7523 British pound per U.S. dollar.

To calculate the product’s unit price in British pounds:

Step 1

Multiply the unit price 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 (fundingTotals_grandTotalAmount) when you have multiple items:

Step 1

Convert each item’s unit price to the customer’s local currency.

Step 2

Sum the unit prices of all the items 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 item’s unit price separately before calculating the sum of the items. 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:

■	item_0 unit price in U.S. dollars = $2.00

■	item_1 unit price in U.S. dollars = $9.00

■	The exchange rate (ccAuthReply_fxQuoteRate) = 0.7523 British pound per U.S. dollar.

To calculate the total funding amount:

Step 1

Convert each item’s unit price to the customer’s local currency:

item_0: 2.00 * 0.7523 = 1.5046. Round up to 1.51 British pounds.

item_1: 9.00 * 0.7523 = 6.7707. Round up to 6.78 British pounds.

Step 2

Sum the unit prices of all the items 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 purchaseTotals_currency to the customer’s local currency.

■	The item’s unit price 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 fundingTotals_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 ccAuthReply_fxQuote.

■	The total amount of the authorization in both currencies:

●	ccAuthReply_amount is in the customer’s local currency.

●	ccAuthReply_fundingTotals_grandTotalAmount 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 ccCaptureReply_fxQuote.

■	The total amount of the capture in both currencies:

●	ccCaptureReply_amount is in the customer’s local currency.

●	ccCaptureReply_fundingTotals_grandTotalAmount 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 fundingTotals_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 ccCreditReply_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 Simple Order API.

Request Fields

Table 1

Request Fields for Authorizations, Captures, and Credits

Data Type & Length

ccAuthService_fxQuoteID

Exchange rate quote identifier that was returned by the multicurrency service. See Multicurrency Service: fxRatesService.

ccAuthService (O)

String (30)

fundingTotals_currency

Funding currency for the request. Overrides the funding currency that is associated with your CyberSource merchant ID. Use the ISO currency codes.

ccAuthService (O)

ccCreditService (O)

String (5)

fundingTotals_grandTotalAmount

Total amount of the authorization in the funding currency. See Calculating a Unit Price for information about calculating this amount.

This field is required if ccAuthService_fxQuoteID is included in the request.

ccAuthService (See description)

String (15)

purchaseTotals_currency

The customer’s local currency.

ccAuthService (R)

ccCaptureService (R)

ccCreditService (R)

String (5)

Reply Fields

Table 2

Reply Fields for Authorizations, Captures, and Credits

Data Type & Length

Total amount of the authorization in the customer’s local currency.

ccAuthReply

String (15)

ccAuthReply_fundingTotals_currency

Funding currency used for the authorization.

ccAuthReply

String (5)

ccAuthReply_fundingTotals_grandTotalAmount

Total amount of the authorization in your funding currency.

ccAuthReply

String (15)

ccAuthReply_fxQuoteExpiration
DateTime

Expiration date and time of the exchange rate quote.

ccAuthReply

String (20)

ccAuthReply_fxQuoteID

Exchange rate quote identifier associated with the authorization. See Multicurrency Service: fxRatesService for more information.

ccAuthReply

String (30)

ccAuthReply_fxQuoteRate

Exchange rate for the quote.

ccAuthReply

String (30)

ccAuthReply_fxQuoteType

Type of quote. Indicates a single use or recurring usage for a subscription.

ccAuthReply

String (10)

ccCaptureReply_amount

Total amount of the capture in the customer’s local currency.

ccCaptureReply

String (15)

ccCaptureReply_fundingTotals_currency

Funding currency used for the capture.

ccCaptureReply

String (5)

ccCaptureReply_fundingTotals_grandTotalAmount

Total amount of the capture in your funding currency.

ccCaptureReply

String (15)

ccCaptureReply_fxQuoteExpiration
DateTime

Expiration date and time of the exchange rate quote.

ccCaptureReply

String (20)

ccCaptureReply_fxQuoteID

Exchange rate quote identifier associated with the capture.

ccCaptureReply

String (30)

ccCaptureReply_fxQuoteRate

Exchange rate for the quote.

ccCaptureReply

String (30)

ccCaptureReply_fxQuoteType

Type of quote. Indicates a single use or recurring usage for a subscription.

ccCaptureReply

String (10)

Multicurrency Service: fxRatesService

Use fxRatesService 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 fxRatesReply_quote_0_id, fxRatesReply_quote_1_id, and fxRatesReply_quote_2_id.

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 fxRatesService, do not request any other CyberSource services.

Request Fields for the Multicurrency Service

Table 3

Request Fields for the Multicurrency Service

Data Type & Length

Whether to include fxRatesService in your request. Possible values: