Request

The foreignexchange API sends the following request:

<?xml version="1.0" encoding="UTF-8"?>
<OfferCriteria>
	<order-number>orderno</order-number>
<card-number>5194630000000000</card-number> 
<!— for new card, send PAN -->
	
<card-id>73931</card-id>  
<!-- additionally added for stored card This should come instead of card number-->


<!—For new card, send card-number and for send stored card card-id received in the initialize response -->


	<card-type-id>7</card-type-id> <!—card type id from initialize response -->
	<country-id>200</country-id>
	<sale-amount>
		<price>1050</price>
		<currency>USD</currency>
	</sale-amount>
<exchange-currencies>
         <exchange-currency>
            <iso-numeric-code>640</iso-numeric-code>
        </exchange-currency>
        <exchange-currency>
            <iso-numeric-code>684</iso-numeric-code>
        </exchange-currency>
   </exchange-currencies>
<!—This is applicable only for PCC flow. A list of currencies in which conversion can be done is shown in the exchange-currencies node. Send the list sent in the settlement-currencies node of the initialize response.-->
	<transaction-id>12</transaction-id>
	<client-id>10077</client-id>
	<client-info language="en" version="1.43" platform="html5">
		<mobile operator-id="60300" country-id="640">12345678</mobile>
		<email>[email id]</email>
		<client-id>{{clientid}}</client-id>
		<device-id>4ddc592f-fca5-48c5-befc-7286d4cc010e</device-id>
		<customer-reference>123</customer-reference>
	</client-info>
</OfferCriteria>

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.
exchange-currencies	String	No	An object that provides a list of currencies in which conversion can be done. The list is the same as that sent in the settlement-currencies node of the initialize response.

Response

The FX provider returns the following response only if the DCC value is true. The currency amount with which a payment is initialized is shown in the country-id. When customers enter their card details, the foreignexchange API shows all the offers (or exchange rates) available for that card. For example, a customer is making a transaction in USD, the API can show the price of a product or service in the BHD. The response contains an additional node of foreignexchangeinfo.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <Offer>
        <foreign-exchange-offer-id>182</foreign-exchange-offer-id>
        <default_opt_in >false</default_opt_in >
        <payment-currency-offers>
            <payment-currency-offer>
                <exchange-amount>
                    <price>4280</price>
                    <currency>BHD</currency>
                </exchange-amount>
                <exchange-currency>
                    <iso-alpha-code>BHD</iso-alpha-code>
                    <iso-numeric-code>48</iso-numeric-code>
                    <exponent>3</exponent>
                </exchange-currency>
                <sale_amount>
                   <price>11</price>
                   <currency>JPY</currency>
               </sale_amount>
             <sale_currency>
                 <iso_alpha_code>JPY</iso_alpha_code>
                 <iso_numeric_code>392</iso_numeric_code>
                 <exponent>0</exponent>
             </sale_currency>


               <validation-hmac>58c3ffe765886cc0fd7ebbc57f82d5071f8a22e3b58f5fafec6b34fd4209781aee3d47b20cb3a06bf600dae35a564280c02ac20b0fae6dc5552b58de4b97e7d4</validation-hmac>
<!—The fields highlighted in yellow are applicable only for DCC-->


          <offered-exchange-rate>0.407808</offered-exchange-rate>
                <margin-percentage>8.0</margin-percentage>
                <display-margin-percentage>8.0</display-margin-percentage>
                <rate-source>Reuters</rate-source>
            </payment-currency-offer>
        </payment-currency-offers>
    </Offer>
</root>

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.

🚧
Note: If you use foreignexchange API, you must use HMAC and amount for the Pay API from the response.