OfferCriteria | DCC
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 • 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.
Updated 3 months ago