This page provides API reference information for Velocity API's FX OfferCriteria operation. For information on how to integrate this operation, see the Foreign Exchange (FX) guide.

Request

Endpoint: /foreignexchange/offers

Method: GET

Sample Request

See the sample below for an FX OfferCriteria request:

<?xml version="1.0" encoding="UTF-8"?>
<OfferCriteria>
    <order-number>CPM111</order-number>
    <card-number>5194630000000000</card-number>
    <card-id>73931</card-id>
    <card-type-id>8</card-type-id>
    <country-id>403</country-id>
    <account>111111</account>
    <sale-amount>
        <price>1200000</price>
        <currency>BRL</currency>
    </sale-amount>
    <transaction-id>3333333</transaction-id>
    <client-id>22222</client-id>
    <client-info language="en" sdk-version="2.0.0" version="2.0.0" platform="HTML5" profileid="" app-version="5.01" app-id="1">
        <mobile country-id="403" operator-id="40300">9881112222</mobile>
        <email>[email protected]</email>
        <customer-reference>123</customer-reference>
        <device-id>2E8888F78B88877BBFF6176313BD88D333333333</device-id>
        <ip>50f1:055b:f555:b5ad:5e5f:cf5d:5b55:515c</ip>
    </client-info>
</OfferCriteria>

Request Parameters

`OfferCriteria`

Please note:

The OfferCriteria element is required.
The OfferCriteria element has two children that are objects: sale-amount and client-info; see their descriptions below.
The rest of the OfferCriteria element's children have only text content.

Below are the children of OfferCriteria that only have text content:

Element	Requirement	Format of text content	Description of text content
`order-number`	Optional	String	A unique identification number of an order. Note: For travel merchants, this can be the passenger name record (PNR) number.
`card-number`	Conditional Requirement: Required for a transaction using a new card.	Integer	The full payment card number. Applicable to a transaction using a new card.
`card-id`	Conditional Requirement: Required for a transaction using a stored card.	Integer	The card ID for a stored card. This value is found in the Initialize response, in `stored-cards: card: id`. Applicable to a transaction using a stored card.
`card-type-id`	Required	Integer	The numeric code for the type of card used for the transaction. For example, `7` indicates MasterCard. This value is found in the Initialize response, in `card: id`.
`country-id`	Required	Integer	The CellPoint Digital-specific country code from which a customer searches for a product or service.
`account`	Optional	Integer	The account number associated with this transaction.
`transaction-id`	Required	String	The CellPoint Digital ID of the transaction for which currency conversion offers are being requested.
`client-id`	Required	Integer	A unique ID configured for a merchant on the Velocity POP.

`sale-amount`

Parents: root: OfferCriteria

The sale-amount element is required, and it has the following children:

Element	Requirement	Format of text content	Description of text content
`price`	Optional	String	The transaction amount in the original currency. This should be the same as `amount` in your Initialize request.
`currency`	Optional	String	The three-letter currency code for the currency against which you want to offer an exchange price. This should represent the same currency as the one used in your Initialize request.

`client-info`

Parents: root: OfferCriteria

The client-info element is required, and it has these children: mobile, email, device-id, and customer-reference. See their descriptions below.

The client-info element has the following attributes:

Parameter	Format	Requirement	Description
`language`	String	Required	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.
`platform`	String	Required	The platform from which the request is sent. For example, web, iOS, Android, HTML, B2B, and B2C.
`version`	String	Required	The version of the API or app that sends the request.
`sdk-version`	String	Optional	The software development kit (SDK) version used to send the request.
`profileid`	Integer	Optional	The ID of the client's profile in the merchant database.
`app-version`	String	Optional	The version of the app that sends the request.
`app-id`	String	Optional	The ID of the app that sends the request.

The mobile child element can be mandatory or optional, based on the requirement of a merchant or a PSP. It has the following attributes:

Parameter	Format	Requirement	Description
`country-id`	Integer	Conditional Requirement: Required if mobile number is present.	The CellPoint Digital-specific country code provided to merchants on request.
`operator-id`	Integer	Optional	The ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in a request to ensure that Velocity interacts with the operator accurately.

The mobile child element has the following text content:

Parameter	Format	Requirement	Description
mobile number	Integer	Conditional Requirement: A mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.	The MSISDN of a customer without International Dialing Code.

The email child element can be mandatory or optional, based on the requirement of a merchant or a PSP. It has the following text content:

Parameter	Format	Requirement	Description
email address	String	Conditional Requirement: Email can be mandatory or optional, based on the requirement of a merchant or a PSP.	The customer's email address.

The device-id child element is optional for a web channel, and it has the following text content:

Parameter	Format	Requirement	Description
device ID	String	Conditional Requirement: Optional for a web channel.	The device ID of a customer’s device.

