LiqPay payments: checkout form, signature, and payment status | Dorokhov.codes

open_in_new LiqPay is a payment gateway (mainly used in Ukraine) that accepts card and other methods through a hosted checkout page.

How it works

You send a POST request to a special URL (https://www.liqpay.ua/api/3/checkout) and get the payment page in response.

The POST body has only two parameters:

data — a Base64-encoded JSON object with the full set of payment parameters.
signature — a signature of data, built with the public and private keys.

Example form that submits such a request:

<form method="POST" action="https://www.liqpay.ua/api/3/checkout" accept-charset="utf-8">
    <input type="hidden" name="data" value="eyAidmVyc2lvbiIgOiAzLCAicHVibGljX2tleSIgOiAieW91cl9wdWJsaWNfa2V5IiwgImFjdGlv
    biIgOiAicGF5IiwgImFtb3VudCIgOiAxLCAiY3VycmVuY3kiIDogIlVTRCIsICJkZXNjcmlwdGlv
    biIgOiAiZGVzY3JpcHRpb24gdGV4dCIsICJvcmRlcl9pZCIgOiAib3JkZXJfaWRfMSIgfQ=="/>
    <input type="hidden" name="signature" value="QvJD5u9Fg55PCx/Hdz6lzWtYwcI="/>
    <input type="image" src="//static.liqpay.ua/buttons/p1ru.radius.png"/>
</form>

Parameters

Full parameter list: open_in_new Checkout API documentation .

Useful ones:

order_id — unique purchase ID in your store. Required. LiqPay stores these IDs and rejects a second payment with the same one.
paytypes — payment methods shown on checkout. If omitted, the store settings from the Checkout tab apply.
result_url — URL in your store where the buyer is redirected after the purchase. Can also be set under Settings → API → URL of the client-server store. Parameters passed via the API take priority. The buyer is sent to result_url after a successful payment and after pressing the button (or automatically, if that is enabled in the site settings).

Getting the payment status

There are two ways to receive the status and details of a payment:

Via the same result_url — in the settings you can make LiqPay POST the full payload there.
Via server_url — a separate URL that handles the server-to-server notification.

Example payload (decoded):

stdClass Object
(
    [action] => pay
    [payment_id] => 992322703
    [status] => sandbox
    [version] => 3
    [type] => buy
    [paytype] => card
    [public_key] => i54025453481
    [acq_id] => 414963
    [order_id] => 4-1-1554549838
    [liqpay_order_id] => TY1GSZWV1554549850160703
    [description] => Basic deposit at 25% per year for 1 year.
    [sender_first_name] => Andrey
    [sender_last_name] => Dorokhov
    [sender_card_mask2] => 473118*62
    [sender_card_bank] => pb
    [sender_card_type] => visa
    [sender_card_country] => 804
    [ip] => 46.119.5.36
    [amount] => 2
    [currency] => USD
    [sender_commission] => 0
    [receiver_commission] => 0.06
    [agent_commission] => 0
    [amount_debit] => 53.91
    [amount_credit] => 53.91
    [commission_debit] => 0
    [commission_credit] => 1.48
    [currency_debit] => UAH
    [currency_credit] => UAH
    [sender_bonus] => 0
    [amount_bonus] => 0
    [mpi_eci] => 7
    [is_3ds] =>
    [language] => ru
    [create_date] => 1554549850163
    [end_date] => 1554549850195
    [transaction_id] => 992322703
)

PHP verification (Yii2 example) — always check the signature before trusting data:

if ($request->isPost && $request->post('data') && $request->post('signature')) {

    $sign = base64_encode(sha1(
        Yii::$app->params['liqpay_private_key'] . $request->post('data') . Yii::$app->params['liqpay_private_key'],
        true
    ));

    if ($sign == $request->post('signature')) {
        $data = json_decode(base64_decode($request->post('data')));
    }
}

Details

After LiqPay processing finishes and the final status is known, a POST with data and signature is sent to your server.

Library

Official PHP SDK: open_in_new liqpay/sdk-php .

Rules

open_in_new LiqPay rules

Possible issues

Not every project gets approved. There are frequent reports that activating a store with an unusual business model is difficult.