Server SDKs

Qasimha's server SDKs provide a lightweight, consistent way to integrate with the Merchant API from your backend. Official SDKs are available for Node.js, PHP, .NET, and Java, and each follows the same core design principles. Regardless of the language you choose, you'll work with the same resources, methods, request options, and error models, adapted to match the conventions and idioms of that language.

The SDKs are intended to run exclusively on your server. Your secret API key (sktest... or sklive...) should never leave your backend environment and must never be exposed in a browser, mobile application, or any other client-side code.

In a typical integration:

1. Your backend creates a checkout session using the SDK.
2. The customer completes payment on the Qasimha-hosted checkout page.
3. Your server retrieves and verifies the resulting order.
4. Webhooks notify your application when order events occur.
5. Your backend responds to those events and updates your business systems accordingly.

Because payment collection happens on the hosted checkout, sensitive payment information never passes through your servers. This reduces integration complexity while helping you maintain a secure architecture.

Use this documentation to select your preferred language and compare SDK functionality across platforms. Although the syntax differs, the underlying capabilities remain consistent, making it straightforward to switch languages or support multiple services within the same organization.

Each language-specific guide includes:

• Complete API reference documentation
• Installation and configuration instructions
• Framework integration examples
• Authentication and error-handling guidance
• End-to-end sample applications
• Webhook verification examples
• Production-ready server implementations

Whether you're building a new integration or migrating an existing one, the SDKs provide a familiar and predictable developer experience across all supported languages.

Why use an SDK instead of raw HTTP

You can call the API directly. The SDKs save you from rebuilding the parts that are easy to get wrong:

Packages

Install sdk

npm install @qasimha/sdk

composer require qasimha/php-sdk

dotnet add package Qasimha.Sdk

<dependency>
  <groupId>com.qasimha</groupId>
  <artifactId>qasimha-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

implementation("com.qasimha:qasimha-sdk:0.1.0")

Shared behaviour

All four SDKs share these rules:

• Configuration. Pass the secret key; everything else is optional. Defaults: timeout 30 seconds per attempt, maxRetries 2 (allowed 0–5), language en (ar returns Arabic API messages). A baseUrl override must be https://, except localhost / 127.0.0.1 for test servers.
• Basket rules, checked to the halala (0.01 SAR) before sending:
  • item.totalAmount = quantity × unitPrice − item.discountAmount
  • totalAmount = Σ item.totalAmount + taxAmount + shippingAmount − discountAmount
• shippingAddress is required on an online session, even for digital baskets.
• Hosted checkout outcome. An order that completes the hosted checkout is already Confirmed (first instalment paid). Mark it paid on Confirmed, call fulfill when you ship, and refund after that. capture only applies to New / Approved orders.
• The return URL is not proof. Always read the order back with orders.get before marking it paid. See Return URLs.
• Plan quotes (getPlans) use the publishable key (pk_test_...) and never send the secret key.
• Duplicate references. A 409 DUPLICATE_ORDER_REFERENCE on the first attempt is raised as an error that carries the existing order and payment URL. The same 409 on a retry means the first attempt succeeded, and the SDK returns that session.

Demo merchant backend

Each server SDK ships a demo merchant backend in its examples/ folder (sdks/<lang>/examples/ in the source repository). It is the part every merchant writes: a small server that holds the secret key, prices the basket, creates the session, confirms the order and verifies webhooks.

All four backends expose the same HTTP API on port 4300, so the Angular and React demo stores run unchanged against any of them.

The backend reads QASIMHA_API_KEY, QASIMHA_PUBLISHABLE_KEY, QASIMHA_WEBHOOK_SECRET and QASIMHA_BASE_URL from the environment.

Mock mode. With no QASIMHA_API_KEY set, the backend talks to a local mock Qasimha instead of a real environment. The Node backend starts the mock itself. The PHP, .NET and Java backends expect it running on port 4301:

node sdks/node/examples/demo-merchant-server/mock-qasimha.mjs

To run against UAT instead, set QASIMHA_API_KEY=sk_test_... and QASIMHA_PUBLISHABLE_KEY=pk_test_.... The backend listens on 127.0.0.1:4300 by default (HOST and PORT change this).

Errors at a glance

Every error extends one base class (QasimhaError in Node.js, QasimhaException in PHP, .NET and Java) and carries the API code, the HTTP status, field errors and a requestId. Quote the requestId when you contact support.

See Errors for the API codes.

Security

• The secret key belongs in a secrets manager or environment variable on your server. Never send it to a browser or a mobile app.
• The publishable key (pk_...) only opens the plan quote and is safe to put in a page.
• The SDKs talk TLS only. Certificate checks cannot be switched off, there is no certificate pinning, and redirects are never followed. If you hand the PHP, .NET or Java SDK your own HTTP client, turn redirects off on that client.
• Keys, webhook secrets and customer data never appear in SDK logs, error messages or a printed client.
• No SDK handles card data. Customers pay on the Qasimha hosted checkout, so your integration stays in PCI DSS SAQ-A scope.

Choose your language