> ## 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.

# Test and troubleshoot Apple Pay through VGS

> Verify one-time donations, understand test organizations, and resolve common Apple Pay setup and checkout problems.

Use this guide after [setting up Apple Pay through VGS](/external/support/settings/apple-pay-vgs-setup). A successful domain check or Wallet authorization is one part of the process. Verify the donation result before you launch.

## Agree on the test environment

Check the organization label in **Settings → Payments → Apple Pay** and agree on the test with your WeGive contact.

| Environment | What a test proves |
| - | - |
| **Test organization — payments are simulated** | You can verify the customer setup and checkout flow. WeGive simulates the payment without sending a processor charge. This does not prove live processor acceptance or settlement. |
| **Live organization** | A completed donation can charge the donor's real payment method. Agree on the amount and any refund handling before testing. |
| Apple's sandbox, coordinated with WeGive | This requires a compatible test device, sandbox tester account, test Wallet card, and a matching test arrangement. A test organization or staging domain alone does not switch Wallet to Apple's sandbox. |

Production-hosted test organizations still need valid Apple certificates, verified domains, and the production VGS connection. “Test” controls payment execution; it does not bypass Apple's merchant setup.

<Note>
  Use [Apple's sandbox testing instructions](https://developer.apple.com/apple-pay/sandbox-testing/) only for an agreed sandbox test. A private browser window or a second Mac user alone does not create a working Apple Pay test environment.
</Note>

## Run a complete checkout test

Use Safari on a supported Apple device with an eligible Wallet card for the agreed environment.

<Steps>
  <Step title="Open the exact verified checkout domain">
    Use the intended donation URL and select **One time**, with an amount in **USD**. Make sure this checkout uses the approved Chase Orbital or enabled Finix connection.
  </Step>

  <Step title="Reach payment details">
    On a stepper checkout, advance to the payment step. On a single-page checkout, complete the required fields and find the payment section. Choose Apple Pay where offered.

    Apple Pay itself does not require a donor to sign in to WeGive. Guest checkout must still be allowed by that checkout's settings.
  </Step>

  <Step title="Authorize in Wallet">
    Review the organization and amount in the Apple Pay sheet, then authorize using the device's normal confirmation method.
  </Step>

  <Step title="Verify the donation result">
    Wait for WeGive's confirmation page. Check the corresponding donation in your dashboard, including its amount and status. For a live test, confirm the processor result with your finance or onboarding team.

    If a payment is still processing or the result is unclear, check its status with WeGive before attempting another charge.
  </Step>
</Steps>

## Cover the checkout experiences you use

| Scenario | Expected result |
| - | - |
| One-time gift on a single-page checkout | Apple Pay can appear in payment details and complete the gift. |
| One-time gift on a stepper checkout | Apple Pay can appear at the payment step and complete the gift. |
| Guest donor, when guest checkout is allowed | Signing in is not a prerequisite for Apple Pay. |
| Signed-in donor | The donor can choose Apple Pay for a new eligible payment. |
| Cancel the Wallet sheet | No completed donation; the donor can return to checkout and choose how to pay. |
| Recurring donation | VGS Apple Pay is unavailable. The donor needs a payment method supported for recurring gifts. |
| A prompt changes the gift to recurring after Apple Pay was selected | The one-time Apple Pay authorization cannot be reused. Resolve any validation message by choosing a supported recurring method, or return to a one-time gift and authorize again. |
| An ordinary card donation | The existing card payment flow continues to work. |

Test each hostname and checkout layout you plan to launch. If you use paid event registration, also test its existing Apple Pay placement for an immediate one-time payment.

## Troubleshoot by what you see

<AccordionGroup>
  <Accordion title="The Apple Pay setup section is missing">
    Confirm you are managing the correct organization and have permission to edit payment settings. WeGive must enable setup access for that organization. A separate UAT organization needs its own access.
  </Accordion>

  <Accordion title="Apple will not let me create the identity certificate or add domains">
    Open the Merchant ID in Apple Developer and check for pending agreements. Ask your Account Holder to accept the web merchant terms. Creating the processing certificate alone does not unlock every web setup step.
  </Accordion>

  <Accordion title="WeGive rejects my certificate upload">
    Check that the signed certificate belongs to the same Merchant ID and was created from the CSR downloaded from the matching WeGive card. Upload the signed `.cer`, not the CSR. Certificates created from another provider's request will not match this setup.
  </Accordion>

  <Accordion title="Connection status is not Ready">
    Wait for the processing certificate installation to finish. Follow the displayed error or select **Retry setup** if offered. If it remains unsuccessful, send the status and time to WeGive. Creating another Merchant ID or repeatedly replacing valid certificates will not resolve a platform connection problem.
  </Accordion>

  <Accordion title="The domain file returns an error, a homepage, or another provider's file">
    Confirm you uploaded the file to the correct domain row and selected **Publish file** or **Replace file**. Check the exact HTTPS hostname and both supported association paths from the setup guide.

    A descriptive filename on your computer does not change the public URL. If the response is unavailable, redirects, or still differs from your upload, contact WeGive with that URL and the time. WeGive can check domain routing and file delivery.
  </Accordion>

  <Accordion title="The file serves correctly, but the domain is not verified">
    **Check domain** verifies file delivery. Complete **Verify** in Apple Developer, then select the confirmation checkbox and **Confirm Apple verification** in WeGive. Repeat for every hostname. Replacing the association file requires verification again.
  </Accordion>

  <Accordion title="The settings page says Ready, but Apple Pay is missing">
    Check these in order:

    1. VGS is saved and activated as the organization's Apple Pay provider. If it is already selected and **Save provider** is disabled, ask WeGive to confirm the configuration is enabled.
    2. The checkout has Apple Pay enabled and uses Donor Portal V2.
    3. The gift is **one-time USD**. Switching to recurring makes this Apple Pay option unavailable.
    4. This exact domain is verified; another verified domain does not cover it.
    5. The processor used by this checkout or brand is supported and enabled. Another processor connection on the organization does not make every checkout eligible.
    6. The device, browser, and Wallet card support Apple Pay for the agreed environment.

    Reload after changing settings. Donor sign-in is not a general requirement for VGS Apple Pay.
  </Accordion>

  <Accordion title="Wallet says the card cannot be used">
    Confirm the Wallet card is eligible for the merchant and testing environment. An Apple sandbox test needs Apple's test account and card arrangement; a live Wallet card and a sandbox card are not interchangeable. Share the exact message with WeGive before changing the merchant setup.
  </Accordion>

  <Accordion title="Authorization finishes, but the donation fails or has no response">
    Record the error, time, and checkout URL, then check whether a donation was created. A Wallet authorization does not establish that WeGive or the processor completed the payment.

    A browser request with no status or response headers can indicate a browser or network problem, including a failed cross-origin preflight. WeGive needs to inspect that path before attributing it to certificates or the processor. Do not regenerate certificates solely because of this symptom.
  </Accordion>

  <Accordion title="The checkout asks me to sign in after I gave as a guest">
    Apple Pay authorizes the payment; it does not sign you in to WeGive. A guest donation can succeed while account access still requires sign-in. Verify the donation separately from your account session.
  </Accordion>
</AccordionGroup>

## Send WeGive the right information

Include the organization name, exact checkout URL, single-page or stepper layout, one-time or recurring selection, amount, device/browser, error text, and the time with timezone. Add the donation reference or request ID if available.

Send screenshots of the relevant status or error. Remove authorization headers, session cookies, payment payloads, and private keys before sharing technical captures.

<CardGroup cols={2}>
  <Card title="Setup walkthrough" icon="list-check" href="/external/support/settings/apple-pay-vgs-setup">
    Return to certificates, domains, and activation.
  </Card>

  <Card title="Renew certificates" icon="refresh-cw" href="/external/support/settings/apple-pay-vgs-renewal">
    Maintain an existing configuration without starting over.
  </Card>
</CardGroup>


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