Manual

Introdution

The sidebar on the left contains links to the corresponding section:

• Username - links to personal profile.
• Dashboard - view the current status in the form of charts and graphs.
• Apps - manage your applications.
• Unlock codes - unlock codes generated automatically or downloaded by you.
• Payments - history of users' incoming payments.
• Manual - current user manual.

Dashboard

You can set common filters for all widgets in the dashboard:

• Currency - currency in which the values will be converted.
• Period - period of time for which the data is displayed.

Balance

The balance includes the following amounts:

• Gross amount - the total amount of all user payments for the selected period excluding the fees of payment systems and PayToUse.
• Net amount - the total amount of all payments for the selected period minus fees of payment systems and PayToUse.
• Pending amount - the total amount of all payments for the specified period minus the fees of payment systems and PayToUse pending withdrawal to the developer's account. The payment becomes available for withdrawal 7 days after the payment.
• Available amount - the total amount of all payments for all time minus the fees of payment systems and PayToUse, available for withdrawal to the developer's account.

Payments

The Payments widget includes a table of payments grouped by application for the selected period.

Table fields:

• App - application. The table displays only the applications that had payments in the selected period.
• Payments - number of payments.
• Gross amount - the total amount of all user payments for the selected period excluding the fees of payment systems and PayToUse.
• Net amount - the total amount of all payments for the selected period minus fees of payment systems and PayToUse.

The graph shows the dynamics of Net amount and Gross amount values by day.

New users

The graph of new users shows two values in dynamics by day:

• New users - the number of new API calls. API accesses are recorded only if the device parameter - a unique device identifier - is passed when sending a request to the API. This parameter must be really unique for the device. (see Sending a request)
• Payments - the number of payments for the same period by day.

Conversion

The Conversion metric refers to the assessment of your sales efficiency to convert New users into Payments.

The graph shows the ratio of the number of Payments to the number of New users, in percent.

Apps

When you go to this section, a list of your applications opens.

The list of columns in the application table:

• # - is the unique identifier of the application. It is used when checking the application code or displaying the payment form.
• Name - name of the application. Visible only to you in reports and dashboard. A link to the application name leads to the page of editing the application.
• Status - current status of the application. It can be:
• Created - application has just been created, it is not yet configured.
• Released - the application is running.
• Created - the date of application creation.
• Additional control buttons:
• Delete - to remove the application from the list.

Creating or editing an application

To accept payments, you must consistently fill out all the necessary application data and activate app.

The button to create a new application is located in the title bar of the application list.

App

Fields available when creating an application:

• Name - the name of the application that only you can see in reports or on the dashboard. The name will be displayed in the page header of the saved application. As long as the application is not saved, "New app" is displayed instead of the name. The field is mandatory to enter.
• Contact email - the email address to which copies of messages sent to users will be sent. This address is also specified in the "Reply-to" field and is used to reply the user to the received e-mail with the code. The field is mandatory to enter. By default, the field is populated with the value from the developer profile. The value can be changed to a different value.
• App type - type of application. If you select a group type of application, a list of applications will be displayed for grouping. Only single applications for which unlock codes are generated are available in the list.
• Allow feedback on payment - adds a field to the payment form for the user to enter free text. The feedback is added to the copy of the email to the developer. The feedback can also be seen in the payment details.

Start typing changing values and the Save button appears. The Save button allows you to save your changes without going to the next page. The Next button saves the changes and moves to the next page. You can always return to make changes later.

In the page header, only the saved application pages are available for navigation. You can click Next or go to the section in the page header.

Description

Select a language from the list and click Add.

A tab with localized application texts for the selected language will appear.

Available languages:

• German
• English
• French
• Spanish
• Russian
• Chinese Simplified

The fields in the description are used to display information on the payment form and in the reply message to the user:

• Name - application name for the selected language. Displayed on the payment form. By default, when you add a language, the name of the application is substituted, which you can change. Required to be filled in.
• Description - a brief description of the application. Displays on the payment form under the application name. Can be left blank.
• Reply - additional information which will be sent to the user in the email on successful payment. The reply text is added at the end of the mail after the standard reply.

At least one language must be added to save and go to the next page.

The language displayed in the payment form is determined automatically on the basis of the user's preferences specified in his browser settings. You can save the application language for the application.

