Checkout 3.0 public

Receiving payments on a personal checkout Liqpay client->server

To start receiving payments on your personal Liqpay checkout:

  • Register on www.liqpay.com

  • Create personal checkout in your account using designer

  • Share the link on your personal checkout for payment or create a simple HTML form

HTML form should be sent by POST to URL https://www.liqpay.com/api/3/checkout Two parameters data and signature, where:

data - function result base64_encode( $json_string )

signature - function result base64_encode( sha1( $private_key . $data . $private_key, 1 ) )

Request
Param Required Type Description
version yes Number Version API. Current value - 3
public_key yes String Public key - the store identifier. You can get the key in the store settings
merchant_public_key yes String Public_key of agent shop
action yes String Transaction type. Possible values: pay - payment, hold - amount of hold on sender's account, subscribe - regular payment, paydonate - donation, auth - card preauth
action yes String checkout
order_id yes String order_id of successful payment
email yes String email for reciept sending
compensation_id no* String compensation_id проводки зачисления
resp_format no* String Possible report format json, csv, xml. If parameter is not passed, will be passed by default json.
date no** String If the compensation id parameter is unknown, then date by which you need to get a compensation id list, is transferred
phone yes String Payer's mobile phone. One time password will be sent to the number to confirm the payment. Mobile number should be in the international format (Ukraine +380, Russia +7). For example: +380950000001 (with +) or 380950000001 (without +)
amount yes Number Payment amount.For example: 5, 7.34
currency yes String Payment currency. Available values: USD, EUR, RUB, UAH BYN KZT. Additional currencies can be added by company's request.
description yes String Payment description.
order_id yes String Unique purchase id in your store.The maximum length is 255 characters.
confirm yes String Flag of request confirmation. Possible values: yes, no
card yes String Card number of the payer
card_exp_month yes String Expiry month of the payer's card.For example: 08
card_exp_year yes String Expiry year of the payer's card.For example:19
card_cvv yes String CVV/CVV2
card_token yes String Sender's card token.For example: B5BВB0D00B88B00ED00A00D0D
card_track yes String Sender's card track.For example:1111222233334444=1703000000000000000
imei yes String Device IMEI
receiver_card yes String Recipient's card number
bitcoin_addr yes String Bitcoin wallet that needs to be topped up
ip yes String client IP.
email yes String customer's e-mail to send invoice
channel_type yes String Bot channel. Supported values: telegram
account yes String User ID in messenger
language no String Customer's language ru, uk, en.
sandbox no String Enables the testing environment for developers. Payer card will not be charged. To enable testing environment you will need to transmit value 1. All test payments will have sandbox status - success test payment.
prepare no String Preparation of the request. This mode allows to check if all data are filled in, if 3DS authentication is required, if transaction is within limit. Payer card will not be charged. To enable this mode you will need to transmit value 1.
recurringbytoken no String This parameter allows to generate payer card_token which you receive in callback request to server_url. card_token allows to make recurring payments without payer card requisites using paytoken. To receive card_token please send in request value: 1
server_url no String URL API in your store for notifications of payment status change (server->server). The maximum length is 510 characters. Learn more
result_url no String Your store URL where customer will be redirected after purchasing in case of redirecting through 3ds page 3DS-verify. Maximum length 510 symbols.
receiver_card_token no String Recipient's card token. For example: B5BВB0D00B88B00ED00A00D0D
result_url no String URL in your store where the payer will be redirected after the payment. The maximum length is characters .
paytypes no String Parameter that gets the methods of payments that displayed on checkout. Possible values card - card payment, liqpay - with liqpay account, privat24 - with privat24 account, masterpass - with masterpass account, moment_part - installments, cash - cash, invoice - to email, qr - qr code scanning. If the parameter is not passed, shop settings will be applied, Checkout tab.
verifycode no String Possible Y value. Dynamic verification code is generated and going back to Callback. Also generated code will be transferred to verification transactions for displaying in statement by client's card. Works for action = auth.
token no String payment token
otp no String One time password that customer received to his phone numbert
date_from no String Start date of a report in timestamp in milliseconds
date_to no String End date of a report in timestamp in milliseconds
resp_format no String Possible report format json, csv, xml. If parameter is not passed, will be passed by default json.
phone yes String Shop phone number
public_phone no String Shop public phone number
logo no String URL shop logo
site yes String Store URL
description yes String Store description
email yes String Store e-mail
name yes String Store name
card yes * String Card number to receive payments in this store
card_exp_month yes * String Expiry month of the card
card_exp_year yes * String Expiry year of the card
card_cvv yes * String CVV/CVV2
account yes ** String Account number to receive payments in this store
mfo yes ** String Formation
okpo yes ** String OKPO of the account
company yes ** String Account name
amount_procent_agent no Number Agent fee in %
amount_static_agent no * Number Agent static fee
currency_static_agent no * String Currency of agent static fee
expired_date no String Date and time untill which customer is able to pay invoice by UTC. Should be sent in the following format 2016-04-24 00:00:00
action_payment no String Transaction type. Possible values: pay - payment, hold - amount of hold on sender's account, subscribe - regular payment, paydonate - donation
goods no String List of items
[
  {
    "amount": 1,
    "count": 2,
    "unit": "pcs.",
    "name": "USB"
  },
  {
    "amount": 10,
    "count": 1,
    "unit": "pcs.",
    "name": "Phone"
  }
]
Sender parameters
sender_first_name no String Payer first name
sender_last_name no String Payer last name
sender_country_code no String Payer card country. Digital ISO 3166-1 code
sender_city no String Payer city
sender_address no String Payer address
sender_postal_code no String Payer zip code
Receiver parameters
receiver_first_name no String Recipient first name
receiver_last_name no String Recipient last name
Regular payment parameters
subscribe no String Regular payment.Possible values: 1
subscribe_date_start no String Date of the first payment.
Time must be specified in the following format 2015-03-31 00:00:00 according to UTC. If past date is indicated - subscription will be activated with the date and time of request
subscribe_periodicity no String Period of payments.
Possible values:
month - once in a month
year - once in a year
Letter of credit parameters
letter_of_credit no String To enable receipt of payments within letter of credit send request with the value 1
letter_of_credit_date no String Letter of credit expiration date UTC. Should be sent in the following format 2015-04-24 00:00:00
3DS parameters
mpi_pares no String Parameter that returns from ACS pares.
This parameter is transmitted only in case when is used the API MPI
mpi_md no String Parameter that returns from ACS MD.
This parameter is transmitted only in case when is used the API MPI
Other parameters
product_url no String Product page address. The maximum length is 2000 characters.
product_category no String Product category in your shop. The maximum length is 25 characters.
product_name no String Product name in your shop. The maximum length is 100 characters.
product_description no String Product description in your shop. The maximum length is 500 characters.
expired_date no String Date and time untill which customer is able to pay invoice, also lifetime of checkout session by UTC. Should be sent in the following format 2016-04-24 00:00:00
info no String Information to add to payment details. For example: "External information for payments"
customer no String Unique customer ID in your shop. Max length 100 characters.
mpi_action no String Parameters defining payment type. Possible values:
pay - Acquiring
p2p - Money transfer from card to card
verifycode no String Dynamic verification code
suburl no String URL of submerchant
dae no String Detail Addenda.
Parameter dae is JSON string, to which function base64 is applied. JSON can contain the following parameters:
{
  "airLine": "DNIPROAVIA", // airline name
  "ticketNumber": "ACSFD12354SA", // ticket number
  "passengerName": "John Doe", // passenger name
  "flightNumber": "742", // flight number
  "originCity": "DP", // departure city/airport code
  "destinationCity": "NY", // arrival city/airport code
  "departureDate": "100514" // departure date, MMDDYY
}

