Payment (Action) Links Variable Reference

Using our Payment Links API you can program payment buttons and links, as well as links for subscriptions and pre-approved billing signup. These links are the same kind as those created with the Button Generator, however, Payment Links API offers more advanced features. Refer to the Integration Guides for practical examples of payment links and buttons usage for various applications.

Specifying HTML variables

When you create a button, you must specify the same HTML variables that you use with a Button Generator.

The following table provides additional information about these variables.

HTML Variable Required or Optional Description Length, characters

Receiver parameters

ok_receiver Required One of the following: e-mail address/mobile phone number or wallet ID. 127

Common parameters

ok_kind Optional Allowed values: payment (payment checkout), subscription (subscription checkout), or preapproved (pre-approved payments contract) . By default, if this variable is omitted OKPAY handles it as a payment and validates the supplied parameters accordingly. 127
ok_currency Optional The currency of the payment. The default is EUR. For valid values see Currency Codes. 3
ok_invoice Optional Invoice reference number or ID. Pass-through variable for you to track the product or service purchased or contribution made. The value you specify is passed back to you upon payment completion (you can use it in your IPN handler or Auto Return URLs). Please note: the value of this parameter has to be unique, otherwise payments with the same Invoice will be forbidden, e.g. the corresponding exception will be thrown. 127
ok_tag Optional Optional tag number or ID. Pass-through variable for you to track the product or service purchased or contribution made. The value you specify is passed back to you upon payment completion (you can use it in your IPN handler or Auto Return URLs). Please note: the value of this parameter does not have to be unique. 127
ok_fees Optional This field can assume one of two values. “0” – commission payable by the merchant (default); “1” – commission payable by the buyer. 1

Payment parameters (ok_kind=payment)

ok_item_#_name Required Name of the item. 127
ok_item_#_article Optional Item article number. Pass-through variable for you to track the product or service purchased or contribution made. The value you specify is passed back to you upon payment completion (you can use it in your IPN handler or Auto Return URLs). 40
ok_item_#_type Optional One of item types. The default is digital. 64
ok_item_#_quantity Optional Number of items as entered by your customer or as passed by you, the merchant. This will multiply the amount if greater than one. 8
ok_item_#_price Optional Item price. Limitations: the value must be a positive number; there must be no currency symbol; there must be two decimal places; the decimal separator must be a period (.) and the optional thousands separator must be a comma (,).
The total amount for each item will be calculated as follows:
ItemTotal = ok_item_#_price * ok_item_#_quantity + ok_item_#_tax + ok_item_#_handling + ShippingTotal (see bottom);
15
ok_item_#_handling Optional Used only when the merchant applies a handling charge for a specific item. 15
ok_item_#_shipping Optional Used only when the merchant applies a shipping charge for a specific item.
Total shipping for each item will be calculated as follows:
ShippingTotal = ok_item_#_shipping + ok_item_#_shipping2 * (ok_item_#_quantity -1);
15
ok_item_#_shipping2 Optional The cost of shipping for each additional item. 15
ok_item_#_tax Optional Used only when the merchant applies a tax charge for a specific item. 15
ok_item_#_custom_1_title Optional Custom field 1 title as passed by you, the merchant. 127
ok_item_#_custom_1_value Optional Custom field 1 value as entered by your customer or as passed by you, the merchant. 127
ok_item_#_custom_2_title Optional Custom field 2 title as passed by you, the merchant. 127
ok_item_#_custom_2_value Optional Custom field 2 value as entered by your customer or as passed by you, the merchant. 127

Subscription parameters (ok_kind=subscription)

