Skip to main content

​
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. Your integration makes this request from its server, using an API key for the appropriate WeGive organization:
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, as POST /dashboard/virtual-terminal/generate-url (virtualTerminal.generateUrl). The API reference’s base URL already includes /api. See 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:
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:
Open the returned URL exactly as provided. Do not construct the URL yourself, edit its token, or decode and rebuild its parameters.

​
Common options

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.
  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 for a detailed walkthrough. 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

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.
Last modified on October 20, 2026