Cash a Check for a Flexible Amount

As long as the Check is in the ledger and not expired, the specified recipient can cash it to receive a flexible amount by sending a CheckCash transaction with a DeliverMin field. When cashing a Check in this way, the receiver gets as much as is possible to deliver, debiting the Check's sender for the Check's full SendMax amount or as much as is available. Cashing fails if it doesn't deliver at least the DeliverMin amount to the Check's recipient.

You might cash a Check for a flexible amount if you just want to get as much as possible from the Check.

Prerequisites

The prerequisites for cashing a check are the same whether you are cashing it for an exact amount or a flexible amount.

You need the ID of a Check object currently in the ledger.

For example, the ID of one Check in these examples is 838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334, although you must use a different ID to go through these steps yourself.

The address and secret key of the Check's stated recipient. The address must match the Destination address in the Check object.

If the Check is for an issued currency, you (the recipient) must have a trust line to the issuer. Your limit on that trust line must be enough higher than the balance to add the amount you would receive.

1. Prepare the CheckCash transaction

Figure out the values of the CheckCash transaction fields. To cash a check for a flexible amount, the following fields are the bare minimum; everything else is either optional or can be auto-filled when signing:

Field

Value

Description

TransactionType

String

The value CheckCash indicates this is a CheckCash transaction.

Account

String (Address)

The address of the sender who is cashing the Check. (In other words, your address.)

CheckID

String

The ID of the Check object in the ledger to cash. You can get this information by looking up the metadata of the CheckCreate transaction using the tx method or by looking for Checks using the account_objects method.

DeliverMin

String or Object (Amount)

A minimum amount to receive from the Check. If you cannot receive at least this much, cashing the Check fails, leaving the Check in the ledger so you can try again. For XRP, this must be a string specifying drops of XRP. For issued currencies, this is an object with currency, issuer, and value fields. The currency and issuer fields must match the corresponding fields in the Check object, and the value must be less than or equal to the amount in the Check object. For more information on specifying currency amounts, see Specifying Currency Amounts.

Example CheckCash Preparation for a flexible amount

The following examples show how to prepare a transaction to cash a Check for a flexible amount.

2. Sign the CheckCash transaction

The most secure way to sign a transaction is to do it locally with a signing library, such as RippleAPI. Alternatively, you can sign the transaction using the sign method command, but this must be done through a trusted and encrypted connection, or through a local connection, and only to a server you control.

In all cases, note the signed transaction's identifying hash for later.

3. Submit the signed CheckCash transaction

Take the signed transaction blob from the previous step and submit it to a rippled server. You can do this safely even if you do not operate the rippled server. The response contains a provisional result, which should be tesSUCCESS, but this result is usually not final. A provisional response of terQUEUED is also OK, since queued transactions are generally included in the next open ledger version (usually about 10 seconds after submission).

Tip: If the preliminary result is tefMAX_LEDGER, the transaction has failed permanently because its LastLedgerSequence parameter is lower than the current ledger. This happens when you take longer than the expected number of ledger versions between preparing and submitting the transaction. If this occurs, start over from step 1 with a higher LastLedgerSequence value.

4. Wait for validation

On the live network or the Ripple Test Net, you can wait 4-7 seconds for the ledger to close automatically.

If you're running rippled in stand-alone mode, use the ledger_accept method to manually close the ledger.

5. Confirm final result

Use the tx method with the CheckCash transaction's identifying hash to check its status. Look for a "TransactionResult": "tesSUCCESS" field in the transaction's metadata, indicating that the transaction succeeded, and the field "validated": true in the result, indicating that this result is final.

Handling Errors

If cashing the Check failed with a tec-class code, look up the code in the Full Transaction Response List and respond accordingly. Some common possibilities for CheckCash transactions:

Result Code

Meaning

How to Respond

tecEXPIRED

The Check has expired.

Cancel the Check and ask the sender to create a new Check with a later Expiration time.

tecNO_ENTRY

The Check ID doesn't exist.

