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.
- You can use the XRP Ledger Test Net Faucet to get a funded address and secret with 10,000 Test Net XRP.
The address of a funded account to receive the Check.
A secure way to sign transactions.
A client library or any HTTP or WebSocket library.

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 tokens, 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.)

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.

ripple-lib 1.x
JSON-RPC, WebSocket, or Commandline

'use strict'
const RippleAPI = require('ripple-lib').RippleAPI

// This example connects to a public Test Net server
const api = new RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'})
api.connect().then(() => {
  console.log('Connected')

  const sender = 'rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za'
  const receiver = 'rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis'
  const options = {
    // Allow up to 60 ledger versions (~5 min) instead of the default 3 versions
    // before this transaction fails permanently.
    "maxLedgerVersionOffset": 60
  }
  return api.prepareCheckCreate(sender, {
    "destination": receiver,
    "sendMax": {
      "currency": "XRP",
      "value": "100" // RippleAPI uses decimal XRP, not integer drops
    },
    "invoiceID": "46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291"
  }, options)

}).then(prepared => {
  console.log("txJSON:", prepared.txJSON);

// Disconnect and return
}).then(() => {
  api.disconnect().then(() => {
    console.log('Disconnected')
    process.exit()
  })
}).catch(console.error)


// Example output:
//
// Connected
// txJSON: {"Account":"rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za",
//  "TransactionType":"CheckCreate",
//  "Destination":"rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
//  "SendMax":"100000000",
//  "Flags":2147483648,
//  "InvoiceID": "46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291",
//  "LastLedgerSequence":7835917,"Fee":"12","Sequence":2}
// Disconnected

2. Sign the CheckCreate transaction

The most secure way to sign a transaction is to sign locally with a client library. Alternatively, if you run your own rippled node you can sign the transaction using the sign method, but this must be done through a trusted and encrypted connection, or through a local (same-machine) connection.

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

Example Request

ripple-lib 1.x
WebSocket
Commandline

'use strict'
const RippleAPI = require('ripple-lib').RippleAPI

// Can sign offline if the txJSON has all required fields
const api = new RippleAPI()

const txJSON = '{"Account":"rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za", \
  "TransactionType":"CheckCreate", \
  "Destination":"rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis", \
  "SendMax":"100000000", \
  "Flags":2147483648, \
  "LastLedgerSequence":7835923, \
  "Fee":"12", \
  "Sequence":2}'

// Be careful where you store your real secret.
const secret = 's████████████████████████████'

const signed = api.sign(txJSON, secret)

console.log("tx_blob is:", signed.signedTransaction)
console.log("tx hash is:", signed.id)

Example Response

ripple-lib 1.x
WebSocket
Commandline

tx_blob is: 12001022800000002400000002201B0077911368400000000000000C694000000005F5E100732103B6FCD7FAC4F665FE92415DD6E8450AD90F7D6B3D45A6CFCF2E359045FF4BB400744630440220181FE2F945EBEE632966D5FB03114611E3047ACD155AA1BDB9DF8545C7A2431502201E873A4B0D177AB250AF790CE80621E16F141506CF507586038FC4A8E95887358114735FF88E5269C80CD7F7AF10530DAB840BBF6FDF8314A8B6B9FF3246856CADC4A0106198C066EA1F9C39
tx hash is: C0B27D20669BAB837B3CDF4B8148B988F17CE1EF8EDF48C806AE9BF69E16F441

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 run 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.

Example Request

ripple-lib 1.x
WebSocket
Commandline

'use strict'
const RippleAPI = require('ripple-lib').RippleAPI

// This example connects to a public Test Net server
const api = new RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'})
api.connect().then(() => {
  console.log('Connected')

  const tx_blob = "12001022800000002400000002201B0077911368400000000000000"+
    "C694000000005F5E100732103B6FCD7FAC4F665FE92415DD6E8450AD90F7D6B3D45A6"+
    "CFCF2E359045FF4BB400744630440220181FE2F945EBEE632966D5FB03114611E3047"+
    "ACD155AA1BDB9DF8545C7A2431502201E873A4B0D177AB250AF790CE80621E16F1415"+
    "06CF507586038FC4A8E95887358114735FF88E5269C80CD7F7AF10530DAB840BBF6FD"+
    "F8314A8B6B9FF3246856CADC4A0106198C066EA1F9C39"

  return api.submit(tx_blob)
}).then(response => {
  console.log("Preliminary transaction result:", response.resultCode)

// Disconnect and return
}).then(() => {
  api.disconnect().then(() => {
    console.log('Disconnected')
    process.exit()
  })
}).catch(console.error)

Example Response

ripple-lib 1.x
WebSocket
Commandline

Connected
Preliminary transaction result: tesSUCCESS
Disconnected

4. Wait for validation

On a live network (including Mainnet, Testnet, or Devnet), 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 with a LedgerEntryType of "Check". This indicates 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 84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9.

Example Request

ripple-lib 1.x
WebSocket
Commandline

'use strict'
const RippleAPI = require('ripple-lib').RippleAPI
const decodeAddress = require('ripple-address-codec').decodeAddress;
const createHash = require('crypto').createHash;

// This example connects to a public Test Net server
const api = new RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'})
api.connect().then(() => {
  console.log('Connected')

  const tx_hash = "C0B27D20669BAB837B3CDF4B8148B988F17CE1EF8EDF48C806AE9BF69E16F441"

  return api.getTransaction(tx_hash)
}).then(response => {
  console.log("Final transaction result:", response)

  // Re-calculate checkID to work around issue ripple-lib#876
  const checkIDhasher = createHash('sha512')
  checkIDhasher.update(Buffer.from('0043', 'hex'))
  checkIDhasher.update(new Buffer(decodeAddress(response.address)))
  const seqBuf = Buffer.alloc(4)
  seqBuf.writeUInt32BE(response.sequence, 0)
  checkIDhasher.update(seqBuf)
  const checkID = checkIDhasher.digest('hex').slice(0,64).toUpperCase()
  console.log("Calculated checkID:", checkID)

// Disconnect and return
}).then(() => {
  api.disconnect().then(() => {
    console.log('Disconnected')
    process.exit()
  })
}).catch(console.error)

Example Response

ripple-lib 1.x
WebSocket
Commandline

Connected
Final transaction result: { type: 'checkCreate',
  address: 'rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za',
  sequence: 2,
  id: 'C0B27D20669BAB837B3CDF4B8148B988F17CE1EF8EDF48C806AE9BF69E16F441',
  specification:
   { destination: 'rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis',
     sendMax: { currency: 'XRP', value: '100' } },
  outcome:
   { result: 'tesSUCCESS',
     timestamp: '2018-03-27T20:47:40.000Z',
     fee: '0.000012',
     balanceChanges: { rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za: [Array] },
     orderbookChanges: {},
     ledgerVersion: 7835887,
     indexInLedger: 0 } }
Calculated checkID: CEA5F0BD7B2B5C85A70AE735E4CE722C43C86410A79AB87C11938AA13A11DBF9
Disconnected

Send a Check

Prerequisites

1. Prepare the CheckCreate transaction

Example CheckCreate Preparation

2. Sign the CheckCreate transaction

Example Request

Example Response

3. Submit the signed transaction

Example Request

Example Response

4. Wait for validation

5. Confirm final result

Example Request

Example Response

Was this helpful?