Liberty Reserve. API Reference.

Introduction

This document contains description of all functions and specifics of Liberty Reserve’s XML API. XML 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.

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 HTTS protocol.

Developers are also encouraged to have knowledge of XML 1.0 and experience with HASH operations

We additionally recommend experience with XML-X.

Basic information about XML API

XML API is a set of commands, utilized in communication between Liberty Reserve and any other web site. Format and data structure of XML API are developed on a concept of open standard XML-X.

How XML API works

XML API is a system that sends and accepts requests for information. This system will process such requests and act on these requests, by performing requested actions. It then compiles necessary reporting data and sends it back to requesting source. Each request consists of a specific command that API interprets and instructs server to follow. After each request system receives a response with either result of the requested operation or an error code of why requested operation was not completed successfully. Each request and response has to be formatted in a certain way to comply with a specific data format, dictated by XML API. Some requests will result in more than one task performed or in more than one response received. Successful completion of XML API requests requires the following steps:

Gathering data for operation.
Creation of an XML document in correct format for Organizing data in correct XML.
Creation of HTTP GET command based on prepared XML document.
Transmittal of HTTP GET request to Liberty Reserve server via HTTPS.
Retrieving server response.
Processing of data returned by Liberty Reserve server.

Preparation

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

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 “Manage APIs” link and click “CREATE” button, which will let you create an API for your account. Your API will not work properly without this procedure.
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.
- REQUESTING IP ADDRESSES. This should list IP address that you authorize to make requests for your XML 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
- SECURITY WORD. This code word will be used in every request as a part of authentication process.

You may create an unlimited amount of APIs attached to the same account. This should help you separate certain functions based on website or interface.

Please note that you may only select STATIC IP addresses as your REQUESTING IP ADDRESS.

System requirements

While working with XML 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 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.

XML API operations

XML 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. Additional parameters may be used such as: date range, currency, destination account, etc. This function is also necessary if you wish to receive information about specific single or multiple transactions.
Balance. Account balance request. His function requests balances of all specified currencies.
Account name. Request for account name. Function is utilized to verify is account in question exists on our system.

Authentication

XML-document always has to contain information that will let XML API server to authenticate requesting user. This document will contain account and other information that will help server to accurately identify the user submitting request. Every server request to XML API has to contain the following authentication information:

Liberty Reserve account number. Depending on a function, account number may be specified in various parts of XML document.
API Name.
Authentication token, This parameter consists of hashed line of text, formed by the concatenation of API’s secret word and UTC date.

Creation of authentication token

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

Obtain by concatenation the following line

Security Word:Date UTC in YYYYMMDD format:Time UTC in HH format.

Get hash of above line by SHA256. For example: secret word - MySecWord, date UTC - 01.02.2007 14:55 (24h format)

Concatenation of parameters: MySecWord:20070201:14
Hash SHA256 for above created line: 9A0EFBDCE4F4126C9F1EDD38AA39F3817B9C479C4A1F80B7409597F5403CA860

Request and response identification

XML 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 request, set by a program or website and be unique to every account. Every time response is sent to a specific request, server includes obtained id parameter in a body of XML document. 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.

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 XML 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 or Xnnnnnnn up to 8 characters long, where nnnnnnn – is account number	U4506734 X1205
Amount	Fraction with up to 4 digits in denominator, comma (.) as a separator	1.26 456.7895
Date	YYYY-DD-MM HH:mm:SS	2007-25-03 10:45:55 2005-01-02 01:01:30
Transaction ID	Very long number (64-bit integer)	1234567890 9994456683762355345868
Currency	Currency is listed in of the following formats: LRUSD (Liberty Reserve, USD) LREUR (Liberty Reserve, EUR)	LRUSD

XML API transaction data structure

Here is the structure of data utilized in transactions via XML API and format of required elements:

