McAfee Secure sites help keep you safe from identity theft, credit card fraud, spyware, spam, viruses and online scams

Liberty Reserve. API Reference.


Introduction

This document contains description of all functions and specifics of Liberty Reserve’s API. Liberty Reserve API is a programming interface, which allows you to automate the process of sending and receiving payments, receiving information about incoming and outgoing payments, obtaining history of performed transactions or receiving information about Liberty Reserve accounts. These capabilities are required for all web sites that wish to accept Liberty Reserve as one of the payment options and businesses that wish to conduct electronic autonomous transfers between Liberty Reserve accounts.
Currently Liberty Reserve provides XML API, NVP API, JSON API and SOAP API.

Who needs this information

This document is required for all developers working on programming interface to integrate Liberty Reserve payment option into their websites. To be successful, developers will need experience in following:
  • preparation and sending requests to web server;
  • receiving and analyzing information received from web server;
  • working with HTTPS protocol.
Developers are also encouraged to have knowledge of XML 1.0, NVP, , SOAP and JSON standards, and experience with HASH operations.


Preparation

You need to follow steps listed below to start working with our API:

1. You need to create an API attached to your account. To accomplish this, you need to login to your Liberty Reserve account and visit “Merchant Tools” section. Click on 'Create API' link, which will let you create an API for your account. Your API will not work properly without this procedure.
2. You need to set the following parameters of your API in order for it to function:
  • API NAME. This name will be used in every request as a part of authentication process.
  • SECURITY WORD. This code word will be used in every request as a part of authentication process.
  • REQUESTING IP ADDRESSES. This should list IP address or subnetwork that you authorize to make requests for your API from. You may leave it blank if you do not wish to restrict access by IP address. More information about this subject is listed in Security considerations.
Please note that you may only select STATIC IP addresses as your REQUESTING IP ADDRESS.
For non-developers Liberty Reserve provides API function that allows you to confirm each API Transfer by SMS Code that is sent to your verified mobile phone number. More information about this subject is listed in Security considerations.

You may create up to 100 APIs attached to the same account. This should help you separate certain functions based on website or interface.

System requirements

While working with Liberty Reserve API you will need the following:
  • Programming language that will let you create XML documents or working in command line mode and send HTTPS GET or POST requests.
  • If you have restricted access to your account with one or more IP addresses please make sure that computer that sends requests to Liberty Reserve is located on at least one of the selected IP addresses. Please note that API requests via proxy servers are not supported.
  • Your must include an HTTP Host header in all requests.
  • Your HTTP request must contain a valid “User-Agent” HTTP header.
Table below contains examples of some common “User-Agent” values of popular web-browsers that are valid for API web-request executing:

Browser User-Agent String
Internet Explorer 7 Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 5.2; Trident/4.0; .NET CLR 1.1.4322; .NET CLR 2.0.50727; .NET CLR 3.0.4506.2152; .NET CLR 3.5.30729; .NET4.0C; .NET4.0E)
Google Chrome 6.0 Mozilla/5.0 (X11; U; Linux i686; en-US) AppleWebKit/534.3 (KHTML, like Gecko) Chrome/6.0.472.63 Safari/534.3
Iceweasel 3.5.19 Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.19) Gecko/20110430 Iceweasel/3.5.19 (like Firefox/3.5.19) Accept-Language: en-us
Opera 9.0 Mozilla/4.0 (compatible; MSIE 6.0; Mac_PowerPC; en) Opera 9.00


API operations

