Papaya Pay Any Bill (US)

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

{
  "type": "object",
  "properties": {
    "bill_description": {
      "properties": {
        "user_id": {
          "anyOf": [
            {
              "pattern": "^[a-zA-Z0-9]{10}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "identifier for the user if a user already exists from a previous bill payment",
          "title": "User Id"
        },
        "auth_token": {
          "anyOf": [
            {
              "pattern": "^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "authorization token attached to the user (if a user already exists from a previous bill payment). MUST be the most recent/current auth_token (check latest call with the same user id, possibly in a previous session). Depending how long ago the previous payment was made, may first need to obtain a new token.",
          "title": "Auth Token"
        },
        "userAddress": {
          "anyOf": [
            {
              "properties": {
                "name": {
                  "maxLength": 50,
                  "minLength": 2,
                  "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
                  "title": "Name",
                  "type": "string"
                },
                "address": {
                  "maxLength": 100,
                  "minLength": 5,
                  "pattern": "^[a-zA-Z0-9\\s\\-\\.',#]+$",
                  "title": "Address",
                  "type": "string"
                },
                "city": {
                  "maxLength": 50,
                  "minLength": 2,
                  "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
                  "title": "City",
                  "type": "string"
                },
                "stateCode": {
                  "pattern": "^[A-Z]{2}$",
                  "title": "Statecode",
                  "type": "string"
                },
                "zip": {
                  "pattern": "^\\d{5}(-\\d{4})?$",
                  "title": "Zip",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "address",
                "city",
                "stateCode",
                "zip"
              ],
              "title": "BillingAddress",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The payer's identity: the user's name and billing address (who is paying). Billers use this to attribute the payment to the right person, so a missing or wrong payer identity can cause the payment to be rejected or misapplied. Take it from the bill's account-holder / addressee section if shown; otherwise ask the user for their name and billing address rather than leaving it empty."
        },
        "remitAddress": {
          "properties": {
            "name": {
              "maxLength": 50,
              "minLength": 2,
              "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
              "title": "Name",
              "type": "string"
            },
            "address": {
              "maxLength": 100,
              "minLength": 5,
              "pattern": "^[a-zA-Z0-9\\s\\-\\.',#]+$",
              "title": "Address",
              "type": "string"
            },
            "city": {
              "maxLength": 50,
              "minLength": 2,
              "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
              "title": "City",
              "type": "string"
            },
            "stateCode": {
              "pattern": "^[A-Z]{2}$",
              "title": "Statecode",
              "type": "string"
            },
            "zip": {
              "pattern": "^\\d{5}(-\\d{4})?$",
              "title": "Zip",
              "type": "string"
            }
          },
          "required": [
            "name",
            "address",
            "city",
            "stateCode",
            "zip"
          ],
          "title": "BillingAddress",
          "type": "object",
          "description": "Biller remit-to address (where payment is sent). REQUIRED - a bill cannot be analyzed without it. It is the key signal for safely identifying the biller; without a remit-to address (or another strong identifier) the biller may not be identifiable and the bill will be unpayable. Always provide it: take it from the bill, or if the bill does not show one, identify the biller and research their official remit-to / payment address online. Never omit it or invent a placeholder - if you cannot determine a real remit-to address, ask the user for it."
        },
        "correspondenceAddress": {
          "anyOf": [
            {
              "properties": {
                "name": {
                  "maxLength": 50,
                  "minLength": 2,
                  "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
                  "title": "Name",
                  "type": "string"
                },
                "address": {
                  "maxLength": 100,
                  "minLength": 5,
                  "pattern": "^[a-zA-Z0-9\\s\\-\\.',#]+$",
                  "title": "Address",
                  "type": "string"
                },
                "city": {
                  "maxLength": 50,
                  "minLength": 2,
                  "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
                  "title": "City",
                  "type": "string"
                },
                "stateCode": {
                  "pattern": "^[A-Z]{2}$",
                  "title": "Statecode",
                  "type": "string"
                },
                "zip": {
                  "pattern": "^\\d{5}(-\\d{4})?$",
                  "title": "Zip",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "address",
                "city",
                "stateCode",
                "zip"
              ],
              "title": "BillingAddress",
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Biller correspondence address"
        },
        "account": {
          "anyOf": [
            {
              "pattern": "^(([A-Za-z0-9\\s\\*\\.\\-#]{1,20})|(N/A))$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The user's account or customer number on the bill (the biller's identifier for the user's account). Capture it whenever the bill shows one. Put any invoice, ticket, or reference number in otherInfo (in addition to the account number - some billers need both), not here.",
          "title": "Account"
        },
        "otherInfo": {
          "default": {},
          "description": "Other information extracted from the bill that helps identify the provider or complete the payment (like code, pin, pass ...). Also capture the user's charge identifiers here - invoice number, ticket number, or reference number (e.g. 'invoice_number': '12345', 'reference_number': 'A1B2C3') - whenever the bill shows them, even if it also has an account number: some billers' payment automation needs the account number plus one of these. If the bill shows a payment phone number, include it here too (e.g. 'pay_by_phone': '1-800-555-1234') - like the remit-to address it helps identify the correct biller. For a web-payment URL use the payUrl field instead, not this map.",
          "patternProperties": {
            "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "integer"
                },
                {
                  "maxLength": 75,
                  "minLength": 2,
                  "pattern": "^[a-zA-Z0-9 \\-\\./,'&@*#:?=+()]+$",
                  "type": "string"
                }
              ]
            }
          },
          "propertyNames": {
            "maxLength": 50,
            "minLength": 2
          },
          "title": "Otherinfo",
          "type": "object"
        },
        "payUrl": {
          "anyOf": [
            {
              "maxLength": 120,
              "minLength": 4,
              "pattern": "^[a-zA-Z0-9\\-._~:/?#\\[\\]@!$&'()*+,;=%]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The web address where the bill can be paid online (the 'pay at' / 'pay online' URL printed on the bill), e.g. https://www.biller.com/pay. Like the remit-to address it strongly identifies the correct biller, so include it whenever the bill shows one to reduce the risk of a misidentified, failed, or delayed payment. Must be a single URL of at most 120 characters (just the base 'pay online' address, no extra text); omit it rather than sending anything longer.",
          "title": "Payurl"
        },
        "amountDue": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Total balance due on the bill (the full amount owed), as read from the bill. This is NOT necessarily what the user will pay - see amount_to_pay.",
          "title": "Amountdue"
        },
        "amount_to_pay": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The amount the user wants to pay now. May be a partial payment, distinct from amountDue (the bill total). Ask the user how much they want to pay before calling; set equal to amountDue to pay in full. Passing it previews any fee for that amount in the result.",
          "title": "Amount To Pay"
        },
        "user_amount_statement": {
          "anyOf": [
            {
              "maxLength": 200,
              "minLength": 3,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Required proof that you asked the user how much to pay and they answered: quote what the user actually said (e.g. 'pay the full 150' or 'just 50 this month'). You MUST have asked the user before setting amount_to_pay - never invent the amount or this quote.",
          "title": "User Amount Statement"
        },
        "dueDate": {
          "anyOf": [
            {
              "pattern": "\\d{1,2}\\s?(/|-)\\s?\\d{1,2}\\s?(/|-)\\s?(\\d{4}|\\d{2})",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Due date for the bill in MM/DD/YYYY format MM/DD/YY is acceptable",
          "title": "Duedate"
        },
        "billerName": {
          "description": "Name of the biller",
          "maxLength": 50,
          "minLength": 2,
          "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
          "title": "Billername",
          "type": "string"
        }
      },
      "required": [
        "remitAddress",
        "billerName"
      ],
      "title": "BillDescription",
      "type": "object"
    }
  },
  "required": [
    "bill_description"
  ],
  "title": "analyze_billArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "analyze_billDictOutput"
}

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

{
  "type": "object",
  "properties": {
    "check_input": {
      "description": "Identifiers to look up whether a card has been set on a bill yet.",
      "properties": {
        "user_id": {
          "description": "identifier for the user the bill belongs to",
          "pattern": "^[a-zA-Z0-9]{10}$",
          "title": "User Id",
          "type": "string"
        },
        "bill_id": {
          "description": "identifier for the bill",
          "pattern": "^[a-zA-Z0-9]{10}$",
          "title": "Bill Id",
          "type": "string"
        }
      },
      "required": [
        "user_id",
        "bill_id"
      ],
      "title": "PaymentMethodCheckInput",
      "type": "object"
    }
  },
  "required": [
    "check_input"
  ],
  "title": "check_payment_methodArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "check_payment_methodDictOutput"
}

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

{
  "type": "object",
  "properties": {
    "confirm_input": {
      "properties": {
        "user_id": {
          "description": "identifier for the user that was provided as a result of bill extraction",
          "pattern": "^[a-zA-Z0-9]{10}$",
          "title": "User Id",
          "type": "string"
        },
        "bill_id": {
          "description": "identifier for the specific bill that was provided as a result of a bill extraction",
          "pattern": "^[a-zA-Z0-9]{10}$",
          "title": "Bill Id",
          "type": "string"
        },
        "auth_token": {
          "description": "authorization token attached to the user as obtained when submitting the bill, searching for a biller or getting a new auth token",
          "pattern": "^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$",
          "title": "Auth Token",
          "type": "string"
        },
        "refresh_token": {
          "description": "Refresh token obtained when the user was created during a bill analysis or as input to a previous confirm_payment_intent tool call in previous bill payment sessions",
          "pattern": "^r:[a-z0-9]{32}$",
          "title": "Refresh Token",
          "type": "string"
        },
        "amount_to_pay": {
          "description": "The amount the user has chosen to pay - this is what gets charged. May be a partial payment (less than the bill's full balance). Use the amount the user agreed to when the bill was analyzed, unless they have since changed it.",
          "title": "Amount To Pay",
          "type": "number"
        },
        "user_amount_statement": {
          "description": "Required proof that you asked the user and they confirmed the amount: quote what the user actually said about how much to pay (e.g. 'pay the full 150' or 'just pay 50 this month'). You MUST have confirmed amount_to_pay with the user before calling this - never invent this.",
          "maxLength": 200,
          "minLength": 3,
          "title": "User Amount Statement",
          "type": "string"
        },
        "extra_infos": {
          "default": {},
          "description": "dictionary of information provided by the user as {<fieldname1>:<value1> , <fieldname2>:<value2> ,...}",
          "patternProperties": {
            "^[a-zA-Z0-9_]{2,20}$": {
              "anyOf": [
                {
                  "maxLength": 50,
                  "minLength": 2,
                  "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
                  "type": "string"
                },
                {
                  "pattern": "^(([A-Za-z0-9\\s\\*\\.\\-#]{1,20})|(N/A))$",
                  "type": "string"
                },
                {
                  "pattern": "\\d{1,2}\\s?(/|-)\\s?\\d{1,2}\\s?(/|-)\\s?\\d{4}",
                  "type": "string"
                }
              ]
            }
          },
          "title": "Extra Infos",
          "type": "object"
        },
        "entered_account": {
          "anyOf": [
            {
              "pattern": "^(([A-Za-z0-9\\s\\*\\.\\-#]{1,20})|(N/A))$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "(optional) if the user wishes to change the value extracted for the account by the bill analysis or provided during maual creation, provide the new value here",
          "title": "Entered Account"
        },
        "entered_provider": {
          "anyOf": [
            {
              "maxLength": 50,
              "minLength": 2,
              "pattern": "^(([a-zA-Z0-9 \\-\\_.,'&]+)|(N/A))$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "(optional) if the user wishes to change the provider name extracted by bill analysis or use during manual bill creation provide the new value here",
          "title": "Entered Provider"
        },
        "email": {
          "description": "The user's real email, used to send them payment-status updates. You MUST ask the user for it (or reuse an email they gave earlier in this conversation) and confirm the spelling. NEVER invent, guess, or derive it from their name or the bill - a made-up email means the user gets no updates and could send their payment notifications to a stranger.",
          "maxLength": 254,
          "pattern": "^[a-zA-Z0-9]+([a-zA-Z0-9._%+-]*[a-zA-Z0-9])?@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
          "title": "Email",
          "type": "string"
        },
        "phone": {
          "default": "2223334444",
          "description": "phone number for the user (use the default if you do not have a real one)",
          "pattern": "^(\\+?1[\\s.\\-]?)?(\\([2-9]\\d{2}\\)|[2-9]\\d{2})[\\s.\\-\\\\\\/]?\\d{3}[\\s.\\-\\\\\\/]?\\d{4}$",
          "title": "Phone",
          "type": "string"
        },
        "fee_approved": {
          "description": "True if any fees on the payment have been disclosed to the user and they accepted them",
          "title": "Fee Approved",
          "type": "boolean"
        }
      },
      "required": [
        "user_id",
        "bill_id",
        "auth_token",
        "refresh_token",
        "amount_to_pay",
        "user_amount_statement",
        "email",
        "fee_approved"
      ],
      "title": "ConfirmInput",
      "type": "object"
    }
  },
  "required": [
    "confirm_input"
  ],
  "title": "confirm_payment_intentArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "confirm_payment_intentDictOutput"
}

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

{
  "type": "object",
  "properties": {
    "new_token_input": {
      "properties": {
        "refresh_token": {
          "description": "a  token used to refresh expired auth token provided by previous calls to analyze_bill or create_manual_bills",
          "pattern": "^r:[a-z0-9]{32}$",
          "title": "Refresh Token",
          "type": "string"
        }
      },
      "required": [
        "refresh_token"
      ],
      "title": "NewTokenInput",
      "type": "object"
    }
  },
  "required": [
    "new_token_input"
  ],
  "title": "get_new_auth_tokenArguments"
}

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  },
  "title": "get_new_auth_tokenDictOutput"
}

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

{
  "type": "object",
  "properties": {
    "bill_status_input": {
      "properties": {
        "bill_id": {
          "description": "identifier for the specific bill that was provided as a result of a bill extraction",
          "pattern": "^[a-zA-Z0-9]{10}$",
          "title": "Bill Id",
          "type": "string"
        },
        "auth_token": {
          "description": "authorization token attached to the user as obtained when submitting the bill, searching for a biller or getting a new auth token",
          "pattern": "^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$",
          "title": "Auth Token",
          "type": "string"
        }
      },
      "required": [
        "bill_id",
        "auth_token"
      ],
      "title": "BillStatusInput",
      "type": "object"
    }
  },
  "required": [
    "bill_status_input"
  ],
  "title": "fetch_bill_statusArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "fetch_bill_statusDictOutput"
}

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

{
  "type": "object",
  "properties": {
    "bill_cancel_input": {
      "properties": {
        "bill_id": {
          "description": "identifier for the specific bill that was provided as a result of a bill extraction",
          "pattern": "^[a-zA-Z0-9]{10}$",
          "title": "Bill Id",
          "type": "string"
        },
        "auth_token": {
          "description": "authorization token attached to the user as obtained when submitting the bill, searching for a biller or getting a new auth token",
          "pattern": "^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$",
          "title": "Auth Token",
          "type": "string"
        }
      },
      "required": [
        "bill_id",
        "auth_token"
      ],
      "title": "BillStatusInput",
      "type": "object"
    }
  },
  "required": [
    "bill_cancel_input"
  ],
  "title": "request_bill_cancellationArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "request_bill_cancellationDictOutput"
}