API Data Structures

Contents:

Structures

Balance Structure

Balance Information.

Field Type Description Example
Currency Currency String One of the currencies supported by OKPAY.

"USD", "EUR", etc.

Amount Amount Decimal The amount must have two decimal places. 1.26, 456.78, etc.

TxnInfo Structure

Transaction details.

Field Type Description Example
ID TransactionID Long Integer The merchant's original transaction identification number. 1401265, 1802587, etc.
Date Timestamp String Transaction date and time. "2011-05-16 10:22:33"
OperationName String Operation name. "Money sent"
Status TxnStatuses Value Transaction status. Completed, Pending, etc.
Net Amount Decimal Net amount. Amount + Fees. 1.26, 456.78, etc.
Amount Amount Decimal Transaction amount. 1.26, 456.78, etc.
Fees Amount Decimal Transaction fees. 1.26, -2.78, etc.
Currency Currency String One of the currencies supported by OKPAY.

"USD", "EUR", etc.

Comment String Comment for transaction. "Some comment for payment"
Sender AccountInfo Structure Transaction sender details. -
Receiver AccountInfo Structure Transaction receiver details. -
Invoice String Variable that can be used to identify your invoice number for this payment. Up to 127 characters. Empty string is returned if not used. "ID345X24"

WithdrawalInfo Structure

Withdrawal details.

Field Type Description Example
OperationID Transaction ID
Long Integer
The original OKPAY transaction identification number. 1401265, 1802587, etc.
PaySystemTransactionID String Supported payment method transaction number. "1234567890"
Status TxnStatuses Value Transaction status. Completed, Pending, etc.
Gross

Amount Decimal

Total amount deducted from the account balance (amount + fee). 1.26, 456.78, etc.
Amount Amount Decimal Funds intended for withdrawal. 1.26, 456.78, etc.
Fee Amount Decimal Withdrawal fee. 1.26, 456.78 etc.
PaymentMethodAmount Amount Decimal Amount sent in the currency of the selected method. 1.26, 456.78, etc.
PaymentMethod String One of the payment methods used for withdrawal. "BTC", "LIQ", etc.
Currency Currency String One of the currencies supported by OKPAY.

"USD", "EUR", etc.

ExchangeRate Amount Decimal Exchange rate of OKPAY e-currency to selected payment method. 1, 12.1458, etc.

AccountInfo Structure

Account details.

Field Type Description Example
WalletID Wallet ID
String
Client's Wallet ID. "OK123456789", "OK987654321"
Email String Email address. "user@okpay.com"
Name String Client's name. "John Doe"
AccountID Account ID
Long Integer
Client's Account ID. 123456789, 987654321
Country_ISO Country
String
2-character code of client's country. "FR", "DE", "CN", etc.
VerificationStatus VerificationStatuses Value Client verification status. Verified, Unverified, etc.

HistoryInfo Structure

Transaction history details

Field Type Description Example
PageSize Integer Number of returned transactions per page. Max value - 50. 50, 20
PageNumber Integer Number of returned page. 1, 2
PageCount Integer Number of transactions on current page. 50, 20
TotalCount Integer Number of all transactions. 100, 200
Transactions List of TxnInfo Structures List of transactions for current page. -

Client Structure

Contains general information on the client.

Field Type Description Example
ID Account ID
Long Integer
Unique 9-digit client identification number in OKPAY. 123456789
Status ClientStatuses Value Client status. Active
Verification VerificationStatuses Value Verification status. Unverified
PersonalInfo PersonalData Structure Personal information of the client. -
DocumentInfo Document
Structure
Client main identification document information. -
Phones List of Phone Structures List of client's phone numbers. -
Addresses List of Address Structures List of client's addresses. -
Emails List of Strings List of client's emails. -
IPs List of IPInfo Structures List of recent IP addresses. -

Client_PublicInfo Structure

Contains public information on the client.

Field Type Description Example
ID Account ID
Long Integer
Unique 9-digit client identification number in OKPAY. 123456789
Verification VerificationStatuses Value Verification status. Unverified
FullName String Client's full name. "John Doe"
RegistrationDate Timestamp String Client's registration date. "1985-05-16 10:22:33"
Email String Client's email address. email@email.com
Address Class Address Client's address. -
Phone Class Phone Client's phone number. -

PersonalData Structure

Contains personal information on the client.

Field Type Description Example
FirstName String Client's first name. "Mike"
LastName String Client's last name. "Smith"
MiddleName String Client's middle name. "J."
BirthDate Timestamp String Birth date. If not present, empty string is returned. "1985-05-16 10:22:33"
PlaceOfBirth String Place of birth. "New York"
Citizenship Country
String
Citizenship country of the client is 2-chars code according to the country codes list. "US"
CountryOfResidence Country
String
Country of residence of the client is 2-chars code according to the country codes list. "US"

