SuperQi 0.8.0-alhpa

SuperQi .NET SDK

.NET SDK for SuperQi Wallet Mini Program OpenAPIs.

Supports .NET 9, and .NET 10.

Installation

dotnet add package SuperQi

Setup

using SuperQi;

var client = new SuperQi(
    gatewayBaseUrl: "https://***************",
    clientId: "YOUR_CLIENT_ID",
    merchantPrivateKey: "BASE64_ENCODED_RSA_PRIVATE_KEY"
);

The merchantPrivateKey is a Base64-encoded PEM RSA private key. All requests are automatically signed with RSA-256.

Authorization

Get Access Token

Exchange an authorization code (from my.getAuthCode) for an access token:

using SuperQi.Models.AccessToken;

var response = await client.GetAccessTokenAsync(new AccessTokenRequest
{
    AuthorizationCode = "AUTH_CODE_FROM_WALLET"
});

var accessToken = response.AccessToken;
var customerId = response.CustomerId;

Refresh Token

using SuperQi.Models.RefreshToken;

var response = await client.GetRefreshTokenAsync(new RefreshTokenRequest
{
    RefreshToken = "YOUR_REFRESH_TOKEN"
});

Users

Get User Info

Retrieve user profile details using an access token:

using SuperQi.Models.UserInfo;

var response = await client.GetUserInfoAsync(new UserInfoRequest
{
    AccessToken = "ACCESS_TOKEN"
});

var user = response.UserInfo;
// user.UserId, user.UserName, user.Avatar, user.Gender, etc.

Payments

Create Payment (Cashier)

Redirect the user to the wallet cashier for payment approval:

using SuperQi.Models;
using SuperQi.Models.Pay;

var response = await client.PayAsync(new PayRequest
{
    ProductCode = "51051000101000000011",
    PaymentRequestId = "UNIQUE_MERCHANT_PAYMENT_ID",
    PaymentAmount = new Amount { Currency = "IQD", Value = "150000" },
    Order = new PayOrder
    {
        OrderDescription = "Order #1234",
        Buyer = new PayBuyer { ReferenceBuyerId = customerId }
    },
    PaymentNotifyUrl = "https://your-server.com/notify"
});

if (response.Result.ResultStatus == ResultStatus.Accepted)
{
    // Redirect user to: response.RedirectActionForm.RedirectionUrl
}

Create Payment (Agreement / Auto-Debit)

Charge the user automatically using a signed agreement:

var response = await client.PayAsync(new PayRequest
{
    ProductCode = "51051000101000100031",
    PaymentRequestId = "UNIQUE_MERCHANT_PAYMENT_ID",
    PaymentAuthCode = "ACCESS_TOKEN_FROM_AGREEMENT",
    PaymentAmount = new Amount { Currency = "IQD", Value = "150000" },
    Order = new PayOrder
    {
        OrderDescription = "Monthly subscription"
    }
});

Refund

Issue a full or partial refund against a completed payment:

using SuperQi.Models;
using SuperQi.Models.Refund;

var response = await client.RefundAsync(new RefundRequest
{
    RefundRequestId = "UNIQUE_MERCHANT_REFUND_ID",
    PaymentId = "WALLET_PAYMENT_ID",
    RefundAmount = new Amount { Currency = "IQD", Value = "50000" },
    RefundReason = "Customer requested cancellation"
});

Inquiry Payment

Poll for the latest payment status:

using SuperQi.Models.InquiryPayment;

var response = await client.InquiryPaymentAsync(new InquiryPaymentRequest
{
    PaymentId = "WALLET_PAYMENT_ID"
});

// response.PaymentStatus: Processing, AuthSuccess, Success, Fail

Inquiry Refund

Poll for the latest refund status:

using SuperQi.Models.InquiryRefund;

var response = await client.InquiryRefundAsync(new InquiryRefundRequest
{
    RefundId = "WALLET_REFUND_ID"
});

// response.RefundStatus: Processing, Success, Fail

Messages

Send Push Notification

using SuperQi.Models.SendPush;

var response = await client.SendPushAsync(new SendPushRequest
{
    AccessToken = "ACCESS_TOKEN",
    RequestId = "UNIQUE_REQUEST_ID",
    Content = new SendPushContentRequest
    {
        Title = "Order Shipped",
        Content = "Your order #1234 has been shipped.",
        AppIdentifier = "YOUR_MINI_APP_ID"
    }
});

Send Inbox Message

Requires the NOTIFICATION_INBOX scope on the access token:

using SuperQi.Models.SendInbox;

var response = await client.SendInboxAsync(new SendInboxRequest
{
    AccessToken = "ACCESS_TOKEN",
    RequestId = "UNIQUE_REQUEST_ID",
    Content = new SendInboxContentRequest
    {
        Title = "Welcome",
        Content = "Thanks for signing up!",
        AppIdentifier = "YOUR_MINI_APP_ID"
    }
});

Result Handling

All responses include a Result object with ResultStatus:

using SuperQi.Enums;

switch (response.Result.ResultStatus)
{
    case ResultStatus.Successful:
        // Operation succeeded
        break;
    case ResultStatus.Accepted:
        // Accepted, further action needed (e.g. cashier redirect)
        break;
    case ResultStatus.Unknown:
        // Unknown outcome, retry or poll
        break;
    case ResultStatus.Failed:
        // Failed, check ResultCode and ResultMessage
        break;
}

License

MIT