Papaya Pay Any Bill (USA)

Read a bill from the user's description and create it for payment. This is the first step. Capture every address and identifier on the bill (remit-to address, account/invoice number, any code or pin) - missing details can delay or fail the payment. The remit-to address (where payment is sent) is especially important: it is what identifies the correct biller, and a wrong or missing one can match the bill to the wrong biller and cause a failed or delayed payment. Always include it. If the bill does not show a remit-to address, research the biller's official remit-to / payment address online and use that rather than omitting it. For the same reason, capture the bill's online-payment URL in payUrl and any payment phone number in otherInfo whenever the bill shows them - these strongly identify the correct biller. Always secure a user identifier so the payment can be applied to the right account or charge: capture the account/customer number in the account field, and any invoice, ticket, or reference number in otherInfo - capture all that the bill shows, since some billers need the account number plus another identifier. If the bill shows none, ask the user for one rather than proceeding without it. Before calling, ask the user how much they want to pay (the full balance amountDue, or a partial amount), then pass it as amount_to_pay and quote what they said in user_amount_statement - both are required (never invent the amount). If the payment carries a fee, the result includes a fees list - show any returned fee to the user before continuing. The result also includes a payment_link: give this link to the user as-is so they can enter their card on the secure form (the only way to set a payment method). If the user already exists from a prior bill, pass their user_id and auth_token to reuse the account.

Args:
    bill_description: structured bill details, including amountDue, amount_to_pay
        and user_amount_statement

Returns:
    bill/user identifiers, tokens, provider, amount due, the chosen amount_to_pay,
    a payment_link to the secure card form, and any user-facing fees

Optional: check whether the user has finished the secure form and a card is on the bill yet. Returns the card's last 4 digits and name when one is set, or a PENDING status when the form has not been completed. Use only if you need to confirm the card landed (e.g. the user asks) - it is not a required step; the normal path is analyze_bill -> user fills the form -> confirm_payment_intent.

Args:
    check_input: the user_id and bill_id to look up

Final step: submit the bill for payment, after a card has been set. You must have confirmed the amount with the user first (amount_to_pay may be partial) and quote their confirmation in user_amount_statement - do not call this until you have asked. If analyze_bill reported a need for extra information, supply it in extra_infos or submission will fail. Use entered_account / entered_provider only to correct a mis-extracted value. Pass the user's current refresh_token (from analyze_bill or a prior confirm) - do not guess.

Args:
    confirm_input: identifiers, the amount to pay, contact info and any extra info

Check the payment status of a submitted bill. Read value for the current status. statusEvaluatedDescription is only present when the payment was declined or failed, and then explains why - relay that reason to the user. It is omitted for every other status, so treat its presence as a decline/failure.

Args:
    bill_status_input: the bill identifier and auth token

Returns:
    dictionary with keys value, statusDescription, and - only for declined/failed
    bills - statusEvaluatedDescription explaining why the payment did not go through

Get a fresh auth token when another tool fails with an authorization error. Pass the user's current refresh_token; returns a new auth_token/refresh_token pair to use on the retried call and on later calls. Call this only in response to an auth failure, not preemptively.

Args:
    new_token_input: contains the user's refresh token

Returns:
    a new auth_token and refresh_token pair, or an error if the refresh token is
    missing or invalid

Cancel a submitted bill so it will not be paid. Use when the user wants to stop a bill they submitted; cancellation may be rejected if the payment has already progressed too far - relay any error to the user. Not for correcting bill details: re-run analyze_bill for that.

Args:
    bill_cancel_input: the bill identifier and auth token

Returns:
    the cancelled bill id and status, or error details