Send a Check

Sending a Check is like writing permission for an intended recipient to pull a payment from you. The outcome of this process is a Check object in the ledger which the recipient can cash later.

In many cases, you want to send a Payment instead of a Check, since that delivers the money directly to the recipient in one step. However, if your intended recipient uses DepositAuth, you cannot send them Payments directly, so a Check is a good alternative.

This tutorial uses the example of a fictitious company, BoxSend SG (whose XRP Ledger address is rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za) paying a fictitious cryptocurrency consulting company named Grand Payments (with XRP Ledger address rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis) for some consulting work. Grand Payments prefers be paid in XRP, but to simplify their taxes and regulation, only accepts payments they've explicitly approved.

Outside of the XRP Ledger, Grand Payments sends an invoice to BoxSend SG with the ID 46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291, and requests a Check for 100 XRP be sent to Grand Payments' XRP Ledger address of rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis.

Prerequisites

To send a Check with this tutorial, you need the following:

The address and secret key of a funded account to send the Check from.

1. Prepare the CheckCreate transaction

Decide how much money the Check is for and who can cash it. Figure out the values of the CheckCreate 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 CheckCreate here.

Account

String (Address)

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

Destination

String (Address)

The address of the intended recipient who can cash the Check.

SendMax

String or Object (Amount)

The maximum amount the sender can be debited when this Check gets cashed. For XRP, use a string representing drops of XRP. For issued currencies, use an object with currency, issuer, and value fields. See Specifying Currency Amounts for details. If you want the recipient to be able to cash the Check for an exact amount of a non-XRP currency with a transfer fee, remember to include an extra percentage to pay for the transfer fee. (For example, for the recipient to cash a Check for 100 CAD from an issuer with a 2% transfer fee, you must set the SendMax to 102 CAD from that issuer.)

If you are using RippleAPI, you can use the prepareCheckCreate() helper method.

Note: RippleAPI supports Checks in versions 0.19.0 and up.

Example CheckCreate Preparation

The following example shows a prepared Check from BoxSend SG (rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za) to Grand Payments (rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis) for 100 XRP. As additional (optional) metadata, BoxSend SG adds the ID of the invoice from Grand Payments so Grand Payments knows which invoice this Check is intended to pay.

2. Sign the CheckCreate 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 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 CheckCreate 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.

Look for a CreatedNode object in the transaction metadata to indicate that the transaction created a Check ledger object. The LedgerIndex of this object is the ID of the Check. In the following example, the Check's ID is 49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0.

Note: RippleAPI does not report the Check's ID when you look up a CheckCreate transaction. You can work around this by calculating the Check's ID from the Check ID format, as in the example RippleAPI code below.

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.