Cash a Check for an Exact Amount

This tutorial shows how to cash a Check for an exact amount. As long as the Check is not expired, the specified recipient can cash it to receive any exact amount up to the amount specified. You would cash a Check this way if you want to receive a specific amount, for example to pay off an invoice or bill exactly. If the sender does not have enough money, cashing the check fails but you can try again later.

You can also cash a check for a flexible amount.

Prerequisites

• You should be familiar with the basics of using the xrpl.js client library.
• You need an XRP Ledger account including its secret key. (You can get one on Testnet for free.) See also: XRP Faucets.
• You need the ID of a Check ledger entry that you are the recipient of. See also: Send a Check and Look Up Checks.

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 CheckCash transaction

Figure out the values of the CheckCash transaction fields. You also need to create a Wallet instance for your account's key pair. To cash a check for an exact amount, the following fields are the bare minimum; everything else is either optional or can be auto-filled when signing:

In the sample code, these values are hard-coded, so you should edit them to match your case:

// Define parameters. Edit this code with your values before running it.
const secret = "s████████████████████████████" // Replace with your secret
const check_id =  "49D339B76FAB3FE3C9DFAD32EB7DB9269FD07B07E165DD7BAFDF68D14CE6CAB8"
const amount = "30000000" // Replace with the amount you want to cash
               // String for XRP in drops
               // {currency, issuer, value} object for token amount

Then, you use these parameters to fill out the transaction. For example:

    // Prepare the transaction ------------------------------------------------
    const checkcash = {
        TransactionType: "CheckCash",
        Account: wallet.address,
        CheckID: check_id,
        Amount: amount
    }

    

2. Submit the transaction

Send the transaction and wait for it to be validated by the consensus process, as normal:

    // Submit the transaction -------------------------------------------------
    const tx = await client.submitAndWait(
      checkcash, 
      { autofill: true, 
          wallet: wallet }
    )

    

3. Confirm transaction result

If the transaction succeeded, it should have a "TransactionResult": "tesSUCCESS" field in the metadata, and the field "validated": true in the result, indicating that this result is final.

You can look at the transaction metadata to confirm the balance changes that occurred as a result of delivering the exact amount. The xrpl.getBalanceChanges() function can help to summarize this. For example:

    // Confirm transaction results --------------------------------------------
    console.log(`Transaction result: ${JSON.stringify(tx, null, 2)}`)

    if (tx.result.meta.TransactionResult === "tesSUCCESS") {
      // submitAndWait() only returns when the transaction's outcome is final,
      // so you don't also have to check for validated: true.
      console.log("Transaction was successful.")

      console.log("Balance changes:", 
        JSON.stringify(xrpl.getBalanceChanges(tx.result.meta), null, 2)
      )
    }

    

Example balance changes output:

Balance changes: [
  {
    "account": "rEHjrKs86KfPjgeZvso2uQqhU2iA7AqD6r",
    "balances": [
      {
        "currency": "XRP",
        "value": "29.999988"
      }
    ]
  },
  {
    "account": "rh8pPR6p87egsGuAg53QrJ7Y4PLf4Qdrf7",
    "balances": [
      {
        "currency": "XRP",
        "value": "-30"
      }
    ]
  }
]