API endpoint: /plugin/payment

Umožní na eshopu vytvořit vlastní způsob platby. Po dokončení objednávky je možné vypsat vlastní html kód (například přesměrování na platební bránu).

Vytvoření nového způsobu platby

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": "Zaplaceno",
                "image": "https://plugin.tld/images/icon.png"
            },
            {
                "description": "Nezaplaceno",
                "image": "https://plugin.tld/images/icon.png"
            },
            {
                "description": "Neznámý stav",
                "image": "https://plugin.tld/images/icon.png"
            }
        ]
    }
 

Požadavek výše vytvoří na eshopu vlastní způsob platby, včetně jeho možných stavů. Po vytvoření platby bude zapotřebí eshopařem platbu propojit s konkrétní dopravou. Zároveň ji může případně nastavit vlastní cenu nebo změnit název.


Příklad:

 
    $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" => "Zaplaceno",
                    "image" => "https://plugin.tld/images/icon.png"
                ],
                [
                    "description" => "Nezaplaceno",
                    "image" => "https://plugin.tld/images/icon.png"
                ],
                [
                    "description" => "Neznámý stav",
                    "image" => "https://plugin.tld/images/icon.png"
                ]
            ]
      ])
        CURLOPT_HTTPHEADER => array(
            'X-Wa-api-token: ' . $api_token, // apiToken
            'Authorization: Bearer ' . $bearer, // access token
            'Content-Type: application/json'
      ),
    ));

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


Vytvoření objednávky

Po vytvoření objednávky se odešle request na 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
            }
        ]
    }
 

Jako odpověď se očekává HTML kód (výpis hlášky o úspěšném dokončení objednávky, otevření widgetu s platební bránou popřípadě přesměrování).

Návrat z platební brány do eshopu

Při návratu z platební brány (popřípadě z doplňku, který zpracoval stav platby) se lze přesměrovat na adresu https://domena-eshopu.tld/plugin_payment_after . Této adrese je potřeba předat pomocí GET parametry payment které by mělo obsahovat ID platební metody a success který vyžaduje hodnoty 1 (true) nebo 0 (false). Na základě těchto informací následně zákazník uvidí buď successMessage nebo errorMessage.

Stavy plateb

Po vytvoření objednávky a provedení platby je následně možné k objednávce přidat stav platby (zaplaceno, nezaplaceno apod.). Seznam dostupných platebních stavů lze získat voláním GET /plugin/states

Přidání stavu platbu k objednávce

POST /plugin/state/payment

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

Požadavek vloží k objednávce ID stavu platby, které se následně zobrazí pomocí dříve vloženého obrázku u objednávky (maximální velikost obrázku je 30x30 px).


Příklad:

 
    $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
            'Authorization: Bearer ' . $bearer, // access token
            'Content-Type: application/json'
      ),
    ));

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


Seznam ostatní requestů

POST /plugin/payment - vytvoří novou platební metodu

PUT /plugin/payment/{id} - update platební metody

DELETE /plugin/payment/{id} - smazání platební metody

POST /plugin/state/payment - vloží k objednávce nový stav platby

PUT /plugin/state/payment - upraví stav platby u objednávky

DELETE /plugin/state/payment/{idOrder} - smaže stav platby u objednávky

GET /plugin/state/payment/{idOrder} - vrátí stav platby u dané objednávky

GET /plugin/states - vrátí seznam všech dostupných stavů