payments

Make a payment on a single policy.

Code
This is intended to be used when the payment DOES NOT need to be ran through a vendor,
but instead has already been collected and is simply being posted to the policy.

Parameters
----------
json_dict : dict
    The json_dict dict have the format
    {
        'paymentType': 'Cash',
        'depositDate': '2020-04-13',
        "policyNumber": "10-2015-36",
        'amount': '100.00'
    }

Returns
-------
success : bool
    True if completely successful, false if not
messages : list
    empty
data : dict
    empty

Raises
------
UserWarning
    You must submit a policy_number.
    You must submit an amount.

Add payment method for contact

Code
Parameters
----------
contact_id : str
    Contact id
ach_account : str
    account id
ach_bank : str
    Bank name
ach_name_on : str
    Accountholder's name
ach_routing : str
    Routing number
ach_type : str
    Account type
card_cvv2 : str
    Card CVV2
card_expires_mm : str
    Card expiration (month)
card_expires_yy : str
    Card expiration (year)
card_name_on : str
    Cardholder's name
card_number : str
    Card number
card_type : str
    Card type
type : str
    Payment type ACH/CVV2
address : dict
    Address information for new payment method
customer_profile_id : str
    Customer profile identification from vendor
vendor_payment_method_id : str
    Vendor payment method identification
account_description : str
    Account description
metadata : dict
    Additional vendor specific data

Returns
-------
success : bool
    True, if all necessary information was provided. Otherwise False
messages : list of str
    List of human-readable error messages
data : dict
    result

Apply selected payments and optionally generate deposit receipt upon successful application

Code
Parameters
----------
payment_ids : list
    List of Payment ID objects to apply
print_deposit_receipt : bool
    Boolean flag to print deposit receipt on applied payments

Returns
-------
success : bool
    True if successful, False if not
message : str
    Human readable description of failure reasons
data : dict
    Dictionary containing the `attachmentId` of the deposit receipt, if selected to print

approve_pending_payment

Setup payment method for policies

Code
Parameters
----------
policy_list : list of str
    Policies to update
auto_payment_method_id : str
    auto payment method id
auto_pay_days_before : int
    Payment date shift
contact_id : str
    contact id. Used if auto_payment_method_id is None or if payment-method owner need to be declared explicitly

Returns
-------
success : bool
    True, if all necessary information was provided. Otherwise False
messages : list of str
    List of human-readable error messages
data : dict
    result

Setup payment method for policy or policy term (if policy term id passed)

Code
Parameters
----------
policy_id : str
    Policy to update (optional)
policy_term_id : str
    Policy term to update (optional)
auto_payment_method_id : str
    auto payment method id
auto_pay_days_before : int
    Payment date shift
contact_id : str
    contact id. Used if auto_payment_method_id is None or if payment-method owner need to be declared explicitly
override_propagation: bool
    Overrides BC setting 'billing.store-pay-method-across-terms' if passed (propagate autopay method to next terms)

Returns
-------
success : bool
    True, if all necessary information was provided and update was successful
messages : list of str
    List of human-readable error messages
data : dict
    result

Creates a PaymentBatch instance in the database.

Code
Parameters
----------
data : dict
    A dictionary with batch info
    ::

        {
            "id": str,                          # (optional) UUID (defaults to create)
            "title": str,
            "creator_id": str,                  # (optional) UUID (defaults to logged user)
            "created_at": str,                  # (optional) MM/DD/YYYY (defaults to now)
            "expected_entry_count": int,        # (optional)
            "expected_total_amount": str,       # (optional) Float parseable
            "capture_mode": str,                # (optional) "Policy Number" (default), "Invoice Code"
            "default_paid_amount_source": str,  # (optional) "Term Payoff", "Current Due"
        }

Returns
-------
data : dict
    A dictionary containing the created batch info
    ::

        {
            "id": str,                          # UUID,
            "title": str,
            "created_at": str,                  # MM/DD/YYYY
            "creator_name": str,
            "creator_username": str,
            "expected_entry_count": int,
            "expected_total_amount": str,       # Float parseable
            "capture_mode": str,                # "Policy Number", "Invoice Code"
            "default_paid_amount_source": str,  # "Term Payoff", "Current Due"
        }

success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

Creates payment entries in the database from the given serialized dataset

