SuperQiSdk 1.0.3

SuperQiSdk

C# SDK for the Super Qi (QiNEO) mini-program OpenAPI platform. Handles RSA-SHA256 request signing, token management, payments, refunds, user queries, and messaging.

Requirements

• .NET 9.0 or .NET 10.0

Installation

dotnet add package SuperQiSdk

Configuration

Register the SDK in your DI container using one of two approaches:

Option 1: Inline

services.AddSuperQi(new SuperQiOptions
{
    ClientId = "your-client-id",
    MerchantId = "your-merchant-id",
    GatewayUrl = "https://gateway.qi.iq",
    PrivateKey = "base64-encoded-pem-private-key",
    PublicKey = "base64-encoded-pem-public-key",
});

Option 2: Configuration binding

// appsettings.json
{
  "SuperQi": {
    "ClientId": "your-client-id",
    "MerchantId": "your-merchant-id",
    "GatewayUrl": "https://gateway.qi.iq",
    "PrivateKey": "base64-encoded-pem-private-key",
    "PublicKey": "base64-encoded-pem-public-key"
  }
}

services.AddSuperQi(configuration.GetSection("SuperQi"));

Both overloads register ISuperQiService as a singleton with IHttpClientFactory.

Usage

Inject ISuperQiService and call the desired method:

public class PaymentController(ISuperQiService superQi) : ControllerBase
{
    [HttpPost("pay")]
    public async Task<IActionResult> Pay()
    {
        var response = await superQi.PayAsync(new Pay.Request
        {
            ProductCode = Pay.ProductCode.OnlinePurchase,
            PaymentRequestId = Guid.NewGuid().ToString(),
            PaymentAmount = new Amount { Value = "1000", Currency = "IQD" },
            Order = new Pay.Order
            {
                OrderDescription = "Test order",
            },
            PaymentRedirectUrl = "https://example.com/callback",
            PaymentNotifyUrl = "https://example.com/notify"
        });

        if (response.Result?.IsSuccess == true)
            return Ok(new { response.PaymentId });

        return BadRequest(response.Result?.ResultMessage);
    }
}

API Reference

Authorization

User Information

Payments

Refunds

Messaging

Webhooks

Request Signing

All outbound API calls are automatically signed. The SDK:

1. Builds the sign content: POST {endpoint}\n{ClientId}.{RequestTime}.{jsonBody}
2. Signs with RSA-SHA256 (PKCS#1 v1.5) using your private key
3. Sets the Client-Id, Request-Time, and Signature headers

No manual signing is required.

Webhook Verification

Verify inbound payment notifications to ensure they originate from Super Qi:

[HttpPost("notify")]
public IActionResult HandleNotification([FromBody] JsonElement body, [FromHeader] string signature)
{
    var notification = new PaymentNotification.Request
    {
        NotifyPath = "/v1/payments/notify",
        ClientId = Request.Headers["Client-Id"]!,
        RequestTime = Request.Headers["Request-Time"]!,
        SignatureHeader = Request.Headers["Signature"]!,
        Body = JsonSerializer.Deserialize<PaymentNotification.RequestBody>(body)!
    };

    if (!superQi.VerifyPaymentNotification(notification))
        return Unauthorized();

    // Process the notification
    return Ok();
}

Building

dotnet build

Testing

dotnet test

The test project (SuperQiSdk.Tests) targets .NET 9 and uses xUnit and Moq. All tests are pure unit tests — no network access or real credentials required.

Test coverage

Endpoint tests (EndpointTests)

Every service method is covered. Each test:

• Verifies the correct HTTP path is called (e.g. /v1/payments/pay)
• Supplies a canned JSON response and asserts all relevant fields are deserialized correctly

Signature / notification tests (SuperQiServiceTests)

License

MIT