Data	Description and Format	Examples
Transaction ID	Unique number representing a transaction in Liberty Reserve. long number (64-bit integer)	1234567890 9994456683762355345868
Type	Purpose of transaction. Line supports one of these arguments: transfer (transfer between Liberty Reserve accounts)	transfer
Source	Source of transaction. Line supports one of these arguments: Site (transfer performed from Liberty Reserve site) Wallet (transfer performed from Liberty Reserve Wallet) SCI (transfer performed from Liberty Reserve SCI) API (transfer performed from Liberty Reserve API interface)	SCI
Date	Date of transaction (UTC). Represented in YYYY-DD-MM HH:mm:SS	2007-25-03 10:45:55 2005-01-02 01:01:30
Account number	Liberty Reserve account number. in a format of Unnnnnnn or Xnnnnnnn and up to 8 characters long, where nnnnnnn – is account number	U4506734 X1205
Corresponding account number	Destination Liberty Reserve account. in a format of Unnnnnnn or Xnnnnnnn and up to 8 characters long, where nnnnnnn – is account number	U4506734 X1205
Currency	Currency being transferred. You may use of the following parameters: LRUSD LREUR	LRUSD
Amount	Amount of transaction. Fraction with up to 4 digits in denominator, comma (.) as a separator. For incoming transactions amounts are > 0 and for outgoing < 0, used for requests of history of transactions.	1.26 456.7895
Fee	Fee for this transfer. Fraction with up to 4 digits in denominator, comma (.) as a separator.	0.26 6.75
Closing balance	Account balance after completion of transaction. Fraction with up to 4 digits in denominator, comma (.) as a separator.	456.55 0.76
Memo	Memo field. Line of text up to 100 characters long (varchar(100))	For John
Merchant reference	Optional, additional identifying information that can be set by Merchant. Up to 20 characters long (varchar(20))	mref12345
Anonymous	Privacy option selector. With privacy option account number of sender of funds is not revealed. You may use one of the following: true false	true

XML API operations

General structure of request

Below, you will find a basic XML-template of request to XML API server. Requests for all operations have the same structure.
The root element of document is the name of request xxxxxxRequest, which contains authentication block and request data.

<Request prefixRequest id="id">
  <Auth>  <!-- authentication block -->
    <ApiName>API name</ApiName>
    <Token>authentication token</Token>
  </Auth>

  <Operation name>  <!-- operation #1 -->
  ... operation data ...
  </Operation name>
  
  ...
  
  <Operation name>  <!-- operation #N -->
  ... operation data ...
  </Operation name>
</Request prefixRequest>

Except for History, you can specify multiple commands (operations) in the same request, as long as they are of the same type. For example, you may specify more than one request for balance OR more than one request to perform a transaction but, you may never combine different types of operations within the same request. Accordingly, if you submit more the one operation in single request you will receive multiple responses in server reply.

General structure of server response

Below, you will find a basic template, in XML format, of a typical XML API server response. All server responses have the same structure. The root element of document is the element named as xxxxxxResponse, which contains result data or errors descriptions.

<Request prefixResponse id="id" date="response date">
  <Element name>  <!-- result of operation #1 -->
  ... response data ...
  </Element name>

   ...

  <Element name>  <!-- result of operation #N -->
  ... response data ...
  </Element name>
</Request prefixResponse>

If your request contained more than one operation of the same type – server’s reply will contain response data to all processed operations and will contain error information if any errors encountered.

Requesting Liberty Reserve XML API server

All requests are need to be submitted to a URL with the following format:

https://api.libertyreserve.com/xml/operation name.aspx?req=request body

where:

operation name – name of a specific XML API operation
request body – XML document contents

All requests are to be submitted via HTTPS protocol via GET or POST command. Request body must be URL-encoded.

Performing transfers of funds between accounts (Transfer)

Operation name

Transfer

Requesting URL

https://api.libertyreserve.com/xml/transfer.aspx?req=request body

Request structure

<TransferRequest id="id">
  <Auth>  <!-- authentication block -->      
    <ApiName>API name</ApiName>
    <Token>authentication token</Token>
  </Auth>
  <Transfer>  <!-- operation #1 -->
    <TransferId>merchant reference</TransferId>  <!-- not required -->
    <TransferType>transfer type</TransferType>  <!-- must always be transfer -->
    <Payer>payer account number</Payer>
    <Payee>payee account number</Payee>
    <CurrencyId>currency</CurrencyId>
    <Amount>amount</Amount>
    <Memo>memo</Memo>  <!-- not required -->
    <Anonymous>anonymous</Anonymous>
  </Transfer>

  ...

  <Transfer>  <!-- operation #N -->
  ... operation data ...
  </Transfer>
</TransferRequest>

It is necessary to specify the same <Payer> for each requested transfer in a single request.

Response structure

