With the checkout system you can accept payments in Lucks directly on your website!

Your store key

The first thing you need to accept payments is a store key. This key is unique and is strictly personal, anyone in possession of your key may be able to validate payments on your site without transferring Lucks to your account.
Warning: Never share your store key even if someone asks you to!

Button operation

Get a transaction ID

To display a functional payment button you must retrieve a unique transaction identifier. This identifier guarantees that no one can change the amount you indicated. To obtain this identifier you must send a request to the checkout API as explained below. It is also with this identifier that the result of the transaction will be sent to you.

Note: The transaction ID is only valid for 15 minutes. If the user exceeds this deadline to validate the transaction, it will be automatically refused.

All requests to the API should be sent to the URL below. All parameters must be passed in POST. However you can pass the parameters in GET if you wish by adding the GET parameter "mode".

URL
Parameters

• api_key — Your API key
• amount — The amount of the transaction in Lucks (minimum 0.01)
• message — The description of the transaction (optional, maximum 256 bytes)
• return_url — The address to redirect the user to after the transaction, this redirection will be done in POST with a "transaction" parameter containing the identifier of the transaction
• mode — Set to "get" to use GET parameters instead of POST (optional, all POST parameters will be ignored)

Return value A JSON containing the "code" and "data" fields:

• code — The return code of the operation (see below)
• data — Response data (if relevant)

List of return codes

• 0 — Everything went well
• 2 — Cannot find the user associated with this key
• 5 — A parameter is missing
• 13 — API key is invalid
• 18 — The message is too long
• 19 — The amount is invalid
• 20 — The recipient does not accept transfers
• 22 — Cannot find the account linked to this API key
• 24 — Error preparing the transaction
• 26 — Parameter "return_url" does not contain a valid URL

Response data
If the preparation of the transaction was successful, the "data" field contains a string of 16 alphanumeric characters corresponding to the transaction identifier.

Example
Below is an example of a GET request to the API and a possible return JSON:

URL
Response data

{
    "code": 0,
    "data": "0123456789ABCDEF"
}

Button code

You will find below the HTML / JavaScript code to integrate into your web page when offering the user to pay with Lucks. You must first have retrieved a unique transaction ID from the checkout API.

Code You can customize the button by modifying the following attributes of the <div> tag

data-transaction-key
The transaction identifier associated with the button.

data-size
The size of the button: "small", "medium" and "large".

data-pay-with
You can translate the button into your language with this field.

data-disable
Set to "true" disable the button.

Example of the button in the three sizes

Retrieve the status of a transaction

After step 7, you will need to check the status of a transaction, in which case you will need to make a call to the Status API. For a given transaction ID, it will return its status to you (pending, paid, rejected, not found).

All requests to the API should be sent to the URL below. All parameters must be passed in POST. However you can pass the parameters in GET if you wish by adding the GET parameter "mode".

URL
Parameters

• api_key — Your API key
• id — The identifier of the transaction to verify
• mode — Set to "get" to use GET parameters instead of POST (optional, all POST parameters will be ignored)

Return value A JSON containing the "code" and "data" fields:

• code — The return code of the operation (see below)
• data — Response data (if relevant)

List of return codes

• 0 — Everything went well
• 2 — Cannot find the user associated with this key
• 5 — A parameter is missing
• 11 — The transaction could not be found (this code is also used if the transaction has expired)
• 13 — API key is invalid

Response data
If the transaction exists, the "data" field contains a "status" field which can be "pending" (the transaction is awaiting validation), "rejected" (the transaction has been rejected) or "paid" (the transaction was paid and everything went good). For "pending" and "paid" cases, an additional field "transaction" contains the JSON of the transaction.

Example
Below is an example of a GET request to the API and a possible return JSON:

URL
Response data

{
    "code": 0,
    "data": {
        "status": "pending",
        "transaction": {
            "id": "0123456789ABCDEF",
            "amount": 42.00,
            "formatted_amount": "42,00",
            "init_time": 1612822912,
            "message": "Payment to example.com"
        }
    }
}

Good practices

It is possible for technical reasons that the redirection (step 7 of the diagram) does not reach your server. In this case it may be that the user does not return to your site, this does not necessarily mean that the transaction has been rejected! We advise you to check via the API all transactions for which you have no news after 20 minutes and process them if necessary.

Example code in PHP

Below you can download a simple shop source code example written in PHP and commented in English

Download