Test a Jovvie Checkout integration with Stripe test mode

This page shows you how to test your integration without charging a real card, and what to check before the merchant takes real payments.

Test mode is available with the Stripe SDK. The NMI SDK has no test mode. See Testing with NMI.

Turn on test mode

With the Stripe SDK, you choose the mode when you create the client. Pass 'test' as the fourth argument:

use JovviePayments\JovviePaymentsClient;

$jovvie = new JovviePaymentsClient(
    'YOUR_PUBLIC_KEY',
    'YOUR_SECRET_KEY',
    'YOUR_PLATFORM_PROVIDER',
    'test',
    ['userAgent' => 'YourApp/1.0.0']
);

You use the same keys and platform provider ID as in live mode. You do not need a separate application.

Test with the platform provider ID that Jovvie support gave you, not a made-up or placeholder value. Some values are accepted in test mode only, so tests can pass and the integration can still fail in live mode. If you do not have a platform provider ID yet, see Get started.

Make the mode a setting in your integration, such as an environment variable or an admin option, so the merchant can switch to live mode without a code change. For more about creating the client, see Install the SDK.

What changes in test mode

• No real card is charged, and no money is collected.
• Every payment you create has its mode set to test.
• Jovvie adds (Test) to the end of the payment’s description.
• When you pass metadata, Jovvie adds a mode key with the value TEST MODE to it. Avoid using mode as one of your own metadata keys.
• Test payments, card readers, locations, and authorization links are kept apart from live ones. A test payment cannot be fetched with a live client, and a live payment cannot be fetched with a test client.
• Test payments appear in the merchant’s Stripe Dashboard when it is switched to test mode.

Take a test payment

1. Create a payment with your test client. See Create a payment (Stripe).
2. Send your browser to the payment’s checkout link.
3. Check that the payment page shows the orange Test Mode bar at the top.
4. Select In-Person Payment.
5. If the page shows Provide PIN to access, enter the merchant’s Access PIN in PIN and click Submit.
6. Under Choose a reader, select a simulated reader.
7. Click Process Payment.

To skip the PIN step, open the payment through an authorization link instead of the plain checkout link. Create the link with your test client, always pass a redirectUrl, and only give the link to the merchant’s staff. See Unlock card readers for staff.

When the payment finishes, the page sends the browser back to your return URL. Check that your integration confirms the payment on the server before it marks the order as paid.

A simulated reader is not a real device. You do not need any hardware to test this way.

Test with a real card reader

Simulated readers are the simplest way to test. Readers registered in live mode do not appear in test mode, so a physical reader only appears in test mode if it was registered in test mode. If you need to test with a physical reader, contact Jovvie support.

On the payment page, Switch to live readers lists the readers available in test mode. Despite its name, this button does not take you out of test mode. The payment is still a test payment. For more about what staff see in test mode, see Use test mode.

If you give staff an authorization link to unlock the readers, create it with your test client. A link created in one mode only works in that mode. See Unlock card readers for staff.

Test your webhooks

Jovvie sends webhooks for test payments to the same Webhook URL as live payments. To keep test events away from your live orders:

• In your webhook handler, check the event’s mode with getPaymentMode(). It returns live or test.
• Ignore events whose mode does not match the mode your integration is running in, and still respond with HTTP 200.

Things to test:

• Staff leaving the payment page without paying. Your app should not mark the order as paid.
• A payment that is declined or fails on the reader.
• The same event arriving twice. Your handler should only update the order once.
• A request with a wrong signature. Your handler should reject it.

For how to verify and handle events, see Handle webhooks.

Testing with NMI

The NMI SDK has no test mode, and every payment you create with it is real. Before you test an NMI integration, contact Jovvie support to plan how to test it.

If an NMI test does take a real payment, the merchant can refund it in the NMI portal. See Refunds.

Before you go live

1. Switch your client’s mode to 'live'.
2. Check that your client passes the platform provider ID from Jovvie support. Then check your connection with the live client. If creating the live client throws an InvalidArgumentException, see Handle errors.
3. Check that the merchant’s card readers are registered in live mode.
4. Create new authorization links with your live client for staff who need them. Links from test mode do not work in live mode.
5. Check that your Webhook URL is set on the application, starts with https://, and is reachable from the internet.
6. Check that your webhook handler verifies every request with the webhook key and rejects any that fail.
7. Check that your integration never marks an order as paid from the return URL alone. It should fetch the payment or use a verified webhook.
8. Check that the secret key and webhook key are stored on your server only, and that they do not appear in your logs.
9. Take the first live payment with staff watching. If the payment page still shows the Test Mode bar, the payment is not real.

Need help?

If readers do not appear on the payment page, see Reader not showing on the payment page.

Contact Jovvie support.