<TransferResponse id="id" date="response date">
  <Receipt>
    <ReceiptId>transaction ID</ReceiptId>
    <Date>transaction date</Date>
    <PayerName>payer account name</PayerName>
    <PayeeName>payee account name</PayeeName>
    <Amount>amount</Amount>
    <Fee>fee</Fee>
    <ClosingBalance>payer account balance after executing transfer</ClosingBalance>
    
    <Transfer>
      <TransferId>merchant reference</TransferId>
      <TransferType>transfer type</TransferType>
      <Payer>payer account number</Payer>
      <Payee>payee account number</Payee>
      <CurrencyId>currency</CurrencyId>
      <Amount>amount</Amount>
      <Memo>memo</Memo>
      <Anonymous>anonymous</Anonymous>
      <Source>source</Source>
    </Transfer>
  </Receipt>

  ...

  <Receipt>
  ... result data of operation ...
  </Receipt>
</TransferResponse>

Example

For this example, we will use the following information:

Payments will commence from account U12345. Account name - test1, there is an API setting for this account with API name APIEntry1, and secret API word - secword123
Destination account is X567, account name - test2

You are making a payment of 10.25 Liberty Reserve USD, memo - "test". Privacy option is not selected.

<!--XML document of request-->

<TransferRequest id="123456789">
  <Auth>
    <ApiName>APIEntry1</ApiName>
    <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <Transfer>
    <TransferId></TransferId>
    <TransferType>transfer</TransferType>
    <Payer>U12345</Payer>
    <Payee>X567</Payee>
    <CurrencyId>LRUSD</CurrencyId>
    <Amount>10.25</Amount>
    <Memo>tests</Memo>
    <Anonymous>false</Anonymous>
  </Transfer>
</TransferRequest>


<!--XML document of server response(in a case of successfully processed request)-->

<TransferResponse id="123456789" date="2007-01-02 12:45:55">
  <Receipt>
    <ReceiptId>7659984532145</ReceiptId>
    <Date>2007-01-02 12:45:55</Date>
    <PayerName>test1</PayerName>
    <PayeeName>test2</PayeeName>
    <Amount>-10.2500</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>340.5600</ClosingBalance>
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>U12345</Payer>
      <Payee>X567</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>10.25</Amount>
      <Memo>tests</Memo>
      <Anonymous>false</Anonymous>
      <Source>API</Source>
    </Transfer>
  </Receipt>
</TransferResponse>

Example of multiple payments (bulk transfer)

You are making the following payments: payment of 14.00 Liberty Reserve USD to account X567, 5.15 Liberty Reserve USD to account U334455 and 6.05 Liberty Reserve USD USD to account U9876543.

<!--XML document of request-->

<TransferRequest id="123456790">
  <Auth>
    <ApiName>APIEntry1</ApiName>
    <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <Transfer>
    <TransferId></TransferId>
    <TransferType>transfer</TransferType>
    <Payer>U12345</Payer>
    <Payee>X567</Payee>
    <CurrencyId>LRUSD</CurrencyId>
    <Amount>14.00</Amount>
    <Memo>test 1</Memo>
    <Anonymous>false</Anonymous>
  </Transfer>

  <Transfer>
    <TransferId></TransferId>
    <TransferType>transfer</TransferType>
    <Payer>U12345</Payer>
    <Payee>U334455</Payee>
    <CurrencyId>LRUSD</CurrencyId>
    <Amount>5.15</Amount>
    <Memo>test 2</Memo>
    <Anonymous>false</Anonymous>
  </Transfer>

  <Transfer>
    <TransferId></TransferId>
    <TransferType>transfer</TransferType>
    <Payer>U12345</Payer>
    <Payee>U9876543</Payee>
    <CurrencyId>LRUSD</CurrencyId>
    <Amount>6.05</Amount>
    <Memo>test 3</Memo>
    <Anonymous>false</Anonymous>
  </Transfer>
</TransferRequest>

<!--XML document of server response (in a case of successfully processed request)-->