Liberty Reserve API supports the following operations:
  • Transfer. Allows you to transfer funds from one account to another. With this command you may transfer any of the available currencies that Liberty Reserve supports. This function also permits you to perform multiple (bulk) transfers.
  • History. Requests history of a specified account by date range. Additional parameters may be used such as: currency, destination account, etc. This function is necessary if you wish to receive information about specific multiple transactions.
  • Find Transaction. Requests transaction details by transaction ID (batch number). Using this function you can find a transaction by its batch number in the transaction history of your account. Search of the transaction performed within all available transaction history of the account.
  • Balance. Account balance request. This function requests balances of all specified currencies.
  • Account Name. Request for account name. Function is utilized to verify if account in question exists on our system.
  • Confirm Transfer. Request to confirm pending API Transfer. This operation is introduced for non-developers that use API in their Liberty Reserve accounts. If this operation is enabled API Transfer is conducted in two phases – first you send Transfer request, then you send Confirm Transfer request with a code from SMS that was delivered to mobile phone number associated with your Liberty Reserve account. Lifetime of pending transfer is restricted by one hour). If during 1 hour you didn't send Confirm Transfer request – SMS code gets invalidated. SMS confirmation code is also invalidated if you fail to confirm Transfer with a correct code.
Please note that Confirm Transfer operation is supported only in JSON and NVP API.

Authentication

API requests always has to contain information that will let Liberty Reserve API server to authenticate requesting user. This request will contain account and other information that will help server to accurately identify the user submitting request. Every server request to Liberty Reserve API has to contain the following authentication information:
  • Liberty Reserve account number.
  • API Name.
  • Authentication token, This parameter consists of hashed line of text, formed by the concatenation of API’s secret word and UTC date (in case of unsigned requests in API v2.0) or API’s secret word, request parameters and UTC date (in case of signed requests in API v2.1).

Creation of authentication token

You need to create authentication token with the help of the following procedure:

For unsigned requests in API v2.0:
  • Obtain by concatenation the following line 
Security Word:Date UTC in YYYYMMDD format:Time UTC in HH format (only hours, not minutes).

  • Get hash of above line by SHA256. For example: secret word - MySecWord, date UTC - 2007.02.25 14:55 (24h format) 
Concatenation of parameters: MySecWord:20070225:14
Hash SHA256 for above created line: 2496DA449AE8CD7872A257A1D9BFDF03CF11EB18D2BF1FBCAA68ACA135CE1856


For signed requests in API v2.1 Authentication token is created unique for each request and depends on API operation you are going to perform.
  • For Transfer obtain by concatenation the following line:
Security Word:ID:Reference:Payee:Currency:Amount:Date UTC in YYYYMMDD format:Time UTC in HH format (only hours, not minutes).

Get hash of above line by SHA256.

For example: security word - MySecWord, request Id – 20121227170733, merchant reference – Reference, payee – U1234567, currency – usd, amount – 10.00, date UTC - 2012.12.27 17:07 (24h format). Note: currency is always in lower case (usd, euro, gold).
Concatenation of parameters: MySecWord:20121227170733:Reference:U1234567:usd:10.00:20121227:17
Hash SHA256 for above created line: 1C93E3EA9FCC172CB747DC5B4B94B86F307414907AF67CFB6A07BB64D5E153EA


Security Word:ID:Reference1:Payee1:Currency1:Amount1:Reference2:Payee2:Currency2:Amount2:...:ReferenceN:PayeeN:CurrencyN:AmountN:Date UTC in YYYYMMDD format:Time UTC in HH format (only hours, not minutes).

Get hash of above line by SHA256.

For example: security word - MySecWord, request Id – 20121227175533, 1st payment merchant reference – Reference1, 1st payee – U1234567, 1st currency – usd, 1st amount – 10.00, 2nd payment merchant reference – Reference2, 2nd payee – U567, 2nd currency – usd, 2nd amount – 20.00, 3rd payment merchant reference – Reference3, 3rd payee – X123, 3rd currency – euro, 3rd amount – 30.00,date UTC - 2012.12.27 17:55 (24h format). 
Concatenation of parameters: 
MySecWord:20121227175533:Reference1:U1234567:usd:10.00:Reference2:U567:usd:20.00:Reference3:X123:euro:30.00:20121227:17
Hash SHA256 for above created line: 6B4E94B61EC1CE84EF3044FC7E36C62DCC406E410A3B608776470750E5CFBF11

  • For History obtain by concatenation the following line:
Security Word:ID:From Date in YYYY-MM-DD hh:mm:ss format:Till Date in YYYY-MM-DD hh:mm:ss format:Date UTC in YYYYMMDD format:Time UTC in HH format (only hours, not minutes).

Get hash of above line by SHA256.

For example: security word - MySecWord, request Id – 20121227171008, From Date – 2012-12-01 00:00:00, Till Date – 2012-12-15 00:00:00, date UTC - 2012.12.27 17:10 (24h format).
Concatenation of parameters:
MySecWord:20121227171008:2012-12-01 00:00:00:2012-12-15 00:00:00:20121227:17
Hash SHA256 for above created line: E872E4000E186315AB0FC2C0EF9A67B75A8379223A00D65468BC756DEC0A3760


Security Word:ID:Transaction ID:Date UTC in YYYYMMDD format:Time UTC in HH format (only hours, not minutes).

Get hash of above line by SHA256.

For example: security word - MySecWord, request Id – 20121227171708, Transaction ID (batch number) - 123455678, date UTC - 2012.12.27 17:27 (24h format).
Concatenation of parameters: MySecWord:20121227171708:123455678:20121227:17
Hash SHA256 for above created line: 23184B5BA3C6DE2664FD7BFA4E092E3FF87A6E5321AED2250410A6626E262D6B


Security Word:ID:Date UTC in YYYYMMDD format:Time UTC in HH format (only hours, not minutes).

Get hash of above line by SHA256.

For example: security word - MySecWord, request Id – 20121227175937, date UTC - 2012.12.27 17:55 (24h format).
Concatenation of parameters: MySecWord:20121227175937:20121227:17
Hash SHA256 for above created line: D0EB65045E0FF8A604C6C35AEF715B2D67DE4471A1DC4AFBF21FF7987106D272



Security Word:ID:Transfer Request ID:Confirmation Code:Date UTC in YYYYMMDD format:Time UTC in HH format (only hours, not minutes).

Get hash of above line by SHA256.

For example: security word - MySecWord, request Id – 201301281133137, Transfer request Id: 201301281132521, SMS Confirmation Code: 11111-11111 date UTC - 2013.01.28 13:31 (24h format).
Concatenation of parameters: MySecWord:201301281133137:201301281132521:11111-11111: 20130128:13
Hash SHA256 for above created line: 10C6DC07A8C14C141DAB2C3E8F41808828C3324E32E326DB704C6C4810310D50



Request and response identification

Liberty Reserve API allows an additional parameter of identification which permits to accurately match each request with response. This insures that correct response is received to a specific request and prevents system from sending responses to incorrect or misguided requests. id string plays a role of identification parameter. It needs to be present in a body of XML, JSON or NVP request, set by a program or website and be unique for account. Every time response is sent to a specific request, server includes obtained id parameter in a body of response. Once response is received, user’s end of API has to analyze and confirm that response’s id string matches the id string of request. If id strings are not matched - you have either received an incorrect response or there was a malfunction within system. id parameter is also used to prevent accidental duplicate payments via API. Once request is submitted server performs search for requests with identical id submitted recently by this account via this API entry. If no matches found, request is processed. If request with same id parameter is found request is not processed. As a response user will get error like in the examples below
XML API:
<TransferResponse date="2011-05-24 15:07:00" id="id">
<Error>
<Code>101</Code>
<Text>Duplicate Request</Text>
<Description>
Duplicate request found. Please use unique request id to avoid such error.
</Description>
</Error>
</TransferResponse>

NVP API:
ID=123
&TIMESTAMP=2011-10-04+09%3a07%3a55
&STATUS=Error
&ERRORCODE=101
&ERRORMESSAGE=Duplicate+request+found.++Please+use+unique+request+id+to+avoid+such+error.