Document Structure

Contains document information on the client.

Field Type Description Example
DateOfIssue Timestamp String Date of issue. If not present, empty string is returned. "2011-05-16 10:22:33", ""
DateOfExpire Timestamp String Expiration date. If not present, empty string is returned. "2011-05-16 10:22:33", ""
Number String Document number. "1234567"
PlaceOfIssue String Place of issue. "New York"
Type DocumentTypes Value Document type. Passport

Phone Structure

Contains phone information on the client.

Field Type Description Example
Number String Phone number. "+123456789"
IsVerified Boolean True for verified phone. True or False

Address Structure

Contains address information on the client.

Field Type Description Example
AddressLine String Client's street address. "250 5th Street"
City String Client's city. "New York"
Country Country
String
2-chars country code of the client's address according to the country codes list. "US"
Region String State/province of the client's address. "New York, NY"
ZipCode String Zip/postal code of the client's address. "12345"
Type AddressTypes Value Address type. Postal
IsVerified Boolean True for verified address. True or False

IPInfo Structure

Contains IP address used by the client to access OKPAY account.

Field Type Description Example
IP String IP address. "192.168.1.1"
Date Timestamp String Date and time of the event. "2011-05-16 10:22:33"

Subscription Structure

Contains information about particular instance of subscription.