Code
Parameters
----------
entries : list of dicts
    List containing serialized data for the entries to be created
    ::

        {
            "entry_id": str,             # (optional) UUID
            "payor_id": str,             # (optional) UUID
            "batch_id": str,             # UUID
            "paid_amount": str,          # (optional)
            "check_number": str,         # (optional)
            "batch_datetime": str,       # (optional) MM/DD/YYYY (defaults to now)
            "invoice_code": str,         # (optional if policy_number is specified)
            "policy_number": str,        # (optional if invoice code is specified)
            "distribution_amount": str,  # (optional) Float parseable
            "distribution_action": str,  # (optional)
            "billing_schedule_id": str,  # (optional) UUID
        }

Returns
-------
data : list of dicts
    List containing serialized data for the created entries
    ::

        {
            "entry_id": str,
            "group_id": str,
            "payor_name": str,
            "paid_amount": str,
            "payment_id": str,
            "payment_applied": bool,
            "owed_amount": str,
            "full_amount": str,
            "agent_name": str,
            "insured_name": str,
            "invoice_code": str,
            "policy_number": str,
            "distribution_amount": str,
            "distribution_action": str,
            "billing_schedule_id": str,
            "has_future_invoice": bool,
            "policy_is_canceled": bool,
        }

success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

Code
Create a recurring payment consent record.
The administered_by_contact_id is automatically set from the current session.
A detailed note is created with payment method information for audit trail.

Request body should contain:
{
    "contact_id": "uuid",
    "payment_method_id": "uuid" or null
}

Returns:
{
    "success": true,
    "data": {
        "id": "uuid",
        "contact_id": "uuid",
        "payment_method_id": "uuid" or null,
        "administered_by_contact_id": "uuid" or null,
        "consent_timestamp": "ISO datetime string"
    }
}

decline_pending_payment

Removes a PaymentBatch instance from the database.

Code
Parameters
----------
batch_id : str
    UUID of the target batch

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

Deletes payment entries from the database from the given entry ids

Code
Parameters
----------
entry_ids : list of str
    List containing the ids of the target payment entries

Returns
-------
data : list of str
    List containing the ids of the removed payment entries

success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

Code
Ensures receipt exists for specific payment/policy combination.
Generates if missing. Idempotent and safe to call multiple times.

Both parameters are REQUIRED.

Parameters
----------
payment_id : str, required
    UUID of payment
policy_number : str, required
    Policy number to get receipt for

Returns
-------
success : bool
    True if receipt was found or generated successfully
data : dict
    {
        "file_id": "uuid",
        "policy_number": "12345",
        "generated": False,
        "policy_index": 0
    }

Errors
------
- Missing required parameters (payment_id or policy_number)
- Payment not found
- Policy not associated with payment
- Receipt generation failure (propagates from Report().build_receipt())

Notes
-----
- Fail-fast: Errors propagate without generic exception handling
- Idempotent: Safe to call multiple times, won't regenerate existing receipts
- For group payments: Call once per policy to get each receipt

Design-time tester for convenience-fee formulas.

Code
Evaluates the supplied per-method formulas against a test amount and
returns the resolved fee per method. Drives the live "Fee: $X.XX"
chips next to each formula on the convenience-fee settings page
(Settings > Payments). Distinct from
``retrieve_convenience_fee_preview``, which reads *saved* formulas
from the resolver and is consumed at payment time; this endpoint
evaluates *unsaved* admin-supplied formula strings so an admin can
sanity-check syntax and output before clicking Save.

The evaluator (``lib.payments.fee_formula.evaluate_fee_formula``) is
byte-identical to the production path at
``lib.payments.controllers.PaymentProcessorController.get_fee`` --
same Decimal substitution, same whitespace normalization, same
``python2_round`` rounding, same NegativeFeeError. Only the wrapper
differs intentionally: production swallows formula exceptions and
returns 0 + emails admins (runtime safety net); preview surfaces
the real error per-method so the admin sees what's broken
(design-time feedback).

Parameters
----------
payload : dict
    amount : str or number, required
        Test amount to evaluate each formula against. Must parse as
        a positive Decimal.
    formulas : dict, optional
        Logical-method-keyed dict ``{"cc"?, "ach"?, "debit"?}``.
        Each value is a formula string (e.g. ``amount * 0.03``).
        Missing or empty values are skipped and reported as
        ``{"inherited": True}`` so the frontend can render an
        ``(inherits)`` badge instead of an error.
    disclosure_style : str, optional
        ``"new_york"`` or ``"standard"`` (default). Drives the
        ``messages`` formatting. Any other value is treated as
        ``"standard"``.