<TransferResponse id="123456790" date="2007-01-02 12:45:55">

  <Receipt>
    <ReceiptId>7659984532146</ReceiptId>
    <Date>2007-01-02 12:45:56</Date>
    <PayerName>test1</PayerName>
    <PayeeName>test2</PayeeName>
    <Amount>-14.0000</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>300.6000</ClosingBalance>
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>U12345</Payer>
      <Payee>X567</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>14.00</Amount>
      <Memo>test 1</Memo>
      <Anonymous>false</Anonymous>
      <Source>API</Source>
    </Transfer>
  </Receipt>
  
  <Receipt>
    <ReceiptId>7659984532147</ReceiptId>
    <Date>2007-01-02 12:45:57</Date>
    <PayerName>test1</PayerName>
    <PayeeName>test3</PayeeName>
    <Amount>-5.1500</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>10.0400</ClosingBalance>
    
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>U12345</Payer>
      <Payee>U334455</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>5.15</Amount>
      <Memo>test 2</Memo>
      <Anonymous>false</Anonymous>
      <Source>API</Source>
    </Transfer>
  </Receipt>
  
  <Receipt>
    <ReceiptId>7659984532148</ReceiptId>
    <Date>2007-01-02 12:45:57</Date>
    <PayerName>test1</PayerName>
    <PayeeName>test4</PayeeName>
    <Amount>-6.0500</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>110.0000</ClosingBalance>
    
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>U12345</Payer>
      <Payee>U9876543</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>6.05</Amount>
      <Memo>test 3</Memo>
      <Anonymous>false</Anonymous>
      <Source>API</Source>
    </Transfer>
  </Receipt>

</TransferResponse>

Requesting transaction history (History)

Operation name

History

Requesting URL

https://api.libertyreserve.com/xml/history.aspx?req=request body

Request format

<HistoryRequest id="id">
  <Auth>  <!-- authentication block -->
    <ApiName>API name</ApiName>
    <Token>authentication token</Token>
  </Auth>

  <History>
    <CurrencyId>currency</CurrencyId>  <!-- not required (defaults to any currency) -->
    <!-- you may use set of currencies separated by comma to retrieve transactions for;
     for example: LRUSD, LREUR -->
    <AccountId>account number</AccountId>
    <From>start date</From>  <!-- not required -->
    <Till>end date</Till> <!-- not required -->
    <CorrespondingAccountId>correspondent account number</CorrespondingAccountId>  <!-- not required -->
    <Direction>transaction direction, one of incoming/outgoing/any</Direction> <!-- not required (default empty)-->
    <TransferId>merchant reference</TransferId>  <!-- not required -->
    <ReceiptId>transaction id</ReceiptId>  <!-- not required -->
    <TransferType>transfer type</TransferType>  <!-- not required -->
    <Source>source</Source>  <!-- not required; if omitted, defaults to any source -->
    <Anonymous>anonymity, one of yes/no/any</Anonymous>  <!-- not required; if omitted, defaults to any anonymity -->
    <AmountFrom>amount, minimal absolute value</AmountFrom>  <!-- not required; if omitted, defaults to any amount -->
    <AmountTo>amount, maximal absolute value</AmountTo>  <!-- not required; if omitted, defaults to any amount -->
    
    <Pager>  <!-- result paging block, not required -->
      <PageSize>transactions per page of result</PageSize>
      <PageNumber>page number</PageNumber>
    </Pager>
  </History>
</HistoryRequest>

With XML API, you have an option to request not more than 50 transactions per single history data request. If data parameters, such as size and page number (<Pager> command is not used), are not specified you will receive only the first 50 transactions in a specified account, even if there are more than 50 transactions available. You need to use <Pager> element in order to select all needed transactions. You need to send as many separate server requests as there are pages in your request. The most proper way to accomplish this is to specify the page size (not more than 50 transactions) in <PageSize> parameter and <PageNumber> set to 1 (can be omitted) in your first request. You will receive the total amount of pages and the number if current page in server response. (explained below). To select the consequent pages you just need to specify the page number, where page size should remain the same as in the first request. You may also choose to select pages at random.

If you omit all optional parameters in History request, Liberty Reserve XML API will return last 50 transactions from your history.

Response format

<HistoryResponse id="id" date="response date">

  <Pager>
    <PageSize> <!-- actual page size (transaction count) --></PageSize>
    <PageCount> <!-- page count --></PageCount>
    <PageNumber> <!-- current page number --></PageNumber>
    <TotalCount> <!-- total count of selected transactions --></TotalCount>
  </Pager>

  <Receipt>  <!-- transaction #1 -->
    <ReceiptId>transaction ID</ReceiptId>
    <Date>transaction date</Date>
    <PayerName>payer account name</PayerName>
    <PayeeName>payee account name</PayeeName>
    <Amount>amount</Amount>
    <Fee>fee</Fee>
    <ClosingBalance>payer account balance after execution of transaction</ClosingBalance>
  
    <Transfer>
      <TransferId>merchant reference</TransferId>
      <TransferType>transfer type</TransferType>
      <Payer>payer account number</Payer>
      <Payee>payee account number</Payee>
      <CurrencyId>currency</CurrencyId>
      <Amount>amount</Amount>
      <Memo>memo</Memo>
      <Anonymous>anonymous</Anonymous>
      <Source>source</Source>
    </Transfer>
  </Receipt>

  ...

  <Receipt>  <!-- transaction #N -->
  ... transaction data ...
  </Receipt>

