Payment Integration Guide

Learn how to use HTML forms so that you can integrate OKPAY into your website or e-commerce application in order to receive payments. With OKPAY you add buttons to your webpages for different types of payments. Shoppers click the payment buttons to pay for their purchases.

Table of contents:

§1. General Information

OKPAY electronic payment solution provides extensive processing features for merchants selling digital content, services and physical goods (buyer will be asked to provide a shipping address). It can also be used for donations. Your clients can pay with their OKPAY wallet balance as well as by additional payment methods activated for your business/wallet.

Note: Merchant functionality is only available to a verified corporate account owners. Read more in the General Reference Guide for Merchants.

OKPAY offers you the following beneficial features:

  • Receive payments in any of the 21 supported world currencies.
  • In addition to prices you can set shipping and handling fees as well as taxes. This information is displayed on the checkout pages.
  • Charge payments for digital content, services and physical goods (buyer will be asked to provide a shipping address) and even for donations.
  • Combine several items within one payment (shopping cart contents) so that the buyer pays only once for several goods and/or services.
  • A transaction fee can be paid either by the seller (you) or the buyer (your client), depending on your settings. If you pay the fee, regardless of the chosen payment method, the client will only be charged a specified price and you will receive the remaining amount after all commissions (amount minus fees). If the buyer pays the fee, the exact amount you specified will be credited to your OKPAY account and the client pays a little more (amount plus fees).
  • Your clients can use any of the payment methods activated for your business/wallet.

The image below shows an average buying process in an online store. Depending on your type of business, the process may look slightly different.

Figure 1. Scheme of the buying process.

Scheme of the buying process.

In order to accept payments, your website must feature a special payment link (or graphical button). Clients using a payment link are redirected from your website to a checkout page where they complete their payment. With the Auto Return feature enabled, your customers are then quickly returned to your site.

Merchants receive an e-mail notification of each payment received from customers. OKPAY also uses an IPN notification service to transfer all the necessary technical details to your website/back office application.

All payments are instantly displayed on the main page of your OKPAY account. You can split the cash flows of different groups of goods/websites into different wallets, allowing you to simplify your accounting and perform a quick search and navigation. See Managing Payments via Web Interface.

Figure 2. Transactions list.

Almost any task carried out using the web interface can also be performed via OKPAY API.

We will explain these steps and features in detail.

In order to let your customers pay for a product or service, you need to create a special URL link to be placed on your website. Use Button Generator or manually create a URL using variables described in the Payment Links Variable Reference.

The easiest way is to use Button Generator. The resulting automatic code is no different from one created manually.

Note: To learn more about general payment links and button usage, see Payment Links section of the Comprehensive Manual.

Here are some examples of how one can create and use different types of payment buttons. You can combine variables to create your own custom payment forms:

A detailed description of payment button variables can be found in Payment Links Variable Reference, section Payment Links of Comprehensive Manual.



Basic Payment

The Basic Payment form is the simplest way to sell any type of digital goods or receive payent for a service. As an example, we will use it to sell an OKPAY poster.
The form contains only the minimum required variables such as ok_item_1_name, ok_item_1_price, ok_currency.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD"></a>
buy now

- View the checkout page example in action.




Basic Payment with Invoice

The Basic Payment with Invoice payment form works the same way as the Basic Payment form except that you can also add a custom invoice number to the transaction. An invoice number can be used to identify the order in the merchant's system. For example, invoice number "99999" will be assigned to the OKPAY poster.
An invoice variable ok_invoice is added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
   <input type="hidden" name="ok_invoice" value="99999"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD&ok_invoice=99999"></a>
buy now

- View the checkout page example in action.




Several Items

The Several Items payment form is useful for selling more than one product. This is a required feature for online stores with a "Shopping Cart". The buyer will pay for several items within a single payment transaction.
Additional item variables ok_item_N_name, ok_item_N_price, ok_item_N_article are added to the payment form, where N is an item number.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_item_1_article" value="555"/>
   <input type="hidden" name="ok_item_2_name" value="Robot"/>
   <input type="hidden" name="ok_item_2_price" value="50"/>
   <input type="hidden" name="ok_item_2_article" value="777"/>
   <input type="hidden" name="ok_currency" value="USD"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_item_1_article=555&ok_item_2_name=Robot&ok_item_2_price=50&ok_item_2_article=777&ok_currency=USD"></a>
