Making API Call

Once an API Key is created, you can start calling API functions.

Authorization Scheme

An OKPAY API function requires a special signature which is generated from the values โ€‹โ€‹of variables that are sent to the function and are sorted by variable name in ascending order + the API Key Password at the end, separated by colons (:).

Below we describe an example of signature formation for the Balance function. It has only one function-specific parameter โ€” walletID, two other parameters are common: apiKeyID and a special parameter nonce. Nonce (incrementing number) is an additional security measure that helps eliminating duplicate requests. Usually, a current date and time including milliseconds is used as a nonce.

  1. First of all, we need to sort the parameters in alphabetical order: apiKeyID, nonce, walletID
  2. Then we need to form a string from the parameter values, using ":" as a delimiter. We get something like:
    100:636365626161058917:OK111111111
  3. Then we put our secret API password at the end of this line using the same ":" delimiter
    100:636365626161058917:OK111111111:R9PhUi983FAU2Qpz
  4. So, in order to get a signature, we need to execute SHA256 hash generation using the following variables: apiKeyID:nonce:walletID:APIKeyPassword
    signature = SHA256 ("100:636365626161058917:OK7111111111:R9PhUi983FAU2Qpz") = "A100352E6C26A24F15CC68BF74DC229B504EFBC7022AA4E218C4696AF1587B9F5"

Note: By adding the signature parameter to the end of the API request, we are able to call API functions. Keep in mind that the secret API key is not transmitted, as it is only used for signature generation.

Hint: Signature generation as well as code samples in various programming languages can be found in the "Code Samples" section of each API Function.

Making API Call

API requests need authentication. You can find out more about authentication in the section above (Authorization scheme). Parameters can be sent to https://api.okpay.eu/v2/ using either POST or GET methods

Mandatory parameters include:

  • [Function name] - the name of the API function called
  • API Key ID [apiKeyID] - the unique identifier of your API in the OKPAY system
  • Nonce [nonce] - an increasing unique integer (for example, you can use the system time in milliseconds)
  • Signature [signature] - a signature based on your secret API password (API Key)
  • Various function specific parameters based on the API function called

Serialization of Parameters During API Call

  • Integer parameters are passed as they are, with no spaces or other group delimiters
  • Numbers with fractional parts are transmitted using the decimal separator "."
  • Date is serialized to a string by the mask "dd-MM-yyyy HH:mm"
  • Boolean values true/false are converted to 1/0, respectively

For example, the URL link for the API function Balance (requesting OKPAY wallet balance) in GET mode will look like this:

https://api.okpay.eu/v2/Balance?apiKeyID=100&nonce=636365614474893514&walletID=OK111111111&signature=A100352E6C26A24F15CC68BF74DC229B504EFBC7055AA4E218C4696AF1587B9F5

API Response Handling

Upon request, the OKPAY server responds with a JSON structure containing the isSuccess, errorMessage and result fields.

Note: Also note that the isSuccess parameter has the value of false in the case of any error messages.
  • Successfully processed

    If the request has been processed without errors, the isSuccess parameter has the value of true ("isSuccess":true) and the result parameter contains a function specific reply. "errorMessage":null means that no errors occurred while performing the API call.

    {"errorMessage":null,"isSuccess":true,"result":[{"currencyCode":"EUR","totalAvailable":21.8200},{"currencyCode":"USD","totalAvailable":482.6300}]}
  • Errors occurred

    If any errors occurred ("isSuccess":false), the errorMessage is followed by the descriptions of those errors:

    {"errorMessage":"Minimum nonce is: 6363589851835193071","isSuccess":false,"result":null}

    The example above contains error message description "Minimum nonce is: 6363589851835193071" meaning that the nonce used in the API call was not unique, and the minimum nonce should have been one point higher than the previous value (as stated in the error description).

Next, you can read about the existing functions, their parameters, return values and code samples in the Functions section.

OKPAY RSS
OKPAY Forum
OKPAY on Facebook
OKPAY on Livejournal
OKPAY on Twitter
OKPAY on VK
OKPAY on Linkedin
OKPAY on Youtube