</HistoryResponse>

<Receipt> element is absolutely identical the same in transfer server response.

Example

You need to retrieve all incoming transactions in Liberty Reserve USD from 01-01-2007 (UTC) to 01-02-2007 (UTC).

<!--XML document of request-->

<HistoryRequest id="1234568123">
  <Auth>
    <ApiName>APIEntry1</ApiName>
    <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <History>
    <CurrencyId>LRUSD</CurrencyId>
    <AccountId>U12345</AccountId>
    <From>2007-01-01 00:00:00</From>
    <Till>2007-01-02 23:59:59</Till>
    <Direction>incoming</Direction>
    <Pager>
      <PageSize>20</PageSize>
      <PageNumber>1</PageNumber>
    </Pager>
  </History>

</HistoryRequest>

<!--XML document of server response (in a case of successfully processed request)-->

<HistoryResponse id="1234568123" date="2007-01-02 12:45:55">

  <Pager>
    <PageSize>20</PageSize>
    <PageCount>2</PageCount>
    <PageNumber>1</PageNumber>
    <TotalCount>35</TotalCount>
  </Pager>

  <Receipt>  <!-- transaction #1 -->
    <ReceiptId>5669984532148</ReceiptId>
    <Date>2007-01-01 10:00:45</Date>
    <PayerName>test2</PayerName>
    <PayeeName>test1</PayeeName>
    <Amount>1.2500</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>56.3400</ClosingBalance>
    
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>X567</Payer>
      <Payee>U12345</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>1.25</Amount>
      <Memo>for test1</Memo>
      <Anonymous>false</Anonymous>
      <Source>SCI</Source>
    </Transfer>
  </Receipt>
  
  <Receipt>  <!-- transaction #2 -->
    <ReceiptId>5669984532256</ReceiptId>
    <Date>2007-01-02 23:11:10</Date>
    <PayerName>test4</PayerName>
    <PayeeName>test1</PayeeName>
    <Amount>3.6700</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>65.1200</ClosingBalance>
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>U9876543</Payer>
      <Payee>U12345</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>3.67</Amount>
      <Memo>example 1</Memo>
      <Anonymous>false</Anonymous>
      <Source>Site</Source>
    </Transfer>
  </Receipt>
  
  <Receipt>  <!-- transaction #3 -->
    <ReceiptId>5669984532260</ReceiptId>
    <Date>2007-01-02 23:59:10</Date>
    <PayerName></PayerName>  <!-- hidden (anonymous transaction) -->
    <PayeeName>test1</PayeeName>
    <Amount>0.4000</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>66.0000</ClosingBalance>
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer></Payer>  <!-- hidden (anonymous transaction) -->
      <Payee>U12345</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>0.4</Amount>
      <Memo>privacy test</Memo>
      <Anonymous>true</Anonymous>
      <Source>API</Source>
    </Transfer>
  </Receipt>
  
  ...
  
  <Receipt>  <!-- transaction #20 -->
  ... transaction data ...
  </Receipt>
</HistoryResponse>

Searching for a specific transaction by transaction ID

You are looking for information on transaction #667984537694, currency - Liberty Reserve USD.

<!--XML document of request-->

<HistoryRequest id="1234568124">
  <Auth>
  <ApiName>APIEntry1</ApiName>
  <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <History>
    <CurrencyId>LRUSD</CurrencyId>
    <AccountId>U12345</AccountId>
    <ReceiptId>667984537694</ReceiptId>
  </History>

</HistoryRequest>

<!--XML document of server response (in a case of successfully processed request)-->

<HistoryResponse id="1234568124" date="2007-01-02 12:45:55">

  <Pager>
    <PageSize>1</PageSize>
    <PageCount>1</PageCount>
    <PageNumber>1</PageNumber>
    <TotalCount>1</TotalCount>
  </Pager>

  <Receipt>
  <ReceiptId>667984537694</ReceiptId>
  <Date>2007-10-03 05:45:10</Date>
  <PayerName>test1</PayerName>
  <PayeeName>test2</PayeeName>
  <Amount>-100.0000</Amount>
  <Fee>0.0000</Fee>
  <ClosingBalance>3400.0000</ClosingBalance>
  
  <Transfer>
    <TransferId></TransferId>
    <TransferType>transfer</TransferType>
    <Payer>U12345</Payer>
    <Payee>X567</Payee>
    <CurrencyId>LRUSD</CurrencyId>
    <Amount>100.0</Amount>
    <Memo>sample transfer</Memo>
    <Anonymous>false</Anonymous>
    <Source>Wallet</Source>
   </Transfer>
  </Receipt>
