IPN Variable Reference

ATTENTION: OKPAY Subscription and Pre-approved Billing as well as Client Verification services are temporarily unavailable. The functionality will be added in the nearest future.

OKPAY returns certain variables with every IPN message. Not all variables listed below may always be returned.

Variables with Enumerable Values

Transaction Kind

Typically, your back-end or administrative processes will perform specific actions based on the IPN message received. You can use the ok_txn_kind variable in the message to trigger the processing you want.

Transaction Kind (ok_txn_kind) Description
mass_pay

Payment received; the source is the OKPAY Mass Payment option.

SendMoney

Payment received; the source is the OKPAY Send Money option.

payment_link

Payment received; the source is an OKPAY Payment Link or Button.

marketplace Payment received; the source is the OKPAY Marketplace.
subscription Payment received; the source is an OKPAY Subscription.
verification Verification events.
recurring Payment received; the source is an OKPAY Recurring Payment.
preapproved Pre-approved payment events.

Transaction Payment Method

Use the ok_txn_payment_method variable in the message to find out how the operation was performed. The variable contains the three-char code of one of the OKPAY payment instruments listed on the Payment Methods Reference page.

Transaction Status

Use the ok_txn_status variable in the message to learn the status of the payment. You would apply different processing depending on the status values below.

Transaction Status (ok_txn_status) Description
completed

The operation has been completed and the funds have been successfully added to your account balance.

pending The operation is pending. See ok_txn_pending_reason for more information.
reversed The operation has been reversed together with all the related commission payments (if any).
error An error occurred during the operation processing.
canceled The operation has been canceled; transaction fees in this case are not returned.
hold The operation is held.

Transaction Pending Reason

The ok_txn_pending_reason variable provides additional information about transactions with ok_txn_status = pending.

Pending Reason (ok_txn_pending_reason) Description
review The payment is pending while it is being reviewed by OKPAY for risk.
unilateral The payment is pending because it was made to an e-mail address that is not yet registered or confirmed.
verify

The payment is pending because you are not yet verified. You must verify your account before you can accept this payment.

other

The payment is pending for a reason other than those listed above. For more information, contact OKPAY Customer Service.

Transaction Reversal Reason

In the case of a transaction with ok_txn_status = reversed use the ok_txn_reversal_reason variable in the message to learn the cause of the reversal. Note: Additional codes may be returned.

Reversal Reason (ok_txn_reversal_reason) Description
other

Non-specified reason.

refund A reversal has occurred on this transaction because you have given the customer a refund.
chargeback This transaction has been reversed due to a chargeback issued by the initial payment processor.

Item Types

Types of items sold.

