Create a Stripe payment with the Jovvie PHP SDK

This page shows you how to create a one-time payment with the Stripe SDK. Your server creates the payment, and Jovvie gives you a checkout link to the Jovvie payment page. Your staff open that link, choose a card reader, and the customer pays.

For NMI, see Take payments with NMI. For recurring payments, see Recurring payments.

Before you start

• You installed the Stripe SDK and can create a client. See Install the SDK.
• The merchant’s Stripe account is connected, and you have the server application keys. See Get started.
• You use test mode while you build. See Test your integration.

Create the payment

Call payments()->createOneTimePayment() on your server. It takes these arguments, in this order:

Argument	Type	What it is
$amount	integer	The amount to charge, in the smallest currency unit. See Amounts.
$currency	string	A three-letter ISO currency code, such as usd. The SDK sends it in lowercase.
$description	string	A description of the payment. It cannot be empty. The payment page shows it.
$returnUrl	string	Where the browser goes after the payment page is done. Must be a full URL.
$cancelUrl	string	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.
$options	array	Optional. See Options.

<?php
use JovviePayments\JovviePaymentsClient;

$client = new JovviePaymentsClient(
    'YOUR_PUBLIC_KEY',
    'YOUR_SECRET_KEY',
    'YOUR_PLATFORM_PROVIDER',
    'test'
);

$payment = $client->payments()->createOneTimePayment(
    2500,                                         // 25.00 in USD
    'usd',
    'Order YOUR_ORDER_ID',
    'YOUR_RETURN_URL',
    'YOUR_CANCEL_URL',
    [
        'lineItems' => [
            ['name' => 'Coffee beans', 'quantity' => '2', 'amount' => '20.00'],
            ['name' => 'Mug', 'quantity' => '1', 'amount' => '5.00'],
        ],
        'lineTotal' => '25.00',
        'metadata' => [
            'order_id' => 'YOUR_ORDER_ID',
        ],
    ]
);

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

The method returns a OneTimePayment object. The fields you will use most:

Field	What it is
id	The Jovvie payment ID. Save it with your order. You need it to check the payment and to match webhooks.
status	The payment status. A new payment is pending. See Check a payment’s status.
mode	live or test.
amount, currency	The amount (smallest currency unit) and currency.
generatedData->checkoutLink	The link to the Jovvie payment page for this payment.
generatedData->paymentIntentId	The ID of the Stripe payment behind this Jovvie payment. It helps you find the payment in your Stripe Dashboard.

Amounts

Pass $amount as an integer in the smallest unit of the currency. For example, pass 2500 for 25.00 USD.

Stripe treats some currencies, such as JPY and KRW, as zero-decimal currencies. They have no smaller unit, so you pass the whole amount. For example, pass 1000 for 1,000 JPY, not 100000. Check Stripe’s list of zero-decimal currencies and keep your own list in your code.

Caution

Always pass lineItems and lineTotal when you use a zero-decimal currency, so the payment page shows the right amounts.

The amount you charge is always $amount. Line items and the line total only control what the payment page shows.

If the merchant’s Stripe account cannot take the currency for this payment, the SDK throws a BadRequestError. See Handle errors.

Options

All options are optional. Pass them in the $options array.

Option	What it does
lineItems	An array of items to show on the payment page. Each item has name, amount, and quantity, all as strings. amount is the amount to show for that line, in normal currency units, such as '20.00'. If you leave it out, the page shows one line with your description.
lineTotal	The total to show on the payment page, as a plain number in normal currency units, such as '25.00'. Do not add a currency code to it.
metadata	Your own key and value pairs, such as your order ID. Values can be strings, numbers, or null.
preferences	Settings for the payment page. locationId limits the reader list to one Stripe Terminal location. terminalType can be web, app, or all (the default) to choose which terminals the page offers. See Web terminals and app terminals.

About metadata:

• Jovvie stores metadata on the Stripe payment, so you can see it in your Stripe Dashboard.
• Do not use the keys lineItems, lineTotal, or preferences. Jovvie uses them for its own data.
• Never put card data, passwords, or keys in metadata.

Note

Jovvie stores your line items with the Stripe payment, and Stripe limits how long that stored value can be. Keep line item names short. If an order has many items, show a summary line instead of every item.

Send staff to the payment page

The checkout link opens the Jovvie payment page for this payment.

1. Store the payment ID with your order.
2. Send your staff member’s browser to the payment page.
   • If the staff member is signed in to your app, create an authorization link that redirects to the checkout link, and send the browser to the authorization link. The payment page then shows the card readers without asking for the Access PIN. See Unlock card readers for staff.
   • Otherwise, send the browser to the checkout link. To use a reader, staff select In-Person Payment and enter the Access PIN when the page shows Provide PIN to access.
3. Staff take the payment on the payment page. See Take a payment on the Jovvie payment page.

When payment processing finishes, Jovvie sends the browser to your $returnUrl. Clicking ← Back changes a pending payment to cancelled. Jovvie then uses $cancelUrl for a cancelled payment and $returnUrl for any other status, for example a failed payment after a declined card.

Caution

Treat the checkout link like a key to this payment. Show it only to the merchant’s staff. Do not put it in emails, logs, or pages that customers can see.

If a payment’s outcome is unclear, do not create another payment for the same order yet. Check every saved payment for the order with payments()->get() and check your Stripe Dashboard. Confirm that no payment went through and none is still processing before retrying or using another payment method. If you are unsure, contact Jovvie support.

Confirm the payment

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

When the browser arrives at your return URL:

1. Look up the Jovvie payment ID you saved for this order. Do not take the payment ID from the URL.
2. Fetch the payment with $client->payments()->get($paymentId).
3. Mark the order paid only if status is completed.

See Check a payment’s status for the full list of statuses and how to find payments that never came back. Also handle webhooks for changes that happen later, such as refunds. See Handle webhooks.

Related pages

• Unlock card readers for staff
• Check a payment’s status
• Handle webhooks
• Handle errors