Start typing or changing values and the Save button appears. The Save button allows you to save your changes without going to the next page. The Next button saves the changes and moves to the next page. You can always return to make changes later.

In the page header, only the saved application pages are available for navigation. You can click Next or go to the section in the page header.

Price

The page contains a list of prices and fields related to payment:

• Trial period - the length of the trial period.
• Unit of time - the time unit of the trial period. For example, if you specify 7 days, it means that after 7 days after the application's first API call it will return a response that the trial period has expired. The time of the first device call is saved.
• Price calculating method - The method of price calculation from the list:
• Price calculation depending on the term - In the payment form, the user specifies the activation code term and the price is calculated automatically according to the table below. User receives automatically generated code in the reply letter.
• Term calculation depending on the price - in the payment form the user specifies the price from the list or enters his/her own price value and the term is calculated automatically according to the table below. The user receives automatically generated code in the reply message.
• Permanent code - in the payment form the user specifies the price from the list or enters his price value and receives in the reply letter a code from the list below according to the price.
• Donation - in the payment form the user specifies the price from the list or enters his/her own price value. In this case the code is not generated.

The price is set in U.S. dollars. The minimum value of the price is 1 USD.

Start typing or changing values and the Save button appears. The Save button allows you to save your changes without going to the next page. The Next button saves the changes and moves to the next page. You can always return to make changes later.

In the page header, only the saved application pages are available for navigation. You can click Next or go to the section in the page header.

Preview

This page sets the values:

• Code length - the length of the generated code, if applicable.
• Code character set - the set of characters from which the code is generated:
• Numeric code - only digits 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 are used for code generation. The code can be with leading zeros. The leading zeros are important when checking the code.
• Alphanumeric code - the characters 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, G, H, I, G, K, L, M, N, P, Q, R, S, T, U, V, X, Y, Z are used for code generation. The code is generated with uppercase characters. Character case is irrelevant when checking the code.
• Link to check code - an example of a link that should be used to check code.
• Link to pay - a link to make a payment. The link can be copied and pasted into the application description on the application site. Transmittable parameters:
• app - the unique identifier of the application. Required parameter.
• amount - the amount that will be specified in the price field when purchasing. The default price is ignored. However, the amount can't be less than the minimum price and can't be lower than the minimum price set for the application. Optional parameter.

To start accepting payments, you need to activate the application with the Launch button. Before activating the application, make sure that all the data entered is correct. The keys generated by the application cannot be changed.

Code verification

Checking the application unlock code is done in 3 steps:

1. Writing and sending a request for code verification
2. Checks on the API side
3. Receiving and processing API response

Sending a request

To verify the code, the user of your application must enter it in the field in the application settings.

<properties>
    <property id="UnlockCode" type="string"></property>
    <property id="UnlockResult" type="string">Checking...</property>
    ...
<properties>

<settings>
    <setting propertyKey="@Properties.UnlockCode" title="@Strings.UnlockCode">
        <settingConfig type="alphaNumeric" maxLength="12"/>
    </setting>
    <setting propertyKey="@Properties.UnlockResult" title="@Strings.UnlockResult">
        <settingConfig type="alphaNumeric" readonly="true"/>
    </setting>
    ...
</settings>

Then you need to send a request to the Pay-to-use API server:

function onTemporalEvent() as Void {
    return Toybox.Communications.makeWebRequest(
        "https://api.pay-to-use.com", // API URL
        {
            "device" => System.getDeviceSettings().uniqueIdentifier, // device unique identifier
            "app" => "6", // your App id
            "code" => Application.Properties.getValue("UnlockCode") // unlock code value in your application
        },
        {
            :method => Communications.HTTP_REQUEST_METHOD_POST,
            :headers => { "Content-Type" => Communications.REQUEST_CONTENT_TYPE_JSON },
            :responseType => Communications.HTTP_RESPONSE_CONTENT_TYPE_JSON
        },
        method(:onReceive)
    );
}

API request parameters:

• url - https://api.pay-to-use.com. The use of HTTPS is mandatory.
• The body of the request (the values passed). A Dictionary of keys and values:
• device - unique identifier of the device.
• app - unique identifier of your application.
• code - unlock code entered by the user in your application settings.
• Request options:
• :method - API supports GET and POST methods of request.
• :headers - for POST method you should pass parameters in JSON.
• :responseType - the response is returned in JSON.
• responseCallback - s reference to a callback method which must accept two arguments:
• responseCode - the server response header code.
• data - the content if the request was successful, or null.