ok_s_title Required Text title describing this particular type of subscription. It will be displayed to the customer during checkout and subsequently, can be used to group the subscriptions inside your account profile (in Merchant' Subscriptions Billing). 200
ok_s_type Optional One of item types. The default is digital. 64
ok_s_reattempt_days Optional Number of days OKPAY will try to attempt collection of an outstanding balance from a customer. If payment cannot be collected after the specified number of days have passed, the subscription will be canceled. Enter "0" (zero) for instant subscription cancellation on first failed payment, and "-1" means that the number of attempts is unlimited.. 8
ok_s_reattempt_accum Optional This field can assume one of two values. “0” – on reattempt the system will not charge more than the price of the next billing cycle (default); “1” – system will add all previous payments that failed to the next bill. 1
ok_s_setup_price Optional Amount that can be charged only once at the moment of subscribing. Example of valid values: "2.99", "20", etc. 15
ok_s_trial_cycle Optional Trial period is a timeframe during which the subscription price is usually less or free. The cycle multiplier can be calculated in days - "D" (up to 365), weeks - "W" (up to 52), months - "M" (up to 12) or years -"Y" (up to 10). The number must be separated from multiplier by a space. Example of valid values: "1 W", "5 D", "2 M", "1 Y", etc. 5
ok_s_trial_price Optional A single cycle price during the trial period. If ok_s_trial_cycle and ok_s_trial_count variables are set to valid values and ok_s_trial_price value is 0 (zero) or this parameter is omitted, then the trial period of subscription will be considered free of charge. 15
ok_s_trial_count Optional Number of cycles (with a step of ok_s_trial_cycle) when trial subscription payment will be charged. A value of 0 (default) implies that the subscription does not have a trial period. 8
ok_s_regular_cycle Required Regular (main) subscription billing cycle. Use the same format as for ok_s_trial_cycle. 1
ok_s_regular_price Required Price of the regular (main) subscription cycle. 127
ok_s_regular_count Optional Number of cycles (with a step of ok_s_regular_cycle) for which a regular subscription payment will be charged. A value of 0 (default) implies that the subscription will continue until it is cancelled by a customer or by the merchant. 8

Pre-approved Payment parameters (ok_kind=preapproved)

ok_p_title Required Text title describing this particular type of pre-approved payments contract. It will be displayed to the customer during checkout and subsequently can be used to group the pre-approved payments contract inside your account profile (in Merchant' Pre-approved Payments). 200
ok_p_end_date Optional Termination date of the contract after which it will be automatically expired. Date and time is in the following format: "YYYY-MM-DD hh:mm:ss". 8
ok_p_limits_total Optional Allows you to specify the total maximum amount of payments by this pre-approved payment contract. 8
ok_p_limits_monthly Optional Allows you to specify the monthly maximum amount of payments by this pre-approved payment contract. 8
ok_p_limits_weekly Optional Allows you to specify the weekly maximum amount of payments by this pre-approved payment contract. 8
ok_p_limits_daily Optional Allows you to specify the daily maximum amount of payments by this pre-approved payment contract. 8

Payer parameters

If this information is provided, it will be used to pre-fill the appropriate fields of the registration form for a new OKPAY client.

General

ok_payer_first_name Optional

Customer's first name. Use only letters of English alphabet.

64
ok_payer_last_name Optional

Customer's last name. Use only letters of English alphabet.

64
ok_payer_birthdate Optional

Customer's date of birth in the yyyy-MM-dd format.

64
ok_payer_birthplace Optional

Customer's place of birth. Use only letters of English alphabet.

64
ok_payer_document_id Optional

Customer's ID document number. Use only letters of English alphabet and digits.

64
ok_payer_business_name Optional

Customer's company name, if the customer is a business. Use only letters of English alphabet.

127
ok_payer_email Optional

Customer's email address. Use only letters of English alphabet.

127
ok_payer_phone Optional

Customer's telephone number. Use only letters of English alphabet.

20

Address

ok_payer_country_code Optional

ISO 3166 country code associated with customer's address. Use only letters of English alphabet.

2
ok_payer_country Optional Country of customer's address. Use only letters of English alphabet. 64
ok_payer_city Optional City of customer's address. Use only letters of English alphabet. 40
ok_payer_state Optional

State/province of customer's address. Use only letters of English alphabet.

40
ok_payer_street Optional

Customer's street address. Use only letters of English alphabet.

200
ok_payer_zip Optional

Zip/postal code of customer's address. Use only letters of English alphabet.

20

Extra parameters

ok_return_success Optional The URL to which the payer's browser is redirected after completing the payment; for example, a URL on your site that displays a “Thank you for your payment” page. By default, the browser is redirected to an OKPAY web page. 127
ok_return_fail Optional A URL to which the payer's browser is redirected if payment is cancelled; for example, a URL on your website that displays a “Payment Canceled” page. By default, the browser is redirected to an OKPAY web page. 127
ok_ipn Optional The URL to which OKPAY posts information about the transaction, in the form of Instant Payment Notification messages. 127
ok_language Optional The language of the log-in or sign-up page for a payer. If unspecified, the language is determined by an OKPAY cookie in the customer's browser. If there is no OKPAY cookie, the language is selected automatically by IP address or browser language. 2

Payment methods

ok_payment_methods Optional You can display only selected payment methods on the OKPAY checkout pages by specifying this variable. Enter the three-character code of one or more of the OKPAY payment instruments listed on the Payment Methods Reference page separated by a space, for instance, "okpay qiwi moneypolo". Learn more in our Payment Integration Guide. 127
ok_direct_payment Optional This variable allows the user to skip selection of the available payment options on the OKPAY checkout page and continue with a different payment option instead. For example, by designating "moneypolo", the client will see the MoneyPolo checkout page. Available OKPAY payment instruments are listed on the Payment Methods Reference page. Learn more from our Payment Integration Guide. 3
OKPAY RSS
OKPAY Forum
OKPAY on Facebook
OKPAY on Livejournal
OKPAY on Twitter
OKPAY on VK
OKPAY on Linkedin
OKPAY on Youtube