Returns
-------
data : dict
    results : dict
        Per-method dict. Each method maps to one of:

        * ``{"fee": "3.00"}`` -- successful evaluation
        * ``{"error": "<reason>"}`` -- formula raised; admin sees
          the message inline. Includes negative-fee rejections via
          ``NegativeFeeError``.
        * ``{"inherited": true}`` -- formula was empty; the resolver
          would inherit from the broader scope at runtime.
    messages : list of str
        Customer-facing preview lines for the selected
        ``disclosure_style``, formatted by
        ``PaymentService.format_preview_messages`` (the single
        source of truth shared with the saved-config preview).
        Errored / inherited formulas contribute a $0 fee here.

Permissions
-----------
Admin-only. Mirrors the ``convenience_fees.store_config`` permission
gate -- only users who can save these formulas can preview them. The
eval target is the same restricted scope production uses; the gate
is for consistency, not because the preview adds new attack surface.
No connected payment processor is required: admins
pre-configure and preview convenience fees ahead of Stripe Connect
go-live, matching ``convenience_fees.store_config``.

Code
Get the primary email and all email options for billing-related contacts on the policy revision.

policy_number is required. Policy is looked up by policy_number. Collects emails for
named insureds, additional interests, mortgagees, bill whom, agent, and premium finance
company. Options are deduped by email; when the same email appears for multiple roles,
the single option lists all roles in contact_type and label.

Parameters
----------
policy_number : str, required
    Policy number

Returns
-------
success : bool
data : dict
    email : str or None
        Primary (first) email when at least one contact has an email, else None.
    email_options : list of dict
        Each has: name, email, contact_type, label. Deduped by email; multiple roles
        combined in contact_type and label.

Provides info about policy and terms where it is involved

Code
Parameters
----------
payment_method_id : str
    Payment method id

Returns
-------
success : bool
    True, if all necessary information was provided. Otherwise False
data : dict
    A dictionary with payment method info
    ::

        {
            "payment_method": dict,                     # payment method
            "policies_with_auto_payment_method": dict   # policies &  terms where payment method is used as autopay
        }
messages : list of str
    List of human-readable error messages

Retrieve unpaid invoices for bill_date/due_date with additional information

Code
Parameters
----------
bill_date : str, optional
                Format is yyyy-mm-dd
due_date : str, optional
                Format is yyyy-mm-dd
manualpay_date_adjustment : bool, optional
                If false/not provided - returns invoices with requested bill date/ due date fot policies
                    with manual payments
                If true - returns invoices with correlated date if autopay disabled for policy.
                       F.e. If you requested invoices with due date 2022-09-09, and report_due_date_minus_x is -1
                       - you will get in invoice with due date 2022-09-10 - because in paper doc
                         this invoice has date 2022-09-09
autopay_date_adjustment : bool, optional
                If false/not provided - returns invoices with requested bill date/ due date fot policies
                    with auto payments
                If true - returns invoices with correlated date if autopay enabled for policy.
                       F.e. If you requested invoices with due date 2022-09-09, and report_due_date_minus_x is -1
                       - you will get in invoice with due date 2022-09-10 - because in paper doc
                       this invoice has date 2022-09-09

Returns
-------
success : bool
messages : []
data : list of dicts
    ::
    [{
        "policy": {
            "active": true,
            "is_valid": true,
            "id": "444f33ba-c313-49da-9999-133e96ef339a",
            "inception_date": "2008-05-23",
            "policy_number": "H09533"
        },
        "term": {
            "effective_date": "2021-05-23",
            "expiration_date": "2022-05-23",
            "is_valid": true,
            "term_type": "1 Year"
        },
        "billing_schedule": {
            "name": "Monthly EFT",
            "id": "fff045c3-37c6-4872-ac72-09be2fc0ea86"
        },
        "active_revision": {
            "revision_date": "2021-05-23",
            "named_insureds": [
                {
                    "phones": [
                        {
                            "date_updated": "2019-03-24 01:57:00",
                            "phone": "1114636251",
                            "type": "Home"
                        }
                    ],
                    "name": "John Doe",
                    "contact_id": "1112d33f-3c57-4d22-bda5-6300e03a4d38"
                },
                {
                    "phones": [],
                    "name": "Jane Doe",
                    "contact_id": "111f1e42-1b05-436e-9087-9ee386222161"
                }
            ],
            "policy_id": "444f33ba-c313-49da-9999-133e96ef339a",
            "id": "79d4d7a9-4444-4199-8a60-e62134689b76",
            "policy_status": "Active",
            "policy_term_id": "fcd2066b-d8f9-2222-ac46-bf3f70e01c68"
        },
        "invoice": {
            "due_date": "2021-06-28",
            "debits": 260.06,
            "description": "Installment Invoice",
            "paid_in_full": false,
            "is_valid": true,
            "cancel_date": "2021-07-13",
            "account_balance": 260.06,
            "file_id": "ce06e321-1111-4bd2-810e-84a6f1947583",
            "revision_id": "79d4d7a9-4444-4199-8a60-e62134689b76",
            "id": "92c10551-eeb8-4023-807e-443b51e6cccc",
            "bill_date": "2021-06-08"
        }
    },...]