Example of parameter dae: ewogICJhaXJMaW5lIjogIkROSVBST0FWSUEiLAogICJ0aWNr
ZXROdW1iZXIiOiAiQUNTRkQxMjM1NFNBIiwKICAicGFzc2VuZ2VyTmFtZSI6ICJKb2huIERvZSIs
CiAgImZsaWdodE51bWJlciI6ICI3NDIiLAogICJvcmlnaW5DaXR5IjogIkRQIiwKICAiZGVzdGluY
XRpb25DaXR5IjogIk5ZIiwKICAiZGVwYXJ0dXJlRGF0ZSI6ICIxMDA1MTQiCn0=
split_rules no String Payment with split amount for a few receivers. This parameter is a JSON array containing split rules. While using split_rules paarameter, card is being charged and amount is split and credited to a few receivers. Acquiring fee is being charged from each shop in the split_rules array. Example of JSON string:
[
  {
    "public_key": "i000000001",
    "amount": 1,
    "commission_payer": "sender",
    "server_url": "https://server1/callback"
  },
  {
    "public_key": "i000000002",
    "amount": 2,
    "commission_payer": "receiver",
    "server_url": "https://server2/callback"
  }
]
Example of data and signature
#!/bin/bash
PUBLIC_KEY='your_public_key'
PRIVATE_KEY='your_private_key'
JSON="{ 
\"version\" : 3,
\"public_key\" : \"${PUBLIC_KEY}\", 
\"action\" : \"pay\", 
\"amount\" : 1, 
\"currency\" : \"USD\",
\"description\" : \"description text\",
\"order_id\" : \"order_id_1\"
}"
# DATA is besa64 encode result from JSON string
DATA=$(echo -n ${JSON} | base64)
# SIGNATURE is base64 encode result from sha1 binary hash from concatenate string ${PRIVATE_KEY}${DATA}${PRIVATE_KEY}
SIGNATURE=$(echo -n "${PRIVATE_KEY}${DATA}${PRIVATE_KEY}" | openssl dgst -binary -sha1 | base64)
echo "data: ${DATA}"
echo "signature: ${SIGNATURE}"

