Cash
General Purpose
Retrieves a specific patron’s cash charge information. The cash charge information may be retrieved as a patron’s cash charges list, or as specific cash charge information. The cash charge list information is exported per institution (ADM library).
Product Version Compatibility
Versions 18, 20.1 and later
Interface Type
RESTful API
Hierarchy
Input Parameters
REST Resource IDs:
Patron ID: The Aleph patron system identifier.
Cash ID: The ID of the specific loan that is requested. May be used to fetch a specific loan’s information.
URL Parameters:
institution: The ID of an institution (ADM library) for which the information is requested. Optional.
view: The format in which the cash charge list will be displayed. Possible values are brief and full. Optional.
Input URI
Cash Charge List:
<Base URL>:/patron/<patron ID>/circulationActions/cash?institution=<Institution ID>
For example:
To retrieve the cash charges list for the patron ID 00000036, use:
http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash
To retrieve the cash charges list for the patron ID 00000036 for a specific institution, use:
http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash?institution=USM50
To retrieve the cash charges list for the patron ID 00000036 in brief format, use:
http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash?view=brief
To retrieve the cash charges list for the patron ID 00000036 in full format, use:
http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash?view=full
Two parameters (separated by the “&” sign)
Two parameters (separated by the “&” sign):
The “institute” and the “view” parameters can be used together – separated by the “&” sign:
Specific institution *and* brief format:
Specific institution *and* full format:
http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash?institution=USM50?view=full
Specific Cash Charge
Specific Cash Charge:
<Base URL>:/patron/<patron ID>/circulationActions/cash/<cash id>
For example:
To retrieve a specific cash charge information for the patron ID 00000036, use:
Input XML – PUT (update) action
In Aleph 22.1 and later it is possible to send an update – from external system – that the Patron has payed the cash debit.
To update Aleph that the Patron has paid a debit sum – use the same URL with a PUT method of HTTP.
Note that the payment is done for a specific ADM library, and the institution parameter of the URL is mandatory for the PUT action.
The PUT action receives the following XML input (example):
post_xml=<pay-cash-parameters> <sum>121.13</sum> <pay-reference>54144</pay-reference></pay-cash-parameters>
Note:
The “sum” is a mandatory tag.
The “pay-reference” is an optional tag. It can be used to provide the receipt or reference number of the pay action as provided by the external system.
The payment is NOT done for a specific cash transaction (and can not be activated from a specific cash charge retrieval).
It is done only from the list of all patron’s charges per institution (ADM library). For example (see above): http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash?institution=USM50 .
Output XML Format
The returned XML includes the patron’s cash charge list per institution, including balance information per sublibrary, or a specific cash charge information. The information is exported as Z31,Z30 and Z13 tags. When setting the view parameter to full, the records are fully extracted. When setting the view parameter to brief, only some of the elements are extracted, in addition to balance tags that report the cash balance per sublibrary.
The list of institutes can be limited to those in which the patron is active, depending on the institute’s setup of the FILTER-LIBRARY-CARD tab100 variable.
Cash charges list example:
<?xml version="1.0" encoding="UTF-8"?>
<pat-cash-list>
<reply-text>ok</reply-text>
<reply-code>0000</reply-code>
<charges>
<translate-change-active-library>USM50</translate-change-active-library>
<institution code="USM50">
<inst-name>Exlibris Demo Libraries</inst-name>
<balance>
<sublibrary code="USM50">
<sublib-name>Exlibris Demo Libraries</sublib-name>
<open-sum>- 1.00</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
<sublibrary code="HYL ">
<sublib-name>East Asian Library</sublib-name>
<open-sum>- 5.00</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
<sublibrary code="HIL ">
<sublib-name>Humanities Library and Reading</sublib-name>
<open-sum>- 5.00</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
<sublibrary code="HILR ">
<sublib-name>Humanities Library and Reading</sublib-name>
<open-sum>- 31.50</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
<sublibrary code="LAW ">
<sublib-name>Law Library</sublib-name>
<open-sum> 18.90</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
<sublibrary code="WID ">
<sublib-name>Main Library</sublib-name>
<open-sum>- 30.52</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
<sublibrary code="MED ">
<sublib-name>Medicine Library</sublib-name>
<open-sum>- 5.00</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
</balance>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000046"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000049"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000057"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000393"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000415"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000432"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000449"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20201401050001068"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000041"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000456"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000424"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200608110000521"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20201401020001059"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20201401020001061"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000441"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20201401010000993"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606030000385"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000002"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000004"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000015"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000023"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000027"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000018"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000068"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606050000461"/>
<cash type="credit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200606060000485"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000066"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5000000036%20%20%20%20200602280000022"/>
</institution>
<translate-change-active-library>USM51</translate-change-active-library>
<institution code="USM51">
<inst-name>USM51 Demo Libraries</inst-name>
<balance>
<sublibrary code="EDUC5">
<sublib-name>Education Library 51</sublib-name>
<open-sum>- 2.00</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
<sublibrary code="LINC5">
<sublib-name>Lincoln Library 51</sublib-name>
<open-sum>- 2.00</open-sum>
<transferred-sum>0.00</transferred-sum>
</sublibrary>
</balance>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5100000036%20%20%20%20200602210000325"/>
<cash type="debit" transferred="N" href="http://server.name:1892/rest-dlf/patron/00000036/circulationActions/cash/USM5100000036%20%20%20%20200602210000326"/>
</institution>
<translate-change-active-library>MAB50</translate-change-active-library>
<institution code="MAB50">
<inst-name>MAB Demo Library</inst-name>
<balance/>
</institution>
</charges>
</pat-cash-list>Specific cash charge example:
<?xml version="1.0" encoding="UTF-8"?>
<get-pat-cash>
<reply-text>ok</reply-text>
<reply-code>0000</reply-code>
<cash type="debit" transferred="N">
<z31>
<translate-change-active-library>USM50</translate-change-active-library>
<z31-id>00000036</z31-id>
<z31-sequence>200602280000046</z31-sequence>
<z31-date>20060228</z31-date>
<z31-status>Not paid by/credited to patron</z31-status>
<z31-sub-library>Medicine Library</z31-sub-library>
<z31-alpha>L</z31-alpha>
<z31-type>Local Patron Registration</z31-type>
<z31-credit-debit>Debit</z31-credit-debit>
<z31-sum>(5.00)</z31-sum>
<z31-vat-sum>(0.00)</z31-vat-sum>
<z31-net-sum>(5.00)</z31-net-sum>
<z31-payment-date>00000000</z31-payment-date>
<z31-payment-hour>0000</z31-payment-hour>
<z31-payment-cataloger/>
<z31-payment-target>Medicine Library</z31-payment-target>
<z31-payment-ip/>
<z31-payment-receipt-number/>
<z31-payment-mode/>
<z31-payment-identifier/>
<z31-description>Local Patron Registration</z31-description>
<z31-key/>
<z31-key-type/>
<z31-transfer-department/>
<z31-transfer-date>00000000</z31-transfer-date>
<z31-transfer-number/>
<z31-recall-transfer-status/>
<z31-recall-transfer-date>00000000</z31-recall-transfer-date>
<z31-recall-transfer-number/>
<z31-related-z31-key/>
<z31-related-z31-key-type/>
<z31-requester-name/>
<z31-upd-time-stamp>200001011200000</z31-upd-time-stamp>
<z31-payment-ip-v6/>
<z31-note/>
</z31>
</cash>
</get-pat-cash>Output XML – PUT (update) action:
In case where the PUT action successfully updated Aleph data, the following response is reported:
<?xml version = "1.0" encoding = "UTF-8"?>
<put-pat-cash>
<reply-text>ok</reply-text>
<reply-code>0000</reply-code>
</put-pat-cash>In case where Aleph data is failed to be updated, the following response is reported (failure can be a result of rare cases like non-responding server):
<?xml version = "1.0" encoding = "UTF-8"?>
<put-pat-cash>
<reply-text>fail to update cash balance</reply-text>
<reply-code>0001</reply-code>
</put-pat-cash>Possible Error Codes
01 : The supplied institution ID is invalid
02 : The patron ID is invalid
04 : Cash charge does not belong to the requested patron
07 : Cash charge does not exist