buy now

- View the checkout page example in action.




Item Quantity

The Item Quantity payment form allows the merchant to specify the quantity of the product. For example Quantity "3" will be assigned to the OKPAY poster.
A quantity variable ok_item_1_quantity is added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_item_1_quantity" value="3"/>
   <input type="hidden" name="ok_currency" value="USD"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_item_1_quantity=3&ok_currency=USD"></a>
buy now

- View the checkout page example in action.




Shipping

The Shipping payment form is required for merchants selling tangible goods. Buyers will need to log in to their OKPAY account, select a payment method and enter a shipping address.
A shipping variable ok_item_1_shipping is added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_item_1_type" value="shipment"/>
   <input type="hidden" name="ok_item_1_shipping" value="10"/>
   <input type="hidden" name="ok_currency" value="USD"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_item_1_type=shipment&ok_item_1_shipping=10&ok_currency=USD"></a>
buy now

- View the checkout page example in action.




Taxes and Handling

The Taxes and Handling payment form includes shipping, handling and sales tax information. In addition to asking for a shipping address, merchants selling tangible goods can also include handling and sales tax charges in the total price. Buyers will need to log in to their OKPAY account, select a payment method and then enter a shipping address.
A shipping variable ok_item_1_shipping, ok_item_1_handling, ok_item_1_tax is added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_item_1_shipping" value="10"/>
   <input type="hidden" name="ok_item_1_handling" value="7"/>
   <input type="hidden" name="ok_item_1_tax" value="3"/>
   <input type="hidden" name="ok_currency" value="USD"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_item_1_shipping=10&ok_item_1_handling=7&ok_item_1_tax=3&ok_currency=USD"></a>
buy now

- View the checkout page example in action.




Payment Argument

The Payment Argument form provides an additional information input field. Merchants can create a custom information box on the checkout page to request additional information from a client: account number, transfer number, order details, etc. It will feature as a required field in order to complete the payment transaction.
A Payment Argument variable ok_item_1_custom_1_title with the value "Description" is added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
   <input type="hidden" name="ok_item_1_custom_1_title" value="Description"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD&ok_item_1_custom_1_title=Description"></a>
buy now

- View the checkout page example in action.




Custom Payment Arguments

The Custom Payment Arguments form allows merchants to add their own custom variables. Merchants can create custom information rows on the checkout page with additional information: description, order details, customer info, etc.
A Custom Payment Argument variable ok_item_1_custom_1_title with the value "Description" and ok_item_1_custom_1_value with the value "OKPAY Company promo wall poster" are added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
   <input type="hidden" name="ok_item_1_custom_1_title" value="Description"/>
   <input type="hidden" name="ok_item_1_custom_1_value" value="OKPAY Company promo wall poster"/>
   <input type="hidden" name="ok_item_1_custom_2_title" value="Size"/>
   <input type="hidden" name="ok_item_1_custom_2_value" value="A1 Poster"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD&ok_item_1_custom_1_title=Description&ok_item_1_custom_1_value=OKPAY Company promo wall poster&ok_item_1_custom_2_title=Size&ok_item_1_custom_2_value=A1 Poster"></a>
buy now

- View the checkout page example in action.




Custom Price

The Custom Price payment form is an ideal option for a merchant who allows buyers to pay as much as they want. It is the perfect solution for donation purposes. Buyers manually enter the amount they desire to pay.
Please note that no additional variable is required. You just need to remove the ok_item_1_price variable from the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_currency" value="USD"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_currency=USD"></a>
buy now

- View the checkout page example in action.




Commission on Buyer

The Commission on Buyer payment form specifies that the buyer will be paying the transaction fee. Buyers will see the total product/service price and the amount they will need to pay with each of the payment options. This amount will include the total price plus the transaction fee.
A commission variable ok_fees with a value "1" is added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
   <input type="hidden" name="ok_fees" value="1"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD&ok_fees=1"></a>
buy now

- View the checkout page example in action.




Custom Payment Options

