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.

This section applies to OSF. This section applies to Open Storefront Framework (OSF).

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:

  1. 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.
  2. 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 /v1/payment/calculateRemainingBalance} {POST ccstore/v1/payment/calculateRemainingBalance }
This request contains:
  • 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 and payShippingInSecondaryCurrency 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"
}