Checks on the API side

If no parameters are passed to the API, the API returns a HTTP/1.1 404 Not Found header.

If at least one parameter is passed to the API, the API returns header HTTP/1.1 200 OK.

The server response consists of:

• response - response code
• msg - text description of the response
• expires - UNIXTIME timestamp (if applicable)

A check is performed to ensure that the application identifier passed in is correct. The application must be in Released status at the time of payment. In case of an error, response code 301 is returned.

If a unique device ID is transmitted, the device ID is searched for and stored. If errors occur when checking or saving, an error code 402 is returned. If such a return code is found, immediately write to support at [email protected]

If the code is passed, the following steps are performed for applications with the Price calculation depending on the term and Term calculation depending on the price calculation methods:

• If an empty code is transmitted, it is detached from the unique device identifier defined in the previous steps.
• If a non-empty code is transmitted and it is not activated, the code is activated depending on the conditions of the price specified when the code was purchased, regardless of the date of activation.
• If no code has been transmitted or if the transmitted code is not found, error code 201 is returned.
• The activated code is checked against the device and, if a unique device identifier other than the stored one was transmitted during activation, an error code 202 is returned.
• If the transmitted code has no expiration date and all previous checks have been passed, code 101 is returned.
• If the code is time limited, a check is performed. If the key is not expired, code 101 is returned. If the code has expired, error code 203 is returned.
• This type of application requires the code to be bound to the device. If the unique device ID has not been transmitted, error code 304 is returned.

For an app with a Permanent code, only the availability of the code at the time of purchase is checked. If a code is found, code 101 is returned. If no code is found, error code 201 is returned.

For an application with the Donation calculation method, the code is not checked. The code 101 is always returned.

If the previous checks have not been passed the test period is checked. If more time has elapsed since the device was first contacted than the current application settings, error code 204 is returned. If the trial period has not yet expired, error code 102 is returned.

If only the application ID is transmitted and neither the unlock code nor the unique device ID is transmitted, error code 303 is returned.

If the response returned is 500, you should write to support at [email protected]

Below is a table of all returned codes:

{
    "response":101,
    "msg":"Active forever",
    "expires":0
}

{
    "response":101,
    "msg":"Active until 19 Oct 2024",
    "expires":1729381641
}

{
    "response":101,
    "msg":"The code check was successfull",
    "expires":0
}

{
    "response":101,
    "msg":"No code check required",
    "expires":0
}

{
    "response":102,
    "msg":"Trial period expires in 21h 34m",
    "expires":1714080130
}

{
    "response":201,
    "msg":"Code not found"
}

{
    "response":202,
    "msg":"Used on the another device"
}

{
    "response":203,
    "msg":"Expired on 8 Apr 2024",
    "expires":1712620041
}

{
    "response":204,
    "msg":"Trial period expired"
}

{
    "response":301,
    "msg":"App not found"
}

{
    "response":302,
    "msg":"Term undefined"
}

{
    "response":303,
    "msg":"Not enought arguments"
}

{
    "response":304,
    "msg":"Device is nesessary"
}

{
    "response":401,
    "msg":"Error code saving"
}

{
    "response":402,
    "msg":"Error device saving"
}

{
    "response":500,
    "msg":"Unknown error"
}

Checking the response

Then you should check the response from the Pay-to-use API server:

function onReceive(responseHeader, data) as Void {
    if (responseHeader == 200) { Toybox.Background.exit(data); }
}

You can check all headers and codes, you can display your own messages for user convenience, but in the simplest form the verification will look something like this:

function onBackgroundData(data) as Void {
    if (data.hasKey("response")) {
        if (data.hasKey("msg")) {
            // You can show data["msg"] in the properties field with the name "UnlockResult".
            Application.Properties.setValue("UnlockResult", data["msg"]);
        }
        if (data["response"].toString().substring(0, 1).equals("2")) {
            // Code verification failed
            // Paid functions are NOT available
            ...
        } else {
            // The code check was successful or the error is your fault or the fault of the API
            // Paid functions are available
            ...
        }
    }
}

Unlock codes

When you go to this section, a list of unlock codes will open.

