Take NMI payments with the Jovvie PHP SDK

This page shows you how to take in-person payments for a merchant who uses NMI. You use the NMI SDK to manage the merchant’s terminals (called devices in the SDK), create a payment, and either send it straight to a terminal or send your staff to the Jovvie payment page.

The NMI SDK works a little differently from the Stripe SDK:

The client takes only the public key and the secret key.
There are no authorization links. You choose per payment whether the payment page asks for the Access PIN.
You can send a payment straight to a terminal when you create it.
There are no recurring payments.

For the Stripe SDK, see Create a payment (Stripe). For a side-by-side view, see Stripe and NMI: what’s different.

Before you start

You installed the NMI SDK. See Install the SDK.
The merchant’s NMI account is connected, and you have the server application keys. See Get started.

<?php
use JovviePaymentsGateway\JovviePaymentsGatewayClient;

$client = new JovviePaymentsGatewayClient('YOUR_PUBLIC_KEY', 'YOUR_SECRET_KEY');

Manage terminals

Each terminal you register gets a Jovvie device ID (publicId). You use this ID to send a payment to that terminal.

Method	What it does
`devices()->list()`	Returns all of the merchant’s registered devices.
`devices()->get($deviceId)`	Returns one device.
`devices()->create($registrationCode, $name)`	Registers a terminal with its registration code and returns the new device.
`devices()->delete($deviceId)`	Removes the device from the merchant’s account.

Each device has these fields:

Field	What it is
`publicId`	The Jovvie device ID.
`name`	The device name. Staff see it on the payment page.
`serialNumber`	The terminal’s serial number, if known.
`createdAt`	When the device was registered.

Register a terminal

Get the terminal’s registration code.
Choose a name for it, from 1 to 20 characters. Use only letters, numbers, spaces, dashes (-), and underscores (_).
Call devices()->create() with the code and the name.
Save the returned publicId if you want to send payments to this terminal.

<?php
$device = $client->devices()->create('YOUR_REGISTRATION_CODE', 'Front Counter');

echo $device->publicId;

If the registration code is not accepted, the SDK throws a ResponseError. See Handle errors.

Create a payment

Call payments()->create($amount, $currency, $description, $options).

Argument	What it is
`$amount`	The amount to charge, as an integer in the smallest currency unit. For example, `2500` for 25.00 USD.
`$currency`	A three-letter ISO currency code, such as `usd`. Use a currency with two decimal places.
`$description`	A description of the payment. It cannot be empty. The payment page shows it as the only line of the payment.
`$options`	Optional. See the table of options in this section.

Option	What it does
`returnUrl`	Where the browser goes after the payment page is done. Must be a full URL.
`cancelUrl`	Where the browser goes when staff click ← Back and the payment is `cancelled`. A `pending` payment is first marked `cancelled`. Other statuses use `returnUrl`. Must be a full URL.
`deviceId`	A Jovvie device ID. Jovvie sends the payment to that terminal right away.
`paymentMethodType`	`request-terminal` (the default) makes the payment page ask for the Access PIN. `terminal` shows the terminals without the PIN.

If you leave out returnUrl or cancelUrl, Jovvie uses its own payment status page in place of the missing URL. A URL you do pass still works as usual. Pass both so staff return to your app for either outcome.

<?php
$payment = $client->payments()->create(
    2500,
    'usd',
    'Order YOUR_ORDER_ID',
    [
        'returnUrl' => 'YOUR_RETURN_URL',
        'cancelUrl' => 'YOUR_CANCEL_URL',
        'deviceId' => 'YOUR_DEVICE_ID',
    ]
);

// Save these with your order.
$paymentId = $payment->id;
$checkoutLink = $payment->generatedData->checkoutLink;

The method returns a OneTimePayment object with these fields:

Field	What it is
`id`	The Jovvie payment ID. Save it with your order.
`status`	The payment status. A new payment is `pending`.
`amount`, `currency`	The amount (smallest currency unit) and currency.
`generatedData->checkoutLink`	The link to the Jovvie payment page for this payment.

To get the NMI transaction ID, use getTransactionId() on a verified NMI webhook event, such as jovvie-gateway.payment.completed. See Handle webhooks.

If the device ID does not belong to the merchant, the SDK throws a BadRequestError.

Take the payment

How staff take the payment depends on whether you passed a deviceId.

With a device ID: Jovvie sends the payment to that terminal as soon as you create it. The customer can pay on the terminal right away. If you also open the checkout link, the payment page asks for the Access PIN (unless paymentMethodType is terminal), then shows Pay with Device while it waits for the customer to finish on the terminal.

Without a device ID:

Send a staff member’s browser to the checkout link.
If the page shows Enter PIN, the staff member enters the Access PIN and clicks Continue.
Under Choose a reader, the staff member selects a terminal.
The staff member clicks Process Payment.
The customer pays on the terminal.

For how staff take an NMI payment in Point of Sale, see Take a card payment with an NMI terminal.

Confirm the payment

A visit to your return URL does not prove that the customer paid.

Look up the Jovvie payment ID you saved for this order.
Fetch the payment with $client->payments()->get($paymentId).
Mark the order paid only if status is completed.

Also handle NMI webhooks, which tell you when a payment completes, fails, is cancelled, or is refunded. See Handle webhooks and Check a payment’s status.

If a payment’s outcome is unclear, do not create a second payment for the same order until you have confirmed that the first one did not go through and is not still processing.

Refunds

The NMI SDK cannot refund a payment yet. SDK support for refunds is planned. Refunds are made in the NMI portal. See Refunds.