The Custom Payment Options payment form is useful for merchants who want to accept only certain payment instruments for specific products/services. In this case, buyers can only use OKPAY e-currency and merchant-specified payment method(s) to pay for an item.
In the example below, the variable ok_payment_methods is added to the payment form with the value "moneypolo", i.e. we will only accept MoneyPolo (the custom value determines which payment methods will be available during checkout).

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
   <input type="hidden" name="ok_payment_methods" value="moneypolo"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD&ok_payment_methods=moneypolo"></a>
buy now

- View the checkout page example in action.




Direct Payment Processing

The Direct Payment Processing form can be used to skip the payment methods selection page during checkout. This is especially useful when buyers have already stated a payment choice on the merchant's website and it is not necessary to repeat the same choice on the OKPAY checkout page. The merchant just forwards buyers directly to the particular Payment System processing page, bypassing some initial checkout pages. Please note that buyers will no longer be able to select other payment methods than what is specified.

In the general example below we select MoneyPolo for direct payment. The variable ok_direct_payment with a custom payment method value is added to the payment form.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
   <input type="hidden" name="ok_direct_payment" value="moneypolo"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD&ok_direct_payment=moneypolo"></a>
buy now

- View the checkout page example in action.


 

In the specific example below we will choose a Visa/MasterCard as a direct payment method. In order to process card payment without asking a client to enter personal information on the OKPAY Checkout page we need to provide data for the following variables using letters of English alphabet and digits: ok_payer_email, ok_payer_phone, ok_payer_country_code, ok_payer_city, ok_payer_street, ok_payer_zip, ok_payer_first_name, ok_payer_last_name in addition to the ok_direct_payment variable.

<form  method="post" action="https://checkout.okpay.com/">
   <input type="hidden" name="ok_receiver" value="OK823912027"/>
   <input type="hidden" name="ok_item_1_name" value="OKPAY Poster"/>
   <input type="hidden" name="ok_item_1_price" value="100"/>
   <input type="hidden" name="ok_currency" value="USD"/>
   <input type="hidden" name="ok_direct_payment" value="VMF"/>
   <input type="hidden" name="ok_payer_email" value="email@email.com"/>
   <input type="hidden" name="ok_payer_phone" value="+123456789"/>
   <input type="hidden" name="ok_payer_country_code" value="US"/>
   <input type="hidden" name="ok_payer_city" value="City"/>
   <input type="hidden" name="ok_payer_street" value="Street"/>
   <input type="hidden" name="ok_payer_zip" value="123456"/>
   <input type="hidden" name="ok_payer_first_name" value="First Name"/>
   <input type="hidden" name="ok_payer_last_name" value="Last Name"/>
<input type="image" name="submit" alt="OKPAY Payment" src="https://download.okpay.com/images_buttons/en/buy/b07g56x35en.png" />
</form>
<a href="https://checkout.okpay.com/?ok_receiver=OK823912027&ok_item_1_name=OKPAY Poster&ok_item_1_price=100&ok_currency=USD&ok_direct_payment=VMF&ok_payer_email=email@email.com&ok_payer_phone=+123456789&ok_payer_country_code=US&ok_payer_city=City&ok_payer_street=Street&ok_payer_zip=123456&ok_payer_first_name=First Name&ok_payer_last_name=Last Name"></a>
buy now

- View the checkout page example in action.


 

By displaying your relationship with OKPAY you demonstrate to your customers your commitment to improving their shopping experience. The more customers know about this new payment method and the flexibility of your overall payment solution, the more customers will use it and return to your website.

Displaying logos and information on your homepage, cashier/top-up pages and in your Help or Support section ensures that customers are always aware of the flexibility of payment methods. Providing a range of payment methods offers your customers a choice, which is highly valued and enables you to stay ahead of your competition.

Payment buttons

You can place payment buttons on your website to attract customers and display payment methods.

Figure 3. Payment button variations.

Displaying payment methods available via OKPAY

In order to boost sales and convert more visitors into buyers, in addition to placing OKPAY graphics on your website we also recommend inserting graphics of additional payment methods supported by OKPAY. This increases spontaneous purchases and general confidence in your website. Please note that you need to activate extra payment methods for your business first. See the sample below:

Figure 4. Example of a "Select Payment Method" page.

Hint: Feel free to use the graphics from the OKPAY Brand Center.

Displaying OKPAY logo and information on your homepage