</HistoryResponse>

Retrieving last 50 transactions

You want to retrieve last 50 transactions, any currency.

<!--XML document of request-->

<HistoryRequest id="1234568125">
  <Auth>
  <ApiName>APIEntry1</ApiName>
  <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <History>
    <AccountId>U12345</AccountId>
  </History>

</HistoryRequest>

<!--XML document of server response (in a case of successfully processed request)-->

<HistoryResponse id="1234568125" date="2007-01-02 12:45:55">

  <Pager>
    <PageSize>50</PageSize>
    <PageCount>27</PageCount>
    <PageNumber>1</PageNumber>
    <TotalCount>1350</TotalCount>
  </Pager>

  <Receipt>  <!-- transaction #1 -->
    <ReceiptId>5669984532148</ReceiptId>
    <Date>2007-01-01 10:00:45</Date>
    <PayerName>test2</PayerName>
    <PayeeName>test1</PayeeName>
    <Amount>1.2500</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>56.3400</ClosingBalance>
    
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>X567</Payer>
      <Payee>U12345</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>1.25</Amount>
      <Memo>for test1</Memo>
      <Anonymous>false</Anonymous>
      <Source>Site</Source>
    </Transfer>
  </Receipt>
  
  <Receipt>  <!-- transaction #2 -->
    <ReceiptId>5669984532256</ReceiptId>
    <Date>2007-01-02 23:11:10</Date>
    <PayerName>test3</PayerName>
    <PayeeName>test1</PayeeName>
    <Amount>3.6700</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>65.1200</ClosingBalance>
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>U9876543</Payer>
      <Payee>U12345</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>3.67</Amount>
      <Memo>example 1</Memo>
      <Anonymous>false</Anonymous>
      <Source>Site</Source>
    </Transfer>
  </Receipt>
  
  <Receipt>  <!-- transaction #3 -->
    <ReceiptId>5669984532260</ReceiptId>
    <Date>2007-01-02 23:59:10</Date>
    <PayerName></PayerName>  <!-- hidden (anonymous transaction) -->
    <PayeeName>test1</PayeeName>
    <Amount>0.4000</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>66.0000</ClosingBalance>
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer></Payer>  <!-- hidden (anonymous transaction) -->
      <Payee>U12345</Payee>
      <CurrencyId>LRUSD</CurrencyId>
      <Amount>0.4</Amount>
      <Memo>privacy test</Memo>
      <Anonymous>true</Anonymous>
      <Source>Wallet</Source>
    </Transfer>
  </Receipt>
  
  ...
  
  <Receipt>  <!-- transaction #50 -->
  ... transaction data ...
  </Receipt>
</HistoryResponse>

Example with Source, AmountFrom and AmountTo

You want to retrieve all transactions made from SCI with amount range from 10 to 20 LREUR (absolute values).

<!--XML document of request-->

<HistoryRequest id="1234568127">
  <Auth>
  <ApiName>APIEntry1</ApiName>
  <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <History>
    <AccountId>U12345</AccountId>
    <CurrencyId>LREUR</CurrencyId>
    <Source>SCI</Source>
    <AmountFrom>10</AmountFrom>
    <AmountTo>20</AmountTo>
  </History>

</HistoryRequest>

<!--XML document of server response (in a case of successfully processed request)-->

