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.
Before you start
Section titled “Before you start”- You can create payments with the TypeScript SDK. See Create a payment (Stripe).
- You save the Jovvie payment ID of every payment you create for an order. See Check a payment’s status.
When to use it
Section titled “When to use it”- 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.
Change a pending payment
Section titled “Change a pending payment”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
lineItemsandlineTotal. Otherwise the payment page keeps showing the old ones. The amount you charge is alwaysamount. - 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, orpreferences, and never put card data, passwords, or keys in metadata. - A payment that is not
pendingcannot be changed, and you get aConflictError. This includesfailedandcancelledpayments. - 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.
Close an unpaid payment
Section titled “Close an unpaid payment”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
completedpayment cannot be abandoned, and neither can a payment with any status other thanpendingorfailed. You get aConflictError. - A
cancelledpayment 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 acancelledpayment 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
failedrecurring payment can be one that was running until its renewals failed. Abandoning it ends that subscription. Anactiverecurring payment cannot be abandoned: the merchant cancels it in the Stripe Dashboard. See Recurring payments.
Replace a payment for the same order
Section titled “Replace a payment for the same order”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()returnstrueonly if staff confirmed in the Stripe Dashboard that thiscancelledpayment took no money.claimPaymentAttempt()saves a claim that a new payment is being created, and returnsfalseif 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()andflagOrderForReview()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 aRequestErrorafter 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.
Errors
Section titled “Errors”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.