We recommend then you place the OKPAY logo on your website's homepage along with any other accepted payment methods. Upon seeing a list of available payment options, customers are likely to choose a familiar and convenient payment method - OKPAY (see figure below).

Figure 5. Example of the homepage.

Footer

Please ensure that a link to the OKPAY homepage (www.okpay.com) is always inserted 'behind' the logo.

If you require any extra information please contact OKPAY Support Desk.

Clients click on a payment link and are directed to the first checkout page to select a method of payment. In some cases there are options to enter the amount to pay and/or enter order options.

Note: The image below shows merchant logo, order description as well as available payment methods and fees.

Figure 6. Checkout page sample: payment method section.

Hint: You can change the layout of available payment methods for your business on the checkout pages in the wallet preferences.

Figure 7. Checkout page sample: providing payment instructions.

Clients may need to log in to their account or proceed with another checkout page upon selection of certain payment methods.

Hint: The generated payment link is not assigned to a particular session and remains active for 24 hours. This URL can be safely saved for later or even transferred to another user to complete the payment on another computer.

You can set up the URL to which OKPAY redirects the buyers' browser after payment is complete. For example, specify a URL on your site that displays a "Thank you for your payment" page. Furthermore, you can specify an additional return URL in case of payment cancellation/failed payment.

As a default (if no corresponding return URL is provided), the buyer simply remains on the OKPAY webpage displaying appropriate messages.

To learn more about the auto-return feature, see Auto Return URLs (section of Payment Links of the Comprehensive Manual).

§3. Handling IPN Messages

Receive instant IPN notification of a new payment and perform required actions in your information system, i.e. automatically credit a client's account or complete an order. Additionally, you receive IPN messages when a transaction is frozen (held), canceled, etc.

The specific features of IPN are described below with regard to receiving payments. For a general understanding of the IPN mechanism, please refer to the IPN section of the Comprehensive Manual.

§3.1. IPN Handler Setup

In order to use IPN, you first need to inform OKPAY where the IPN handler script is located on your server, as follows:

  • In wallet settings (Under the main menu find Profile column » Payment Accounts » select wallet and open Integration tab. Tick the "Enable IPN" checkbox under "Payment Notification [IPN]" and enter the URL address of your IPN handler);
  • Dynamically in the payment link by specifying the IPN handler address in ok_ipn.

Read more on how to set up an IPN handler. If you are looking for more information on IPN, for example, basic code writing rules, testing, IPN messages history, etc., refer to the IPN section of the Comprehensive Manual.

§3.2. Writing Handler Code

General code writing rules for the IPN handler can be found in the Implementing a Generic IPN Listener section of the Comprehensive Manual.

For proper and safe handling, first verify that the received IPN is genuine by sending the request to OKPAY for validation (as mentioned in the paragraphs 1-5 here). Thereafter, make sure that it has not been handled before by checking the ok_ipn_id or unique transaction ID ok_txn_id.

Hint: Each IPN message has a unique ID which is transferred in ok_ipn_id. You can check for this variable in order to avoid duplicates. If you use this mechanism do not forget to label a successfully processed IPN in your database.

In the handler code you have to consistently check and make sure that all items in the IPN payment are correct:

  • To identify an incoming IPN as a payment you need to lookup up the ok_txn_kind variable which should be equal to ok_txn_kind=payment_link;
  • Check that the recipient's wallet number ok_receiver_wallet, account ID ok_receiver_id or e-mail address ok_receiver_email belongs to you;
  • Depending on the ok_txn_status=completed, take further action. The list of available statuses can be found in the Transaction Statuses Enumeration;
    • Completed - The transaction has been successfully completed. Before you fund the client's account or send ordered goods it is important to:
      • Check the incoming amount - ok_txn_net (amount minus OKPAY fee) or ok_txn_gross (amount charged from a client) and make sure the ok_txn_gross value matches the value transferred in the payment link;
      • Check whether the currency of the payment ok_txn_currency, corresponds to the expected value;
      • Check whether a transaction with this ID ok_txn_id has been processed before.
    • Pending - A client's intention to make a payment in your favor has been obtained but the transaction is not completed. You do not need to process this order before another IPN with a Completed status is received. In fact, actual payment has not been made ​​by the client yet;
    • Reversed - A transaction with ID transferred in ok_txn_id including all fees has been reversed. You need to stop processing the order and/or block the client in your system;
    • Error - An error occurred during execution of the transaction;
    • Canceled - A transaction with ID transferred in ok_txn_id has been canceled. Corresponding fees may be deducted from your account. You need to stop processing the order and/or block the client in your system;
    • Held - A transaction with ID transferred in ok_txn_id has been frozen until required conditions are met or the actual transfer is received on your account. You need to stop processing the order and/or block the client in your system.

