To start working with the QR Provider SDK as a partner, submit the form to create a merchant account. After creating and connecting the merchant in your personal account, you will receive a Merchant_ID and Secret_key, which are required to interact with the SDK.
All necessary interactions within the library occur exclusively through the FreedomQrProvider class. To initialize the SDK in your fragment or activity, you need to create an object:
secretKey: String - The secret key provided when connecting the merchant in the personal account.merchantId: String - A unique identifier assigned to the merchant after creating the account.region: Region – an enum parameter that specifies the regional domain for forming API requests. Supported values:Region.KZ – Kazakhstan Region.UZ – Uzbekistan Region.KG – Kyrgyzstan.
After creating the SDK object, it is necessary to study the main structure of parameters for initializing requests, which consists of params and callbacks.
sdkObject - The SDK object that has been initialized. methodName - The name of the method that was called by the user. Request Parameters:
Parameter
Description
params
One or more parameters that need to be passed to the user for making the request.
onResult
Returns the execution result object <T>.
onError
Returns an ErrorResponse object, which provides information about the error.
onFailure
Returns an Exception object, which provides information about the request sending error.
To retrieve the payment QR code, you need to call the sdk.getQR method. You also need to pass the following parameters to the method:
orderId: String - The payment identifier in the merchant's system. It is recommended to ensure the uniqueness of this field.
amount: Double - The payment amount in the currency.
description: String - A description of the product or service. It will be displayed to the customer during the payment process.
currency: String - The currency in which the amount is specified. Example: KZT, USD, EUR.
Example of calling the method to retrieve the payment QR code:
As a result of a successful obtaining the payment QR code method call, the onResult callback will return an InitPaymentResponse object, containing the following fields:
Field
Description
status
The status of the request execution
invoiceStatus
The status of the invoice
errorCode
Error code ID
errorDescription
A textual description of the error
invoiceId
The transaction identifier in the Freedom Pay system
invoiceMethods
The object containing the payment methods requested by the merchant InvoiceMethods
dt
Date and time of the request in the format YYYY-MM-DDThh:mm:ss±hh:mm
The invoice status invoiceStatus can have various states:
Value
Description
new
A new invoice has been created
process
Waiting for payer or payment system
ok
The invoice has been successfully paid
failed
Payment failed
incomplete
Invoice expired
The invoice method invoiceMethods is an InvoiceMethods object containing a single field:
Field
Description
qr
Image for displaying the payment QR code in Bitmap format
Also, note the onStatusChanged callback, which allows you to track the payment status of the QR code and return the status from the invoiceStatus field based on the payment result.
To stop tracking the QR payment status, you need to override onPause or onDestroy in your fragment or activity and call the sdk.stopStatusUpdates() method.
The method call is only required if the onStatusChanged callback is being listened to. Example of calling the method to stop listening for the QR payment status:
To obtain the payment status, the following methods are available:
Get the payment status by orderId: String – payment identifier in the merchant's system.
Get the payment status by invoiceId: Int – payment identifier in the Freedom Pay system.
To retrieve the payment status, you need to call the method sdk.getPaymentStatus and pass one of the fields, either orderId or invoiceId. Example of calling the method to get the payment status by orderId:
Example of calling the method to get the payment status by invoiceId:
In the case of a successful call to one of the payment status methods, the onResult callback will return a PaymentStatusResponse object with the following fields:
Field
Description
status
The result of the request execution.
invoiceStatus
The status of the invoice.
invoiceId
The unique identifier of the invoice in the Freedom Pay system.
errorCode
The error code ID, if applicable.
errorDescription
A textual description of the error, if applicable.
cardPan
The masked PAN (Primary Account Number) of the card used for payment.
cardToken
The unique identifier of the card used for payment.
amount
The amount of payment in the currency specified in the currency field.
currency
The currency used for the payment.
dt
The date and time of the request, in the format YYYY-MM-DDThh:mm:ss±hh:mm.
To cancel a payment, you need to call the sdk.cancelPayment method. You also need to pass a single parameter to the method:
invoiceId: Int - the unique identifier of the payment transaction in Freedom Pay.
Example of calling the method to cancel the payment:
As a result of a successful payment cancellation method call, the callback onResult will return an OperationResultResponse object, which contains the following fields:
Field
Description
status
Status of the operation
The status of the operation can have the following values:
To refund a payment, you need to call the sdk.refundPayment method. The method requires two parameters:
invoiceId: Int - a unique identifier of the payment transaction in Freedom Pay.
refundAmount: Double - the amount to be refunded.
Here’s an example of calling the method for a payment refund:
In the case of a successful payment refund, the onResult callback will return the same object as in the payment cancellation operation: OperationResultResponse.
