Payment

View as Markdown The page’s .md file llms.txt All pages, for AI tools Open in ChatGPT Ask questions about the page Open in Claude Ask questions about the page

Paying a patron's fees. Depending on the provider, the vendor first initializes a payment and gets an order ID, then finalizes it once the money has been taken, which marks the chosen fees as paid. Finalizing the same payment again returns the same result.

2 operations

POST /patron/{patronId}/payment/finalize

Finalize Payment

Bearer token FinalizePayment

Finalize payment, mark fees as paid.

Multiple calls to finalize payment with the same payment ID will return the same confirmation ID, and the FinalizeFeeStatus will be 'registered' (provided, of course, that the previous call also resulted in status 'registered').

If in the configuration, payment->initialize->state is use_initialize and the initialize endpoint has not been called (e.g. if the order ID is not created), finalize returns the error code 300005.
This also means that orderId is required in the request if payment->initialize->state is use_initialize.

Multiple calls to finalize payment with the same payment ID will return the same confirmation ID for a minimum of 48 hours.
If finalize is called a second time with the same payment ID, and any information in the request has changed, finalize returns the error code 300301.

Example request

cURL

curl -X POST "$PLAS_BASE_URL/patron/40218873/payment/finalize?version=0.6.7" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN" \
  -d '{
  "fees": [
    {
      "amount": 15000,
      "id": "94549"
    }
  ],
  "method": "mobile_pay",
  "orderId": "ord_5f2a91c3",
  "paymentId": "pay_8d61b0e4"
}'

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/patron/40218873/payment/finalize?version=0.6.7`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
  body: JSON.stringify({
    "fees": [
      {
        "amount": 15000,
        "id": "94549"
      }
    ],
    "method": "mobile_pay",
    "orderId": "ord_5f2a91c3",
    "paymentId": "pay_8d61b0e4"
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    f"{os.environ['PLAS_BASE_URL']}/patron/40218873/payment/finalize",
    params={
        "version": "0.6.7",
    },
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
    json={
        "fees": [
            {
                "amount": 15000,
                "id": "94549",
            },
        ],
        "method": "mobile_pay",
        "orderId": "ord_5f2a91c3",
        "paymentId": "pay_8d61b0e4",
    },
)
data = response.json()

The host and token are environment variables: PLAS_BASE_URL the provider’s base URL · PLAS_TOKEN an access token.

Parameters

patronIdrequired: path · string
Patron ID from authentication
Example: 40218873

Shared across operations: version. See the shared contract on the version page.

Request body

application/json · required · FinalizePaymentRequestBody

feesarray of FinalizePaymentFeerequired
The list of fees that should be finalized.
This array must not contain any fees with the same ID. In that case, an error will be returned.
Show 2 fieldsHide 2 fields
- amountintegermin 0
  This should only be used with a partial enabled payment methods. If the partial payment is not enabled, but this field is set, the error code 300013 is returned.
  The amount is in minor unit (see ISO 4217).
- idstringrequired
  This is the fee ID.
methodstringrequired
This represents the payment method type.
One of: mobile_pay · vipps ·
orderIdstring
Order ID from initialize payment.
If in the configuration, payment->initialize->state is use_initialize, this field is required.
paymentIdstringrequired
Payment ID from the payment gateway.

Responses

200 Returns a response detailing how the finalize operation went for each fee ID. FinalizeFeesResponseBody

Generated from the schema

Example

{
  "responses": {
    "response-1": {
      "confirmationId": "61946",
      "status": "registered"
    }
  }
}

Schema

FinalizeFeesResponseBody

responsesmap of objectrequired
A mapping from each fee ID (from the request) to a FinalizeFee.
Show 1 fieldHide 1 field
- any keyobject
  Details of how the finalize operation went for a specific fee.
  Show 2 fieldsHide 2 fields
  - confirmationIdstring
    Uniquely identifies a single successful payment finalize operation. This is only set if status was 'registered'.
  - statusstringrequired
    The results of a payment finalize operation. If any other value than the following is returned, it can be assumed that the operation was unsuccessful (i.e. it was not finalized by the current request).
    registered: The fee was successfully finalized
    registered_by_different_payment_id: The fee had already been finalized by a different payment ID
    fee_not_payable: The fee was not payable, and therefore could not be finalized
    not_allowed: The client is not authorized to finalize this fee
    One of: registered · registered_by_different_payment_id · fee_not_payable · not_allowed

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
  A number representing the type of error.
  List of error codes:
  - \<error code\>: \<error description\>
  - 500: System error
  - 600: Unsupported Open Library API version
  - 10001: Endpoint disabled
  - 71001: Consent has not been given for 'loan history'
  - 100001: Wrong patron identifier, password or pin code
  - 100011: New password or pin code rejected, because it does not meet the provider's requirements
  - 100013: The provider does not let the patron change the given credential
  - 100023: Patron ID not found
  - 100101: Patron could not be deleted, because the patron has something unresolved issue with the library (this could be anything from a loan to a fee, and so on ...)
  - 100211: maxNumberOfEmailAddresses exceeded
  - 100215: maxNumberOfPhoneNumbers exceeded
  - 100221: Pickup location cannot contain sections
  - 100411: Updating patron consent failed
  - 100611: Updating patron notification settings failed
  - 101001: Reservation ID not found
  - 101047: Branch ID cannot be used as pick up branch
  - 101053: Section ID cannot be used as pick up branch
  - 102001: Loan ID not found
  - 102301: Loan not renewable, because it is an interlibrary loan
  - 102311: Loan not renewable, because it is reserved
  - 110001: Branch ID not found
  - 200001: Publication ID not found
  - 200077: ui language not supported
  - 200101: missing required query parameter
  - 200103: invalid/unsupported query parameter value
  - 300001: Initialize payment should not be used
  - 300005: Initialize payment should be used
  - 300009: Payment method not supported
  - 300013: Payment method does not support partial payment
  - 300301: Finalized payment can not de changed
  - 300311: FinalizePaymentRequest.fees contains fees with the same ID
  - 310001: Loan history ID not found
  - 310011: Loan history ID already exists
  - 330001: List ID not found
  - 330011: List ID already exists
  - 330101: List item ID not found
  - 330111: List item ID already exists
  One of: 500 · 600 · 10001 · 71001 · 100001 · 100011 · 100013 · 100023 · 100101 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
  Starts with the text matching the error code field (defined above), and a describing text could be added.

401 Bearer token invalid, missing, or expired.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.

404 Resource not found.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.

POST /patron/{patronId}/payment/initialize

Initialize payment

Bearer token InitializePayment

This validates that the method can be used, initializes the payment, and returns an order ID.

Example request

cURL

curl -X POST "$PLAS_BASE_URL/patron/40218873/payment/initialize?version=0.6.7" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN" \
  -d '{
  "initialize": {
    "fees": [
      {
        "id": "94549"
      }
    ],
    "method": "mobile_pay"
  }
}'

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/patron/40218873/payment/initialize?version=0.6.7`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
  body: JSON.stringify({
    "initialize": {
      "fees": [
        {
          "id": "94549"
        }
      ],
      "method": "mobile_pay"
    }
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    f"{os.environ['PLAS_BASE_URL']}/patron/40218873/payment/initialize",
    params={
        "version": "0.6.7",
    },
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
    json={
        "initialize": {
            "fees": [
                {
                    "id": "94549",
                },
            ],
            "method": "mobile_pay",
        },
    },
)
data = response.json()

The host and token are environment variables: PLAS_BASE_URL the provider’s base URL · PLAS_TOKEN an access token.

Parameters

patronIdrequired: path · string
Patron ID from authentication
Example: 40218873

Shared across operations: version. See the shared contract on the version page.

Request body

application/json · required · InitializePaymentRequestBody

initializeobjectrequired
Show 2 fieldsHide 2 fields
- feesarray of objectrequired
  Show 1 fieldHide 1 field
  - idstringrequired
    This is the fee ID.
- methodstringrequired
  This represents the payment method type.
  One of: mobile_pay · vipps ·

Responses

200 Returns a order ID which can be used to finalize the payment. InitializePaymentResponseBody

Generated from the schema

Example

{
  "order": {
    "id": "94549"
  }
}

Schema

InitializePaymentResponseBody

orderobjectrequired
Show 1 fieldHide 1 field
- idstringrequired
  This order ID, should be used to finalize the payment.

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
  A number representing the type of error.
  List of error codes:
  - \<error code\>: \<error description\>
  - 500: System error
  - 600: Unsupported Open Library API version
  - 10001: Endpoint disabled
  - 71001: Consent has not been given for 'loan history'
  - 100001: Wrong patron identifier, password or pin code
  - 100011: New password or pin code rejected, because it does not meet the provider's requirements
  - 100013: The provider does not let the patron change the given credential
  - 100023: Patron ID not found
  - 100101: Patron could not be deleted, because the patron has something unresolved issue with the library (this could be anything from a loan to a fee, and so on ...)
  - 100211: maxNumberOfEmailAddresses exceeded
  - 100215: maxNumberOfPhoneNumbers exceeded
  - 100221: Pickup location cannot contain sections
  - 100411: Updating patron consent failed
  - 100611: Updating patron notification settings failed
  - 101001: Reservation ID not found
  - 101047: Branch ID cannot be used as pick up branch
  - 101053: Section ID cannot be used as pick up branch
  - 102001: Loan ID not found
  - 102301: Loan not renewable, because it is an interlibrary loan
  - 102311: Loan not renewable, because it is reserved
  - 110001: Branch ID not found
  - 200001: Publication ID not found
  - 200077: ui language not supported
  - 200101: missing required query parameter
  - 200103: invalid/unsupported query parameter value
  - 300001: Initialize payment should not be used
  - 300005: Initialize payment should be used
  - 300009: Payment method not supported
  - 300013: Payment method does not support partial payment
  - 300301: Finalized payment can not de changed
  - 300311: FinalizePaymentRequest.fees contains fees with the same ID
  - 310001: Loan history ID not found
  - 310011: Loan history ID already exists
  - 330001: List ID not found
  - 330011: List ID already exists
  - 330101: List item ID not found
  - 330111: List item ID already exists
  One of: 500 · 600 · 10001 · 71001 · 100001 · 100011 · 100013 · 100023 · 100101 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
  Starts with the text matching the error code field (defined above), and a describing text could be added.

401 Bearer token invalid, missing, or expired.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.

404 Resource not found.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.