Hint: Learn more about transaction statuses in General Reference Guide for Merchants, subsection Transaction Statuses.

In Code Samples in Various Programming Languages you can find a detailed example of how IPN handler payment processing should look. You can use this example to create your own handler.

§3.3. Testing Your IPN Handler

OKPAY contains an IPN simulator to test message handling of your scripts. This functionality is described in the IPN Testing subsection of the Comprehensive Manual.

An IPN payments simulator can be used for initial testing of your source code. For more thorough real-world testing of your business logic please refer to Final Testing of Payment Processing.

§4. Using API Functions: Managing Payments via API

The OKPAY system allows you to fully automate your organization's payment processing. API functions can be used for advanced integration. You can automatically receive information about payments, check balances, etc., right inside your information system. To implement these features your IT specialists should write a code that uses the appropriate API functions as listed below:

  • Balance - Returns specified wallet balance for all currencies.
  • Transactions - Returns transaction history for the selected period.
  • SendMoney - Transfers money with OKPAY e-currency.

Please note that only a small number of the functions related to payment processing is mentioned above. The full list of API functions can be found on the API Functions page.

An example of API Functions calls can be found in the Code Samples section on the individual function page.

§5. Managing Payments via Web Interface

More detailed information on topics related to understanding the transaction of your account and accepting payments can be found in the General Reference Guide for Merchants:

Read more at General Reference Guide for Merchants.

§6. Final Testing of Payment Processing

As we explained in Testing Your IPN Handler, you can check the basic transaction of your handler by using the offered IPN simulation service.

In addition, for final and more complete testing of your code as well as business-logic transaction, you may need additional real-world testing with real clients and OKPAY system replies.

We recommend that you create a test account under the name of your developer which can be used to perform test payments. You can temporarily amend the price of your goods/services to $0.01 USD for this purpose.

If you have any questions or problems feel free to contact OKPAY Support Service. Our technicians are happy to assist you.

§7. Code Samples in Various Programming Languages

For your reference, several examples of accepting payments with OKPAY are provided in popular programming languages.

  1. IPN message handler example.
  2. API class example for accepting payments.

Sample in PHP
 <?php
 	/* Check IPN and process payment */
 	error_reporting(E_ALL ^ E_NOTICE);
 
 	// Read the post from OKPAY and add 'ok_verify'
 	$request = 'ok_verify=true';
 
 	foreach ($_POST as $key => $value) {
 		$value = urlencode(stripslashes($value));
 		$request .= "&$key=$value";
 	}
 
 	$fsocket = false;
 	$result = false;
 
 	// Try to connect via SSL due sucurity reason
 	if ( $fp = @fsockopen('ssl://checkout.okpay.com', 443, $errno, $errstr, 30) ) {
 		// Connected via HTTPS
 		$fsocket = true;
 	} elseif ($fp = @fsockopen('checkout.okpay.com', 80, $errno, $errstr, 30)) {
 		// Connected via HTTP
 		$fsocket = true;
 	}
 
 	// If connected to OKPAY
 	if ($fsocket == true) {
 		$header = 'POST /ipn-verify HTTP/1.1' . "\r\n" .
 				  'Host: checkout.okpay.com'."\r\n" .
 				  'Content-Type: application/x-www-form-urlencoded' . "\r\n" .
 				  'Content-Length: ' . strlen($request) . "\r\n" .
 				  'Connection: close' . "\r\n\r\n";
 
 		@fputs($fp, $header . $request);
 		$string = '';
 		while (!@feof($fp)) {
 			$res = @fgets($fp, 1024);
 			$string .= $res;
 			// Find verification result in response
 			if ( $res == 'VERIFIED' || $res == 'INVALID' || $res == 'TEST') {
 				$result = $res;
 				break;
 			}
 		}
 		@fclose($fp);
 	}
 
 	if ($result == 'VERIFIED') {
 		// check the "ok_txn_status" is "completed"
 		// check that "ok_txn_id" has not been previously processed
 		// check that "ok_receiver_email" is your OKPAY email
 		// check that "ok_txn_gross"/"ok_txn_currency" are correct
 		// process payment
 
 
 
 	} elseif($result == 'INVALID') {
 		// If 'INVALID': log for manual investigation.
 
 
 	} elseif($result == 'TEST') {
 		// If 'TEST': do something
 
 
 	} else {
 		// IPN not verified or connection errors
 		// If status != 200 IPN will be repeated later
 
 		header("HTTP/1.1 404 Not Found");
 		exit;
 	}
 ?>
