Testing and troubleshooting - WeGive Documentation

Test before switching to live keys

Use pk_test_ and, for Payframes, a matching sk_test_ key. Test and live mode use the same public SDK, checkout, and API URLs. Use the test payment details provided for your account’s processor. A familiar test card from another processor is not guaranteed to work with your configuration. Verify the paths you offer:

Scenario	Expected application behavior
Successful donation	Show the correct amount/currency and retain the transaction ID
Invalid or declined payment	Show a useful failure state without claiming success
Pending payment	Display awaiting confirmation; do not count it as settled revenue
Close or cancel checkout	Restore the page and avoid assuming an in-flight payment failed
Popup blocked	Explain how to allow pop-ups or use a regular browser
Required card authentication	Complete the hosted flow before handling success
Double click or repeated submission	Your backend uses one stable attempt and does not duplicate a charge
Lost response or timeout	Retain the attempt for reconciliation; do not start a new charge automatically
Long-lived Payframes form	Obtain fresh verification context before the first submission
Recurring plan starting today	Inspect the initial transaction and plan state
Recurring plan starting later	Show scheduled status without claiming payment was taken
Mobile and embedded browsers	Confirm opening checkout and returning the result on your actual devices
Custom themes and translations	Verify text contrast, focus, keyboard use, labels, and overflow
Page navigation or component removal	Unmount buttons and destroy fields without duplicating listeners

Check WeGive’s recorded donation details: organization, test mode, currency, amount, brand, designation, campaign, and recurring schedule. Check receipts and the reporting fields your integration relies on. Browser callbacks alone do not replace checking the recorded result. Once your test cases pass and your account is enabled for live processing, change to your live credentials. For Payframes, switch browser and server credentials together. Keep the same pinned SDK URL.

SDK fails to load

Confirm the exact versioned file URL, including /v0.1.0/ and the filename.
If using integrity, verify that its hash belongs to that exact file and version.
Load the SDK before calling WeGive.Pay.init(); do not race an async script.
Check your site’s content security policy and the browser’s Network panel.
For a vendored ESM build, include the manifest’s companion JavaScript files.
Initialize in browser code, not during server rendering.

See installation options.

Button appears, but checkout does not work

A rendered button does not prove credentials or account configuration are valid. Confirm the organization is enabled, the publishable key is active, and the exact embedding origin is allowed. Include the correct scheme and development port. Check that amount is an integer, label is present, and any explicit currency matches your organization’s processing currency. Call pay.open() directly from a user interaction. Browser popup blockers can reject a call after an awaited network request. Do not launch checkout through your own iframe, window-message implementation, or hand-built checkout URL. If checkout opens but the result never reaches your page, examine browser policies that isolate windows or remove the opener relationship, and test in a regular browser outside an application’s embedded webview.

Payframes are blank or invalid

Mount into existing, separate containers with visible height. Wait for mounting to finish, then call ready(). Check for blocked secure-field or verification resources in the Network panel and confirm the publishable key’s origin settings. ready() does not mean the card is valid. Check isValid() after the donor fills all three fields and still handle a rejected tokenize() call. Host-page CSS cannot style inside the fields; use the SDK’s style option. For a fraud-session error before first submission, confirm your browser and server keys belong to the same organization and mode, use a fresh session, and preserve the initiating browser context on the server request. Do not bypass verification if it fails. After submission, follow retry rules rather than changing the original request’s fraud-session value.

The API returned success, but the donation is pending or failed

HTTP success means the request received a response. Check data.status for a transaction. For recurring creation, check data.cancelled and initialTransaction.status when an initial transaction is present. A null initial transaction represents a plan without an initial payment, not a failed attempt to return a transaction ID. Handle unknown or non-success states conservatively and reconcile them using the WeGive record. Do not display a completed donation based solely on HTTP 200.

A retry returned 409

Check whether the error identifies a changed request or an unresolved attempt. Use the same credential, method, endpoint, idempotency key, and exact body bytes for a replay. Do not generate new tokens, change whitespace in stored JSON, or switch keys while replaying the request. If the attempt remains unresolved, contact WeGive before creating another charge. See idempotency and retries.

Get integration support

Contact [email protected] with your organization, SDK version, website origin, browser/device, approximate time and timezone, test/live mode, and the steps needed to reproduce the issue. Include transaction, recurring-plan, or your own attempt identifiers when available, along with a sanitized error message and HTTP status. Never send secret keys, card or bank details, tokenized payment values, complete fraud-session handles, or unsanitized network captures. Remove donor personal information from screenshots and logs before sharing them.

​Test before switching to live keys

​SDK fails to load

​Button appears, but checkout does not work

​Payframes are blank or invalid

​The API returned success, but the donation is pending or failed

​A retry returned 409

​Get integration support