Import a collection of payment entries into the accounting system.

Code
Parameters
----------
entry_ids : list of str
    List containing the ids of the target payment entries
bypass_duplicates_check : bool
    Whether to bypass duplicate check for all the entries being imported

Returns
-------
data : list of dict
    List of dict in the format
    ::

        {
            'entry_id': str,
            'payment_id': str,
            'duplicate_payment_id': str,
            'payment_applied': bool,
        }

success : bool
    True if successful, false if not

messages : list of dict
    List of dict representing errors respective to the index at the given entry_ids
    ::

        {
            "entry_id": str,
            "message": str
        }

import_payment_method

Make payment for policy/contact with payment_method_id and payment_amount

Code
Parameters
----------
payment_method_id : str
    Payment method id
payment_amount : str or decimal
    min/max/next_term or explicit amount to pay
contact_id : str
    Contact which policies should be paid(optional)
policy_id : str
    Policy that should be paid (optional)
payor_name : str
    Display name of the payer (optional); stored on the payment and used
    on the confirmation's payor line. Same meaning as store_payment's
    payor_name.
payor_email : str
    The payer's email address (optional). When present and valid, the
    standard payment confirmation is auto-emailed to it.
bypass_cannotpay_guard : bool
    Skip the payability guard (BC-24420) and accept the payment on a policy
    the carrier's configuration would otherwise refuse -- a pending non-pay
    cancellation flagged Poor Payment History, an expired or rejected policy,
    one canceled past its payment window.

    For internal callers acting on behalf of staff, who may take a payment
    the insured cannot make themselves: the life-cycle options behind the
    refusal are scoped to *external* payments. Defaults to False, so the
    guard applies unless a caller deliberately opts out and a new or
    forgotten caller fails closed.

    Must be a real boolean. A non-boolean is rejected with ``error_code``
    ``invalid_parameter`` rather than coerced, so a stringy ``"false"``
    cannot be read as an enabled bypass.

Returns
-------
success : bool
    True, if all necessary information was provided. Otherwise False
messages : list of str
    List of human-readable error messages
data : dict
    results of payment

Please use api/v2/payments/store_external_payment endpoint if you're simply registering an external payment.

Code
For given invoice/policy number we identify it's respective policy and primary payment method,
to then apply the respective amount on the payment_date. System uses the auto-pay payment method,
but if non located it will default to the primary insureds' first payment method.

- Payments are always invoked through PaymentController().make_payment(). When payment_transaction_id is set, it's
assumed funds are already deducted any payment recorded would have similar effects as a "Cash" (but instead of
payment type cash, shows as respective payment vendor). Other information such as payor name and an identifier
to track the source of the payment are also optionally captured for tracking purposes.

- `payment_transaction_id` and `source_id` and `meta` are mandatory when recording a payment that has already
happened.


Parameters
----------
amount : float
    amount payment was recoded as.
payment_date : str, optional
    date in format 'YYYY-MM-dd' representing when payment was made.
    Date-only values (no time of day) use the API receive time on the
    same calendar day, and 23:59:59 of that date for prior-day posts
    (BC-24707). A payload that already includes a time is stored as-is.
invoice_number : str
    AccountHistory.id (UUID) for invoice for respective policy term payment
    was made against.
policy_number : str, optional
    Policy.policy_number of the account we want to make payment on.
payment_transaction_id : str, optional
    The transaction reference id for the payment.
source_id : str, optional
    A string identifier that shows where the payment originates from.
meta: object: dict, optional
    An object containing payment metadata.
    ::
        {
            'payorName': <string>,
            'maskedNumber': <string>, # Last four of ACH account or CC number
            'payment_method': <string>, # One of Visa, MC, AMEX, Discover, ACH
        }

