Usage Guide¶
Overview¶
The Client
class serves as the primary interface for communication with the QosIc API within the qosic-sdk package.
This guide offers comprehensive instructions on how to effectively utilize the Client
class for interacting with the payment platform API.
Initialization¶
To use the Client
class, you need to initialize an instance of it with the required parameters. The following parameters are available for initialization:
login: Your server authentication login/user.
password: Your server authentication password.
mobile_carriers: The list of configured mobile carriers.
base_url: The QosIC server root domain, if you ever need to change it. Default is https://qosic.net:8443.
logger: Custom logger for logging API requests and responses.
from qosic import Client, bj
mobile_carriers = [bj.MTN("mtn_client_id"), bj.MOOV("moov_client_id")]
client = Client(login="your_login", password="your_password", mobile_carriers=mobile_carriers)
Making Payments¶
To make a payment using the Client
class, you can call the pay()
method with the following parameters:
phone: The phone number of the payer.
amount: The amount to be paid.
first_name (optional): The first name of the payer. Default is an empty string.
last_name (optional): The last name of the payer. Default is an empty string.
result = client.pay(phone="22901020304", amount=1000, first_name="John", last_name="Doe")
if result.success:
print("Payment successful")
else:
print("Payment failed. Error: ", result.response)
Processing Refunds¶
To request a refund using the Client
class, you can call the refund()
method with the following parameters:
reference: The reference ID of the original payment, available in the
Result
object returned by thepay()
method.phone: The phone number of the payer.
result = client.refund(reference="1234567890", phone="22901020304")
if result.success:
print("Refund successful")
else:
print("Refund failed. Error: ", result.response)
Result
class¶
A helper class that encapsulates the response from the server for a payment or refund request made using the Python SDK for the Payment Platform API.
status (Result.Status): The status of the request, which can be either
Result.Status.CONFIRMED
orResult.Status.FAILED
.reference (str): The reference number associated with the request.
phone (str): The phone number associated with the request.
mobile_carrier (MobileCarrier): The mobile carrier associated with the request.
response (httpx.Response): The HTTP response object returned from the server.
Properties
success (bool): A property that indicates whether the request was successful or not. Returns
True
if thestatus
isResult.Status.CONFIRMED
, indicating a successful request, andFalse
otherwise.
Logging¶
The Client
class uses the logging
module to log API requests and responses. You can customize the logging behavior and format
by passing a custom logger to the Client
class during initialization. For debugging purpose you can configure the logging
level to display all the interactions with the payment API.
import logging
logging.basicConfig(level=logging.DEBUG)
client = Client(login="your_login", password="your_password", mobile_carriers=mobile_carriers)
client.pay(phone="22901020304", amount=1000) # will log everything in your terminal
Error Handling¶
If everything goes well, the pay()
and refund()
methods return a Result
but if the request completely fails to be
processed by the server, one the exceptions listed below is raised.
ServerError : raised when the qos server is busy or fails for some reason.
UserAccountNotFoundError : raised when the phone number provided does not have a mobile money account.
ProviderNotFoundError : raised when for the given phone number, the provider can’t be identified.
InvalidPhoneNumberError : raised when the phone number does not match the valid format.
InvalidClientIDError : raised when the client ID does not match the provider or is incorrect.
InvalidCredentialsError : raised when your api credentials are invalid.
Best Practices¶
Use a task queue¶
To optimize the processing of payment requests, it’s important to note that API response times may vary depending on the mobile carrier used. Factors such as waiting for customer approval or polling for transaction results can cause delays. To prevent your server from being blocked during this process, it’s recommended to implement asynchronous processing using a task queue.
When using a task queue, you can periodically poll a specific endpoint on your server to check the status of the transaction. Alternatively, you can utilize server-side events to push real-time transaction status updates to the frontend. This allows you to efficiently display the transaction status to your users on the frontend, ensuring a smooth user experience.
Use environment variables for your credentials¶
You should never hardcode your credentials in your code. Instead, you should use environment variables to store your credentials and then access them in your code. This includes your login, password, and the client_id for all the mobile carriers you configured.