Get started with a custom Jovvie Checkout integration

Before you build a custom Jovvie Checkout integration, you need a merchant account with Stripe or NMI connected and a set of API keys. For Stripe only, you also need a platform provider ID from Jovvie.

Before you start

• Read Build your own Jovvie Checkout integration to see how a payment works.
• Know whether the merchant uses Stripe or NMI. The steps on this page are the same for both unless a step says otherwise.

Step 1: Get a platform provider ID

The Stripe SDK needs a platform provider ID. It tells Jovvie which integration is making each request. You must get your own platform provider ID from Jovvie and pass it explicitly every time you create the SDK client.

To get one, contact Jovvie support. Tell them about your app and the merchants who will use it.

Your integration can work in test mode and still fail in live mode

Use only the platform provider ID that Jovvie support gives you. Do not make one up, leave a placeholder, or copy a value from another project or example. Some values are accepted in test mode only, so an integration can pass every test and then stop working when you switch it to live mode. Get your platform provider ID before you start testing, and test with the same ID you will use in live mode.

The NMI SDK does not use a platform provider ID. If you are only building for NMI, skip this step.

Step 2: Check the merchant’s account

The merchant needs a Jovvie account with their payment processor connected:

• Stripe: the merchant’s Stripe account is connected in the Payments Dashboard. The Applications page only appears after it is connected.
• NMI: the merchant has an NMI account set up in the Jovvie payments gateway dashboard.

If you are an agency, the merchant (or an administrator they choose) creates the server application in step 3 and enters its keys directly into your integration’s server-side settings or environment. Keys are never sent by email or chat.

Step 3: Create a server application

An application gives your integration its own set of keys. Create a new application for each integration. Do not reuse an application that a Jovvie plugin already uses.

1. Sign in to the Payments Dashboard. For NMI, sign in to the Jovvie payments gateway dashboard instead.
2. Click Applications.
3. Click Create New.
4. In Name, enter a name you will recognize, such as the name of your app.
5. In Webhook URL, enter the address on your server that will receive webhooks. It must start with https://. If your endpoint is not ready yet, you can add it later.
6. Click Create.

The application’s page opens. Under Keys Management, you see:

• Public Key: identifies your application.
• Secret Key: proves requests come from your server. Keep it private.
• Webhook Key: lets you check that a webhook really came from Jovvie. Keep it private.

Webhook Key only appears after the application has a Webhook URL. This is the same with Stripe and NMI. To add a Webhook URL later:

1. Open the application’s page in the dashboard.
2. In Webhook URL, enter the address of your webhook endpoint.
3. Click Save Changes.

The Webhook Key then appears under Keys Management.

Note

With Stripe, use each application’s keys with one platform provider ID only. Create a separate application for each integration.

Step 4: Store your keys

Your code needs the public key, secret key, and webhook key. With Stripe, it also needs a platform provider ID. The examples use these placeholders:

Value	Placeholder
Public Key	YOUR_PUBLIC_KEY
Secret Key	YOUR_SECRET_KEY
Webhook Key	YOUR_WEBHOOK_KEY
Platform provider ID (Stripe only)	YOUR_PLATFORM_PROVIDER

Keep them on your server:

• Store them in environment variables or your platform’s secrets manager.
• Never put the secret key or webhook key in browser code, a mobile app, a URL, or version control.
• Never write them to logs or error messages.

If a key is exposed

If you think someone else has seen the secret key or webhook key:

1. Open the application’s page in the dashboard.
2. Click Regenerate Keys.
3. Copy the new keys to your server right away.

The old keys stop working as soon as you regenerate them, so update your server at the same time.

To stop an integration from making requests, open the application’s page, click Enabled, and confirm. The label changes to Disabled, and requests with that application’s keys are rejected until you click it again.

Step 5: Plan for testing

With Stripe, the same keys and platform provider ID work in live mode and in test mode. You choose the mode when you create the SDK client, so you can test without charging a real card. The NMI SDK has no test mode. See Test your integration.

Next step

Install the SDK and create your first client.