Send and Cash Checks

This example shows how to:

Send a check to transfer XRP or issued currency to another account.
Get a list of checks you have sent or received.
Cash a check received from another account.
Cancel a check you have sent.

Checks offer another option for transferring funds between accounts. Checks have two particular advantages.

You can use a check to send tokens to someone who has not already created a trust line. The trust line is created automatically when the receiver chooses to accept the funds.
The receiver can choose to accept less than the full amount of the check. This allows you to authorize a maximum amount when the actual cost is not finalized.

Prerequisites

Download and expand the Modular Tutorials archive.

Note

Without the Modular Tutorial Samples, you will not be able to try the examples that follow.

Usage

To get test accounts:

Open send-checks.html in a browser.
Get test accounts.
1. If you copied the gathered information from another tutorial:
  1. Paste the gathered information to the Result field.
  2. Click Distribute Account Info.
2. If you have an existing account seed:
  1. Paste the account seed to the Account 1 Seed or Account 2 Seed field.
  2. Click Get Account 1 from Seed or Get Account 2 from Seed.
3. If you do not have existing accounts:
  1. Click Get New Account 1.
  2. Click Get New Account 2.

Send a Check for XRP

To send a check for XRP:

Select Account 1 or Account 2.
Enter the Amount of XRP to send, in drops.
Enter the receiving account address in the Destination field.
Set the Currency Code to XRP.
Click Send Check.

Send a Check for an Issued Currency

To send a check for an issued currency token:

Choose Account 1 or Account 2.
Enter the Amount of currency to send.
Enter the receiving account address in the Destination field.
Enter the issuing account in the Issuer field (for example, the account sending the check).
Enter the Currency code for your issued currency token.
Click Send Check.

Get Checks

Click Get Checks to get a list of the current checks you have sent or received. To uniquely identify a check (for example, when cashing a check), use the check's ledger entry ID, in the index field.

Cash Check

To cash a check you have received:

Enter the Check ID (index value).
Enter the Amount you want to collect, up to the full amount of the check.
Enter the currency code. a. If you are cashing a check for XRP, enter XRP in the Currency Code field. b. If you are cashing a check for an issued currency token:
1. Enter the Issuer of the token.
2. Enter the Currency Code code for the token.
Click Cash Check.

Get Token Balance

Click Get Token Balance to get a list of obligations and assets for the account.

Cancel Check

To cancel a check you have previously sent to another account.

Enter the Check ID (index value).
Click Cancel Check.

Code Walkthrough

Download and expand the Modular Tutorials archive.

send-checks.js

sendCheck()

Connect to the XRP ledger.

async function sendCheck() {
  let net = getNet()
  const client = new xrpl.Client(net)
  await client.connect()
  results = `\n===Connected to ${net}.===\n===Sending check.===\n`
  resultField.value = results

Prepare the transaction. Set the check_amount variable to the value in the Amount field.

  try {     
    const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
    let check_amount = amountField.value

If the currency field is not XRP, create an amount object with the currency, value, and issuer. Otherwise, use the check_amount value as is.

   if (currencyField.value !=  "XRP") {
     check_amount = {
       "currency": currencyField.value,
       "value": amountField.value,
       "issuer": wallet.address  	
     }
   }

Create the transaction object.

const send_check_tx = {
  "TransactionType": "CheckCreate",
  "Account": wallet.address,
  "SendMax": check_amount,
  "Destination": destinationField.value
}

Autofill the remaining values and sign the prepared transaction.

    const check_prepared = await client.autofill(send_check_tx)
    const check_signed = wallet.sign(check_prepared)

Send the transaction and wait for the results.

    results += '\n===Sending ' + amountField.value + ' ' + currencyField.
     value + ' to ' +  destinationField.value + '.===\n'
    resultField.value = results
    const check_result = await client.submitAndWait(check_signed.tx_blob)

Report the results.

    if (check_result.result.meta.TransactionResult == "tesSUCCESS") {
      results = '===Transaction succeeded===\n\n'
      resultField.value += results + JSON.stringify(check_result.result, null, 2)
    }

Update the XRP Balance field.

    xrpBalanceField.value = (await client.getXrpBalance(wallet.address))

Report any errors, then disconnect from the XRP ledger.

  } catch (error) {
    results = `Error sending transaction: ${error}`
    resultField.value += results
  }
  finally {
    client.disconnect()
  }
}//end of sendCheck()

getChecks()

Connect to the XRP Ledger.

async function getChecks() {
  let net = getNet()
  const client = new xrpl.Client(net)
  await client.connect()   
  let results = `\n===Connected to ${net}.===\n===Getting account checks.===\n\n`
  resultField.value = results

Define an account_objects query, filtering for the check object type.

  try {
    const check_objects = await client.request({
      "id": 5,
      "command": "account_objects",
      "account": accountAddressField.value,
      "ledger_index": "validated",
      "type": "check"
    })

Display the retrieved Check objects in the result field.

    resultField.value += JSON.stringify(check_objects.result, null, 2)

Catch and report any errors, then disconnect from the XRP Ledger.

  }  catch (error) {
    results = `Error getting checks: ${error}`
    resultField.value += results
  }
  finally {
    client.disconnect()
  }
} // End of getChecks()

cashCheck()

Connect to the XRP Ledger and get the account wallet

async function cashCheck() {
  let net = getNet()
  const client = new xrpl.Client(net)
  await client.connect()
  results = `\n===Connected to ${net}.===\n===Cashing check.===\n`
  resultField.value = results

Set the check amount.

  try {
    const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
    let check_amount = amountField.value

If the currency is not XRP, create an amount object with value, currency, and issuer.

    if (currencyField.value !=  "XRP") {
      check_amount = {
        "value": amountField.value,
        "currency": currencyField.value,
        "issuer": issuerField.value  	
      }
    }

Create the CheckCash transaction object.

    const cash_check_tx = {
      "TransactionType": "CheckCash",
      "Account": wallet.address,
      "Amount": check_amount,
      "CheckID": checkIdField.value
    }

Autofill the transaction details.

    const cash_prepared = await client.autofill(cash_check_tx)

Sign the prepared transaction.

    const cash_signed = wallet.sign(cash_prepared)
    results = ' Receiving ' + amountField.value + ' ' + currencyField.value + '.\n'
    resultField.value += results

Submit the transaction and wait for the result.

  const check_result = await client.submitAndWait(cash_signed.tx_blob)

Report the transaction results.

    if (check_result.result.meta.TransactionResult == "tesSUCCESS") {
      results = '===Transaction succeeded===\n' + JSON.stringify(check_result.result, null, 2)
      resultField.value += results
    }

Update the XRP Balance field.

  xrpBalanceField.value = (await client.getXrpBalance(wallet.address));

Catch and report any errors, then disconnect from the XRP ledger.

  } catch (error) {
    results = `Error sending transaction: ${error}`
    resultField.value += results
  }
  finally {
    client.disconnect()
} // end of cashCheck()

cancelCheck()