Returns
-------
success : True if payment processed correctly, otherwise false
messages : list of failure messages
    ::
        [
            'Attempted to setup default payment method',
            'Updated account balance'  # present if success payment was processed'
        ]
data : dict
    ::
        {
            'isDuplicate': false,
            'payoffAmount': <decimal>,  # overall amount due to payoff policy term
            'confirmationNumber': "124312312",  # numeric string value that can be used to nsf payment later
        }

Searches respective payment for the specified amount/date/invoice and mark it as NSF.

Code
This also invokes any NSF policy activity that might happen when applying it from the UI.

Parameters
----------
amount : float
    amount payment was recoded as.
payment_date : str
    date in format 'YYYY-MM-dd' representing when payment was made.
policy_number : str
    Policy.policy_number for account we want mark payment as NSF. System
    defaults to latest term if passed instead of invoice_number.
invoice_number : str
    AccountHistory.id for invoice for respective policy term payment
    was made against.
confirmation_number : str
    unique numeric value associated with Payment record. This is
    typically returned by make_payment_by_invoice_or_policy()
disable_auto_pay : bool
    Flag to indicate whether to disable auto pay for current term and
    further terms (if any).

Returns
-------
success : True if processed correctly, else False
messages : list of strings with failure messages if success is ever False
    ::
        [
            'Non pay evaluation complete.',
            'neither the invoice_number or policy_number passed can be located'
        ]

Persist the saved-payment-method authorization attestation for a contact.

Code
Writes provable consent (contact-keyed, unlinked) so a later
``import_payment_method`` can bind it to the created vendor method once it
exists (see ``PaymentMethodAuthorizationService.link_payment_method``). The
acting user comes from the authenticated session, never from caller input.
No-op when capture is turned off for the carrier.

``@api_request`` matters here because this endpoint WRITES: it rolls the
session back on an unexpected failure, so a mid-write exception (e.g. while
``record_consent`` writes its audit note, after the proof row is inserted)
cannot leave a committed row behind a failure response.

Request and response schemas:
``lib/api/api_specs/request-record_saved_method_authorization.json`` and
``response-record_saved_method_authorization.json``.