Field Type Description Example
ID Long Integer Unique subscription identification number in OKPAY. 30020
Title String Text title describing this particular type of subscription. It can be used to filter the subscriptions inside your account profile (in Merchant's Subscriptions Billing). "Tony's Weekly Subscription"
MerchantWalletID Wallet ID
String
Merchant Wallet ID in which subscription payments are received. "OK123456789"
SetupPrice Amount
Decimal
Amount that can be charged only once at the moment of subscribing. 10.00, 0.00, etc.
Currency Currency
String
Currency in which all prices are given for the subscription. One of the currencies supported by OKPAY. "USD", "EUR", etc.
TrialInterval SubscriptionCycleIntervals Value Multiplier for the trial period of the subscription. Days, Months, etc.
TrialCycle Integer The number of TrialInterval units in each trial cycle of the subscription. 1, 3, 10, etc.
TrialPrice Decimal Price for a trial subscription period. If the price equals 0 then no payment for the trial period is charged. 1.00, 0.00, etc.
TrialCount Integer The number of trial cycles of the subscription. If it equals 0 then there is no trial period in this subscription. 0, 5, etc.
TrialPaymentsDone Integer The number of successfully completed payments for a trial subscription cycle. 0, 10, etc.
RegularInterval SubscriptionCycleIntervals Value Multiplier for a regular period of the subscription. Days, Months, etc.
RegularCycle Integer The number of RegularInterval units in each regular cycle of the subscription. 1, 3, 10, etc.
RegularPrice Amount
Decimal
Price for a regular subscription period. 1.00, 0.00, etc.
RegularCount Integer The optional number of regular cycles of the subscription. Value "0" means that this subscription will have an unlimited number of regular cycles (never expires). 0, 50, etc.
RegularPaymentsDone Integer The number of successfully completed payments for a regular subscription cycle. 0, 10, etc.
ReattemptDays Integer Number of days OKPAY will try to attempt the 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. A value of "0" (zero) means instant subscription cancellation on first failed payment, and "-1"means that the number of attempts is unlimited. -1, 0, 10, etc.
ReattemptAcum Boolean This field can assume one of two values. "False" – on reattempt the system will not charge more than the price of the next billing cycle (default); "True" – the system will add all previous payments that failed to the next bill. True or False
Status SubscriptionStatuses Value Current subscription status. Active, Cancelled, etc.
IsActive Boolean If the subscription is still active. This property is useful for determining the state of a suspended or cancelled subscription. True or False
ValidUntil Timestamp
String
Time when the paid subscription period is finished. If the subscription is not active, i.e. IsActive=False, then an empty string returns.  
StartDateTime Timestamp
String
Start date of the subscription. "2013-07-15 20:12:53"
LastPaymentDateTime Timestamp
String
Date of last payment for the renewal/subscription activation. "2013-08-31 07:49:51"
NextPaymentDateTime Timestamp
String
Date of next scheduled renewal. "2013-08-31 07:49:51"
RetryAt Timestamp
String
Returns only for failed subscriptions. This is the date when the system will automatically try to charge renewal payment again. If the subscription is in another status, an empty string returns. "2013-08-31 07:49:51" or ""
OutstandingBalance Amount
Decimal
Returns the amount that the customer should pay when the subscription status is "failed". 2.00, 10.00, etc.
Client AccountInfo
Structure
Structure contains details about a customer's account in OKPAY. -
ShippingNeeded Boolean If physical delivery is required for this subscription item. Address information will be provided in ShippingAddress field if required. True or False
ShippingAddress Address
Structure
Structure contains delivery address. -

Image Structure

Contains information about image file.

Field Type Description Example
ID Long Integer Unique image ID. 123456
Name String Image file name. "passport.jpg"
Data Byte Stream File content. Byte stream

PreapprovedPayment Structure

Contains information about particular instance of Pre-approved Payment Contract.

Field Type Description Example
ID Long Integer Unique pre-approved payments contract identification number in OKPAY. 30020
Title String Text title describing this particular type of pre-approved payments contract. It can be used to filter the pre-approved payments contracts inside your account profile (in Merchant's Pre-approved Payments). "My Title"
Invoice String Invoice reference number or ID. Pass-through variable for you to track pre-approved payment. "ABC123"
MerchantWalletID Wallet ID
String
Merchant Wallet ID in which pre-approved payments are received. "OK123456789"
Currency Currency
String
Currency in which all charges are performed for the pre-approved payment contract. One of the currencies supported by OKPAY. "USD", "EUR", etc.
PaymentsDone Integer The total number of successfully completed payments for a pre-approved payment contract. 0, 10, etc.
PaymentsAmount Amount
Decimal
Returns the total amount of successfully completed payments for a pre-approved payment contract. 2.00, 123.00, etc.
Status PreapprovedPaymentStatuses Value Current pre-approved payment contract status. Active, Canceled, etc.
ClientPaysFee Boolean This field can assume one of two values. “False” – commission payable by the merchant (default); “True” – commission payable by the client. True or False
StartDate Timestamp
String
Creation date of the pre-approved payment contract. "2014-11-28 20:12:53"
EndDate Timestamp
String
Time when the pre-approved payment contract period is or will be terminated. "2014-11-28 20:12:53"
LastPaymentDate Timestamp
String
Date of last charge performed by merchant using this pre-approved payment contract. "2014-11-28 20:12:53"
ChargeLimit Amount
Decimal
Returns an maximum allowed payment amount according to client's spending limits settings. "-1"means that client set no any limits for payments in your address. Please note that returned amount is not necessarily present in the customer's wallet. 100.00, 500.00, etc.
Client AccountInfo
Structure
Structure contains details about a customer's account in OKPAY. -

Enumerable Types

TxnStatuses

Contains description of the operation status.

Value Description
None Operation status is not set yet.
Error An error occurred.
Cancelled Operation is cancelled.
Pending Operation is not finished yet.
Reversed Operation is reversed.
Hold Operation is held.
Completed Operation is successful.

DocumentTypes Enum

Contains a description of the document type.

Value Description
Unset Document type not set.
Other Other document type.
Passport Passport.
Driver_License Driving license.
Identity_Card Identity card.

AddressTypes Enum

Contains description of the address type.

Value Description
Unset Address type not set.
Legal Legal address.
Actual Actual address.
Postal Postal address.

VerificationStatuses Enum

Contains verification statuses description.

Value Description
Unverified Unverified account.
Formal Verified. Electronic photocopies of the documents received.
Verified Verified. Notarised copies of the documents received.

ClientStatuses Enum

Contains client statuses description.

Value Description
Active Active client.
Blocked Blocked client.
Deleted Deleted client.

SubscriptionStatuses Enum

Contains subscription statuses description.

Value Description
Active This is a normal operating subscription.
Cancelled This subscription has been cancelled by the client or the merchant.
Failed Subscription renewal failed.
Expired Subscription came to an end - completed its last cycle.
Modified This subscription has been modified by the merchant and is currently pending client approval.
Suspended This subscription has been suspended by the client or merchant.

SubscriptionCycleIntervals Enum

Contains types of time intervals (multiplier) for the subscription cycle.

Value Description
Days Cycle multiplier is day.
Weeks Cycle multiplier is week.
Months Cycle multiplier is month.
Years Cycle multiplier is year.

PreapprovedPaymentStatuses Enum

Contains pre-approved payments contract statuses description.

Value Description
Active This is a normal operating pre-approved payments contract.
Cancelled This pre-approved payments contract has been cancelled by the client or the merchant.
Failed Pre-approved payment failed.
Expired Pre-approved payments contract came to an end.
OKPAY RSS
OKPAY Forum
OKPAY on Facebook
OKPAY on Livejournal
OKPAY on Twitter
OKPAY on VK
OKPAY on Linkedin
OKPAY on Youtube