Skip to content
jovvie.com

Change or cancel an unpaid Jovvie payment with the TypeScript SDK

This page is for Stripe payments made with the Jovvie TypeScript SDK only. The PHP SDK has no equivalent: PHP integrations create a new payment only after the payment safety check, and the PHP SDK has no method to close the old payment, so never reuse or share an old checkout link.

With the TypeScript SDK, you can change a payment that has not been paid yet (client.payments.update()), or close it so its checkout link can no longer take money (client.payments.abandon()). Both run on your server, like every other SDK call.

  • The amount changed before staff took the payment. For example, the customer added an item. Change the pending payment instead of creating a second one.
  • Staff gave up, or the order was cancelled. Close the unpaid payment so nobody can pay it later by mistake.
  • You need a replacement payment for the same order. Close the old unpaid payment first, then create the new one. See Replace a payment for the same order.

Neither method refunds money. To give money back for a payment that went through, see Refunds.

Call client.payments.update() with the payment ID and the fields you want to change. Only the fields you pass change. It works only for a one-time payment whose status is pending.

You can change these fields. They mean the same as when you create the payment:

Field What it is
amount The amount to charge, as a whole number in the smallest currency unit.
currency A three-letter ISO currency code, such as usd. The SDK sends it in lowercase.
description A description of the payment. It cannot be empty.
returnUrl, cancelUrl Where the browser goes afterward. Each must be a full URL.
lineItems, lineTotal What the payment page shows.
metadata Your own key and value pairs.

You cannot change the customer or the payment page preferences after you create the payment.

import { ConflictError } from '@bizswoop/jovvie-payments/errors.js';
try {
const updated = await client.payments.update(paymentId, {
amount: 3000, // 30.00 in USD
lineItems: [
{ name: 'Coffee beans', quantity: '2', amount: '20.00' },
{ name: 'Mug', quantity: '2', amount: '10.00' },
],
lineTotal: '30.00',
metadata: { order_version: '2' },
});
yourApp.saveOrderAmount(orderId, updated.amount);
} catch (error) {
if (error instanceof ConflictError) {
// The payment is no longer pending, or Stripe will not change it right now.
// Fetch it to see what happened. Do not create a new payment yet.
const current = await client.payments.retrieve(paymentId);
yourApp.flagOrderForReview(orderId, current.status);
} else {
throw error;
}
}

client is your JovviePaymentsClient. paymentId is the Jovvie payment ID you saved for the order, and yourApp.saveOrderAmount() and yourApp.flagOrderForReview() stand for your own code.

Things to know:

  • If you change the amount, also pass new lineItems and lineTotal. Otherwise the payment page keeps showing the old ones. The amount you charge is always amount.
  • Metadata you pass is merged with the metadata the payment already has. A key you pass replaces the value of the same key. Keys you do not pass stay as they were. Do not use the keys lineItems, lineTotal, or preferences, and never put card data, passwords, or keys in metadata.
  • A payment that is not pending cannot be changed, and you get a ConflictError. This includes failed and cancelled payments.
  • If Stripe will not change the payment in its current state, for example while a card reader is processing it, you also get a ConflictError.
  • Recurring payments cannot be changed. You get a BadRequestError.

Call client.payments.abandon() with the payment ID. It closes a payment whose status is pending or failed, so it can no longer be paid:

  • For a one-time payment, Jovvie cancels the Stripe payment.
  • For a recurring payment, Jovvie cancels the Stripe subscription. This works only while Stripe can still cancel the subscription.

The payment’s status becomes abandoned, and Jovvie sends a jovvie.payment.abandoned webhook for a one-time payment, or jovvie.subscription.abandoned for a recurring payment. See Handle webhooks.

const closed = await client.payments.abandon(paymentId);
// closed.status is now 'abandoned'.

Things to know:

  • abandon() never refunds anything.
  • A completed payment cannot be abandoned, and neither can a payment with any status other than pending or failed. You get a ConflictError.
  • A cancelled payment cannot be abandoned. A charge can still go through on a reader after staff click the cancel link on the payment page (Cancel and return by default, ← Back in some layouts), so check a cancelled payment in your Stripe Dashboard as part of the payment safety check.
  • If Stripe will not cancel the payment or subscription in its current state, for example while a reader is processing the payment, you get a ConflictError.
  • A failed recurring payment can be one that was running until its renewals failed. Abandoning it ends that subscription. An active recurring payment cannot be abandoned: the merchant cancels it in the Stripe Dashboard. See Recurring payments.

