Guides

Foreign Exchange (FX)

Integration Guide

Suggest Edits

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:

  1. Initialize request - The customer clicks the payment button, prompting the merchant's front-end application to send an Initialize request to the Velocity API.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. Authorize request - The front-end application uses the customer's selection to send an Authorize request to the API.
  8. Authorize response - The API completes the payment authorization and sends an Authorize response.
  9. 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 our Initialize API reference.

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>

For a description of response parameters, see Initialize.

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 in the API guide 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. For API reference information, see FX OfferCriteria in the Reference section of this site.

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>

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>

For a description of response parameters, see FX OfferCriteria.

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.

Note the following about the 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 our Authorize API reference for more information about this response.

Updated 11 days ago