Sample in C#
 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Web;
 using System.Web.Mvc;
 
 namespace Web.Controllers
 {
   public class ProcessController : Controller
   {
 		public ActionResult Process()
 		{
 			try
 			{
 				var data = new Dictionary<string, string>();
 				foreach (var item in Request.Form)
 				{
 					if (item == null || string.IsNullOrWhiteSpace(item.ToString()))
 					continue;
 
 					data[item.ToString()] = Server.HtmlDecode(Request.Form[item.ToString()]);
 				}
 				processPayment(data);
 			}
 			catch (Exception ex)
 			{
 				//log Exception
 				return  new HttpStatusCodeResult(500);
 			}
 			return new EmptyResult();
 		}
 
 		private void processPayment(Dictionary<string, string> parameters)
 		{
 			parameters = parameters.OrderBy(x => x.Key).ToDictionary(x => x.Key, x => x.Value);
 
 			var req = (System.Net.HttpWebRequest)System.Net.WebRequest.Create("https://checkout.okpay.com/ipn-verify");
 
 			var formatInfo = new System.Globalization.NumberFormatInfo { NumberDecimalSeparator = "." };
 
 			//Set values for the request back
 			req.Method = "POST";
 			req.ContentType = "application/x-www-form-urlencoded";
 
 			var sb = new System.Text.StringBuilder(150);
 			sb.Append(string.Join("&",
 		parameters.Keys.Select(p => string.Format("{0}={1}", p, System.Web.HttpUtility.UrlEncode(parameters[p])))));
 
 			sb.Append("&ok_verify=true");
 
 			req.ContentLength = sb.ToString().Length;
 
 			var streamOut = new System.IO.StreamWriter(req.GetRequestStream(), System.Text.Encoding.ASCII);
 			streamOut.Write(sb.ToString());
 			streamOut.Close();
 			var streamIn = new System.IO.StreamReader(req.GetResponse().GetResponseStream());
 			var strResponse = streamIn.ReadToEnd();
 			streamIn.Close();
 
 
 			if (strResponse != "VERIFIED")
 			{
 				//log for manual investigation
 				throw new Exception("Validation Failed: " + strResponse);
 			}
 
 
 			var invoiceID = parameters["ok_invoice"];
 			if (invoiceID == null)
 			{
 				throw new Exception(string.Format("Wrong invoiceID({0})", parameters["ok_invoice"]));
 			}
 
 			var amount = decimal.Parse(parameters["ok_txn_gross"], formatInfo);
 			if (amount <= 0)
 			{
 				throw new Exception("Failed to Process Amount");
 			}
 
 			var net = decimal.Parse(parameters["ok_txn_net"], formatInfo);
 			if (net <= 0)
 			{
 				throw new Exception("Failed to Process Amount");
 			}
 
 			var fees = decimal.Parse(parameters["ok_txn_fee"], formatInfo);
 			if (fees < 0)
 			{
 				throw new Exception("Failed to Process Amount");
 			}
 
 			//check the "ok_txn_status" is "completed"
 			if (parameters["ok_txn_status"] != "completed")
 			{
 				throw new Exception("Transaction status failed: " + strResponse);
 			}
 
 			//check that "ok_txn_id" has not been previously processed
 			//check that "ok_receiver_email" is your OKPAY email
 			//check that "ok_txn_gross"/"ok_txn_currency" are correct
 
 
 			//process payment
 		}
    }
 }
OKPAY RSS
OKPAY Forum
OKPAY on Facebook
OKPAY on Livejournal
OKPAY on Twitter
OKPAY on VK
OKPAY on Linkedin
OKPAY on Youtube