CellPoint Velocity's Foreign Exchange (FX) feature uses Direct Currency Conversion (DCC) to fetch foreign exchange rates from a third-party provider, supporting transactions in currencies a customer may prefer. This feature is applicable to an API integration for transactions using MasterCard or Visa, and it requires a partnership with a third-party FX provider.

Workflow

The workflow for FX is as follows:

Initialize request - The customer clicks the payment button, prompting the merchant's front-end application to send an Initialize request to the Velocity API.
Initialize response - The API checks available payment operations. It sends an Initialize response to the merchant that includes information on whether each card is eligible for DCC.
Card selection - The front-end application displays payment options to the customer. The customer enters their card number or selects a stored card, and the front-end application checks the Initialize response to determine whether that card is eligible for DCC.
FX OfferCriteria request - If the selected card is eligible for DCC, the front-end application sends an FX OfferCriteria request to the API to get exchange rates for the card's currency.
FX OfferCriteria response - The API gets exchange rates from the third-party provider and sends them to the front-end application in an FX OfferCriteria response.
DCC opt-in - The front-end application shows the option for DCC on the payment page, and the customer selects whether to opt in or opt out of DCC.
Authorize request - The front-end application uses the customer's selection to send an Authorize request to the API.
Authorize response - The API completes the payment authorization and sends an Authorize response.
Third party notification - The API informs the third-party provider of the transaction status. There may be several callbacks depending on third-party and merchant requirements.

Prerequisites

Set up a partnership with a third-party foreign currency exchange provider, such as Continuum.
Work with your CellPoint Digital sales representative or account manager to sign up, set up your test account, and access your testing credentials.

Integration

Complete the following steps to use Foreign Exchange (FX) with your integration.

1. Initialize a payment

Endpoint: /mpoint/initialize-payment
Method: POST

Once the page has loaded, send a POST request to the /mpoint/initialize-payment endpoint of the CellPoint Velocity API. For more information, see Initialize Payment.

Below is sample code for an Initialize request:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<initialize-payment account="111111" client-id="22222">
		<transaction order-no="CPM111" type-id="1">
			<amount country-id="403" currency-id="986">1200000</amount>
			<hmac>[String]</hmac>
		</transaction>
		<client-info language="en" platform="HTML5" profileid="" sdk-version="2.0.0" version="2.0.0">
			<mobile country-id="403" operator-id="40300">9881112222</mobile>
			<email>[email protected]</email>
			<customer-ref/>
			<ip/>
		</client-info>
	</initialize-payment>
</root>

The API sends an Initialize response like the sample code below. If an available payment option is eligible for DCC, its associated card element (within card or stored-cards) will contain the dcc attribute set to true:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<client-config account="111111" auto-capture="false" id="22222" mode="1" store-card="0">
		<name>CPD Demo</name>
	</client-config>
	<transaction order-no="CPM111" type-id="1">
		<amount country-id="403" currency-id="986">1200000</amount>
	</transaction>
	<cards>
		<card cvc-length="3" cvcmandatory="false" dcc="true" enabled="true" id="7" installment="0" max-length="19" min-length="13" payment-type="1" preferred="false" presentment-currency="false" processor-type="1" psp-id="-1" state-id="1" type-id="7">
			<name>Master Card</name>
			<prefixes>
				<prefix id="512">
					<min>2221</min>
					<max>2720</max>
				</prefix>
				<prefix id="513">
					<min>51</min>
					<max>55</max>
				</prefix>
			</prefixes>Master Card</card>
	</cards>
	<stored-cards>
		<card cvc-length="3" cvcmandatory="false" dcc="true" id="8" preferred="true" psp-id="2" type-id="1">
			<name>myVisa</name>
			<card-number-mask>4711 10** **** 0000</card-number-mask>
			<expiry>06/29</expiry>
		</card>
	</stored-cards>
</root>

2. Check selected payment method

Take the available payment options listed in the Initialize response and display them to the customer. When the customer enters their card number or selects a stored card, check the Initialize response to determine whether that card is eligible for DCC.

If the card is eligible, proceed to step 3. If it is not eligible, send an Authorize request without foreign exchange data; see Authorize Payment for more information.

3. Get exchange rates

Endpoint: /foreignexchange/offers
Method: GET

Send an FX OfferCriteria (/foreignexchange/offers) request to get exchange rates for the card's currency.

Please note:

All cards - In the card-type-id, include the value received in card: id in the Initialize response.
New cards - If the customer is using a new card, include the card-number element with the full card number, and do not include card-id.
Stored cards - If the customer is using a stored card, do not include card-number. Instead, include the card-id element with the card's unique ID number in the storage system. Find this value in the Initialize response, in stored-cards: card: id.

Below is a code sample of an FX OfferCriteria request:

<?xml version="1.0" encoding="UTF-8"?>
<OfferCriteria>
	<order-number>CPM111</order-number>
	<card-number>5194630000000000</card-number>
	<card-type-id>8</card-type-id>
	<country-id>403</country-id>
	<account>111111</account>
	<card-id/>
	<sale-amount>
		<price>1200000</price>
		<currency>BRL</currency>
	</sale-amount>
	<transaction-id>3333333</transaction-id>
	<client-id>22222</client-id>
	<client-info app-id="1" app-version="5.01" language="en" platform="HTML5" profileid="" sdk-version="2.0.0" version="2.0.0">
		<mobile country-id="403" operator-id="40300">9881112222</mobile>
		<email>[email protected]</email>
		<customer-ref/>
		<ip/>
	</client-info>
</OfferCriteria>

Expand this section for FX OfferCriteria Request Parameters.

The description of the request parameters is as follows:

Parameter	Type	Required	Description
version	Integer	Yes	The version of the API or app that sends the request.
order-number	Integer	Yes	A unique identification number of an order. Note: For travel merchants, it can be the PNR number.
partial-card-number	Integer	Yes	The first 12 digits of a card number.
card-type-id	Integer	Yes	An identification number to know the type of card used for a transaction. For example, 7 indicates Mastercard.
country-id	Integer	Yes	The CPD-specific country code from which a customer searches for a product or service.
sale-amount	Object	Yes	The amount and currency against which you want to offer exchange price.
transaction-id	String	Yes	CPD transaction ID for which status is being requested
client-id	Integer	Yes	A unique ID configured for a merchant on the Velocity POP.

client-info parameters:

Parameter	Type	Required	Description
language	String	Yes	The language that Velocity uses as default when translating the payment pages. Velocity uses a default language set by a merchant if this parameter is omitted. Note: Velocity language codes are based upon the ISO- 639-1 standard. Refer to http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
version	String	Yes	The version of the API or app that sends the request.
platform	String	Yes	The platform from which the request is sent. For example, web, iOS, Android, HTML, B2B, and B2C.
mobile operator-id	Integer	No	The ID of a customer’s mobile network operator. CPD recommends including this parameter in a request to ensure that Velocity interacts with the operator accurately.
country-id	Integer	Yes	The CPD-specific country code provided to merchants on request.
client-id	Integer	Yes	A unique ID configured for a merchant on the Velocity POP.
device-id	String	No	The device ID of a customer’s device. Note: Device ID is optional for a web channel.
customer-reference	Integer	Yes	A unique reference number used for customer identification.

If the card is eligible for DCC, the API generates a foreign-exchange-offer-id, and it sends a response containing an array of payment currency offers available for that card.

Please note the following about the FX OfferCriteria response:

sale-amount defines the transaction amount in the original currency.
exchange-amount defines the transaction amount in the converted currency if the offered exchange rate is accepted.
The margin (margin-percentage) is included in the offered exchange rate (offered-exchange-rate).
default-opt-in defines whether the target currency is shown to the customer as preselected. CellPoint Digital recommends leaving this as false, where nothing is shown as preselected.

See the sample FX OfferCriteria response code below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<Offer>
		<foreign-exchange-offer-id>277777</foreign-exchange-offer-id>
		<default-opt-in>false</default-opt-in>
		<payment-currency-offers>
			<payment-currency-offer>
				<exchange-amount>
					<price>222541</price>
					<currency>USD</currency>
				</exchange-amount>
				<exchange-currency>
					<iso-alpha-code>USD</iso-alpha-code>
					<iso-numeric-code>840</iso-numeric-code>
					<exponent>2</exponent>
				</exchange-currency>
				<sale-amount>
					<price>1200000</price>
					<currency>BRL</currency>
				</sale-amount>
				<sale-currency>
					<iso-alpha-code>BRL</iso-alpha-code>
					<iso-numeric-code>986</iso-numeric-code>
					<exponent>2</exponent>
				</sale-currency>
				<offered-exchange-rate>0.1854509</offered-exchange-rate>
				<validation-hmac>[String]</validation-hmac>
				<display-margin-percentage>5</display-margin-percentage>
				<rate-source>Worldpay</rate-source>
				<pcs-external-ref>QZ7QQ7DVYQQQQQQ</pcs-external-ref>
			</payment-currency-offer>
		</payment-currency-offers>
	</Offer>