JSON API:
{
"Transaction":null,
"Id":"id1",
"TimeStamp":"2011-10-13 09:35:33",
"Status":2,
"Error":
{
"ErrorCode":101,
"ErrorMessage":"Duplicate request found. Please use unique request id to avoid such error."
}
}

If id parameter is empty, server directly compares Payer, Payee, CurrencyId and Amount values of submitted request with the corresponding parameters of requests submitted recently. In case all those parameters match request is not processed. As a response user will get error as in the example above but with empty id parameter value.

You may use current date and time, in milliseconds, as your id string.

Data formats

This table lists types and format of data utilized by Liberty Reserve’s API.

Data type Format Examples
Id Line of text, up to 20 characters long (varchar(20)) r1234567890
01.02.2007 12:33:45.456
Account number Unnnnnnn, Mnnnnnnn or Xnnnnnnn up to 8 characters long U4506734
X1205
M1212121
Amount Fraction with up to 4 digits in denominator, point (.) as a separator 1.26
456.7895
Date yyyy-MM-dd hh:mm:ss 2011-03-25 10:45:55
2011-01-16 01:01:30
Transaction ID Very long number (64-bit integer) 1234567890
9994456683762355345868
Currency Currency is listed in of the following formats:
usd (Liberty Reserve, USD)
euro (Liberty Reserve, EUR)
gold (Liberty Reserve, GoldGrams) 		usd


Error handling

Errors can occur while our API server is processing or performing your data requests. There could be four types of errors. They are listed below:
  • API access/authentication errors. Such errors may occur when authentication token contains wrong data, when API server is offline (disabled) or when API entry is disabled.
  • Errors resulting from an incorrectly formatted data request or wrong data submitted. Source of such errors usually lays in your software or web site sending requests. You need to try to avoid these errors by making sure that you have formatted your request correctly using request structure outlined above. You also have to make sure it complies with XML/NVP/JSON format and verify that no characters unsupported by corresponding protocol were used in your request.
  • Errors in logic. These errors usually result from inability to complete the task by our server due to various instances or settings applied to a certain account. Having not enough balance to complete a requested transfer or if account access is blocked – are some of those instances. You need to pay close attention to these errors and process them accordingly after response from server has been received.
  • Internal API errors. These errors are usually caused by technical issues with server. Errors of this type are very uncommon, and the most common solution is to retry submitting your request at a later time. IMPORTANT! Please make sure that your previous request was not successful to avoid double payments and other unfavorable situations.
Every time API server encounters an error it will include information about error in its response. Thus, you will always get information of what went wrong in response to every unsuccessfully completed request.

XML API Error response format

<Request prefixResponse date="response date" id="id">
...

<Error>
<Code>error code</Code>
<Text>error text</Text>
<Description>additional information</Description>
</Error>
...

</Request prefixResponse>

NVP API Error response format

ID=id
&TIMESTAMP= response date
&STATUS=operation status
&ERRORCODE= error code
&ERRORMESSAGE= error text

JSON API Error response format

{
...Response specific fields...
"Status":operation status,
"Error":
{
"ErrorCode":error code,
"ErrorMessage":"error text"
}
}

You will normally receive a notice of error rather than requested data, if your request results in error. 

<!--XML document of request-->
<BalanceRequest id="1234569878">
<Auth>
<AccountId>U12345</AccountId>
<ApiName>APIEntry1</ApiName>
<Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
</Auth>
<Balance>
<CurrencyId>PXGLD</CurrencyId>
</Balance>
<Balance>
<CurrencyId>usd</CurrencyId>
</Balance>
</BalanceRequest>
<!--XML document of server response-->
<BalanceResponse date="2011-03-16 12:43:55" id="1234569878">
<Error>
<Code>100</Code>
<Text>Invalid request structure/format</Text>
<Description>
The 'CurrencyId' element is invalid - The value 'PXGLD' is invalid according to its data type 'CurrencyType' - The Enumeration constraint failed.
</Description>
</Error>
<Balance>
<CurrencyId>usd</CurrencyId>
<Value>3500.0000</Value>
</Balance>
</BalanceResponse>

