Plans widget and publishable keys

Show the instalment price right under your product price. A single endpoint powers both promo surfaces: the <qasimha-widget> element on your pages and the promo views in the mobile SDK. To add the widget, see Install the widget.

GET /api/v1/widget/plans returns the plans your policy offers for a given amount. For each plan you'll get the instalment count, the instalment amount, the first and last instalments, the fees including VAT, and the total payable.

Because the endpoint uses no customer data, it's safe to call from anywhere, a shopper's browser or a mobile app with a publishable key, or your own server when deciding whether to offer Qasimha for a basket. Call it directly when you render custom price messaging, and let the widget handle itself otherwise.

Publishable keys

A publishable key (pktest... or pklive...) is designed for use in untrusted environments such as web browsers, mobile applications, and client-side widgets.

Publishable keys are restricted to a single endpoint:

GET /api/v1/widget/plans All other API endpoints reject requests authenticated with a publishable key. In particular, publishable keys cannot access or modify Orders, Settlements and payouts, Customer information etc.
Each publishable key is issued with a single scope widget:read

To create a publishable key, navigate to Merchant Portal → Settings → API Keys and choose Publishable as the key type. Once generated, you can safely use the key in your frontend applications to authenticate requests to the plans endpoint.

• A publishable key works only in the environment where you created it.
• Revoke a publishable key in the portal like any other key. A revoked or expired key gets 401 INVALID_PUBLIC_KEY.
• A secret key (sk_...) sent as a publishable key is refused, and a publishable key sent as X-Api-Key is refused by the merchant API.

Get plan quotes

curl "https://api-uat.qasimha.com/api/v1/widget/plans?amount=1200.00&currency=SAR&lang=ar" \
  -H "X-Public-Key: pk_test_..."

In production, call https://api.qasimha.com with a pk_live_ key.

Request

Headers

Send no cookies and no X-Api-Key. The endpoint does not need them.

Query parameters

Response

{
  "success": true,
  "uuid": "76eeb42b-b7b1-4bc7-9395-dae97215584e",
  "code": "OK",
  "message": "Plans quoted",
  "data": {
    "merchantName": "Demo Store",
    "currency": "SAR",
    "minAmount": 100,
    "maxAmount": 4000,
    "plans": [
      {
        "instalments": 2,
        "frequency": "monthly",
        "instalmentAmount": 614.38,
        "firstInstalmentAmount": 614.38,
        "lastInstalmentAmount": 614.37,
        "feesIncludingVat": 28.75,
        "totalPayable": 1228.75,
        "shariaCompliant": true
      },
      {
        "instalments": 4,
        "frequency": "monthly",
        "instalmentAmount": 307.19,
        "firstInstalmentAmount": 307.19,
        "lastInstalmentAmount": 307.18,
        "feesIncludingVat": 28.75,
        "totalPayable": 1228.75,
        "shariaCompliant": true
      }
    ]
  },
  "errors": null
}

The numbers above are an example. Your own policy sets the plans, fees and limits. Each plan also carries apr, processingFeeIncludingVat and profitIncludingVat, and data also carries products. Both are described in the tables below.

data fields

Plan fields

feesIncludingVat can be larger than processingFeeIncludingVat + profitIncludingVat. The difference is an administration fee, which is included in the total but not listed on its own.

How to read the response

• Each plan shows the instalment count, the instalment amount, the first and last instalment, fees including VAT, and the total payable.
• plans is empty when amount is outside minAmount to maxAmount, or when your account has no active policy. The widget shows nothing in that case.
• When you have more than one active policy, each instalment count shows the cheapest plan across them.
• Quotes come from your price list and use no customer data. The customer's own terms are set at checkout and may differ. A plan here is the lowest price your policy lists.
• shariaCompliant is true for a plan with no finance charge. The widget shows its "interest-free" line only then.
• If the pricing service cannot be reached, plans is empty. The endpoint never returns an estimated number.

From your server

The server SDKs call the same endpoint with the publishable key you set on the client. They never send your secret key on this call.

Set the client's publishableKey option (pk_test_... with an sk_test_... key, pk_live_... with an sk_live_... key), or pass one per call. Without one, getPlans throws a configuration error before any request. An empty plans list is returned as is; it is not an error.

Behaviour

Errors

Errors use the standard envelope with success: false:

{
  "success": false,
  "uuid": "…",
  "code": "INVALID_PUBLIC_KEY",
  "message": "The publishable key is unknown, revoked or expired.",
  "data": null,
  "errors": []
}

Testing in UAT

1. Create a pk_test_... key in https://portal-uat.qasimha.com.
2. Call the endpoint on https://api-uat.qasimha.com with an amount inside your policy's range.
3. Check that plans is not empty. Try an amount below minAmount and check that plans is empty.
4. Before go-live, create a pk_live_... key in https://portal.qasimha.com and switch the host to https://api.qasimha.com.

Related