Fees

What you can build

An overview of outstanding fees with amount, due date and the material each one concerns. Each fee tells whether it can be paid through the API.

Typical flow

1. The client fetches the fees with GetPatronFees.
2. Each fee is shown with its type, amount and, when known, the items it covers.
3. Fees that are payable can be paid (2.7.2).

What the API provides

• type is fee (typically a late return), compensation (typically a damaged or lost item) or send_to_debt_collector.
• amount and remainingAmount are in minor units, currency in ISO 4217. When remainingAmount differs from amount, part of the fee has been paid.
• payableState is payable or not_payable: whether the fee can be paid and finalized through the API.

What you can build

Patrons pay outstanding fees with the payment methods the library offers, and the library system registers each fee as paid.

Typical flow

1. The patron chooses the fees to pay and a payment method.
2. The client starts the payment with InitializePayment and receives an order ID.
3. The patron pays through the payment gateway, which returns a payment ID.
4. The client registers the payment with FinalizePayment, with paymentId and orderId.
5. The response gives a status for each fee.

What the API provides

• payment in GetConfiguration lists the payment methods (mobile_pay, vipps) and whether partial payments are allowed. Without methods, no payment is available.
• When initialize.state is use_initialize (the default), InitializePayment should come first (otherwise FinalizePayment fails with 300005), and orderId is required. With do_not_use_initialize, the client should skip it.
• A fee may only appear once in FinalizePayment. amount on a fee is only allowed when partial payment is enabled.
• registered means the fee was paid with this payment, and registered_by_different_payment_id that another payment had already paid it. fee_not_payable and not_allowed mean it was not paid.
• Calling FinalizePayment again with the same paymentId returns the same confirmation ID for at least 48 hours. If anything in the request has changed, the call fails.