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