Item Types (ok_item_#_type) Description
shipment

Tangible goods (address information is requested by OKPAY during checkout).

digital Digital products.
service Services.
donation Donations.

Subscription Events

Contain possible events for subscription. You can use the ok_s_event variable in the message to trigger the subscription processing you want.

Subscription Event (ok_s_event) Description
started

New subscription registered.

payment Successful subscription payment received.
failed Customer does not have enough funds for the subscription payment. Depending on the ok_s_reattempt_days variable the payment attempt will reoccur or the subscription will be canceled.
canceled Subscription canceled for one of the following reasons: payment failed (and no reattempts left), merchant or customer manually canceled the subscription.
suspended Subscription suspended by client or merchant.
modified Subscription terms change requested and pending client approval.
expired Last regular cycle is finished (this occurs only for subscriptions with a finite number of regular cycles).
ended The term of the subscription is actually finished.

Subscription Statuses

Contain possible statuses for subscriptions.

Subscription Status (ok_s_status) Description
active

Subscription is active.

failed Payment for the subscription is failed.
canceled Subscription canceled.
suspended Subscription suspended.
modified Subscription terms change requested and pending client approval.
expired Last regular cycle is finished.

Pre-approved Payments Contract Events

Contain possible events for pre-approved payment. You can use the ok_p_event variable in the message to trigger the pre-approved payments contract processing you want.

Pre-approved Payment Event (ok_p_event) Description
access_granted

New pre-approved payments contract registered.

access_denied Pre-approved payments contract is finished or invalid.
payment Pre-approved payment event received.

Pre-approved Payments Contract Statuses

Contain possible statuses for pre-approved payments contract.

Pre-approved Payment Status (ok_p_status) Description
active

Pre-approved payments contract is active.

failed Payment for the pre-approved payments contract is failed.
canceled Pre-approved payments contract canceled either by merchant or by customer.
expired The pre-approved payments contract was completed by the expiration date.

Client Verification Events

Contain possible events for Client Verification. You can use the ok_v_event variable in the message to trigger the Client Verification processing you want.

Verification event (ok_v_event) Description
access_granted Access to the client's information is granted.
access_denied Access to the client's information is denied.
image_uploaded Client uploaded a new document in to the profile.
client_updated Client's personal information has been modified.
client_status_updated Client's status/verification level has been modified.

Transaction and Notification-Related Variables

Transaction and notification-related variables provide additional characteristics of the merchant who is receiving the payment or other notification and transaction-specific information.

Variable Name Description Length, Characters Example

General information

ok_ipn_id

Unique ID of this particular IPN message. For instance it allows a check of whether the message has been processed before.

10  
ok_charset

Character set. Always UTF-8.

20  
ok_ipn_test

Whether the message is a test message. If its value is greater than zero, it is a test message.

13  
ok_ipn_resend

Whether this IPN message was re-sent (if it equals true, otherwise it is the original message).

1  

Receiver information

ok_receiver For transactions where Operation Kind is payment_link or marketplace, this variable will have the same value as that of its namesake in the Payment Links Variable Reference. 127  
ok_receiver_email

E-mail address of the payment recipient (merchant).
Note: The value of this variable is normalised to lowercase characters.

127 "merchant@mail.com"
ok_receiver_phone Phone number of the payment recipient (merchant). 127  
ok_receiver_id

Unique account ID of the payment recipient (merchant). This is the same as the recipient's referral ID.

13 123456789
ok_receiver_wallet

Payment recipient's wallet ID.

24  

Buyer Information Variables

Buyer information identifies the buyer or initiator of a transaction by payer ID, e-mail address or phone number. Additional contact or shipping information may be provided.

Variable Name Description Length, Characters Example

Basic Information

ok_payer_first_name

Customer's first name. This field will read "Anonymous" for anonymous users.

64 "John"
ok_payer_last_name

Customer's last name. This field will read "Anonymous" for anonymous users.

64 "Doe"
ok_payer_business_name

Customer's company name, if the customer is a business.

127 "QWERTY Inc."
ok_payer_email

Customer's e-mail address.

127 "client@mail.com"
ok_payer_phone

Customer's telephone number.

20  
ok_payer_id

Unique customer account ID.

13 123456789
ok_payer_reputation Payer business score - payer reputation number. 5  

ok_payer_status

Whether the customer has a verified OKPAY account.

  • verified – Customer has a verified OKPAY account.
  • unverified – Customer has an unverified OKPAY account.
20  

Address Information

ok_payer_country_code

ISO 3166 country code associated with customer's address.

2 "DE"
ok_payer_country Country of customer's address. 64 "Germany"
ok_payer_city City of customer's address. 40  
ok_payer_state

State/province of customer's address.

40  
ok_payer_street

Customer's street address.

200  
ok_payer_zip

Zip/postal code of customer's address.

20  
ok_payer_address_name

Name used with address.

128  
ok_payer_address_status

Whether the customer provided a confirmed address. It is one of the following values:

  • confirmed – Customer provided a confirmed address.
  • unconfirmed – Customer provided an unconfirmed address.
20  

Payment Information Variables

Payment information identifies the amount and status of a payment transaction, including fees.

Variable Name

Description

Length, Characters Example

General Transaction-Related Variables

ok_txn_id

The merchant's original transaction identification number.

19 2500000
ok_txn_parent_id

In the case of a reversal this variable contains the ok_txn_id of the original transaction, while ok_txn_id contains a new ID for the new transaction.

19  
ok_txn_datetime Time/Date stamp generated by OKPAY, in the following format: "YYYY-MM-DD hh:mm:ss" 19 "2013-08-31 07:49:51"
ok_txn_kind

The kind of transaction for which the IPN message was sent.

40  
ok_txn_payment_method

How this operation was performed.

3 OKB
ok_txn_status

The status of the payment.

40  
ok_txn_pending_reason

This variable is set only if ok_txn_status = pending. View list of possible pending reasons.

40  
ok_txn_reversal_reason

This variable is set if ok_txn_status = reversed. View list of possible reversal reasons.

40  
ok_txn_currency The currency of the operation. ISO 4217 3-letter code. 3  
ok_txn_exchange_rate Exchange rate used if a currency conversion occurred. 10  
ok_txn_gross Full amount of the customer's payment, before transaction fee is subtracted. If this amount is negative, it signifies a refund or reversal, and either of those payment statuses can be for the full or partial amount of the original transaction. The total ok_txn_gross is the sum of ok_item_x_gross (where x is the shopping cart detail item number). 15  
ok_txn_net Amount of the customer's payment, with subtraction of the transaction fee. 15  
ok_txn_fee Transaction fee associated with the payment. ok_txn_gross minus ok_txn_fee equals the amount credited to the ok_receiver_email wallet/account. If this amount is negative, it signifies a refund or reversal, and either of those payment statuses can be for the full or partial amount of the original transaction fee. 15  
ok_txn_handling

Total handling amount associated with the transaction.
Format: unsigned, no currency symbol, two decimal places.

15  
ok_txn_shipping

Total shipping amount associated with the transaction. Shipping charges associated with this transaction.
Format: unsigned, no currency symbol, two decimal places.

15  
ok_txn_shipping_method The buyer selected the named shipping method for this transaction. 64  
ok_txn_tax Amount of tax charged on payment.    
ok_txn_comment

Memo as entered by your customer in OKPAY comment field.

255  
ok_invoice

Pass-through variable you can use to identify your invoice number for this purchase. If omitted, no variable is passed back.

127  

Item-Related Variables (for Payment Links and Marketplace Transactions)

If this is a shopping cart transaction, OKPAY will append the number of the item (e.g., ok_item_1_name, ok_item_2_name, and so forth).

ok_items_count

If this is an OKPAY Shopping Cart transaction, number of items in cart.

2  
ok_item_#_id For Marketplace purchases this is the ID of an OKPAY Marketplace item. 19  
ok_item_#_name Item name as passed by you, the merchant. Or, if not passed by you, as entered by your customer. 127  
ok_item_#_article Pass-through variable for you to track purchases. It will be passed back to you upon completion of the payment. If omitted, no variable will be passed back to you. 40  
ok_item_#_type One of the item types. 64  
ok_item_#_quantity Quantity as entered by your customer or as passed by you, the merchant. 8  
ok_item_#_gross The item gross amount is in the currency of ok_txn_currency. The ok_item_x_gross amount is the sum of ok_item_x_price + ok_item_x_handling + ok_item_x_shipping + ok_item_x_tax. 15  
ok_item_#_price The item price without shipping, handling, and/or taxes. 15  
ok_item_#_handling

The handling x variable is only shown when the merchant applies a handling amount to a specific item. The sum of handling x is equal to ok_txn_handling.

15  
ok_item_#_shipping The shipping x variable is only shown when the merchant applies a shipping amount to a specific item. The sum of shipping x is equal to ok_txn_shipping. 15  
ok_item_#_tax The tax x variable is included only if a specific tax amount was applied to a particular shopping cart item. The sum of tax x is equal to ok_txn_tax. 15  

ok_item_#_custom_1_title

Custom field 1 title as passed by you, the merchant.

127  
ok_item_#_custom_1_value Custom field 1 value as passed by your client. 127  
ok_item_#_custom_2_title Custom field 2 title as passed by you, the merchant. 127  
ok_item_#_custom_2_value Custom field 2 value as passed by your client. 127  

Subscription-Related Variables

ok_s_event One of the subscription events which allows you to determine what kind of subscription IPN you received and how it should be handled. 20  
ok_s_id

Unique subscription ID assigned by OKPAY.

10  
ok_s_title Text title displayed to the customer and describing this particular type of subscription. 200  
ok_s_status Current status of the subscription. 20  
ok_s_setup_price Setup amount charged at the moment of subscription. 15  
ok_s_trial_cycle Duration of the single trial cycle. 6  
ok_s_trial_price Subscription price of the trial cycle. 15  
ok_s_trial_count The number of cycles (with a step of ok_s_trial_cycle) for which the trial price for the subscription will be charged. If set to zero (0) then no trial period is defined. 10  
ok_s_trial_payments_done Number of successful payments taken for a trial cycle. 10  
ok_s_regular_cycle Duration of the single regular (main) cycle. 6  
ok_s_regular_price Subscription price of the regular (main) cycle. 15  
ok_s_regular_count Number of cycles (with a step of ok_s_regular_cycle) for which the regular price for the subscription will be charged. A value of 0 (default) implies that the subscription will continue until it is canceled by the customer or by the merchant. 10  
ok_s_regular_payments_done Information about the number of regular cycles a customer paid for. 10  
ok_s_reattempt_days The 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. Value of "0" (zero) means that the subscription will be canceled instantly on first failed payment, and "-1" means that number of attempts is unlimited. 3  
ok_s_reattempt_accum 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_start_datetime Creation date and time of subscription in the following format: "YYYY-MM-DD hh:mm:ss". 20  
ok_s_next_payment_datetime Information about the scheduled date of the next payment for this subscription in the following format: "YYYY-MM-DD hh:mm:ss". 20  
ok_s_retry_at This is the time when the system will automatically try again to charge the current outstanding balance for the subscription. This parameter is returned only for failed subscriptions (ok_s_status=failed). Date and time are specified in the following format: "YYYY-MM-DD hh:mm:ss". 20  
ok_s_active Tells whether that subscription is still active. If equal to "0" - the subscription is active at the moment. If "1" - the subscription is active until the time which is indicated in the parameter ok_s_valid_until. 1  
ok_s_valid_until Date when the paid subscription period will end, in the following format: "YYYY-MM-DD hh:mm:ss". If the subscription is not active, i.e. parameter ok_s_active=0, then none will be returned. 20  

Pre-approved Payment Related Variables

ok_p_event One of the pre-approved payment events which allows you to determine what kind of pre-approved payment IPN you received and how it should be handled. 20 access_granted
ok_p_status Current status of the pre-approved payments contract. 20 active
ok_p_id Unique pre-approved payments contract ID assigned by OKPAY. 10 12345
ok_p_title Text title displayed to the customer and describing this particular type of pre-approved payments contract. 200 "ABC Account Top-up"
ok_p_datetime Timestamp of the event in the following format (UTC): "YYYY-MM-DD hh:mm:ss". 20 "2013-08-31 07:49:51"

Client Verification Variables

Variables with information about client verification.

Variable Name Description Length, Characters Example
ok_v_event Event type on the client's verification. 30 image_uploaded
ok_v_client_id Unique OKPAY account ID of the client. 9 123456789
ok_v_client_email E-mail address of the client. Note: The value of this variable is normalised to lowercase characters. 100 "client@mail.com"
ok_v_reference Unique identifier of the client in the database of the partner as provided by the partner during verification link generation. 9 33333
ok_v_datetime Timestamp of the event in the following format (UTC): "YYYY-MM-DD hh:mm:ss". 20 "2013-08-31 07:49:51"
ok_v_image_id Unique document ID which has been uploaded by the client. This variable is specified only if ok_v_event=image_uploaded. 10 12345
OKPAY RSS
OKPAY Forum
OKPAY on Facebook
OKPAY on Livejournal
OKPAY on Twitter
OKPAY on VK
OKPAY on Linkedin
OKPAY on Youtube