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 FreedomQrClient 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.
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 add a tokenized card to the Freedom Pay system, you need to use the custom view AddCardView, which should be added to your fragment or activity XML file. AddCardView is a webview where the card addition page will open. Example of adding AddCardView:
After adding it to the XML, you need to pass your view to the SDK:
To track the progress of the card linking or the returned result, a public interface AddCardViewListener is available. You need to override this interface in your fragment or activity and pass it to your AddCardView:
this refers to the AddCardViewListener interface, which includes the following methods: Start of the card addition page loading
End of the card addition page loading
Result of card addition
isSuccess indicates the success of the card addition result.
To scan the payment QR code and process the payment, you need to use the custom view FreedomQRScannerView, which should be added to your fragment or activity XML file. FreedomQRScannerView is a camera screen used for scanning the QR code. Example of adding FreedomQRScannerView:
Successful scanning of the QR code is accompanied by a vibration signal, controlled by the special attribute isVibrationAfterScanning.
Result
Description
true
Vibration signal present
false
Vibration signal absent
To control the camera state, such as enabling and disabling it, you need to call the corresponding methods in your fragment or activity. Enabling the camera:
Disabling the camera:
To track the status of a successful QR code scan or the returned result, public interfaces ResultHandler and ErrorHandler are available.ResultHandler is a public interface that returns the result of the QR code scan. To use this method, it must be overridden in your fragment or activity.
this refers to the ResultHandler interface, which has the following method:
result: String - the result of scanning the QR code.
ErrorHandler is a public interface that provides a callback for errors, which you can override as needed. To use this method, you need to override it in your fragment or activity.
this refers to the ErrorHandler interface, which contains the following method:
NOTE
For proper functionality of the QR code scanning view, it is necessary to grant access to android.permission.CAMERA in your fragment or activity.
To get the list of tokenized cards, you need to call the method sdk.getTokenizedCardList. You must pass the following parameter to the method:
userId: String - the unique user identifier in the merchant's system.
Example of calling the method to get the list of tokenized cards:
As a result of successfully calling the method to get the list of tokenized cards, the onResult callback will return an object TokenizedCardResponse, containing a list of cards:
Field
Description
List<TokenizedCardDetailResponse> list
List of tokenized cards
The card list is a collection of objects from the class TokenizedCardDetailResponse, containing the following fields:
Field
Description
status
Displays the status of the card
cardToken
Unique identifier of the card
cardHash
Masked PAN of the card
If no tokenized cards have been added to the Freedom Pay system, the server will also respond with TokenizedCardResponse, where the card list will be empty
Adding a tokenized card to the Freedom Pay system is done on the add card page. Once your AddCardView is passed to the SDK, you need to call the method sdk.initAddingCard. The method also requires the following parameters:
userId: String - Unique identifier of the user in the merchant's system.
postLink: String - An optional field representing the URL to receive the result notification.
Example of calling the method to add a tokenized card:
As a result of a successful method call, the AddCardView will open the card addition page in the webView, where you need to enter the card details to add the card. After successfully filling in the card details, you need to confirm the entered data and submit the information.
There is no onResult callback in the method for initializing the addition of the card sdk.initAddingCard, because the result of adding the card can be tracked through the interface method AddCardViewListener
To remove a tokenized card, you need to call the method sdk.removeTokenizedCard. The method requires the following parameters:
userId: String - unique user identifier in the merchant's system.
tokenCard: String - unique card identifier, which can be obtained in the request for retrieving the list of tokenized cards.
Example of calling the method to remove a tokenized card:
As a result of successfully calling the method to remove a tokenized card, the onResult callback will return an object of TokenizedCardResponse, similar to when retrieving the list of cards. The status field of the card will be updated.
To retrieve the payment status, the following methods are available:
Retrieve the payment status by customerId: String – a unique identifier displayed when initializing payment via QR code generation, which can be obtained when scanning the payment QR code.
Retrieve the payment status by url: Url – a unique URL scanned from the QR code.
To retrieve the payment status, you need to call the sdk.getPaymentStatus method and pass either the customerId or url. Example of calling the method to retrieve the status by customerId:
To call the method for retrieving the status by url, you need to scan the QR code, obtain the unique link, initialize a Url object, and pass it as a parameter to the method:url – is an object that accepts a field of type String.
link - is the unique URL obtained when scanning the merchant's payment QR code. Example of calling the method to get the status by url:
As a result of successfully calling the method to get the payment status, the onResult callback will return an object PaymentStatusResponse, containing the following fields:
Field
Description
amount
The amount of the payment in the currency specified in currency
orderId
The order ID in the merchant's system
invoiceStatus
The status of the invoice
invoiceId
The unique invoice ID in the Freedom Pay system
cardPan
The masked PAN of the card
description
A description of the product or service
currency
The currency in which the payment will be made
dt
The date and time of the request in the format YYYY-MM-DDThh:mm:ss±hh:mm
The invoice status invoiceStatus can have different states:
To pay the invoice using a tokenized card, you must scan the payment QR code, from which you will get the customerId field needed to make the payment. Additionally, you should call the method sdk.payByCard. The method requires the following parameters:
customerId: String - a unique identifier that appears when the payment is initialized through QR code generation, and which can be obtained when scanning the payment QR code.
userId: String - a unique identifier for the user in the merchant's system.
tokenCard: String - a unique card identifier, which can be obtained in the request to get the list of cards.
If you don't have any tokenized cards added to the Freedom Pay system, you will first need to add a card. This can be done using the add card method.
Example of calling the method to pay the invoice.
As a result of a successful method call, the same object as when receiving the invoice status, PaymentStatusResponse, will be returned in the onResult callback.
The main difference in the PaymentStatusResponse model is that the invoiceStatus field will change the status of the invoice.
