# Your guide to the Roster Partner Portal

This guide is for the people setting up and running Roster at your organization. It explains the portal in everyday language, so you can work with your developer and check on your churches without learning the API.

Your developer can find API requests, field definitions, code examples and troubleshooting in the [developer documentation](https://docs.rostergiving.com/introduction). Here, we explain what the portal does and how your team can use it.

## Start here

- [How Roster works](#how-roster-works)
- [What you’ll build](#what-youll-build)
- [Your first steps](#your-first-steps)
- [Sandbox, production and sample data](#sandbox-production-and-sample-data)
- [Find the right screen](#find-the-right-screen)
- [Overview](#overview)
- [Integration Guide](#integration-guide)
- [Donor Flow](#donor-flow)
- [Webhooks](#webhooks)
- [Churches](#churches)
- [Gifts](#gifts)
- [Team](#team)
- [Admin](#admin)
- [API keys](#api-keys)
- [Search and your account](#search-and-your-account)
- [Common questions](#common-questions)
- [Words you’ll see](#words-youll-see)

## How Roster works

With Roster, your platform can offer churches a way to receive recurring gifts from a donor's paycheck. The donor starts in your product, then follows the giving steps hosted by Roster and authorizes the recurring gift.

Your platform introduces the giving option, tells Roster which church the donor chose, and keeps your own records up to date. Roster handles the giving steps and sends your software updates about the recurring gift and its donations. The bank moves the money, following instructions from Roster and reporting what happened.

A recurring gift is the arrangement to keep giving. Each payment under that arrangement is a donation. One recurring gift can produce many donations over time.

When the arrangement becomes active, the donor is set up to give. Money may arrive later. Your records should distinguish a deposit received, a transfer the bank has accepted, and confirmation that money reached its destination.

## What you’ll build

Your developer connects your platform to Roster so a donor can start giving and your team can follow the results. That connection needs to:

1. Register your churches and send the information they need for setup.
2. Let a donor start giving from your product, with the correct church attached to their journey.
3. Pass along information you're allowed to provide, such as a name your platform already knows. This saves typing, though the donor may still need to confirm or correct it.
4. Receive updates about recurring gifts and donations, and check for any updates your software missed.
5. Use the donation and permitted donor information in your own reports and existing connection to church-management software.

Suppose a donor starts a $25 recurring gift. Your platform receives updates when the arrangement is created and activated. When Roster records a deposit, your platform receives the details of that donation. The next deposit is another donation under the same arrangement.

Your developer builds this connection in your software. The portal gives the team a place to set it up, check the results and manage it afterward.

## Your first steps

1. Start in sandbox. Open **Integration Guide** with your developer to find the connection details and technical documentation.
2. Open **Donor Flow** together. Review how it looks, which information you'll provide and the paths a donor might take.
3. Ask your developer to register test churches and set up a receiver for automatic notices. You can check them in **Churches** and **Webhooks**.
4. Follow the sandbox scenarios linked from **Recommended API checks**. Check the results in your own software as well as in Roster.
5. Have an owner review **Admin** with your Roster contact. Roster releases production access separately from the test indicators.
6. Once production is available, configure and verify that environment separately before inviting real donors to use the integration.

Invite colleagues through **Team** so each person can sign in with their own email.

## Sandbox, production and sample data

**Sandbox** is where you test with fictional churches and donors, without moving real money. Its records, API keys and webhook destinations are separate from production.

**Production** is where real activity happens. Check the banner before changing settings or using a key. You'll need to set up production separately; switching environments doesn't copy your test churches, keys or webhook settings.

**Sample data** fills the Overview charts with an example so you can see how they work. It isn't your organization's activity. Choosing a different view only changes what you see; it doesn't create churches or donations.

The **Donor Flow demo** lets you preview the giving steps. You can click through without completing a real identity check or authorizing a gift.

## Find the right screen

| I want to… | Go to… |
| --- | --- |
| Understand activity and adoption across our churches | Overview |
| Give our developer the connection details and testing instructions | Integration Guide |
| Preview and configure the donor experience | Donor Flow |
| Set up automatic notices and inspect delivery attempts | Webhooks |
| Find a church and see its current information | Churches |
| Find a recurring gift and its donation history totals | Gifts |
| Invite people or manage their access | Team |
| Review our agreement, fees and payout account | Admin |
| Issue or replace a credential used by our software | API keys |
| Run sandbox simulations | The API testing guide linked from Integration Guide |

**Docs** takes you to the developer documentation. Use **Book a call** to schedule a conversation with Roster.

## Overview

Open Overview to check donation activity, donor participation and how your churches are using Roster.

### Choose the data you want to see

Check the data selector before reading the numbers. It tells you whether you're viewing sample, sandbox or production data. If you can't access an environment yet, the message explains the next step.

### Total donated, donors and revenue

**Total donated** adds up recorded donations. Transfers to destination accounts are a separate part of the process.

In the donor chart, select **Cumulative** to see the accumulated donor total. Leave it off to see active donors in each period.

**Your organization's revenue** shows your calculated share of gifts under the fee schedule. It doesn't track payouts to your bank account. If a fee changes, later donations use the new rate from its effective date; earlier deposits keep the rate that applied to them.

### Period controls and Cumulative

Choose daily, weekly, biweekly or monthly to group the chart data. **Biweekly** splits each month into its first and second halves.

On money charts, **Cumulative** adds the amounts together over time. With it off, each period shows its own amount. The number inside the chart is its latest point; move your pointer over other points to see their details. The current period may still be in progress, so compare it carefully with a full past period.

### Churches

See how many churches have the Roster button and how many have an active recurring donor. The percentage shows how many churches with the button have reached that second step. Select **All churches** to open the church list.

If installation information is unavailable, Roster cannot show that count yet. It does not mean the count is zero.

### Donors

See how many donors joined or left during the period. **Net new donors** subtracts those who left from those who joined. **Average gift** is the average donation amount for the last 30 days; individual donors may give different amounts.

### API status

Your developer can use the 24-hour or seven-day view to check how often your software calls Roster and spot changes in service behavior. One donor journey can involve several calls, so the request count will differ from the donation count.

Even when the API is healthy, your developer should check that your receiver and reporting software are working too.

## Integration Guide

This is the page to open with your developer when you're connecting to Roster or checking what information passes between the two systems.

### Your credentials

**API base URL** is the address your software uses to contact Roster. The documentation website and the link a donor uses to give have separate addresses.

Your **API key** gives your software permission to use Roster. When an owner issues a new key, copy it into your team's secure storage before leaving. Use **Show**, **Hide** or **Copy** while the new key is available. Later, the portal can only show a masked version. If you need a replacement, ask an owner to open **API keys**.

### MCP servers — for AI

If your developer uses an AI coding tool, MCP gives compatible tools a way to read the documentation or make API calls.

- **Docs server** gives the tool access to technical documentation without an API key.
- **API server** lets it make calls using your key. Those calls can perform actions, just as your software can.
- **Connect a coding agent** has the setup instructions.

**OpenAPI (JSON)** is a file that describes the API for software tools. **Docs for LLMs** provides documentation in a format AI tools can read. **API playground** opens the interactive reference, where your developer can explore the API.

### Your path and Recommended API checks

In sandbox, **Your path** shows your progress through setup, testing and production release. Once Roster releases production, you can open it from here when the link is available. The path disappears in the production view.

Expand **Recommended API checks** for four scenarios: activation, a broken payroll connection, an amount change and cancellation. Each row links to instructions. Your developer runs some steps through API simulations; others require signing into the sandbox donor flow.

**Passed** means Roster found that event in its feed, the record of updates your software can read. Your developer still needs to check what happened in your system. These four checks cover part of the testing; financial scenarios and production release need separate attention.

### API traffic

**Sent (your calls)** means requests from your software to Roster. **Received (webhooks)** means notices sent from Roster to your software. These directions are from your perspective.

Choose a period, then expand the data-type counts to see which fields appear in that activity. These counts describe fields, not people or payments. For the full list of supported fields, use the Glossary below.

### Glossary

Open a Glossary group to see what your software can send or receive in that request, response or event. Each row explains one field and when it appears.

One message can contain both a donor name and a donation amount. Those are two fields inside the message. The same field can also appear in several kinds of message, so you may see it in more than one group.

**Required** means the field must be included, even if its value may be unknown. **Null** means no value was supplied. Some requirements apply only in the situation named in the row. **[]** means each item in a list.

The portal includes the glossary from its software release. **Full glossary** and **Event catalog** open the technical references in the docs. The portal does not fetch those pages live.

## Donor Flow

Preview the steps a donor may see and try the appearance settings before using them in your integration.

### The preview and step explanations

The preview is marked **Demo only**. Move through it with **Next** and **Back**; the dots show your progress. Beside each step, a short explanation tells you what the donor is doing.

You can move past a photo or payroll step without taking a photo or connecting an account. You're previewing the experience here. Testing the supplier connection requires a separate sandbox test.

### General customization

Adjust the appearance with the controls shown. Your developer can find the supported settings under **All API properties**. These are defined options, rather than unrestricted access to every screen’s HTML or CSS.

Use **Customize for each church?** if churches need their own appearance. Check **Appearance for** before editing: it tells you whether you are changing the shared default or a particular church.

Some screens belong to outside providers and may keep their own appearance. The available adjustments still need to be confirmed for each of those screens. Not every element in the demo is necessarily customizable.

### Data collected before the flow

Choose which information your platform plans to send before the donor starts. You are saving a list of intended fields here, not uploading anyone’s details.

The demo fills those fields with fictional values. Your software sends the actual details when it creates a donor session. Your developer can also change the saved field choices through the API.

### Save all settings

**Save all settings** saves your appearance settings and the list of fields you plan to provide. Check the saved status before leaving. Moving between steps or selecting a demo path only changes the preview.

### Explore the paths

Select a path and watch the demo above change. **Prefill** uses information already available, while **Photo ID** shows a route that asks for a document. **Prematch**, **Native Link** and **Forms** show different payroll connection paths.

The percentages are planning estimates for the demo. They are not measurements of your donors. Choosing a path here previews it; real donors may follow a different path.

## Webhooks

Roster can send your software a notice when something changes, such as a recurring gift becoming active. This page is where you choose where those notices go and check whether they arrive.

Think of the destination as an inbox for your software. Its address is called a **webhook endpoint**. Your developer builds the receiver and supplies its public HTTPS address.

### Endpoints and event subscriptions

Select **Add endpoint**, enter the destination and choose the events it should receive. Each event describes a kind of change. Its message can contain many fields, which explains why the Glossary is much longer than the event list.

Register destinations separately in sandbox and production. Roster does not copy the test configuration into production.

### The signing secret

When you create an endpoint, Roster shows its signing secret once. Your developer uses it to check that incoming messages really came from Roster. Store it securely. The API key has a different job: it gives your software permission to call Roster.

Use Show/Hide and Copy while the newly created secret is available. Do not include it in screenshots, support messages or shared documents.

### Send a test delivery

Use this button to send a signed test message to the selected endpoint. It checks whether the address and receiver work, without creating a real donor or donation. Your developer will still need to test how your software handles the actual event types.

### Deliveries

Select an endpoint and a date range. **Delivered** and **Failed** count delivery attempts during that period. **Last success** is the latest successful attempt in the same period.

The table shows the event, attempt time, response and event ID, with 50 attempts per page. Dates are in UTC. Delivery history is retained for 14 days, so this is not a permanent financial ledger.

A successful response tells you the receiver acknowledged the message. Ask your developer to check that your system applied the update too.

### Failures and retries

Roster can try again after a temporary failure. There is a limit to automatic retries. If the address is wrong or the receiver has a bug, your developer needs to fix it.

The same event may arrive more than once. Your software needs to recognize it so a repeated notice does not become another donation in your records. If a notice is missed, your developer can retrieve the update from the event or financial feed. The troubleshooting link explains what to check when problems persist.

Removing an endpoint stops deliveries to that destination. Confirm that the destination is no longer needed before removing it.

## Churches

Find the churches connected to your platform here. The indicators at the top summarize your portfolio; the table shows each church’s name, ID, status, donors with gifts, received amount and latest update.

Your software registers churches through the API. They then appear in this list; you do not add them manually on this page.

Use the status filters and column controls to narrow or sort the list. Lists show 50 rows per page; larger tables can scroll horizontally.

Status labels include **Setting up**, **In review**, **Live**, **Suspended** and **Closed**. If a church is **In review**, review is still underway. The label does not give a reason or completion date. Follow any instructions shown, or ask your Roster contact for help with the next step.

**Received ($)** adds up recorded deposits before returns and fees. To check the church’s bank balance, you need its bank records. A church can appear in this list before its receiving account or giving entry point is ready.

## Gifts

Use Gifts to find a recurring giving arrangement and see the donations recorded against it. Each row is one **enrollment**, the name Roster uses for that arrangement. A donor with two arrangements can appear in two rows, and each row can include several donations.

The indicators summarize enrollments, active enrollments and total received. The table shows:

- Enrollment ID, donor name and donor ID.
- Church name and church ID.
- The arrangement’s status.
- Number of recorded donations and their total received amount.
- First and most recent donation dates.

Use column filtering and sorting to find records; move through pages of 50 or scroll sideways for additional columns. Dates use UTC. Amounts are deposits received before returns and fees, not net payouts.

**Active** means the arrangement is enabled for giving. Check the donation dates to see when a payment was recorded. If financial details say **Unavailable**, the amount is unknown, not zero. Leave missing donor details unfilled rather than guessing from another record.

To change an amount or cancel, the donor signs into their giving experience. Those actions are not edits to this table.

## Team

Invite colleagues and manage who can use your workspace here.

Select **Invite member** and enter your colleague’s email. Check the invitation status to see whether they have accepted it.

**Owners** manage sensitive workspace settings, issue and rotate API keys, manage roles and removals, and register the payout account. **Members** can work on the integration, manage webhooks and invite other members. Fee details and payout-account management are restricted to owners.

Open a person’s menu to see the actions available to you. Owners can change roles and remove access. Invitation actions depend on whether the invitation is still pending. Your workspace must always have at least one owner.

Removing a person stops their portal access, but the company’s API key keeps working. If they knew that key and should no longer use it, ask an owner and your developer to arrange a replacement.

## Admin

Owners use Admin to review the agreement, fees and bank details recorded for your organization.

### Your agreement

Find the agreement here, with its signed copy when available. If the section is empty, contact Roster using the option shown to check what still needs to be recorded.

### Your fees

Owners can see the Roster fee, your partner percentage and your fixed fee, along with the date they take effect. Roster records these from your agreement. If the schedule is missing, check with Roster before assuming any fee is zero.

A recurring gift can keep going after a fee changes. Later donations use the new fee from its effective date. Earlier deposits keep the fee that applied when they arrived.

### Payout account

An owner sets up the account where your organization will receive payouts. When **Connect with Plaid** is available, follow the steps to select the bank account. After connection, the portal shows masked account details.

Connecting saves the bank details; it does not send a payout or confirm money has arrived. Follow the on-screen instructions if you need to replace the account or the connection option is unavailable.

## API keys

Use this page to issue or replace the key your software uses to connect. The list shows its environment, creation date, who issued it and its state. Owners can issue or rotate keys. Members can view these details, but cannot recover a complete existing key.

Copy a new key into your team’s secure storage before leaving the page; Roster shows it only once. Use a test key in sandbox and a live key in production.

**Rotate key** immediately stops the previous key from working. Plan the change with your developer so your software can switch to the replacement. Rotating is not a way to reveal the old key.

For instructions on using the key to connect, open **Integration Guide**.

## Search and your account

Click search or press **Cmd+K / Ctrl+K** to find a page, guidance or a record you can access. Results marked **Help article** open an explanation from the Help Center in another tab. Articles are searched using the guide included with your portal version. Record results stay within your workspace and permissions. They do not expose another partner’s records or hidden secrets.

Your user menu is at the lower left, beside your initials. Open it for **Sign out** or **Account settings**, which takes you to **Admin**. There is no separate personal-profile editor.

The workspace menu shows the partner account, environment, production-release status and your role. Check it if you are unsure which account you are using.

## Common questions

### Why is a screen empty?

Check the environment, filters and date range first. The record might be in another view or still loading. If you see an error or an unavailable message, follow its instructions or ask for help before assuming there are no records.

### Why do two numbers differ?

Start with the labels and dates. Are both numbers counting donations, or is one counting donors or enrollments? Check whether **Cumulative** is on and when the figures were updated. Revenue, received deposits, events and delivery attempts all measure different things.

### Can we test without the Simulators screen?

Yes. The [sandbox testing guide](https://docs.rostergiving.com/certification#sandbox-simulation-catalog) lists the supported API simulations, prerequisites and expected results. Your developer can call them directly or use a compatible API MCP tool. These operations are not available in production.

### Are four passed checks enough to launch?

No. They show that four kinds of event reached the feed. Your team still needs to check its receiver, financial reports and ability to recover missed updates, then coordinate the launch with Roster.

### Does “delivered” mean the donation reached the church?

No. In Webhooks, **Delivered** means your software acknowledged a message. You need separate bank information to confirm where the money is. A bank accepting a transfer is also different from confirming credit at the destination.

### What should we include when asking for help?

Tell your Roster contact which screen and environment you were using, roughly when it happened, and what you expected to see. Include the relevant church, enrollment, event or request ID if you have it. Keep API keys, signing secrets, full bank details and identity documents out of the message. Use the contact options provided in the portal or by Roster.

## Words you’ll see

| Term | Meaning |
| --- | --- |
| Partner | The organization connecting its platform to Roster. |
| Workspace | Your organization’s area in the portal. |
| Enrollment | One recurring giving arrangement between a donor and a church. |
| Donation or deposit | A payment received under a recurring giving arrangement. |
| API | The connection your software uses to request information or actions from Roster. |
| API key | A private key that gives your software permission to use the API. |
| Event | A record that something happened or changed. |
| Webhook | A message Roster sends automatically to your software. |
| Endpoint | The address where your software receives those messages. |
| Signing secret | A private value used to verify incoming webhook messages. |
| Field | One piece of information inside a request, response or event. |
| Prefill | Filling in information you already know so the donor does not have to type it again. |
| MCP | A connection that lets compatible AI tools read documentation or use API operations. |
| ChMS | Church-management software used by a church. |
| UTC | The shared time standard used for timestamps in several portal tables. |