Soft-delete a payment method (as long as it isn't being referenced by a Policy)

Code
Parameters
----------
payment_method_id : str
    Payment method id to remove

Returns
-------
success : bool
    True, if all necessary information was provided. Otherwise False
messages : list of str
    List of human-readable error messages

For a given account (policy) number we determine what's the payoff amount for it's respective active term.

Code
Parameters
----------
policy_number : str policy.policy_number

Returns
-------
success : bool  # true if payoff amount identified, else false
messages : [
        'policy number <policy_number> is not recognized',  # if we can't identify the account
    ]
data : dict
    ::
        {
            # does not show up if success = False
            'payoffAmount': <decimal>  # overall amount due to payoff policy term
        }

retrieve_active_payment_processor

Retrieve the convenience fee to be charged by the enabled payment processor based on the amount of the payment and the type of account being used.

Code
Parameters
----------
payment_amount : decimal
    Amount of the payment being made
account_type : str
    The type of the account being charged.
    For PaymentProcessor integration: "ACH", "CC" or "DEBIT"
    For legacy vendors: "ACH", "MasterCard", "VISA", "AmericanExpress", "Discover"
policy_id : str, optional
    Policy ID

Returns
-------
success : bool
    True, if all necessary information was provided. Otherwise False
messages : list of str
    List of human-readable error messages
data : dict
    Returned fee amount in the form:
    ::

        {
            "fee_amount": decimal or null,
            "fee_message": str or null,
            "disclosure": str,
            "capture_authorization": bool,
            "disclosure_first_party": str,
            "disclosure_third_party": str
        }

    ``capture_authorization`` / ``disclosure_first_party`` /
    ``disclosure_third_party`` are the shared,
    centrally-delivered saved-payment-method authorization capability:
    whether provable consent must be captured before storing a method,
    and the first-party (policyholder) and third-party (agent
    attestation) disclosure copy, all resolved against the same scope as
    the fee.

Retrieve convenience fee preview with messages and fee amounts grouped by payment method.

Code
This endpoint calculates convenience fees for multiple payment methods and groups them
by their total amounts, generating user-friendly messages for display in the payment UI.

Parameters
----------
payload : dict
    Request payload containing:
    - payment_amount (string): Amount of the payment being made. Use string format for precision.
    - payment_methods (list of str, optional): List of payment methods to calculate fees for.
      Valid values: "ach", "cc", "debit". If not provided, defaults to all payment methods.
    - policy_id (str, optional): Policy ID

Returns
-------
data : dict
    Response data containing:
    ::

        {
            "messages": [
                "ACH/debit card price: $100.00",
                "Credit card price: $103.00 (includes a $3.00 card processing cost)"
            ],
            "fees": {
                "ach": "0.00",
                "cc": "3.00",
                "debit": "0.00"
            }
        }

    Note: The "fees" dictionary only contains the payment methods specified in the request.
    Consumers can determine if there's a surcharge by checking if any fee > 0.
success : bool
    True if successful, False otherwise
messages : list of str
    List of human-readable error messages (empty if successful)

Retrieve the specified payment

Code
Parameters
----------
payment_id : str
    Requested payment id

Returns
-------
success : bool
    True, if specified payment was found, False if otherwise (or errors)
messages : list of str
    List of human-readable error messages
data : dict
    the requested payment object, having the form
    ::
        {
            'account_name': str or null,
            'authorization_state': str,
            'check_number': int,
            'comm_pay_id': UUID,
            'commission_payment': bool,
            'committer': str,
            'complete': bool,
            'confirmation_number': str,
            'date_updated': datetime,
            'deleted': bool,
            'distribution': str or null,  # a JSON-encoded dict of how payment was applied to policies
            'entry_date_time': datetime,
            'file_ids': list of UUID,
            'id': UUID,
            'invoice_number': str,
            'is_auto_payment': bool,
            'masked_number': str,
            'nsf': bool,
            'payment_instrument': str,
            'payment_interface': str or null,
            'payment_method_id': UUID,
            'payor_id': UUID,
            'printed_to_deposit': bool,
            'remote_ip': str,
            'selected_on_deposit': bool,
            'sweep': bool,
            'transaction_amount': float,
            'transaction_date_time': datetime,
            'transaction_type': str,
            'vendor_message': str,
            'vendor_stage': str or null,
            'vendor_stage_success': bool,
            'invoices_paid': list of dict with invoice details:
                {
                    'id': UUID,
                    'description': str,
                    'invoice_amount': float,
                    'amount_paid': float,
                    'amount_due': float,
                    'paid_in_full': bool,
                    'revision_id': UUID,
                    'revision_external_system_reference': str or null,
                    'due_date': date or null
                }
        }

Retrieves the entries related to the given batch

Code
Parameters
----------
batch_id : str
    UUID of the target batch

Returns
-------
data : list of dicts
    List containing serialized data for the created entries
    ::

        {
            "entry_id": str,
            "group_id": str,
            "payor_name": str,
            "paid_amount": str,
            "payment_id": str,
            "payment_applied": bool,
            "owed_amount": str,
            "full_amount": str,
            "agent_name": str,
            "insured_name": str,
            "invoice_code": str,
            "policy_number": str,
            "distribution_amount": str,
            "distribution_action": str,
            "billing_schedule_id": str,
            "has_future_invoice": bool,
            "policy_is_canceled": bool,
        }

success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

Retrieves all PaymentBatch instances in the database.

Code
Parameters
----------
load_entries : bool
    Whether to load and serialize batch related entries in the response.

Returns
-------
data : list of dicts
    A list of dictionaries containing all of the existing batches
    ::

        {
            "id": str,
            "title": str,
            "created_at": str,
            "creator_name": str,
            "creator_username": str,
            "expected_entry_count": int,
            "expected_total_amount": decimal,
            "capture_mode": str,
            "default_paid_amount_source": str,
            "entries": [{
                "entry_id": str,
                "payor_name": str,
                "paid_amount": str,
                "payment_id": str,
                "payment_applied": bool,
                "policies": [{
                    "policy_number": str,
                    "owed_amount": str,
                    "full_amount": str,
                    "agent_name": str,
                    "insured_name": str,
                    "policy_is_canceled": bool,
                    "distribution_amount": str,
                    "distribution_action": str,
                    "billing_schedule_id": str,
                    "billing_threshold": str,
                    "has_future_invoice": bool,
                }],
                "invoices": [{
                    "invoice_code": str,
                    "policy_number": str,
                    "owed_amount": str,
                    "full_amount": str,
                    "agent_name": str,
                    "insured_name": str,
                    "policy_is_canceled": bool,
                    "distribution_amount": str,
                    "distribution_action": str,
                    "billing_schedule_id": str,
                    "billing_threshold": str,
                    "has_future_invoice": bool,
                }]
            }]
        }

success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

Retrieves the entries related to the given batch

Code
Parameters
----------
entry_ids : list of str
    List containing the UUID's for the target entries

Returns
-------
data : list of dicts
    List containing serialized data for the created entries
    ::

        {
            "entry_id": str,
            "group_id": str,
            "payor_name": str,
            "paid_amount": str,
            "payment_id": str,
            "payment_applied": bool,
            "owed_amount": str,
            "full_amount": str,
            "agent_name": str,
            "insured_name": str,
            "invoice_code": str,
            "policy_number": str,
            "distribution_amount": str,
            "distribution_action": str,
            "billing_schedule_id": str,
            "has_future_invoice": bool,
            "policy_is_canceled": bool,
        }

success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages

Code
Check if a recurring payment consent record exists for a payment method.

Request body should contain:
{
    "payment_method_id": "uuid"
}

Returns:
{
    "success": true,
    "data": {
        "consent_given": boolean,
        "consent_id": "uuid" or null
    }
}

retrieve_payment_method_creation_details

Retrieves payment methods according to received parameters

Code
Parameters
----------
exp_less_than : int
    Optional. Filter all payment methods where expiration date less than or equal to
    (current date + exp_less_than days).
    If not provided, list all the active payment methods
contact_ids : list
    Filter payments method only for listed ids
min_updated_on : str in ISO 8601 format (e.g. 2025-01-01T00:00:00Z)
    Optional. Filter payment methods created after the given date

Returns
-------
data : list of dicts
    List containing payment methods

success : bool
    True if successful, false if not

retrieve_pending_payments_for_settlement

Retrieve a Policy's billing information

Code
Parameters
----------
policy_id : str
policy_term_id : str, optional
billing_only : bool, optional
    defaults to True

Returns
-------
success : bool
messages : []
data : dict
    ::
        {
            'billWhoms': [
                {
                    'hideSweep': ,
                    'billingSchedules': [
                        {
                            'automaticPaymentReminder': bool,
                            'billingSchedule': string e.g. 'Annual',
                            'id': uuid
                        },
                        ...
                    ],
                    'paymentMethods': ,
                    'billWhom': string e.g. 'Test Insured - (Named Insured)',
                    'id': ,
                    'billHows': [
                        {
                            'billHow': string e.g. 'Mailing/Billing: 123 Fake - Springfield, MO 65802',
                            'id': uuid,
                        },
                        ...
                    ],
                },
                ...
            ],

            'sendInitialInvoice': bool,
            'whenWithdraw': int,
            'billingSchedule': uuid,

            'recurringSelectedValues': {
                'billHows': uuid,
                'billWhoms': uuid,
                'billingSchedules': uuid,
                'paymentMethods': string,
                'whenWithdraw': int
            } ,

            'initialSelectedValues': {
                'billHows': uuid,
                'billWhoms': uuid,
                'billingSchedules': uuid,
                'manualReason': string,
                'paymentMethods': string,
                'whenWithdraw': int
            },
        }

Whether the saved-payment-method consent control must be shown, and the disclosure copy to render with it. Read-only.

Code
Unlike ``retrieve_convenience_fee`` -- which also carries these fields, but
only as a side effect of a fee calculation -- this endpoint needs no payment
amount, account type, or policy, so a caller that only wants to know whether
to render the consent control does not have to invent placeholder fee
arguments to ask.

Request and response schemas:
``lib/api/api_specs/request-retrieve_saved_method_authorization.json`` and
``response-retrieve_saved_method_authorization.json``.

Retrieve pending sweep payments

Code
Parameters
----------
procdate : str, optional
    optionally pass a date. All sweep payments entered before the passed in date
    will be retrieved. by default, this uses the current date minus the grace period in settings

Returns
-------
success : bool
data : list of dicts
    List containing payments with their associated policy numbers and primary property
    {
        "id": str UUID,
        "transaction_amount": decimal,
        "vendor_message": str,
        "policies": [
            {
                "policy_number_normalized": str,
                "latest_revision": {
                    "primary_property": {
                        "address_line2": str or null,
                        "address_city": str,
                        "address_line1": str,
                        "name": str,
                        "address_state": str,
                        "address_country": str,
                        "address_zip": str
                    },
                    "policy_status": str,
                    "revision_state": str
                },
                "policy_number": str
            }
        ],
        "payment_method": {
            "masked_routing": str,
            "account_type": str,
            "name_on_account": str,
            "account_description": str,
            "address_state": str,
            "vendor": str,
            "address_country": str,
            "account_name": str,
            "address_zip": str,
            "address_line2": str or null,
            "address_city": str,
            "address_line1": str,
            "masked_number": str,
            "contact": {
                "confirmation_email": str,
                "name": str,
                "agency_number": str,
                "phones": [
                    {
                        "type": str,
                        "phone": str
                    }
                ],
                "addresses": [
                    {
                        'address_city': str
                        'address_country': str
                        'address_line1': str
                        'address_line2': str
                        'address_state': str
                        'address_zip': str
                        'type': str
                    }
                ]
            },
            "method": str
        },
        "payment_instrument": str,
        "date_updated": str,
        "transaction_type": str,
        "confirmation_number": str,
        "commission_payment": boolean
    }
    messages : list
        Empty

For a given invoice_id we check if an associated invoice record exists If it exists we return the total amount due.

Code
Parameters
----------
invoice_id : AccountHistory.id where AccountHistory.transaction_type == 'invoice'

Returns
-------
success : bool
messages : [
        # returned if we located an AccountHistory record that is not an invoice
        'passed id is not recognized as invoice record',
        # returned if we didn't identify an AccountHistory record for passed value
        'invoice record not found']
data : dict
    ::
        {
            # only returned if success == True, else empty
            'totalAmountDue': ,  # 0 if already paid in full, otherwise returns remaining balance
        }

Code
Send the payment receipt PDF to the given recipient.

payment_id, policy_number, and recipient_email are required. The UI should call
get_billing_contact_emails to pre-fill options; the chosen or entered email is sent here.

Parameters
----------
payment_id : str, required
policy_number : str, required
recipient_email : str, required
    Recipient email address (from UI dropdown or free-form entry).
subject : str, optional
body : str, optional

Returns
-------
success : bool
data : dict
    { "recipient_email": str, "file_id": str, "policy_number": str,
      "attachment_filename": str }
    file_id is the document actually attached: the stored per-policy receipt
    for a single-policy payment, the group confirmation built for this send
    otherwise.

Code
Marks approved payments with a settlement timestamp given a list of dicts with payment ids

Parameters
----------
payments : list of dicts
    With form
    ::
        [{
        'id': payment uuid,
        'settlement_date_time': timezone-aware datetime in format 'YYYY-mm-ddTHH:MM:SSZ',
        }]

Returns
-------
success : bool
    True, if all necessary information was provided. Otherwise False
messages : list of str
    List of human-readable error messages
data : dict
    With form
    ::
        {
            'summary' : {
                'total' : int, # total number of payments
                'succeeded' : int, # number of payments that succeeded
                'failed' : int # number of payments that failed
            },
            'successful_transactions' : list of given payments that succeeded
            'failed_transactions' : list of given payments that failed in the process
        }

Code
Store an external payment (e.g. from a vendor) in BriteCore.

Parameters
----------
policy_number : str, optional
    Policy number to apply payment to. Either this or policy_number_normalized must be provided.
policy_number_normalized : str, optional
    Normalized policy number to apply payment to. Either this or policy_number must be provided.
transaction_amount_in_cents : int
    Amount of the payment in cents (this avoids floating point rounding)
transaction_date_time : datetime, optional
    Date and time of the payment in the format of YYYY-MM-DD HH:MM:SS
    If not specified, defaults to now.
external_account_name : str
    Descriptive name of the external payment account. This will show up as "External - {external_account_name}"
    on Policies > Payments > Payment Log page.
check_number : int, optional
    Check number associated with the payment. Must be an integer.
sweep_check_number : str, optional
    Sweep check number associated with the payment. Alphanumeric, max 36 characters.

Returns
-------
success : bool
    True if the payment was stored successfully, False if not
messages : list of str
    List of human-readable error messages
data : dict
    Dictionary containing the following keys:
    ::
        {
            'payment': {
                'id': str,
                'account_name': str,
                'confirmation_number': str,
                'transaction_date_time': str,
                'entry_date_time': str,
                'transaction_amount': str,
                'check_number': int,
                'sweep_check_number': str
            }
        }

store_payment