<HistoryResponse id="1234568175" date="2007-01-02 12:45:55">

  <Pager>
    <PageSize>2</PageSize>
    <PageCount>1</PageCount>
    <PageNumber>1</PageNumber>
    <TotalCount>2</TotalCount>
  </Pager>

  <Receipt>  <!-- transaction #1 -->
    <ReceiptId>5669984532149</ReceiptId>
    <Date>2007-01-01 10:06:45</Date>
    <PayerName>test2</PayerName>
    <PayeeName>test1</PayeeName>
    <Amount>10.4500</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>156.4000</ClosingBalance>
    
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>X567</Payer>
      <Payee>U12345</Payee>
      <CurrencyId>LREUR</CurrencyId>
      <Amount>10.45</Amount>
      <Memo>SCI tests</Memo>
      <Anonymous>false</Anonymous>
      <Source>SCI</Source>
    </Transfer>
  </Receipt>
  
  <Receipt>  <!-- transaction #2 -->
    <ReceiptId>5669984534556</ReceiptId>
    <Date>2007-01-05 23:11:10</Date>
    <PayerName>test3</PayerName>
    <PayeeName>test1</PayeeName>
    <Amount>15.8500</Amount>
    <Fee>0.0000</Fee>
    <ClosingBalance>65.1200</ClosingBalance>
    <Transfer>
      <TransferId></TransferId>
      <TransferType>transfer</TransferType>
      <Payer>U9876543</Payer>
      <Payee>U12345</Payee>
      <CurrencyId>LREUR</CurrencyId>
      <Amount>15.85</Amount>
      <Memo>example 2</Memo>
      <Anonymous>false</Anonymous>
      <Source>SCI</Source>
    </Transfer>
  </Receipt>
  
</HistoryResponse>

You will receive an <HistoryResponse> element containing <Pager> element and no <Receipt> blocks if there are no recorded transactions within specified range or parameters.

Retrieving account balance (Balance)

Operation name

Balance

Requesting URL

https://api.libertyreserve.com/xml/balance.aspx?req=request body

Request format

<BalanceRequest id="id">
  <Auth>  <!-- authentication block -->
    <ApiName>API name</ApiName>
    <Token>authentication token</Token>
  </Auth>

  <Balance>  <!-- balance of currency #1 -->
  <CurrencyId>currency</CurrencyId>
  <AccountId>account number</AccountId>
  </Balance>

  ...

  <Balance>  <!-- balance of currency #N -->
  ... balance data ...
  </Balance>

</BalanceRequest>

Response format

<BalanceResponse id="id" date="response date">
  <Balance>  <!-- balance of currency #1 -->
    <AccountId>account number</AccountId>
    <CurrencyId>currency</CurrencyId>
    <Date>date</Date>
    <Value>amount (balance value)</Value>
  </Balance>

  ...

  <Balance>  <!-- balance of currency #N -->
  ... balance data ...
  </Balance>

</BalanceResponse>

Example

You need to obtain balance of Liberty Reserve currency in member’s account.

<!--XML document of request-->

<BalanceRequest id="1234569876">
  <Auth>
  <ApiName>APIEntry1</ApiName>
  <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <Balance>
    <CurrencyId>LRUSD</CurrencyId>
    <AccountId>U12345</AccountId>
  </Balance>
</BalanceRequest>

<!--XML document of server response (in case of successfully processed request)-->

<BalanceResponse id="1234569876" date="2007-10-03 12:43:55">
  
  <Balance>
    <CurrencyId>LRUSD</CurrencyId>
    <AccountId>U12345</AccountId>
    <Date>2007-10-03 12:43:55</Date>
    <Value>3500.0000</Value>
  </Balance>
</BalanceResponse>

Retrieving account name (Account name)

Operation name

Account name

Requesting URL

https://api.libertyreserve.com/xml/accountname.aspx?req=request body

Request format

<AccountNameRequest id="id">
  <Auth>  <!-- authentication block -->
    <ApiName>API name</ApiName>
    <Token>authentication token</Token>
  </Auth>

  <AccountName>  <!-- retrieving name for account #1 -->
    <AccountId>account number</AccountId>
    <AccountToRetrieve>number of account for name retrieval</AccountToRetrieve>
  </AccountName>

  ...

  <AccountName>  <!-- retrieving name for account #N -->
  ... parameters ...
  </AccountName>
</AccountNameRequest>

Response format

<AccountNameResponse id="id" date="response date">

  <AccountName>  <!-- name for account #1 -->
    <AccountToRetrieve>number of account for name retrieval</AccountToRetrieve>
    <Date>response date</Date>
    <Name>account name</Name>
  </AccountName>

  ...

  <AccountName>  <!-- name for account #N -->
  ... data ...
  </AccountName>

</AccountNameResponse>

This operation may be useful for checking of some account existence.

Example

You need to obtain name for account X567.

<!--XML document of request-->

<AccountNameRequest id="1234569878">
  <Auth>
    <ApiName>APIEntry1</ApiName>
    <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <AccountName>
    <AccountId>U12345</AccountId>
    <AccountToRetrieve>X567</AccountToRetrieve>
  </AccountName>
</AccountNameRequest>