</root>

Expand this section for FX OfferCriteria Response Parameters.

The description of the response parameters is as follows:

Parameter	Type	Required	Description
foreign-exchange-offer-id	Integer	Yes	A unique CPD-specific identification number for an offer.
default-opt-in	Boolean	No	A Boolean value to show if DCC services is provided to a customer.
payment-currency-offers	Array	Yes	A list of exchange offers for a currency.
payment-currency-offer	Object	Yes	An object of payment currency offer.
exchange-amount	Object	Yes	The exchange amount offered against a currency.
price	Integer	Yes	The price offered against a currency in which a customer makes payment.
currency	String	Yes	The currency for which a price is offered.
exchange-currency	String	Yes	The currency offered against the card currency.
iso-alpha-code	String	Yes	The three-letter alphabetic code for a currency.
iso-numeric-code	Integer	Yes	The two-letter numeric code for a country.
exponent	Integer	Yes	The number of decimals points shown for a currency.
offered-exchange-rate	Float	Yes	The rate at which a currency is offered for a price.
validation-hmac	Alpha numeric string	Yes	The Message Authentication Code is calculated by creating a SHA512 hash comprising the following input fields in the listed order: • clientid • account • orderid • callback-url • amount • auth-url • customer-ref • auth-token • email • mobile • [SALT] Using MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The [SALT] is the merchant's shared secret used to ensure that the provided MAC is unique.

4. Request authorization

Endpoint: /mpoint/authorize-payment
Method: POST

Display the option for DCC on the payment page and let the customer select whether to opt in or opt out of DCC. Use the customer's selection to construct and send an Authorize request; see Authorize Payment for more information on this request.

Note the following about this Authorize request:

All FX Auth requests - In transaction: id, use the transaction-id value used in the FX OfferCriteria request.
Opt In - If the customer opts in to DCC:
- Include conversion-rate, using the offered-exchange-rate value from the FX OfferCriteria response that the customer has chosen.
- amount should define the transaction amount in the new/converted currency.
Opt Out - If the customer opts out of DCC, amount should define the transaction amount in the original currency.

Authorize Request: Opt In

If the customer opts in to DCC, send an Authorize request like the sample code below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<authorize-payment account="111111" client-id="22222">
		<transaction id="3333333" store-card="false" type-id="10091">
			<card type-id="8">
				<amount country-id="403" currency-id="840">222541</amount>
				<cvc>123</cvc>
				<card-holder-name>CellPointMobile</card-holder-name>
				<card-number>4999777777777777</card-number>
				<expiry>10/26</expiry>
				<address/>
			</card>
			<hmac>[String]</hmac>
			<foreign-exchange-info>
				<id>279937</id>
				<service-type-id>11</service-type-id>
				<conversion-rate>0.1854509</conversion-rate>
				<sale-currencyid>986</sale-currencyid>
				<sale-amount>1200000</sale-amount>
			</foreign-exchange-info>
		</transaction>
		<client-info language="en" platform="HTML5" profileid="" sdk-version="2.0.0" version="2.0.0">
			<mobile country-id="403" operator-id="40300">9881112222</mobile>
			<email>[email protected]</email>
			<customer-ref/>
			<ip/>
		</client-info>
	</authorize-payment>
</root>

Authorize Request: Opt Out

If the customer opts out of DCC, send an Authorize request like the sample code below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<authorize-payment account="111111" client-id="22222">
		<transaction id="3333333" type-id="10091">
			<card type-id="8">
				<amount country-id="986">1200000</amount>
				<card-holder-name>CellPointMobile</card-holder-name>
				<card-number>4999777777777777</card-number>
				<expiry>10/26</expiry>
			</card>
			<foreign-exchange-info>
				<id>279937</id>
				<service-type-id>12</service-type-id>
			</foreign-exchange-info>
		</transaction>
		<client-info language="en" platform="HTML5" profileid="" sdk-version="2.0.0" version="2.0.0">
			<mobile country-id="403" operator-id="40300">9881112222</mobile>
			<email>[email protected]</email>
			<customer-ref/>
			<ip/>
		</client-info>
	</authorize-payment>
</root>

5. Confirm success

Velocity API returns an Authorize response confirming whether the transaction authorization succeeded or failed. The example below shows a sample Authorize success response:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<status code="2000" sub-code="2000101">Payment authorized</status>
</root>

See Authorize Payment for more information about this response.