API Data Structures

Contents:

Data Format Conventions

This table lists the types and format of data utilised by OKPAY API.

Data Type Format Examples
Account ID Unique OKPAY Account ID. String containing only numbers (xxxxxxxx) up to 9 digits long. "123456789", "987654321", etc.
Wallet ID Unique OKPAY Wallet ID. String starting with OK followed by 9 digits (OKxxxxxxxxx). "OK123456789", "OK987654321", etc.
Amount


The currency amount field has the following structure:

  • The amount must have two decimal places.
  • The decimal separator must be a period (".").
  • You must not use the thousands separator.
1.26, 456.78, etc.
Timestamp String String containing date and time in the following formats "yyyy-MM-dd HH:mm:ss", "yyyy-MM-dd HH:mm", "yyyy-MM-dd". "2017-02-22 10:33:16", "2018-02-16 14:54", "2016-06-22", etc.
Transaction ID 32-bit integer 1234567890, 9994456683762355345868, etc.
Currency 3-character code of a currency supported by OKPAY.

"USD", "EUR", etc.

Country 2-character code of a country. "US", "DE", "CA", etc.

Structures

Result Structure

A JSON response structure returned with every API function call containing the isSuccess, result and errorMessage fields.

Field Type Description Example
isSuccess Boolean
Determines whether the API function call was processed successfully. true, false.
Result Object Displays a function specific reply or a null value in case of any errors. function specific reply.
errorMessages String Determines whether the API function call was processed successfully. null, one of the error codes.

Balance Structure

Balance Information.

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

"USD", "EUR", etc.

TotalAvailable Amount Decimal Amount must have two decimal places. 1.26, 456.78, 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.

TxnInfo Structure

Transaction details.

Field Type Description Example
ID TransactionID Integer Unique transaction identification number. 1401265, 1802587, etc.
DateCreated Timestamp String Transaction creation date and time. "2017-07-06T14:14:17"
OperationName String Operation name. "Money sent"
Status TxnStatuses Value Transaction status. Completed, Pending, etc.
Net Amount Decimal Net transaction amount (excluding fee). 1.26, 456.78, etc.
Gross Amount Decimal Gross transaction amount (including fee). 1.26, 456.78, etc.
Fee Amount Decimal Transaction fees. 1.26, 456.78, etc.
Currency Currency String One of the currencies supported by OKPAY.

"USD", "EUR", etc.

Comment String Comment for transaction.

"Some comment for payment"

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"

IsIncomingTransaction Boolean Indicates whether the transaction is an incoming. "true", "false"
CounterpartyName String Name of the counterparty. In accordance with the AccountInfo Structure. "John Doe", "OKPAY", etc.
CounterpartyClientAccountID Long Integer Account number of the counterparty. In accordance with the AccountInfo Structure. 632538448, etc.
CounterpartyOtherInfo String Other counterparty information. "Some information"

PaymentRequest Structure

Payment request details.

Field Type Description Example
ID TransactionID Integer Unique transaction identification number. "1401265", "1802587", etc.
GUID string Unique identification in GUID mode. "eabf16d6-1ca9-458f-80fd-c6cc2aaf2b85", etc.
PaymentURL string Unique OKPAY checkout URL including GUID as identification. "https://checkout.okpay.com/eabf16d6-1ca9-458f-80fd-c6cc2aaf2b85", etc.
MerchantClientID Account ID String Internal unique account number of the receiver of payment. "123456789", "987654321", etc.
MerchantWallet Wallet ID String Internal unique wallet number of the receiver of payment. "OK823912027", etc.
Status PayReqStatuses Value Payment request status. "Unpaid", "Paid", etc.
Type String Type of the Payment request. "payment", etc.
Amount Amount Decimal Amount must have two decimal places. "1.26", "456.78", etc.
AmountPaid Amount Decimal Amount must have two decimal places. "1.26", "456.78", etc.
Currency Currency String One of the currencies supported by OKPAY.

"USD", "EUR", etc.

CreationDate JSON serialized Timestamp Payment request creation date and time. "2017-07-06T14:14:17"
ExpirationDate JSON serialized Timestamp Payment request expiration date and time. "2017-07-06T14:14:17"
PaidDate JSON serialized Timestamp Date and time when Payment request has been paid in full. "2017-07-06T14:14:17"
Parameters list List key value variables that are transferred to the checkout page. .

HistoryInfo Structure

Transaction history details

Field Type Description Example
Result List of TxnInfo Structures Transactions according to the specified search criteria. -
TotalRecordsCount Integer Total number of transactions within the searched time frame. 5, 200, etc.

Enumerable Types

TxnStatuses

Contains description of the operation status.

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

PayReqStatuses

Contains description of the payment request status.

Value Description
unpaid Payment request is not yet paid.
expired Payment request wasn't paid in time and is expired.
paid Payment request is paid in full.
overpaid Received amount is more than the amount of the payment request.
underpaid Payment request is not paid in full (partially paid).

VerificationStatuses Enum

Contains verification statuses description.

Value Description
Unverified Unverified account.
Formal Verified. Electronic photocopies of documents received.
Verified Verified. Notarized copies of documents received.
OKPAY RSS
OKPAY Forum
OKPAY on Facebook
OKPAY on Livejournal
OKPAY on Twitter
OKPAY on VK
OKPAY on Linkedin
OKPAY on Youtube