Unlock codes list

You can search the email field or the code in the top search bar. The found codes will be displayed in the list. You can use all or part of the email or the code as the search criterion. Matches will be highlighted in color. Search and filters work simultaneously and do not exclude each other.

The last used filter is stored for the user. That is, the next time you enter the page, the last used filter will be applied automatically. Filters are available for the list of unlock codes:

• Columns - display only selected columns of the unlock codes list.
• App - display only unlock codes for selected applications.
• Status - display only unlock codes that are in the selected statuses.

The list of columns in the unlock codes table:

• App - your application. You can follow the link to edit its settings.
• Code - the unlock code.
• Email - email to which the code is registered. This address is used to search for customer codes in the My purchases section of the site. This section is available to users.
• Term - the period of validity of the sent code (specified in the application settings). A validity period is set for the code, corresponding to the conditions of the application settings at the time of its creation.
• Status - the unlock code status. (see Unlock code status)
• Created - date of unlock code creation.
• Activated - date of code activation. Set when the user's device first accessed the PayToUse API service and correctly transmitted this code. The code status changes to Activated.
• Expires - the date on which the code activation expires. Set for codes that have a limited validity period on code activation. For codes with unlimited expiration date remains blank.
• Deleted - date of code deletion, setting code status Deleted.
• Payment # - unique sequence number of the payment. You can click on the link to view the details of the payment.
• Buttons for actions with unlock codes. For example, deletion.

Unlock code status

During its lifecycle, the unlock code goes to different states, which can be tracked by the code status.

Payments

When you go to this section, a list of user payments will open.

The following payment systems are used to receive payments:

After the payment system's fees, PayToUse will charge a 13% fee. We are constantly working to reduce the fees.

If any disputes or refunds arise in the payment system, the penalties of the payment system are reissued to the developer. Therefore you should not allow such situations to occur. PayToUse fee is not charged in controversial situations.

Payments list

You can search the email field or the sent code in the top search bar. The found payments will be displayed in the list. You can use all or part of the email or the sent code as the search criterion. Matches will be highlighted in color. Search and filters work simultaneously and do not exclude each other.

The last used filter is stored for the user. That is, the next time you enter the page, the last used filter will be applied automatically. Filters are available for the list of payments:

• Columns - display only selected columns of the payment list.
• App - display only payments for selected applications.
• System - display only payments of selected payment systems.
• Status - display only payments that are in the selected statuses.

The list of columns in the payments table:

• App - your application. You can follow the link to edit its settings.
• # - unique sequence number of the payment. It is assigned to the payment automatically when user goes from payment form to payment page in payment system. You can click on the link to view the details of the payment.
• Comments - comments left by the user in the payment form.
• System - the payment system selected by the user.
• Status - the payment status. (see Payment status)
• Email - user's email indicated in the payment form.
• Term - the period of validity of the sent code (specified in the application settings).
• Created - date of payment creation.
• Invoice amount - the amount of payment charged to the user. Specified in the payment form depending on the application settings.
• Payment date - date of payment.
• Payment amount - the amount of payment confirmed by the payment system.
• Sent code - the code sent to the user.
• Available amount - the amount available for withdrawal.
• Payout amount - the amount of withdrawn funds for the payment.

It is not possible to make changes to the payment.

Payment status

During its lifecycle, the payment goes to different states, which can be tracked by the payment status.

Withdrawals

When you go to this section, a list of your withdrawals will open.

Withdrawals list

The last used filter is stored for the user. That is, the next time you enter the page, the last used filter will be applied automatically. Filters are available for the list of withdrawals:

• Columns - display only selected columns of the withdrawals list.
• Status - display only withdrawals that are in the selected statuses.

The list of columns in the withdrawals table:

• # - unique sequence number of the withdrawal. It is assigned to the withdrawal automatically when withdrawal saved. You can click on the link to view the details of the withdrawal.
• Status - the withdrawal status. (see Withdrawal status)
• Created - date of withdrawal creation.
• Amount - the amount of withdrawal.
• Withdrawal - date of withdrawal.
• Buttons for actions with withdrawals. For example, confirmation.

You can confirm the withdrawal when it is in the Sent status.

Withdrawal status

During its lifecycle, the withdrawal goes to different states, which can be tracked by the withdrawal status.