Example of NVP API error response

ID=id4
&TIMESTAMP=2011-10-04+13%3a46%3a39
&STATUS=Error
&ERRORCODE=200
&ERRORMESSAGE=Authentication+error

Example of JSON API error response

{
"Id":"id7",
"TimeStamp":"2011-10-13 08:25:43",
"Status":2,
"Error":
{
"ErrorCode":400,
"ErrorMessage":"Target account doesn't accept anonymous transfers."
},
"Transaction":null
}

It is very important to search for <Error> element in server response first. If this statement exists, you need to thoroughly investigate the source of this error and correct it, if possible, at your earliest convenience.

Please use the table below for reference of all possible errors and their meanings in our API.

API error codes


Error Code Name Error Text Description
100 InvalidRequest Invalid request structure/format Request document is of wrong structure or data are not formatted properly. Description field of API Response provides more specific information on this error.
101 DuplicateRequest Duplicate Request Duplicate request found. Please use unique request id to avoid such error.
200 Authentication Authentication error This error is a result of incorrect secret API word, name of API or incorrect hash string for authentication token.
201 InvalidIpAddress Invalid IP Address Your current IP address is restricted by API entry settings or Your current IP Address is registered as a member of anonymity network.
202 DailyLimitExceeded Daily amount limit exceeded Total daily amount of transfers is exceeded
300 ApiServiceDisabled API service is currently disabled API services are temporarily turned off
301 AccountOperationDisabled Source account blocked Your account is blocked or limited
302 ApiDisabled API entry is disabled Account's API entry is disabled
303 OperationDisabled Operation disabled The operation is not allowed due to settings of API entry.
400 InvalidData Invalid data Incorrect data. For example:
Attempt to send money to/from limited or system account;
Destination account number equals to Source account number;
Target account doesn't accept anonymous transfers;
Insufficient funds to complete the transaction;
User profile not found;
Currency disabled;
Attempt to make transfer with the amount that exceeds limit allotted for this
account;
Date range exceeds limit.
500 InternalError Internal error Internal system error



Security considerations

To insure the most optimum and secure environment for account access through Liberty Reserve API interface we recommend the following:

When you are setting your API, it is always recommended to specify IP addresses for account access. This will prevent attempts to access account though API from an unauthorized computer. Please remember that only static IP addresses are permitted for API access. You may use dynamic IP address only when testing.
Security API word should not be easy to guess or very short, and it should never match your original account password.
Never share your account passwords, security API words and other authentication data with anyone. Never transmit such information in the open or left it unattended.
Please do not include account password or any other authentication information in your program source code. It is very advisable to keep such sensitive information in a separate file with limited access or in a separate database.
If you are not a developer but want to use API for your private purposes it is strongly recommended to enable Non-Developers API option while API entry creating. This measure will prevent your API from unauthorized access and increase the security of your funds in Liberty Reserve.

Change log

Date Subject Description
05-23-2011 Request and response identification Id parameter involved into the mechanism of duplicate API payments prevention.
05-30-2011 System Requirements Your http request must contain valid “User-Agent” http header.
09-13-2011 Transfer request New required element PaymentPurpose added to Transfer request.
09-27-2011 API operations FindTransaction request type added.
09-30-2011 System Requirements Requesting IP Addresses feature added.
09-30-2011 System Requirements HTTP HOST header is required in all requests.
10-06-2011 NVP API Name-value-pairs API instructions added.
10-15-2011 JSON API JSON API instructions added.
10-15-2011 Preparation Subnetworks can be used as Requesting IP Addresses.
11-11-2011 History request Page numbering starts from 0.
11-25-2011 SOAP API SOAP API instructions added.
09-22-2012 History request Date range restricted to 31 days.
12-28-2012 Authentication Creation of authentication token in signed requests.
02-01-2013 API operations Confirm Transfer operation added.