The customer-reference child element is optional, and it has the following text content:

Parameter	Format	Requirement	Description
customer reference number	Integer	Optional	A unique reference number used for customer identification.

Response

See the sample FX OfferCriteria response 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>f55555c661e33dbed8777f0cf23232323232a5858f5f15da89898e000000077777fd08a67d77e1d9ae2d123b869990cb86f4d3cda899251b1cbe20071bc9c6g2</validation-hmac>
                <margin-percentage>5</margin-percentage>
                <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>

Response Parameters

`Offer`

Parents: root

The Offer element is required, and it has three children: foreign-exchange-offer-id, default_opt_in, and payment-currency-offers. See their descriptions below.

`foreign-exchange-offer-id`

Parents: root: Offer

The foreign-exchange-offer-id element is required, and it has the following text content:

Parameter	Format	Requirement	Description
foreign exchange offer ID	Integer	Required	A unique CellPoint Digital-specific identification number for a currency exchange offer.

`default-opt-in`

Parents: root: Offer

The default-opt-in element is required, and it has the following text content:

Parameter	Format	Requirement	Description
Boolean	Boolean	Optional	If `true`, the target currency is shown to the customer as preselected. CellPoint Digital recommends leaving this as `false`, where nothing is shown as preselected.

`payment-currency-offers`

Parents: root: Offer

Note the following:

The payment-currency-offers element is required; it provides an array of available currency exchange offers.
The payment-currency-offers element must have at least one payment-currency-offer child. It may have multiple payment-currency-offer children. See their description below.

`payment-currency-offer`

Parents: root: Offer: payment-currency-offers

Note the following:

At least one payment-currency-offer element is required.
The payment-currency-offer element contains four objects: exchange-amount, exchange-currency, sale_amount, and sale_currency. See their descriptions below.
The remainder of payment-currency-offer's children have only text content.

The payment-currency-offer element has these children with only text content:

Element	Requirement	Format of text content	Description of text content
`validation-hmac`	Required	String	The Message Authentication Code (MAC). It is calculated by creating a SHA-512 hash comprising the input fields in the order listed in the Message Authentication Code table. 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 string used to ensure that the MAC is unique. Note: CellPoint Digital provides the salt value to merchants. Conditional Parameters are optional in `hmac` if they are not provided in request; if those parameters are present in the request, they are mandatory in `hmac`.
`offered-exchange-rate`	Required	String	The offered exchange rate.
`margin-percentage`	Required	Integer	The margin percentage. This is included in the offered exchange rate displayed in `offered-exchange-rate`.
`display-margin-percentage`	Optional	Integer	The margin percentage displayed to the customer.
`rate-source`	Optional	String	The source of the exchange rate.
`pcs-external-ref`	Optional	String	The PCS external reference.

`exchange-amount`

Parents: root: payment-currency-offers: payment-currency-offer

The exchange-amount element is required; it defines the exchange amount offered against a currency (i.e. the transaction amount in the converted currency if the offered exchange rate is accepted). It has the following children:

Element	Requirement	Format of text content	Description of text content
`price`	Required	Integer	The price offered against the currency in which the customer makes payment, formatted as an integer including the number of decimal places defined in `exchange-currency: exponent`. For example, if the offered price is $120.30, then `exponent` is `2` and `price` is `12030`.
`currency`	Required	String	The currency in which the price is offered.

`exchange-currency`

Parents: root: payment-currency-offers: payment-currency-offer

The exchange-currency element is required; it describes the currency offered against the card currency. It has the following children:

Element	Requirement	Format of text content	Description of text content
`iso-alpha-code`	Required	String	The three-letter code for the currency offered against the card currency.
`iso-numeric-code`	Required	Integer	The three-digit numeric code for the currency offered against the card currency.
`exponent`	Required	Integer	The number of decimal points shown for the currency offered against the card currency.

`sale-amount`

Parents: root: payment-currency-offers: payment-currency-offer

The sale-amount element is required; it defines the transaction amount in the original currency. It has the following children:

Element	Requirement	Format of text content	Description of text content
`price`	Required	Integer	The transaction amount in the original currency, formatted as an integer including the number of decimal places defined in `sale-currency: exponent`. For example, if the offered price is $120.30, then `exponent` is `2` and `price` is `12030`.
`currency`	Required	String	The three-letter code for the original currency.

`sale-currency`

Parents: root: payment-currency-offers: payment-currency-offer

The sale-currency element has the following children.

Element	Requirement	Format of text content	Description of text content
`iso-alpha-code`	Required	String	The three-letter code for the original currency.
`iso-numeric-code`	Required	Integer	The three-digit numeric code for the original currency.
`exponent`	Required	Integer	The number of decimal points shown for the original currency.