> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuevesolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

This FAQ explains how the Refer-a-Friend reward program works day-to-day for FI staff (marketing, operations, and admin console users) managing it. It covers eligibility rules, how rewards get paid, and how to use the admin reporting tools.

## Program basics

> **What is this program?**
> An existing member (the *inviter*) shares a referral code. A new or existing member (the *acceptor*) submits that code, and if they meet the program's eligibility criteria within a set time window, both the inviter and acceptor can receive a reward.
>
> **What's the difference between a "New Relationship" campaign and a "New Product" campaign?**
>
> * **New Relationship campaigns** are the member-to-member referral program described above — one member invites another.
> * **New Product campaigns** are a separate campaign type your institution can run independently of any referral relationship (e.g., a new-product signup bonus). Whether each type is available to create is controlled by your program configuration (`CAN_CREATE_REFERAFRIEND_CAMPAIGN` / `CAN_CREATE_FI_REWARD_CAMPAIGN`).

## Eligibility

> **What makes an acceptor (new member) eligible for a reward?**
> All of the following must be true within the eligibility window (see below):
>
> 1. They open an account of an allowed type/product for the campaign.
> 2. They meet an activity requirement — either payroll direct deposit activity **or** debit card activity, depending on your `PAYROLL_DEBIT_CONDITION` setting:
>    * Set to **OR**: either payroll deposits *or* debit card activity is enough.
>    * Set to **AND**: both are required.
> 3. (If enabled) Their account does not have a negative balance.
>
> **What counts as qualifying payroll or debit activity?**
>
> * **Payroll**: a configurable minimum total in direct-deposit credits (default: \$500+), excluding deposits from restricted sources such as PayPal or Venmo.
> * **Debit card**: a configurable minimum number of qualifying debit transactions (default: 5+).
>
> **How long does the acceptor have to meet the criteria?**
> They have a configurable number of days (`DAYS_TO_MEET_CRITERIA`, default 360) from their relationship start date to meet the criteria above.
>
> **What happens if the window expires before they qualify?**
> The referral is automatically closed out — the acceptor is not rewarded, and it's silently excluded from further processing. No error is shown; the widget's help text explains this can happen if the completion window expired or the member never logged in to complete the qualifying activity.
>
> **Does the inviter have any eligibility requirements?**
> The inviter mainly needs an eligible account of their own to receive the reward into (`invtr_act_id`). Beyond that, their reward is primarily gated by the reward limit and skip-code rules below.

## Rewards & payment

> **How does the acceptor's/inviter's reward actually get paid?**
> There are two modes, controlled by the `IS_REWARD_AUTOMATICALLY_PAID` setting:
>
> * **Automatic** ("YES"): the moment eligibility is confirmed (checked whenever the member logs in), the reward is disbursed automatically — no admin action needed.
> * **Manual** ("NO", the default): eligible referrals appear in the admin console (GetReferralsCentral or InviteFriendConsole) for an admin to review and pay using the **"Pay Reward"** action, which triggers the actual fund transfer.
>
> **What's the difference between "Pay Reward" and "Mark as Paid" in the admin console?**
>
> * **Pay Reward** actually moves money — it initiates a real fund transfer to the inviter's and/or acceptor's account.
> * **Mark as Paid** does **not** move any money. It only flags the referral as paid in our records. Use this only when a reward was already paid outside the system (e.g., by check, or another manual process) and you need our reporting to reflect that.
>
> **Can the same referral get paid twice?**
> No. Before any payment attempt (automatic or manual), the system checks whether the inviter and/or acceptor already has a recorded reward transaction for that referral. If one side was already paid but the other wasn't (e.g., a prior attempt partially failed), only the unpaid side is processed — the already-paid side is left untouched. If both sides are already paid, no further payment is attempted at all. A referral marked "Mark as Paid" is also skipped by the automatic-payment flow.
>
> **Is there a limit on how many rewards one inviter can receive?**
> Yes, if `INVITER_REWARD_LIMIT_CHECK` is enabled — the inviter can earn up to `INVITER_REWARD_LIMIT_COUNT` rewards. Once they hit the limit, **their** reward is withheld and they see a configurable limit-reached message — but this does **not** affect the acceptor, who is still paid their reward normally.
>
> **Are there referral codes that never earn an inviter reward?**
> Yes — codes listed in `INVITER_CODES_TO_SKIP_REWARD` (e.g., internal or marketing-distributed codes) always pay \$0 to the inviter, even if every other criterion is met.

## Reporting & admin tools

> **Where do I review and manage referrals?**
> In the admin console — either the classic GetReferralsCentral page or the newer InviteFriendConsole. Both let you:
>
> * Search/filter referrals by date range and status (**All / Not Paid / Paid**).
> * View inviter/acceptor name, account, reward amount, and reward status for each referral.
> * See whether the criteria-completion window has expired for a given referral.
> * Pay a reward or mark one as paid.
> * Manage campaigns (create, edit, view active campaigns).
>
> **Do we get a regular report of referral activity?**
> Yes — a monthly email report is sent automatically (covering the previous calendar month) to the configured admin recipients (`REFERRAL_REPORT_ADMIN_EMAIL_IDS`), with a CSV of that period's referrals attached. If there was no referral activity that month, a "no data" notice is sent instead.

## Troubleshooting

> **A member says they should be eligible but the widget doesn't show it — what should I check?**
>
> * Confirm their account was opened within the criteria-completion window (`DAYS_TO_MEET_CRITERIA`) of their relationship start date.
> * Confirm the account type/product is one your campaign allows.
> * Confirm they meet the payroll/debit activity requirement (and whichever combination — AND/OR — your campaign requires).
> * Check whether `NEGATIVE_BALANCE_CHECK` is blocking them due to a negative balance.
> * Check the admin console to see if their referral shows as expired.
>
> **A referral shows as eligible but hasn't been paid — why?**
>
> * If `IS_REWARD_AUTOMATICALLY_PAID` is off, it's waiting for an admin to trigger **Pay Reward** in the console.
> * If automatic payment is on, it's re-checked and retried on the member's next login — a transient failure (e.g., a temporary transfer error) will be retried rather than silently dropped, but only for the side (inviter/acceptor) that hasn't yet succeeded.
> * Check whether the inviter has hit their reward limit — that only withholds the inviter's portion, not the acceptor's.
>
> **Why does the report show "Not Paid" for something I already paid manually outside the system?**
> Use **Mark as Paid** in the admin console for that referral — it updates the reported status without attempting a duplicate transfer.