Salesforce B2C Commerce Cloud

The Qasimha cartridges add "Qasimha — pay in instalments" to a Salesforce B2C Commerce storefront built on SFRA. The cartridges call the Qasimha API directly through a dw.svc service (there is no SDK on this platform). Your secret key lives only in the Business Manager service credential. The shopper's browser only loads the instalment widget with your publishable key.

Requirements

Install

1. Import metadata. Rename metadata/site_import/sites/RefArch to your site id, zip the site_import directory (npm run release:metadata produces build/site_import.zip), and import it in Administration → Site Development → Site Import & Export. This creates the Qasimha site-preference group, the order attributes, the QasimhaWebhookEvent custom object, the QASIMHA payment method and processor, the qasimha.merchant.api service and the Qasimha-Fulfilment job.
2. Upload code. Upload both cartridges (npm run uploadCartridge with a dw.json, or any WebDAV client). Add them to the storefront cartridge path in front of the SFRA base:

int_qasimha_sfra:int_qasimha:app_storefront_base

There is no compile step.

3. Secret key. Go to Administration → Operations → Services → Credentials. Open qasimha.merchant.api.sandbox (or qasimha.merchant.api.production) and paste the secret key (sk_test_... or sk_live_...) into the password field. The user id is not used. Point the service qasimha.merchant.api at the credential for your environment. Do not enter the key anywhere else.
4. Site preferences. Fill in the Qasimha group (next section).
5. Payment method. Go to Merchant Tools → Ordering → Payment Methods and check that QASIMHA is enabled. The import creates it enabled and restricted to SAR.
6. Webhook. Register the webhook URL (see below) and copy the secret into the site preference.
7. Job. Go to Administration → Operations → Jobs → Qasimha-Fulfilment, set the site and enable the recurring trigger. Hourly is a good default.

Configure

Go to Merchant Tools → Site Preferences → Custom Preferences → Qasimha.

Register the webhook

Register this URL in the Qasimha Merchant Portal, replacing your host, site id and locale:

https://<your-host>/on/demandware.store/Sites-<site>-Site/<locale>/Qasimha-Webhook

Copy the secret into the Webhook secret preference. The webhook answers:

How a payment flows

1. Billing step. The Qasimha tab appears in the payment options. It is hidden when the basket is not in SAR, is outside the amount range, or has a gift certificate applied.
2. Place order. The cartridge creates the order, creates the checkout session with the order number as orderReferenceId, stores custom.qasimhaOrderId, custom.qasimhaPaymentUrl and custom.qasimhaStatus on the order, and sends the shopper to the hosted checkout through Qasimha-Start.
3. Return. Qasimha-Return checks the order token, reads the order from Qasimha, and places the order only when it is Confirmed, the reference matches and the total matches to the halala.
4. Webhook. Applies the same rule when Qasimha sends an event.

SFRA creates a new order number for every attempt, so a retry never collides with an earlier reference.

Order status changes

Each step writes an order note with the Qasimha order id, the reference and the request id.

Widget placement

• Product page: shown under the price on Product-Show automatically (the overlay includes product/qasimhaWidget.isml).
• Checkout: the Qasimha tab shows a summary for the order total and the card snippet.
• Cart page: not automatic. Add this line to your site's cart/cartTotals.isml where you want the badge:

<isinclude template="cart/qasimhaWidget" />

The amount on the cart page stays in sync when the cart changes. The widget script is bundled in the cartridge (LINK cartridges must not load remote scripts). See Plans widget.

Fulfilment, refunds and cancellations

• Fulfilment: the Qasimha-Fulfilment job reports every shipped order with a Qasimha order id, once, with the carrier and tracking number from the default shipment. It marks the order with custom.qasimhaFulfilled. If Qasimha refuses (already fulfilled, not found), the job gives up with a note; network failures are retried on the next run. The job also deletes webhook records older than 30 days.
• Refunds: the cartridge does not send refunds to Qasimha. When a refund event arrives, it adds an order note.
• Cancellations: handled on the shopper's cancel and failure returns, and through order.voided / order.cancelled events.

Test in UAT

• Metadata imported, both cartridges on the cartridge path, QASIMHA payment method enabled.
• sk_test_ key in the qasimha.merchant.api.sandbox credential password; service points at it; Environment sandbox.
• pk_test_ key and webhook secret saved in site preferences.
• Widget shows on a product page, the cart (after adding the include) and the checkout tab.
• Complete a hosted checkout: order placed with payment status PAID.
• Cancel on the hosted checkout: store order failed, shopper back in the cart.
• Ship an order and run the Qasimha-Fulfilment job: custom.qasimhaFulfilled set and a note added.
• custom-qasimha-* logs show no errors.

Troubleshooting

Security

• Secret key: only in the service credential's password field. Never in code, site preferences, templates, custom objects or logs. The logger masks sk_, pk_ and whsec_ values and redacts customer fields.
• Browser: only the publishable key.
• CSRF: Qasimha-Start is a POST guarded by csrfProtection.validateRequest, the order token and the session owner. The return routes are GETs that only select an order and ask the API.
• Webhook route: exempt from CSRF; protected by the HMAC signature (rotated secrets, 5-minute tolerance, constant-time compare) and de-duplicated with the QasimhaWebhookEvent custom object. See Webhook signatures.
• TLS: the service URL is https:// and certificate validation cannot be turned off.
• PCI DSS: no card data touches the storefront; you stay in SAQ-A scope.

Report vulnerabilities privately to the security contact in the Merchant Portal, not in a public issue.

Next steps