Cancel a Check

This tutorial shows how to cancel a Check, which removes the Check entry from the ledger without sending money.

You may want to cancel an incoming Check if you do not want it. You might cancel an outgoing Check if you made a mistake when sending it or if circumstances have changed. If a Check expires, it's also necessary to cancel it to remove it from the ledger so the sender gets their owner reserve back.

Prerequisites

You should be familiar with the basics of using the xrpl.js client library.
You need the ID of a Check ledger entry that you are either the sender or recipient of. See also: Send a Check.

Source Code

The complete source code for this tutorial is available in the source repository for this website:

Checks sample code

Steps

1. Prepare the CheckCancel transaction

Figure out the values of the CheckCancel transaction fields. The following fields are the bare minimum; everything else is either optional or can be auto-filled when signing:

Field	Value	Description
`TransactionType`	String	Use the string `CheckCancel` when canceling a Check.
`Account`	String (Address)	The address of the sender who is canceling the Check. (In other words, your address.)
`CheckID`	String	The ID of the Check entry to cancel. You can get this information when you send a check, or by looking up checks.

This example uses a preconfigured account and check from the checks-setup.js script, but you can replace wallet and checkID with your own values.

// Load setup data --------------------------------------------------------

const setupData = JSON.parse(fs.readFileSync('checks-setup.json', 'utf8'))
const wallet = xrpl.Wallet.fromSeed(setupData.sender.seed)
const checkID = setupData.checkIDs.cancel

console.log(`Wallet address: ${wallet.address}`)
console.log(`Check ID to cancel: ${checkID}`)

Then, use the loaded values to fill out the transaction:

// Prepare the transaction ------------------------------------------------

console.log(`\n=== Preparing CheckCancel transaction ===\n`)
const checkCancel = {
  TransactionType: 'CheckCancel',
  Account: wallet.address,
  CheckID: checkID
}

// Validate the transaction before submitting -----------------------------

xrpl.validate(checkCancel)
console.log(JSON.stringify(checkCancel, null, 2))

2. Submit the CheckCancel transaction

Submit the CheckCancel transaction in the usual way and wait for it to be validated. If the result code is tesSUCCESS and the transaction is in a validated ledger, the transaction is successful. For example:

// Submit the transaction -------------------------------------------------

console.log(`\n=== Submitting CheckCancel transaction ===\n`)
const tx = await client.submitAndWait(
  checkCancel,
  { autofill: true,
    wallet }
)

3. Confirm transaction result

If the transaction succeeds, the code prints the cancelled check's details. For example:

// Confirm transaction result ---------------------------------------------

const resultCode = tx.result.meta.TransactionResult
if (resultCode !== 'tesSUCCESS') {
  console.error('Unable to cancel check:', resultCode)
  await client.disconnect()
  process.exit(1)
}

const deletedCheck = tx.result.meta.AffectedNodes.find(node =>
  node.DeletedNode?.LedgerEntryType === 'Check')
console.log(`Check canceled successfully.`)
console.log(`Deleted check:\n`, JSON.stringify(deletedCheck.DeletedNode.FinalFields, null, 2))

Tip

The submitAndWait() method in xrpl.js only returns when the transaction's result is final, so you can assume that the transaction is validated if it returns a result code of tesSUCCESS.