> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/testing/test-with-paypal.md). # Test with PayPal PayPal is available for testing on a terminal with `type` = `virtual`. In Sandbox, PayPal uses a sandbox test account, so you can complete a test payment and confirm the wallet approval and completion flow end to end. No real assets are required and no live PayPal balance is used. Use this guide when you want to validate the PayPal wallet flow. For the recommended default end to end test, see [Test with Klarna](/testing/test-with-klarna-recommended.md). For a comparison of all test methods, see [Choosing a Test Method](/testing.md). ### 1 – Prerequisites | Item | Notes | | ----------------------------------------------------- | -------------------------------------------------------------------------------------- | | PayPal enabled for your Sandbox merchant and terminal | Contact developer support if PayPal is not yet activated for your Sandbox environment. | | Terminal with `type` = `virtual` | PayPal testing applies to terminals with `type` = `virtual`, not `physical`. | | Sandbox base URL | `https://api.test.devs.beadpay.io` | | Hosted payment page base | Returned in `paymentUrls` | | Terminal API key | You need the real API key value. The masked API key is not usable. | | `merchantId` and `terminalId` | Must match the terminal API key you were issued. | | Sandbox PayPal test account | Provided below. Used to log in and approve the payment in the PayPal Sandbox. | | Webhook endpoint (recommended) | Publicly reachable and registered in the Bead dashboard. | Authentication note: Payments endpoints use header based authentication. Send your API key as `X-Api-Key` on every request. ### 2 – Create Payment Request Send a `POST /Payments/crypto` to generate the hosted checkout URL. On a terminal with `type` = `virtual`, include `refundEmail` and a `customer` object. Required headers: * `X-Api-Key: {apiKey}` * `Content-Type: application/json` To present PayPal as the tender, include `paypal` in `tenderTypes`. **Example request** ```bash curl -s -X POST "https://api.test.devs.beadpay.io/Payments/crypto" \ -H "Content-Type: application/json" \ -H "X-Api-Key: {apiKey}" \ -d '{ "merchantId": "{merchantId}", "terminalId": "{terminalId}", "requestedAmount": 1, "refundEmail": "alex.tester@example.com", "tenderTypes": ["paypal"], "customer": { "firstName": "Jordan", "lastName": "Reed", "email": "jordan.reed@example.com", "address": "456 Market St", "address2": "Suite 210", "city": "Chicago", "state": "IL", "postalCode": "60601", "countryCode": "US" } }' ``` Example response: ```json { "paymentId": "pay_c10b29e3c8104e0f8dc139c20d9eeb6c", "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c", "paymentUrls": [ "https://pay.qa.beadpay.io/crypto?paymentPageId=a12b34c56d789e01" ] } ``` Save these values: * `paymentUrls[0]` for the hosted checkout URL * `paymentId` your primary lookup key for status checks, webhooks, reporting, and support ### 3 – Launch Hosted Payment Page Use `paymentUrls[0]` to launch checkout. | Option | Details | | -------- | ------------------------------------------------------- | | Redirect | Redirect the shopper's browser to the hosted page URL. | | Embed | Load the hosted page URL in an iframe inside your site. | The shopper now sees Bead's hosted payment page. ### 4 – Select PayPal and Open PayPal Checkout 1. In the Bead hosted UI, select PayPal as the payment method. 2. Bead opens the PayPal approval flow. The customer approves the payment via the PayPal app or web. ### 5 – Complete PayPal Sandbox Checkout Log in to the PayPal Sandbox flow using the shared test account below and approve the payment. Because this is a sandbox account, no real PayPal balance is used. | Field | Test value | | ---------------- | ------------------- | | Email / username | | | Password | Password1 | > If the test account stops working, contact developer support to have the Sandbox credentials rotated. Follow the PayPal prompts until the shopper is returned to your `redirectUrl`, if you provided one. ### 6 – Verify Result **Option A: Webhook verification** Confirm your webhook endpoint receives a payment event indicating completion. Look for a status field that indicates the payment is completed. **Option B: API status check (optional)** Endpoint: `GET /Payments/{paymentId}/tracking` ```bash curl -s -X GET "https://api.test.devs.beadpay.io/Payments/{paymentId}/tracking" \ -H "X-Api-Key: {apiKey}" \ -H "Accept: application/json" ``` What to confirm: * The response shows the payment in a completed state. * Amount fields reflect a successful payment for the requested amount. ### Production eligibility PayPal has no US residency restriction and supports customers globally, including all US states and territories. The consumer needs an active PayPal account. See [Which consumers can use Klarna, PayPal, and Venmo?](/faqs-and-troubleshooting/payments-faqs/which-consumers-can-use-klarna-paypal-and-venmo.md) for full details. ### Troubleshooting * **PayPal does not appear as a tender option.** PayPal may not be enabled for the Sandbox merchant or terminal, or the terminal is not `type` = `virtual`. Confirm enablement and terminal type with developer support. * **`401 Unauthorized`.** The API key is missing or invalid, or the header name is wrong. The header must be exactly `X-Api-Key`. * **`403 Forbidden`.** The API key is valid but not permitted for the `merchantId` or `terminalId` in your request. Confirm the IDs match the credential set you were issued and that you are using the correct environment. * **Validation error on payment creation.** On a terminal with `type` = `virtual`, confirm you included `refundEmail` and a complete `customer` object. * **Cannot log in to the PayPal Sandbox account.** Confirm you are using the current Sandbox test account values above. If they have changed, contact developer support. * **Redirect does not happen.** Confirm you set a valid `redirectUrl`. If not provided, Bead will display a hosted confirmation screen instead of redirecting. ### Next Steps * Test different amounts and run cancellation or expiry scenarios. * On a terminal with `type` = `virtual`, you can also validate [Test with Venmo](/testing/test-with-venmo.md). * Validate your production readiness using webhooks plus status checks and avoid tight polling loops. ### Related * [Choosing a Test Method](/testing.md) * [Alternative Payments](/reference-guide/enumerations-and-schemas/tender-types/alternative-payments.md) * [How are PayPal clawbacks reflected in settlement?](/faqs-and-troubleshooting/settlement-faqs/how-are-paypal-clawbacks-reflected-in-settlement.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/testing/test-with-paypal.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.