<!--XML document of server response (in case of successfully processed request)-->

<AccountNameResponse id="1234569878" date="2007-10-03 12:43:55">
  <AccountName>
    <AccountToRetrieve>X567</AccountToRetrieve>
    <Date>2007-10-03 12:43:55</Date>
    <Name>test2</Name>
  </AccountName>
</AccountNameResponse>

Error handling

Errors can occur while our XML API server is processing or performing your data requests. There could be four types of errors. They are listed below:

XML API access/authentication errors. Such errors may occur when authentication token contains wrong data, when XML 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 format and verify that no characters unsupported by XML 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 XML 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 XML 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.

Error response format

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

  ...

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

</Request prefixResponse>

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>
    <ApiName>APIEntry1</ApiName>
    <Token>F95E0B51136706DF1AE283A00579B0D87B5E38F1470B2EC66D5AE1194B8E9A90</Token>
  </Auth>

  <Balance>
    <CurrencyId>PXGLD</CurrencyId>
    <AccountId>U12345</AccountId>
  </Balance>
  
  <Balance>
    <CurrencyId>LRUSD</CurrencyId>
    <AccountId>U12345</AccountId>
  </Balance>
</BalanceRequest>

<!--XML document of server response-->

<BalanceResponse id="1234569878" date="2007-10-03 12:43:55">
  <Error>
    <Code>403</CurrencyId>
    <Text>Currency disabled</Text>
    <Description></Description>
  </Error>

  <Balance>
    <CurrencyId>LRUSD</CurrencyId>
    <AccountId>U12345</AccountId>
    <Date>2007-10-03 12:43:55</Date>
    <Value>3500.0000</Value>
  </Balance>
</BalanceResponse>

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 XML API.

XML API error codes

Error Code	Name	Error Text	Description
100	InvalidXml	Invalid XML structure	Request body contains wrong XML data
101	InvalidRequestStructure	Invalid request structure/format	XML document is of wrong structure
102	InvalidRequestId	Invalid request identifier (id)	(id) of your request already exists. It has to be unique

200^*	Authentication	Authentication error	This error is a result of incorrect account password, secret API word, name of API or incorrect hash string for authentication token.
201	OperationDisabled	Operation disabled	This operation is not allowed
202^*	ApiDisabled	API entry is disabled	Account's API entry is disabled
203^*	InvalidIpAddress	Invalid requesting IP address	Requesting IP address is not contained in API entry's allowed address list

300	InvalidData	Invalid data	Incorrect data. For example, negative payment amount
301	InvalidDataFormat	Invalid data format	Data formatted incorrectly. Wrong or non-existed date entered or amount is in wrong format.
302	DataSizeExceedsLimit	Data size exceeds limit	Data exceeds allowed or allocated range

400	SourceAccountBlocked	Source account blocked	Source account is blocked by administration
401	TargetAccountBlocked	Target account blocked	Destination account is blocked by administration
402	InsufficientFunds	Insufficient funds	Source account has insufficient funds to complete transaction
403	CurrencyDisabled	Currency disabled	Specified currency is disabled
404	SourceAccountDoesntExist	Source account doesn't exist	Source account doesn't exist
405	TargetAccountDoesntExist	Target account doesn't exist	Target account doesn't exist

500	InternalError	Internal error	Internal system error
501	UnexpectedError	Unexpected error	Unexpected or unknown system error

600^*	XmlApiDisabled	XML API is currently disabled	XML API services is temporarily turned off

* — for these errors XML API server response can contain single error description element if the error occurs.

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.

Change log

Date	Subject	Description
09-11-2007	Error handling	XML API server response can contain not more than one XML element for errors 200, 202, 203, 600 if one of them occurs.
09-12-2007	General server response structure	New attribute date added in XML document of API server response. It contains response UTC date.
09-24-2007	Requesting transaction history	New element <TotalCount> added to <Pager> block of History response.
09-24-2007	Requesting transaction history	<CurrencyId>, <From>, <Till>, <Direction> are no longer required in History request.
10-04-2007	Transaction data structure	New term transaction source parameter added to XML transaction data structure. It also added as <Source> element to receipt output structure.
10-04-2007	History request	New element <Anonymous> added to history search filter.
10-04-2007	History request	New element <Source> added to history search filter.
10-04-2007	History request	New elements <AmountFrom>, <AmountTo> added to history search filter.
10-04-2007	History request	History search filter element <CurrencyId> can contain a set of currencies separated by comma to retrieve transactions within currency set.