Use Loyalty Points and Pay with alternate currency
Allow shoppers to pay for an order using either loyalty points or in a monetary currency or a mix of currencies.
The property allowAlternateCurrency
is a boolean introduced at site
level and is not accessible with the admin UI. At the time of order creation,
allowAlternateCurrency
is copied to the order. This setting is
disabled by default, but can be enabled through the update site admin API, for
example:
/ccadminui/v1/sites/siteUS
{ "properties": {
"allowAlternateCurrency": true
}
}
Allowing orders to be paid in mix of currencies
Enable the allowAlternateCurrency
property to allow a
shopper to pay for an order in a mix of currencies, such as:
- A monetary order paid using points and monetary currency.
- A points based order paid using monetary currency and points.
If the payShippingInSecondaryCurrency
and
payTaxInSecondaryCurrency
setting is enabled in addition to
allowAlternateCurrency
, then there are certain restrictions on the
way the order can be paid:
- If the order is monetary order, then the entire order can be paid in monetary, but can not be paid in points. The shipping and tax total paid in monetary and leftover amount can be paid in either, points or in monetary currency or in a mix of both.
- If the order is point based order, then the entire order can be paid in points, but can not be paid in monetary. The shipping and tax total paid in monetary and leftover amount can be paid in either, points or in monetary currency or in a mix of both.
payShippingInSecondaryCurrency
and
payTaxInSecondaryCurrency
impose a restriction on the order, so
that the shipping and tax total must be paid in monetary currency.
Choosing alternate currency
If the order is point based order and the
allowAlternateCurrency
flag is enabled, then the alternate currency
which can be used to pay for the order will be the secondary currency set at the site
level. The shopper is not allowed to choose any other monetary currency.
If the order is monetary based and the
allowAlternateCurrency
flag is enabled, then the alternate currency
of points can be selected at the time of payment, but the shopper is allowed to use only
one point type for one order. For example, if one points payment is done using, for
example "bluePoints" and shopper wishes to make another payment using points, they must
only use "bluePoints" in that order. The point type selected has to be sent in payments
section of the order payload as "currencyCode". This is required because there is no
other way of identifying the alternate currency for monetary orders and to calculate the
conversion and remaining amount.
For point based orders, the alternate currency is always the site level secondary currency and need not be mentioned in the order request payload.
Setting exchange rate for amount conversion
For point based orders, the exchange rate is set at the order level at the time of the order creation itself while the pricing is completed.
For monetary orders, the exchange rate is set at order level, only if there is a payment made in points and it is done when the payment is submitted. The exchange rate set at the order level can only be changed if the order is in the pending payment state and all previous point based payments have been voided.
If the allowAlternateCurrency
flag is disabled and
payTaxInSecondaryCurrency
and
payShippingInSecondaryCurrency
settings are disabled, then orders
created are to be paid in single currency. Therefore, an error will result if a monetary
order is paid using loyalty points or if a point based order is paid using card or any
other monetary payment method. Single currency orders must be paid using payment methods
supporting the order's primary currency.
The calculateRemainingBalance
endpoint is used to calculate the order
amount which can be paid in monetary currency and points. More details about this can be
found at Payment endpoint for supporting mixed currency orders.
For mixed currency payments for a logged in user at checkout, the
createOrderForLoggedInAtCheckout
property must be enabled in client
configuration, for example:
PUT /ccadminui/v1/merchant/clientConfiguration{"createOrderForLoggedInAtCheckout":true}
Payment endpoint for supporting mixed currency orders
The calculateRemainingBalance
endpoint is used as part
of the payment framework for mixed currency orders and you can split the order total
between custom and monetary currency, and this endpoint returns the order amount
which can be paid in points and monetary currency.
The calculateRemainingBalance
endpoint returns the remaining order
amount in primary and alternate currency.
The order states supported are BEING_AMENDED
,
INCOMPLETE
, PENDING_PAYMENT
, and
QUOTED
. To use this endpoint, the
allowAlternateCurrency
flag must be enabled.
For example:
calculateRemainingBalance{POST ccagent/v1/payment/calculateRemainingBalance} {POST ccstore/v1/payment/calculateRemainingBalance }
- amount - The amount the user wants to pay in primary currency.
- alternateCurrencyAmount - The amount the user wants to pay in the alternate currency.
- alternateCurrencyCode - The alternate currency code. This is always the secondary currency for point based orders. For point based orders if the property is empty or null, the API assumes the alternate currency to be the secondary currency, but if an incorrect currency code is sent, then the API will throw an exception.
The following is an example of a
calculateRemainingBalance
request:
If the primary currency is points.
{
"amount":20,
"orderId":"o410438",
"alternateCurrencyCode":"USD",
"alternateCurrencyAmount":19
}
If the primary currency is USD
{
"amount":20,
"orderId":"o410438",
"alternateCurrencyCode":"bluePoints",
"alternateCurrencyAmount":19
}
This response contains:
- amountRemaining - The remaining order amount to be paid in primary currency.
- alternateAmountRemaining - The remaining order amount to be paid in alternate currency.
- minimumMonetaryCurrencyAmountRemaining - The minimum
remaining order amount which must be paid in monetary currency. This occurs when
both the
payTaxInSecondaryCurrency
andpayShippingInSecondaryCurrency
settings are enabled. - alternateCurrencyCode - The alternate currency code given in the input.
- amount - The amount the shopper wants to pay in primary currency given in the input.
- alternateCurrencyAmount - The amount the shopper wants to pay in the alternate currency given in the input.
- payments - The existing payment groups in the order.
The following is an example of a
calculateRemainingBalance
response:
{
"secondaryCurrencyTaxAmount": 0,
"alternateCurrencyAmountRemaining": "746.0",
"secondaryCurrencyShippingAmount": 425,
"orderId": "o410440",
"payments": [
{
"paymentGroupId": "pg530482",
"amountAuthorized": 20,
"amount": 20,
"customPaymentProperties": {
"1000addnl-property-key5": "1000payment-property-value5",
"1000addnl-property-key2": "1000payment-property-value2"
},
"gatewayName": "demoLoyaltyPointsPaymentGateway",
"uiIntervention": null,
"paymentMethod": "customCurrencyPaymentGroup",
"isAmountRemaining": false,
"paymentState": "AUTHORIZED",
"type": "loyaltyPoints",
"currencyCode": "bluePoints"
}
],
"alternateCurrencyCode": "USD",
"payShippingInSecondaryCurrency": true,
"payTaxInSecondaryCurrency": true,
"amountRemaining": "20.0",
"links": [
{
"rel": "self",
"href": "http://localhost:9080/ccagentui/v1/payment/calculateRemainingBalance"
}
],
"state": "PENDING_PAYMENT",
"minimumMonetaryCurrencyAmountRemaining": "406.0",
"currencyCode": "bluePoints"
}