Payment methods

API endpoint: /plugin/payment

Allows you to create a custom payment method on the store. After completing the order, it is possible to write a custom html code (for example, redirection to the payment gateway).

Create a new payment method

POST /plugin/payment

 
    {
        "name": "My Payment Method",
        "description": "Optional Description",
        "image": "https://plugin.tld/images/icon.png",
        "action": "https://plugin.tld/test-payment",
        "errorMessage": "Platbu se nepodařilo zaevidovat.",
        "successMessage": "Platba byla úspěšná.",
        "states": [
            {
                "description": "Paid",
                "image": "https://plugin.tld/images/icon.png"
            },
            {
                "description": "Unpaid",
                "image": "https://plugin.tld/images/icon.png"
            },
            {
                "description": "Unknown",
                "image": "https://plugin.tld/images/icon.png"
            }
        ]
    }
 

The request above creates a custom payment method on the store, including its possible states. After creating the payment, the eshopper will need to link the payment to a specific transport. At the same time, he can possibly set a custom price or change the name of it.

Example:

 
    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => 'https://api.webareal.cz/plugin/payment',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => json_encode([
            "name" => "My Payment Method",
            "description" => "Optional Description",
            "image" => "https://plugin.tld/images/icon.png",
            "action" => "https://plugin.tld/test-payment",
            "errorMessage" => "Platbu se nepodařilo zaevidovat.",
            "successMessage" => "Platba byla úspěšná.",
            "states" => [
                [
                    "description" => "Paid",
                    "image" => "https://plugin.tld/images/icon.png"
                ],
                [
                    "description" => "Unpaid",
                    "image" => "https://plugin.tld/images/icon.png"
                ],
                [
                    "description" => "Unknown",
                    "image" => "https://plugin.tld/images/icon.png"
                ]
            ]
      ])
        CURLOPT_HTTPHEADER => array(
            'X-Wa-api-token: ' . $api_token, // apiToken získáte při instalaci doplňku, viz. nápověda
            'Authorization: Bearer ' . $bearer, // access token získáte zde, údaje zde (záložka API přístup)
            'Content-Type: application/json'
      ),
    ));

    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
 

Creating an order

After the order is created, a request is sent to the action URL.

POST

 
    {
        "id": 1, //ID objednávky
    	"orderNumber": "100001" //číslo objednávky,
        "price": 121.00,
        "currency": "CZK",
        "customer": "email@email.com",
        "returnUrl": "https://eshop/plugin_payment_after", //URL pro návrat
        "items": [
    	    {
    	    	"code": "product_1" //kód zboží,
    	    	"name": "Product 1"
    	        "quantity": 1,
    	        "unit": "ks",
    	        "price": 100.00, //za jednotku
    	        "priceVat": 121.00,
    	        "vat": 21
            }
        ]
    }
 

HTML code is expected as a response (a message about successful completion of the order, opening the payment gateway widget or redirection).

Return from the payment gateway to the e-shop

When returning from the payment gateway (or from the plugin that processed the payment status), you can be redirected to https://eshop-domain.tld/plugin_payment_after . This address needs to be passed the GET parameters payment, which should contain the payment method ID and success which requires values 1 (true) or 0 (false). Based on this information, the customer will then see either a successMessage or errorMessage.

Payment states

After creating an order and making a payment, it is then possible to add the payment status (paid, unpaid, etc.) to the order. The list of available payment statuses can be obtained by calling GET /plugin/states

Adding payment status to an order

POST /plugin/state/payment

 
    {
        "idOrder": 12345,
        "idState": 21
    }
 

The request inserts a payment status ID to the order, which is then displayed using the previously inserted image next to the order (maximum image size is 30x30 px).

Example:

 
    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => 'https://api.webareal.cz/plugin/state/payment',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => json_encode([
            "idOrder" => "12345",
            "idState" => "21",
      ])
        CURLOPT_HTTPHEADER => array(
            'X-Wa-api-token: ' . $api_token, // apiToken získáte při instalaci doplňku, viz. nápověda
            'Authorization: Bearer ' . $bearer, // access token získáte zde, údaje zde (záložka API přístup)
            'Content-Type: application/json'
      ),
    ));

    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
 

List of other requests

POST /plugin/payment - create a new payment method

PUT /plugin/payment/{id} - update payment method

DELETE /plugin/payment/{id} - deleting a payment method

POST /plugin/state/payment - adds a new payment status to the order

PUT /plugin/state/payment - adjusts the payment status of the order

DELETE /plugin/state/payment/{idOrder} - deletes the payment status of the order

GET /plugin/state/payment/{idOrder} - returns the payment status of the order

GET /plugin/states - returns a list of all available states