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

# Setting Up and Using a Custom Virtual Terminal

> Request a custom Virtual Terminal for your CRM or call center, generate a payment-entry link through the WeGive API, and recover from an expired session.

# Setting Up and Using a Custom Virtual Terminal

A custom Virtual Terminal lets your staff or call-center team enter gifts on behalf of supporters using a link generated by your CRM or another approved system. The link can include supporter information, gift details, and your organization's branding.

**Contact WeGive to arrange setup before building the integration.** Your organization needs a Virtual Terminal login configured by WeGive, plus API access for the system that generates links.

## 1. Request setup from WeGive

Send your WeGive contact:

* Your organization name and WeGive organization ID, if available.
* Who will use the terminal, including any call-center or integration partner.
* The system that will generate and open links, and your technical contact.
* The gift types and payment methods your team needs.
* Any default designation, campaign, supporter details, branding, or fields you want hidden or locked.
* The pages agents should return to after completing or canceling a payment, if applicable.
* Whether you need sandbox access for testing.

You can use this request:

> Please help us set up a custom Virtual Terminal for \[organization]. Our \[CRM/call-center system] will generate a fresh link when an agent is ready to enter a gift. Our technical contact is \[name and email]. We need \[gift types, payment methods, and default fields], and would like to test the workflow in sandbox before launch.

WeGive will confirm the setup, available options, and any organization-specific requirements. Ask WeGive to confirm the session timeout for your organization.

## 2. Generate a link through the API

Your integration makes this request **from its server**, using an API key for the appropriate WeGive organization:

```http theme={null}
POST https://api.wegive.com/api/dashboard/virtual-terminal/generate-url
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json
```

For sandbox testing, use `https://api.sandbox.wegive.com/api/dashboard/virtual-terminal/generate-url` with the corresponding sandbox setup and credentials.

The endpoint is listed under **VirtualTerminal** in the [WeGive API reference](https://docs.api.wegive.com/), as `POST /dashboard/virtual-terminal/generate-url` (`virtualTerminal.generateUrl`). The API reference's base URL already includes `/api`.

See [API Overview & Authentication](/external/support/settings/api-overview-authentication) for API key setup. Keep the API key in your server's secret store; agents and browser code should receive only the generated link.

### Example: prefill an individual supporter and a one-time gift

In this server-side example, `WEGIVE_API_KEY` contains your API key:

```bash theme={null}
curl --request POST \
  'https://api.wegive.com/api/dashboard/virtual-terminal/generate-url' \
  --header "Authorization: Bearer $WEGIVE_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "donor_type": "individual",
    "first_name": "Jane",
    "last_name": "Example",
    "donor_email": "jane@example.org",
    "disable_donor_search": true,
    "amount": 25,
    "frequency": "once"
  }'
```

This prefills the supporter form and a \$25 one-time gift in the v1 terminal. For this link-generation endpoint, `amount` is the amount displayed in the terminal, in dollars, rather than cents. Generating the link does not charge a payment method.

Replace the example supporter details with the intended supporter's information. Include `designation_id` or other defaults if required by your organization's setup.

A successful response contains a top-level `url`:

```json theme={null}
{
  "url": "https://dashboard.wegive.com/payments/virtual-terminal?token=REDACTED&params=REDACTED"
}
```

Open the returned URL exactly as provided. Do not construct the URL yourself, edit its token, or decode and rebuild its parameters.

### Common options

| Field | Purpose |
| - | - |
| `donor_id` | Open with an existing WeGive supporter selected. Use a WeGive ID belonging to your organization. |
| `donor_type` | Use `individual` or `company` for the supporter-entry form. |
| `first_name`, `last_name`, `donor_email` | Prefill supporter information. The email parameter is named `donor_email`. |
| `phone`, `address1`, `address2`, `city`, `state`, `postal_code`, `country` | Prefill contact and address information. |
| `disable_donor_search` | Set to `true` to show the supporter-entry form without the existing-supporter search. |
| `amount`, `frequency` | Prefill the gift amount and frequency. Frequencies include `once`, `weekly`, `monthly`, `quarterly`, and `annually`. |
| `designation_id`, `campaign_id` | Prefill gift associations using WeGive IDs from your organization. |
| `primary_color`, `banner_image` | Customize the terminal's color and banner image. |
| `redirect_url`, `cancel_redirect_url` | Set where the browser goes after a completed transaction or cancellation. |

The API reference lists additional display options, including fields such as `hide_campaign` and `disable_campaign`. Confirm the desired behavior with WeGive and test it in the terminal version configured for your integration.

## 3. Use the generated link

1. Generate a fresh link when the agent is ready to enter the gift, then open it promptly.
2. On **Supporter Information**, select an existing supporter or review and complete the supporter-entry form. A link with an existing `donor_id` can open directly at Payment Details.
3. Select **Continue**.
4. Review **Payment Details**, including the supporter, amount, frequency, designation, and payment method, then submit when ready.
5. Confirm the result in WeGive before starting another attempt if the outcome is unclear.

For individual supporters, the entry form requires first name, last name, and a valid email address. Companies also require a company name and the contact's first and last names. Phone and address are optional for advancing past Supporter Information.

See [Adding Supporter Information](/external/support/giving/virtual-terminal-adding-supporter-information) for a detailed walkthrough.

## Session timeout: when you need a new link

**A generated link is valid for up to 15 minutes from the time it is created.** Your organization's security policy can set a shorter lifetime. This is a fixed expiration, not an inactivity timer: keeping the page open, typing, or refreshing it does not renew the link.

After expiration, the form may still be visible, but requests can return **Unauthenticated** or HTTP **401**, preventing the agent from continuing. Correcting form fields will not restore an expired session.

To recover:

1. Return to the CRM or system that supplied the link.
2. Use its Virtual Terminal action to generate and open a **new** link. If you were sent the link by another person, ask them to generate a new one.
3. Review the supporter and gift details in the new session before continuing.

For integrations, the recovery action is another call to `POST /api/dashboard/virtual-terminal/generate-url` with a valid organization API key. Reopening the previous URL does not create a new session.

Generate links on demand. Do not bookmark a generated link, reuse it throughout a shift, or prepare links well before agents need them. Treat each link as temporary access to the terminal and avoid including its token or supporter parameters in support messages or application logs.

## Troubleshooting

| What you see | What to do |
| - | - |
| **Continue** is disabled before any request is submitted | Check the required supporter fields and email format, or select an existing supporter from the search results. An incomplete form and an expired session are separate problems. |
| **Unauthenticated** or **401** while using an older terminal link | Generate a fresh link and open it promptly. If a newly generated link also fails, contact WeGive. |
| **401** from the **generate-url API request** itself | Check the integration's API key, bearer header, organization, and environment. A new terminal link cannot be generated until the API request is authenticated. |
| **404 — Virtual terminal login not found** | Ask WeGive to complete or check the Virtual Terminal setup for that organization and environment. |
| **400 — Designation ID is required** | Supply the designation agreed with WeGive for your organization's setup. |
| **422** from the API | Read the response's validation errors and correct the indicated request fields. |

When requesting help, include the organization, approximate time and time zone, browser, and exact error text. Redact API keys, link tokens, and supporter details. If a payment was submitted before the error appeared, check the payment record with your team before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.