# DATA in this example
# eyAidmVyc2lvbiIgOiAzLCAicHVibGljX2tleSIgOiAieW91cl9wdWJsaWNfa2V5IiwgImFjdGlv
# biIgOiAicGF5IiwgImFtb3VudCIgOiAxLCAiY3VycmVuY3kiIDogIlVTRCIsICJkZXNjcmlwdGlv
# biIgOiAiZGVzY3JpcHRpb24gdGV4dCIsICJvcmRlcl9pZCIgOiAib3JkZXJfaWRfMSIgfQ==

# SIGNATURE in this example
# QvJD5u9Fg55PCx/Hdz6lzWtYwcI=
$liqpay = new LiqPay($public_key, $private_key);
$html = $liqpay->cnb_form(array(
'action'         => 'pay',
'amount'         => '1',
'currency'       => 'USD',
'description'    => 'description text',
'order_id'       => 'order_id_1',
'version'        => '3'
));
HashMap params = new HashMap();
params.put("action", "pay");
params.put("amount", "1");
params.put("currency", "USD");
params.put("description", "description text");
params.put("order_id", "order_id_1"); 
params.put("version", "3"); 
LiqPay liqpay = new LiqPay(PUBLIC_KEY, PRIVATE_KEY);
String html = liqpay.cnb_form(params);    
System.out.println(html);
 
liqpay = LiqPay(public_key, private_key)
html = liqpay.cnb_form({
"action"         : "pay",
"amount"         : "1",
"currency"       : "USD",
"description"    : "description text",
"order_id"       : "order_id_1",
"version"        : "3"
})
liqpay = Liqpay::Liqpay.new(
:public_key  => 'public_key',
:private_key => 'private_key'
)
html = liqpay.cnb_form({
:action         => "pay",
:amount         => "1",
:currency       => "USD",
:description    => "description text",
:order_id       => "order_id_1",
:version        => "3"
})
LiqPay = liqpay:init(PublicKey, PrivateKey),
Html = liqpay:cnb_form([ 
{<<"action">>,      <<"pay">>}, 
{<<"amount">>,      <<"1">>}, 
{<<"currency">>,    <<"USD">>}, 
{<<"description">>, <<"description text">>}, 
{<<"order_id">>,    <<"order_id_1">>},
{<<"version">>,     <<"3">>}
], LiqPay)
var LiqPay = require('liqpay');
var liqpay = new LiqPay(public_key, private_key);
var html = liqpay.cnb_form({
'action'         : 'pay',
'amount'         : '1',
'currency'       : 'USD',
'description'    : 'description text',
'order_id'       : 'order_id_1',
'version'        : '3'
});
my $liqpay = Liqpay->new($public_key,$private_key);
my $html = $liqpay->cnb_form({
'action'         => 'pay',
'amount'         => '1',
'currency'       => 'USD',
'description'    => 'description text',
'order_id'       => 'order_id_1',
'version'        => '3'
}
);
Example of the HTML form
	<form method="POST" action="https://www.liqpay.com/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.com/buttons/p1ru.radius.png"/>
	</form>
	
Example of JS widget
	<div id="liqpay_checkout"></div>
	<script>
	window.LiqPayCheckoutCallback = function() {
	    LiqPayCheckout.init({
			data: "eyAidmVyc2lvbiIgOiAzLCAicHVibGljX2tleSIgOiAieW91cl9wdWJsaWNfa2V5IiwgImFjdGlv" +
			"biIgOiAicGF5IiwgImFtb3VudCIgOiAxLCAiY3VycmVuY3kiIDogIlVTRCIsICJkZXNjcmlwdGlv" +
			"biIgOiAiZGVzY3JpcHRpb24gdGV4dCIsICJvcmRlcl9pZCIgOiAib3JkZXJfaWRfMSIgfQ==",
			signature: "QvJD5u9Fg55PCx/Hdz6lzWtYwcI=",
			embedTo: "#liqpay_checkout",
			mode: "embed" // embed || popup
	    }).on("liqpay.callback", function(data){
	    	console.log(data.status);
	    	console.log(data);
	    }).on("liqpay.ready", function(data){
	    	// ready
	    }).on("liqpay.close", function(data){
	    	// close
	    });
	};
	</script>
	<script src="//static.liqpay.com/libjs/checkout.js" async></script>