Sometimes staff need a fresh payment for an order, for example after a payment failed and they want to start again. Closing the old unpaid payments first means their checkout links can no longer take money.

Before you run this code, do the payment safety check. Check the card reader and your Stripe Dashboard, and confirm that no payment for the order went through and none is still processing. The code then checks every payment you saved for the order again.

import { ConflictError } from '@bizswoop/jovvie-payments/errors.js';
// Call this only after staff confirmed, on the card reader and in the Stripe
// Dashboard, that no payment for this order went through or is still processing.
async function replacePayment(orderId: string, amount: number): Promise<string | null> {
// Only one replacement can run for an order at a time, even if staff
// double-click or two people try at once.
return yourApp.withOrderLock(orderId, async (): Promise<string | null> => {
const savedIds: string[] = await yourApp.paymentIdsForOrder(orderId);
// 1. Check each saved payment, and close it if it can still be paid.
for (const id of savedIds) {
const saved = await client.payments.retrieve(id);
if (saved.status === 'abandoned') {
continue; // Already closed.
}
if (saved.status === 'cancelled' && (await yourApp.staffClearedCancelled(orderId, id))) {
continue; // Staff checked it in the Stripe Dashboard during the safety check.
}
if (saved.status !== 'pending' && saved.status !== 'failed') {
// Paid, refunded, or not cleared. Do not charge again.
await yourApp.flagOrderForReview(orderId, saved.status);
return null;
}
try {
await client.payments.abandon(id);
} catch (error) {
if (error instanceof ConflictError) {
// The payment could not be closed. It may be processing or already paid.
const current = await client.payments.retrieve(id);
await yourApp.flagOrderForReview(orderId, current.status);
return null;
}
throw error;
}
}
// 2. Claim the right to create one payment, and save the claim for good
// before you send anything. An open claim from an earlier attempt means
// its result is still unclear, so stop and let staff check the order.
const claimed: boolean = await yourApp.claimPaymentAttempt(orderId);
if (!claimed) {
await yourApp.flagOrderForReview(orderId, 'unclear earlier attempt');
return null;
}
// 3. Only now create the new payment, and save its ID with the order.
const payment = await client.payments.createOneTimePayment({
amount,
currency: 'usd',
description: `Order ${orderId}`,
returnUrl: 'YOUR_RETURN_URL',
cancelUrl: 'YOUR_CANCEL_URL',
metadata: { order_id: orderId },
});
// Save the new ID and close the claim together.
await yourApp.savePaymentForOrder(orderId, payment.id);
return payment.generatedData.checkoutLink;
});
}

The methods on yourApp stand for your own code:

  • withOrderLock() runs the function while it holds a lock for that order, so two replacements for the same order cannot run at once.
  • staffClearedCancelled() returns true only if staff confirmed in the Stripe Dashboard that this cancelled payment took no money.
  • claimPaymentAttempt() saves a claim that a new payment is being created, and returns false if an earlier claim for the order is still open. Commit the claim on its own, before you call the SDK, so it survives an error, a rolled-back transaction, or a restart. If creating the payment fails or times out, or saving its ID fails, leave the claim open: staff check the order and the Stripe Dashboard, then close the claim by hand.
  • savePaymentForOrder() saves the new payment’s ID and closes the claim in one step.
  • paymentIdsForOrder() and flagOrderForReview() read your saved payment IDs and flag the order for a person to check.

Things to know:

  • Never retry creating a payment automatically. Creating a payment does not use an idempotency key, so a retry after a timeout or network error can create a second payment. Run the safety check again instead.
  • If any call throws an error other than ConflictError, for example a RequestError after a timeout, stop. The payment may or may not have changed. Fetch it before you do anything else.
  • The code checks each payment’s status right before it acts on it, because a payment can be paid at any moment until it is closed.
  • If you are unsure, contact Jovvie support.

Import the error classes from @bizswoop/jovvie-payments/errors.js.

Error When you get it
InvalidArgumentError The payment ID is empty or not valid. The SDK throws it before it sends anything.
BadRequestError update() was called for a recurring payment, or a value you passed is not valid.
ForbiddenError The payment belongs to another merchant account.
NotFoundError No payment has that ID.
ConflictError update(): the payment is not pending, or Stripe will not change it right now. abandon(): the payment is not pending or failed, or Stripe will not cancel it right now. Fetch the payment before you do anything else.
RequestError No response arrived, for example after a network failure or timeout. The change may or may not have happened. Fetch the payment to find out.

See Handle errors for every error and error code.