Confirm that the CheckID from the CheckCash transaction is correct. Confirm that the Check has not already been canceled or successfully cashed.

tecNO_LINE

The recipient doesn't have a trust line for the Check's currency.

If you want to hold this currency from this issuer, create a trust line for the specified currency and issuer with a reasonable limit using a TrustSet transaction, then try to cash the check again.

tecNO_PERMISSION

The sender of the CheckCash transaction isn't the Destination of the Check.

Double-check the Destination of the Check.

tecNO_AUTH

The issuer of the currency from the check is using Authorized Trust Lines but the recipient's trust line to the issuer is not approved.

Ask the issuer to authorize this trust line, then try again to cash the Check after they do.

tecPATH_PARTIAL

The Check could not deliver enough issued currency, either due to trust line limits or because the sender does not have enough balance of the currency to send (after including the issuer's transfer fee, if there is one).

If the problem is the trust line limit, send a TrustSet transaction to increase your limit (if desired) or lower your balance by spending some of the currency, then try to cash the Check again. If the problem is the sender's balance, wait for the sender to have more of the Check's currency, or try again to cash the Check for a lesser amount.

tecUNFUNDED_PAYMENT

The Check could not deliver enough XRP.

Wait for the sender to have more XRP, or try again to cash the Check for a lesser amount.

6. Confirm delivered amount

If the Check was cashed for a flexible DeliverMin amount and succeeded, you can assume that the Check was cashed for at least the DeliverMin amount. To get the exact amount delivered, check the transaction metadata. The metadata's AffectedNodes array contains one or two objects that reflect the change in balances from cashing the Check, depending on the type of currency.

For XRP, the AccountRoot object of the Check's sender has its XRP Balance field debited. The AccountRoot object of the Check's recipient (the one who sent the CheckCash transaction) has its XRP Balance credited for at least the DeliverMin of the CheckCash transaction minus the transaction cost of sending the transaction.

For example, the following ModifiedNode shows that the account rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis, the Check's recipient and the sender of this CheckCash transaction, had its XRP balance change from 9999999970 drops to 10099999960 drops, meaning the recipient was credited a net of 99.99999 XRP as a result of processing the transaction.

The net amount of 99.99999 XRP includes deducting the transaction cost that is destroyed to pay for sending this CheckCash transaction. The following transaction instructions (excerpted) show that the transaction cost (the Fee field) was 10 drops of XRP. By adding this to the net balance change, we conclude that the recipient, rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis, was credited a gross amount of exactly 100 XRP for cashing the Check.

For issued currencies where the sender or recipient of the check is the issuer, the RippleState object representing the trust line between those accounts has its Balance adjusted in the favor of the Check's recipient.

For issued currencies with a third-party issuer, there are changes to two RippleState objects, representing the trust lines connecting the sender to the issuer, and the issuer to the recipient. The RippleState object representing the relationship between the Check's sender and the issuer has its Balance changed in favor of the issuer, and the RippleState object representing the relationship between the issuer and the recipient has its Balance changed in favor of the recipient.

If the issued currency has a transfer fee, the Check's sender may be debited more than the recipient is credited. (The difference is the transfer fee, which is returned to the issuer as a decreased net obligation.)

These resources are provided for informational purposes only, as illustrative references for your independent development of products or services designed to interface with Ripple’s open-source technologies. These resources are not intended to direct or influence how you or any other person interacts with Ripple’s open-source technologies. Ripple does not endorse any specific resource and makes no representations or warranties with respect to the resources listed.

Note that anti-money laundering and counter-terrorism financing laws and regulations, such as the U.S. Bank Secrecy Act and regulations issued by the Financial Crimes Enforcement Network (FinCEN), require certain parties to take certain precautions against financial crime. In particular, you may be interested in the 2013 guidance issued by FinCEN in response to questions concerning the regulatory treatment of persons who use or make a business of exchanging, accepting, or transmitting certain virtual currencies. Additional FinCEN references are available at https://www.fincen.gov.