mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-19 19:25:51 +00:00
Update legacy Checks tutorial & sample code
Clean up legacy Checks tutorials
This commit is contained in:
mDuo13
@@ -1,8 +0,0 @@
|
||||
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 a [token](../concepts/tokens/index.md), you (the recipient) must have a [trust line](../concepts/tokens/fungible-tokens/index.md) to the issuer. Your limit on that trust line must be high enough to hold your previous balance plus the amount you would receive.
|
||||
- A [secure way to sign transactions](../concepts/transactions/secure-signing.md).
|
||||
- A [client library](../references/client-libraries.md) that can connect to the XRP Ledger, or [any HTTP or WebSocket client](../tutorials/http-websocket-apis/build-apps/get-started.md).
|
||||
@@ -48,10 +48,9 @@ For more information about Checks in the XRP Ledger, see:
|
||||
- [CheckCreate][]
|
||||
- [CheckCash][]
|
||||
- [CheckCancel][]
|
||||
- [Checks Tutorials](../../tutorials/how-tos/use-specialized-payment-types/use-checks/use-checks.md)
|
||||
- [Checks Tutorials](../../tutorials/how-tos/use-specialized-payment-types/use-checks/index.md)
|
||||
- [Send a Check](../../tutorials/how-tos/use-specialized-payment-types/use-checks/send-a-check.md)
|
||||
- [Look up Checks by sender address](../../tutorials/how-tos/use-specialized-payment-types/use-checks/look-up-checks-by-sender.md)
|
||||
- [Look up Checks by recipient address](../../tutorials/how-tos/use-specialized-payment-types/use-checks/look-up-checks-by-recipient.md)
|
||||
- [Look up Checks](../../tutorials/how-tos/use-specialized-payment-types/use-checks/look-up-checks.md)
|
||||
- [Cash a Check for an exact amount](../../tutorials/how-tos/use-specialized-payment-types/use-checks/cash-a-check-for-an-exact-amount.md)
|
||||
- [Cash a Check for a flexible amount](../../tutorials/how-tos/use-specialized-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md)
|
||||
- [Cancel a Check](../../tutorials/how-tos/use-specialized-payment-types/use-checks/cancel-a-check.md)
|
||||
|
||||
@@ -1,29 +1,30 @@
|
||||
---
|
||||
html: cancel-a-check.html
|
||||
parent: use-checks.html
|
||||
seo:
|
||||
description: Cancel a Check object without sending money.
|
||||
description: Cancel a Check without sending money.
|
||||
labels:
|
||||
- Checks
|
||||
---
|
||||
# Cancel a Check
|
||||
|
||||
This tutorial shows how to cancel a [Check](../../../../concepts/payment-types/checks.md), which removes the [Check object from the ledger](../../../../references/protocol/ledger-data/ledger-entry-types/check.md) without sending money.
|
||||
This tutorial shows how to cancel a [Check](../../../../concepts/payment-types/checks.md), which removes the [Check entry](../../../../references/protocol/ledger-data/ledger-entry-types/check.md) from the ledger without sending money.
|
||||
|
||||
You may want to cancel an incoming Check if you do not want it. You might cancel an outgoing Check if you made a mistake when sending it or if circumstances have changed. If a Check expires, it's also necessary to cancel it to remove it from the ledger so the sender gets their [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves) back.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To cancel a Check with this tutorial, you need the following:
|
||||
- You should be familiar with the basics of using the [xrpl.js client library](../../../javascript/build-apps/get-started.md).
|
||||
- You need an XRP Ledger account including its secret key. (You can get one on Testnet for free.) See also: [XRP Faucets](/resources/dev-tools/xrp-faucets).
|
||||
- You need the ID of a Check ledger entry that you are either the sender or recipient of. See also: [Send a Check](./send-a-check.md).
|
||||
|
||||
- You need the ID of a Check object currently in the ledger.
|
||||
- For example, this tutorial includes examples that cancel a Check with the ID `49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0`, although you must use a different ID to go through these steps yourself.
|
||||
- The **address** and **secret key** of a funded account to send the CheckCancel transaction. This address must be either the sender or the recipient of the Check, unless the Check is expired.
|
||||
- A [secure way to sign transactions](../../../../concepts/transactions/secure-signing.md).
|
||||
- A [client library](../../../../references/client-libraries.md) or any HTTP or WebSocket library.
|
||||
## Source Code
|
||||
|
||||
The complete source code for this tutorial is available in the source repository for this website:
|
||||
|
||||
## 1. Prepare the CheckCancel transaction
|
||||
{% repo-link path="_code-samples/checks/js/" %}Checks sample code{% /repo-link %}
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Prepare the CheckCancel transaction
|
||||
|
||||
Figure out the values of the [CheckCancel transaction][] fields. The following fields are the bare minimum; everything else is either optional or can be [auto-filled](../../../../references/protocol/transactions/common-fields.md#auto-fillable-fields) when signing:
|
||||
|
||||
@@ -31,135 +32,24 @@ Figure out the values of the [CheckCancel transaction][] fields. The following f
|
||||
|:------------------|:-----------------|:--------------------------------------|
|
||||
| `TransactionType` | String | Use the string `CheckCancel` when canceling a Check. |
|
||||
| `Account` | String (Address) | The address of the sender who is canceling the Check. (In other words, your address.) |
|
||||
| `CheckID` | String | The ID of the Check object in the ledger to cancel. 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][]. |
|
||||
| `CheckID` | String | The ID of the Check entry to cancel. You can get this information when you [send a check](./send-a-check.md), or by [looking up checks](./look-up-checks.md). |
|
||||
|
||||
### Example CheckCancel Preparation
|
||||
For example:
|
||||
|
||||
The following examples show how to cancel a Check.
|
||||
{% code-snippet file="/_code-samples/checks/js/cancel-check.js" from="// Prepare" before="// Submit" /%}
|
||||
|
||||
{% tabs %}
|
||||
### 2. Submit the CheckCancel transaction
|
||||
|
||||
{% tab label="JSON-RPC, WebSocket, or Commandline" %}
|
||||
```json
|
||||
{
|
||||
"TransactionType": "CheckCancel",
|
||||
"Account": "rUn84CUYbNjRoTQ6mSW7BVJPSVJNLb1QLo",
|
||||
"CheckID": "49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0",
|
||||
"Fee": "12"
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
Submit the CheckCancel transaction in the usual way and wait for it to be validated. If the result code is `tesSUCCESS` and the transaction is in a validated ledger, the transaction is successful. For example:
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/prepareCancel.js" language="js" /%}
|
||||
{% /tab %}
|
||||
{% code-snippet file="/_code-samples/checks/js/cancel-check.js" from="// Submit" before="// Confirm" /%}
|
||||
|
||||
{% /tabs %}
|
||||
## 3. Confirm transaction result
|
||||
|
||||
## 2. Sign the CheckCancel transaction
|
||||
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. For example:
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-sign-step.md" /%}
|
||||
{% code-snippet file="/_code-samples/checks/js/cancel-check.js" from="// Confirm" before="// Disconnect" /%}
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/signCancel.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-cancel-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/sign-cancel-resp.txt" language="" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-cancel-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
## 3. Submit the signed CheckCancel transaction
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-submit-step.md" /%}
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/submitCancel.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-cancel-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/submit-cancel-resp.txt" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-cancel-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 4. Wait for validation
|
||||
|
||||
{% partial file="/docs/_snippets/wait-for-validation.md" /%}
|
||||
|
||||
## 5. Confirm final result
|
||||
|
||||
Use the [tx method][] with the CheckCancel 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 `DeletedNode` object in the transaction metadata with `"LedgerEntryType": "Check"` to indicate that the transaction removed a [Check ledger object](../../../../references/protocol/ledger-data/ledger-entry-types/check.md). The `LedgerIndex` of this object should match the ID of the Check.
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/getCancelTx.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-cancel-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/get-cancel-tx-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-cancel-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
{% admonition type="success" name="Tip" %}The `submitAndWait()` method in xrpl.js only returns when the transaction's result is final, so you can assume that the transaction is validated if it returns a result code of `tesSUCCESS`.{% /admonition %}
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
html: cash-a-check-for-a-flexible-amount.html
|
||||
parent: use-checks.html
|
||||
seo:
|
||||
description: Cash a Check for as much as possible.
|
||||
labels:
|
||||
@@ -8,148 +6,68 @@ labels:
|
||||
---
|
||||
# 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.
|
||||
This tutorial shows how to cash a [Check](/docs/concepts/payment-types/checks.md) for a flexible amount. As long as the Check is not expired, the specified recipient can cash it to receive the maximum amount available. You would cash a Check this way if you want to receive as much as possible. When doing this, you set a minimum amount to receive in case the sender does not have enough money to pay the full amount. If the check cannot deliver at least the minimum amount, cashing the check fails but you can try again later.
|
||||
|
||||
You might cash a Check for a flexible amount if you want to get as much as possible from the Check.
|
||||
|
||||
The specified recipient can also [cash the check for an exact amount](cash-a-check-for-a-flexible-amount.md).
|
||||
You can also [cash a check for an exact amount](cash-a-check-for-a-flexible-amount.md).
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{% partial file="/docs/_snippets/checkcash-prereqs.md" /%}
|
||||
- You should be familiar with the basics of using the [xrpl.js client library](../../../javascript/build-apps/get-started.md).
|
||||
- You need an XRP Ledger account including its secret key. (You can get one on Testnet for free.) See also: [XRP Faucets](/resources/dev-tools/xrp-faucets).
|
||||
- You need the ID of a Check ledger entry that you are the recipient of. See also: [Send a Check](./send-a-check.md) and [Look Up Checks](./look-up-checks.md).
|
||||
|
||||
## 1. Prepare the CheckCash transaction
|
||||
|
||||
## Source Code
|
||||
|
||||
The complete source code for this tutorial is available in the source repository for this website:
|
||||
|
||||
{% repo-link path="_code-samples/checks/js/" %}Checks sample code{% /repo-link %}
|
||||
|
||||
|
||||
## Steps
|
||||
### 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](../../../../references/protocol/transactions/common-fields.md#auto-fillable-fields) 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 tokens, 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][]. |
|
||||
| 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 to cash. You can get this information from the person who sent you the Check, or by [looking up checks](./look-up-checks.md) where your account is the destination. |
|
||||
| `DeliverMin` | [Currency 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 tokens, 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
|
||||
In the sample code, these values are hard-coded, so you should edit them to match your case:
|
||||
|
||||
The following examples show how to prepare a transaction to cash a Check for a flexible amount.
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-flexible.js" language="js" from="// Define parameters" before="async function main()" /%}
|
||||
|
||||
{% tabs %}
|
||||
Then, you use these parameters to fill out the transaction. For example:
|
||||
|
||||
{% tab label="JSON-RPC, WebSocket, or Commandline" %}
|
||||
```json
|
||||
{
|
||||
"Account": "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
|
||||
"TransactionType": "CheckCash",
|
||||
"DeliverMin": "95000000",
|
||||
"CheckID": "2E0AD0740B79BE0AAE5EDD1D5FC79E3C5C221D23C6A7F771D85569B5B91195C2"
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/prepareCashFlex.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 2. Sign the CheckCash transaction
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-sign-step.md" /%}
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-cash-flex-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-flexible.js" language="js" from="// Prepare the transaction" before="// Submit the transaction" /%}
|
||||
|
||||
|
||||
### Example Response
|
||||
### 2. Submit the transaction
|
||||
|
||||
{% tabs %}
|
||||
Send the transaction and wait for it to be validated by the consensus process, as normal:
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-cash-flex-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-flexible.js" from="// Submit" before="// Confirm" /%}
|
||||
|
||||
|
||||
## 3. Submit the signed CheckCash transaction
|
||||
## 3. Confirm final result
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-submit-step.md" /%}
|
||||
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.
|
||||
|
||||
### Example Request
|
||||
{% admonition type="success" name="Tip" %}The `submitAndWait()` method in xrpl.js only returns when the transaction's result is final, so you can assume that the transaction is validated if it returns a result code of `tesSUCCESS`.{% /admonition %}
|
||||
|
||||
{% tabs %}
|
||||
If the transaction suceeded, you can assume that it delivered at least the `DeliverMin` amount of this transaction and at most the `SendMax` of the Check. To confirm the exact balance changes that occurred as a result of cashing the check, including how much was actually debited and credited, you must look at the transaction metadata. The `xrpl.getBalanceChanges()` function can help to summarize this. For example:
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-cash-flex-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-flexible.js" from="// Confirm transaction results" before="// Disconnect" /%}
|
||||
|
||||
{% /tabs %}
|
||||
{% admonition type="info" name="Note" %}
|
||||
The metadata shows the net balance changes as the result of all of the transactions effects, which may be surprising in some cases. If an account receives exactly the same amount of XRP as it burns, its balance stays the same so it does not even appear in the list of balance changes.
|
||||
{% /admonition %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-cash-flex-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 4. Wait for validation
|
||||
|
||||
{% partial file="/docs/_snippets/wait-for-validation.md" /%}
|
||||
|
||||
## 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.
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-cash-flex-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-cash-flex-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
### Handling Errors
|
||||
|
||||
If cashing the Check failed with a `tec`-class code, look up the code in the [Full Transaction Response List](../../../../references/protocol/transactions/transaction-results/index.md) 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](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) 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 tokens, either due to trust line limits or because the sender does not have enough balance of the token to send (including the issuer's [transfer fee](../../../../concepts/tokens/transfer-fees.md), 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 `delivered_amount` field in the metadata shows the exact amount delivered. (This field is only provided if the Check was cashed for a flexible amount. If the check was successfully cashed for a fixed amount, then the delivered amount is equal to the `Amount` of the CheckCash transaction.)
|
||||
If you are not using `getBalanceChanges()`, the following guidelines should help with parsing the metadata:
|
||||
|
||||
- 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](../../../../concepts/transactions/transaction-cost.md) of sending the transaction.
|
||||
|
||||
|
||||
@@ -1,139 +1,94 @@
|
||||
---
|
||||
html: cash-a-check-for-an-exact-amount.html
|
||||
parent: use-checks.html
|
||||
seo:
|
||||
description: Cash a Check in the ledger for any exact amount up to the amount it specifies.
|
||||
description: Cash a Check for any exact amount up to the amount it specifies.
|
||||
labels:
|
||||
- Checks
|
||||
---
|
||||
# Cash a Check for an Exact Amount
|
||||
|
||||
As long as the Check is in the ledger and not expired, the specified recipient can cash it to receive any exact amount up to the amount specified in the Check by sending a [CheckCash transaction][] with an `Amount` field. 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.
|
||||
This tutorial shows how to cash a [Check](/docs/concepts/payment-types/checks.md) 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.
|
||||
|
||||
The specified recipient can also [cash the check for a flexible amount](cash-a-check-for-a-flexible-amount.md).
|
||||
You can also [cash a check for a flexible amount](./cash-a-check-for-a-flexible-amount.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{% partial file="/docs/_snippets/checkcash-prereqs.md" /%}
|
||||
- You should be familiar with the basics of using the [xrpl.js client library](../../../javascript/build-apps/get-started.md).
|
||||
- You need an XRP Ledger account including its secret key. (You can get one on Testnet for free.) See also: [XRP Faucets](/resources/dev-tools/xrp-faucets).
|
||||
- You need the ID of a Check ledger entry that you are the recipient of. See also: [Send a Check](./send-a-check.md) and [Look Up Checks](./look-up-checks.md).
|
||||
|
||||
## 1. Prepare the CheckCash transaction
|
||||
## Source Code
|
||||
|
||||
Figure out the values of the [CheckCash transaction][] fields. 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](../../../../references/protocol/transactions/common-fields.md#auto-fillable-fields) when signing:
|
||||
The complete source code for this tutorial is available in the source repository for this website:
|
||||
|
||||
| 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][]. |
|
||||
| `Amount` | String or Object (Amount) | The amount to redeem from the Check. For XRP, this must be a string specifying drops of XRP. For tokens, 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 currencies with transfer fees, you must cash the Check for less than its `SendMax` so the transfer fee can be paid by the `SendMax`.) If you cannot receive this much, cashing the Check fails, leaving the Check in the ledger so you can try again. For more information on specifying currency amounts, see [Specifying Currency Amounts][]. |
|
||||
{% repo-link path="_code-samples/checks/js/" %}Checks sample code{% /repo-link %}
|
||||
|
||||
## 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](../../../../references/protocol/transactions/common-fields.md#auto-fillable-fields) 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 to cash. You can get this information from the person who sent you the Check, or by [looking up checks](./look-up-checks.md) where your account is the destination. |
|
||||
| `Amount` | [Currency Amount][] | The amount to receive. The type of currency (token or XRP) must match the Check object. The quantity in the `value` field must be less than or equal to the amount in the Check object. (For currencies with transfer fees, you must cash the Check for less than its `SendMax` so the transfer fee can be paid by the `SendMax`.) For more information on specifying currency amounts, see [Specifying Currency Amounts][]. |
|
||||
|
||||
In the sample code, these values are hard-coded, so you should edit them to match your case:
|
||||
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-exact.js" language="js" from="// Define parameters" before="async function main()" /%}
|
||||
|
||||
Then, you use these parameters to fill out the transaction. For example:
|
||||
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-exact.js" language="js" from="// Prepare the transaction" before="// Submit the transaction" /%}
|
||||
|
||||
|
||||
### Example CheckCash Preparation for an exact amount
|
||||
### 2. Submit the transaction
|
||||
|
||||
The following examples show how to prepare a transaction to cash a Check for a fixed amount.
|
||||
Send the transaction and wait for it to be validated by the consensus process, as normal:
|
||||
|
||||
{% tabs %}
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-exact.js" from="// Submit" before="// Confirm" /%}
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
{% admonition type="success" name="Tip" %}The `submitAndWait()` method in xrpl.js only returns when the transaction's result is final, so you can assume that the transaction is validated if it returns a result code of `tesSUCCESS`.{% /admonition %}
|
||||
|
||||
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:
|
||||
|
||||
{% code-snippet file="/_code-samples/checks/js/cash-check-exact.js" from="// Confirm transaction results" before="// Disconnect" /%}
|
||||
|
||||
Example balance changes output:
|
||||
|
||||
{% tab label="JSON-RPC, WebSocket, or Commandline" %}
|
||||
```json
|
||||
{
|
||||
"Account": "rfkE1aSy9G8Upk4JssnwBxhEv5p4mn2KTy",
|
||||
"TransactionType": "CheckCash",
|
||||
"Amount": "100000000",
|
||||
"CheckID": "838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334",
|
||||
"Fee": "12"
|
||||
}
|
||||
Balance changes: [
|
||||
{
|
||||
"account": "rEHjrKs86KfPjgeZvso2uQqhU2iA7AqD6r",
|
||||
"balances": [
|
||||
{
|
||||
"currency": "XRP",
|
||||
"value": "29.999988"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"account": "rh8pPR6p87egsGuAg53QrJ7Y4PLf4Qdrf7",
|
||||
"balances": [
|
||||
{
|
||||
"currency": "XRP",
|
||||
"value": "-30"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/prepareCashExact.js" language="js" /%}
|
||||
{% /tab %}
|
||||
{% admonition type="info" name="Note" %}
|
||||
The metadata shows the net balance changes as the result of all of the transactions effects, which may be surprising in some cases. For example, in the above example, rEHjr... received 30 XRP from the Check but burned 12 drops of XRP on the transaction cost, resulting in a net gain of 29.99988 XRP from the transaction.
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 2. Sign the CheckCash transaction
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-sign-step.md" /%}
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-cash-exact-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-cash-exact-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
## 3. Submit the signed CheckCash transaction
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-submit-step.md" /%}
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-cash-exact-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-cash-exact-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 4. Wait for validation
|
||||
|
||||
{% partial file="/docs/_snippets/wait-for-validation.md" /%}
|
||||
|
||||
## 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.
|
||||
|
||||
If the check was cashed for an exact `Amount` and succeeded, you can assume that the recipient was credited for exactly that amount (with possible rounding for very large or very small amounts of tokens).
|
||||
|
||||
If cashing the Check failed, the Check remains in the ledger so you can try cashing again later. You may want to [cash the Check for a flexible amount](cash-a-check-for-a-flexible-amount.md) instead.
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-cash-exact-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-cash-exact-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
If an account receives exactly the same amount of XRP as it burns, its balance stays the same so it does not even appear in the list of balance changes.
|
||||
{% /admonition %}
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
html: use-checks.html
|
||||
parent: use-specialized-payment-types.html
|
||||
seo:
|
||||
description: Checks in the XRP Ledger authorize another account to claim funds later, similar to how personal paper checks work.
|
||||
metadata:
|
||||
@@ -12,7 +10,6 @@ labels:
|
||||
|
||||
Checks in the XRP Ledger authorize another account to claim funds later, similar to how personal paper checks work.
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
|
||||
See also: [Modular Tutorial: Send and Cash Checks](../../../javascript/send-payments/send-and-cash-checks.md).
|
||||
|
||||
{% child-pages /%}
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
html: look-up-checks-by-recipient.html
|
||||
parent: use-checks.html
|
||||
seo:
|
||||
description: Get a list of pending checks sent to an account.
|
||||
labels:
|
||||
- Checks
|
||||
---
|
||||
# Look Up Checks by Recipient
|
||||
|
||||
This tutorial shows how to look up [Checks](../../../../concepts/payment-types/checks.md) by their recipient. You may also want to [look up Checks by sender](look-up-checks-by-sender.md).
|
||||
|
||||
## 1. Look up all Checks for the address
|
||||
|
||||
To get a list of all incoming and outgoing Checks for an account, use the `account_objects` command with the recipient account's address and set the `type` field of the request to `checks`.
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/getChecks.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="JSON-RPC" %}
|
||||
{% code-snippet file="/_code-samples/checks/json-rpc/account_objects-req.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/get-checks-resp.txt" language="" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="JSON-RPC" %}
|
||||
{% code-snippet file="/_code-samples/checks/json-rpc/account_objects-resp.json" language="json" prefix="200 OK\n\n" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
## 2. Filter the responses by recipient
|
||||
|
||||
The response may include Checks where the account from the request is the sender and Checks where the account is the recipient. Each member of the `account_objects` array of the response represents one Check. For each such Check object, the address in the `Destination` is address of that Check's recipient.
|
||||
|
||||
The following pseudocode demonstrates how to filter the responses by recipient:
|
||||
|
||||
```js
|
||||
recipient_address = "rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za"
|
||||
account_objects_response = get_account_objects({
|
||||
account: recipient_address,
|
||||
ledger_index: "validated",
|
||||
type: "check"
|
||||
})
|
||||
|
||||
for (i=0; i < account_objects_response.account_objects.length; i++) {
|
||||
check_object = account_objects_response.account_objects[i]
|
||||
if (check_object.Destination == recipient_address) {
|
||||
log("Check to recipient:", check_object)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
html: look-up-checks-by-sender.html
|
||||
parent: use-checks.html
|
||||
seo:
|
||||
description: Get a list of pending Checks sent by an account.
|
||||
labels:
|
||||
- Checks
|
||||
---
|
||||
# Look Up Checks by Sender
|
||||
|
||||
This tutorial shows how to look up [Checks](../../../../concepts/payment-types/checks.md) by their sender. You may also want to [look up Checks by recipient](look-up-checks-by-recipient.md).
|
||||
|
||||
## 1. Look up all Checks for the address
|
||||
|
||||
To get a list of all incoming and outgoing Checks for an account, use the `account_objects` command with the sending account's address and set the `type` field of the request to `checks`.
|
||||
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/getChecks.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="JSON-RPC" %}
|
||||
{% code-snippet file="/_code-samples/checks/json-rpc/account_objects-req.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/get-checks-resp.txt" language="" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="JSON-RPC" %}
|
||||
{% code-snippet file="/_code-samples/checks/json-rpc/account_objects-resp.json" language="json" prefix="200 OK\n\n" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 2. Filter the responses by sender
|
||||
|
||||
The response may include Checks where the account from the request is the sender and Checks where the account is the recipient. Each member of the `account_objects` array of the response represents one Check. For each such Check object, the address in the `Account` is address of that Check's sender.
|
||||
|
||||
The following pseudocode demonstrates how to filter the responses by sender:
|
||||
|
||||
```js
|
||||
sender_address = "rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za"
|
||||
account_objects_response = get_account_objects({
|
||||
account: sender_address,
|
||||
ledger_index: "validated",
|
||||
type: "check"
|
||||
})
|
||||
|
||||
for (i=0; i < account_objects_response.account_objects.length; i++) {
|
||||
check_object = account_objects_response.account_objects[i]
|
||||
if (check_object.Account == sender_address) {
|
||||
log("Check from sender:", check_object)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
seo:
|
||||
description: Get a list of pending checks sent from or to an account.
|
||||
labels:
|
||||
- Checks
|
||||
---
|
||||
# Look Up Checks
|
||||
|
||||
This tutorial shows how to look up [Checks](../../../../concepts/payment-types/checks.md) by their sender or recipient, in JavaScript.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- You should be familiar with the basics of using the [xrpl.js client library](../../../javascript/build-apps/get-started.md).
|
||||
- To get any results, the addresses you're looking up must have at least one Check entry in the ledger. See also: [Send a Check](./send-a-check.md).
|
||||
|
||||
## Source Code
|
||||
|
||||
The complete source code for this tutorial is available in the source repository for this website:
|
||||
|
||||
{% repo-link path="_code-samples/checks/js/" %}Checks sample code{% /repo-link %}
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Look up all Checks for the address
|
||||
|
||||
To get a list of all incoming and outgoing Checks for an account, use the `account_objects` command and set the `type` field of the request to `checks`. You may need to make multiple requests if the result is [paginated](../../../../references/http-websocket-apis/api-conventions/markers-and-pagination.md).
|
||||
|
||||
{% code-snippet file="/_code-samples/checks/js/get-checks.js" from="// Loop through account objects" before="// Filter results" /%}
|
||||
|
||||
|
||||
### 2. Filter the responses by recipient
|
||||
|
||||
The response may include Checks where the account from the request is the sender or the recipient. Each member of the `account_objects` array of the response represents one Check. For each such Check object, the address in the `Destination` is address of that Check's recipient, such as in the following code:
|
||||
|
||||
{% code-snippet file="/_code-samples/checks/js/get-checks.js" from="// Filter results" before="// Disconnect" /%}
|
||||
|
||||
To filter by sender, check the address in the `Account` field of the Check instead.
|
||||
|
||||
{% admonition type="success" name="tip" %}For each Check entry in the results, the Check's ID is in the `index` field. You'll need this value to cash or cancel the Check.{% /admonition %}
|
||||
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
@@ -1,21 +1,15 @@
|
||||
---
|
||||
html: send-a-check.html
|
||||
parent: use-checks.html
|
||||
seo:
|
||||
description: Put a Check in the ledger so its intended recipient can cash it later.
|
||||
description: Send a Check whose intended recipient can cash it to be paid later.
|
||||
labels:
|
||||
- Checks
|
||||
---
|
||||
# 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](../../../../references/protocol/ledger-data/ledger-entry-types/check.md) which the recipient can cash later.
|
||||
Sending a [Check](/docs/concepts/payment-types/checks.md) is like writing permission for an intended recipient to pull a payment from you. The outcome of this process is a [Check entry in the ledger](../../../../references/protocol/ledger-data/ledger-entry-types/check.md) 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](../../../../concepts/accounts/depositauth.md), 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`. <!-- SPELLING_IGNORE: boxsend -->
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To send a Check with this tutorial, you need the following:
|
||||
@@ -23,10 +17,17 @@ 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](/resources/dev-tools/xrp-faucets) 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](../../../../concepts/transactions/secure-signing.md).
|
||||
- A [client library](../../../../references/client-libraries.md) or any HTTP or WebSocket library.
|
||||
- You should be familiar with the basics of using [xrpl.js](../../../javascript/build-apps/get-started.md).
|
||||
|
||||
## 1. Prepare the CheckCreate transaction
|
||||
## Source Code
|
||||
|
||||
The complete source code for this tutorial is available in the source repository for this website:
|
||||
|
||||
{% repo-link path="_code-samples/checks/js/" %}Checks sample code{% /repo-link %}
|
||||
|
||||
## Steps
|
||||
|
||||
### 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](../../../../references/protocol/transactions/common-fields.md#auto-fillable-fields) when signing:
|
||||
|
||||
@@ -37,157 +38,28 @@ Decide how much money the Check is for and who can cash it. Figure out the value
|
||||
| `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](../../../../concepts/tokens/transfer-fees.md), 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
|
||||
For example, imagine you were asked to pay a company named Grand Payments for some consulting work. By email, Grand Payments informs you that the maximum charge is 120 XRP, their XRP Ledger address is `rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis`, and this work has been billed with an invoice ID of `46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291` which they ask you to attach for their records. The following code shows how you could use a Check to send that payment:
|
||||
|
||||
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.
|
||||
{% code-snippet file="/_code-samples/checks/js/create-check.js" language="js" from="// Prepare the transaction" before="// Submit the transaction" /%}
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/prepareCreate.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="JSON-RPC, WebSocket, or Commandline" %}
|
||||
```json
|
||||
{
|
||||
"TransactionType": "CheckCreate",
|
||||
"Account": "rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za",
|
||||
"Destination": "rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis",
|
||||
"SendMax": "100000000",
|
||||
"InvoiceID": "46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291"
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 2. Sign the CheckCreate transaction
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-sign-step.md" /%}
|
||||
{% admonition type="success" name="Tip" %}The `InvoiceID` is optional metadata that can be attached to any Check (or Payment). This field is purely informational and is not used in transaction processing.{% /admonition %}
|
||||
|
||||
|
||||
### Example Request
|
||||
### 2. Submit the transaction
|
||||
|
||||
{% tabs %}
|
||||
Send the transaction and wait for it to be validated by the consensus process, as normal:
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/signCreate.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="WebSocket" %}
|
||||
{% code-snippet file="/_code-samples/checks/websocket/sign-create-req.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-create-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
#### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/sign-create-resp.txt" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="WebSocket" %}
|
||||
{% code-snippet file="/_code-samples/checks/websocket/sign-create-resp.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/sign-create-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
## 3. Submit the signed transaction
|
||||
|
||||
{% partial file="/docs/_snippets/tutorial-submit-step.md" /%}
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/submitCreate.js" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="WebSocket" %}
|
||||
{% code-snippet file="/_code-samples/checks/websocket/submit-create-req.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-create-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/submit-create-resp.txt" language="js" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="WebSocket" %}
|
||||
{% code-snippet file="/_code-samples/checks/websocket/submit-create-resp.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/submit-create-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
{% code-snippet file="/_code-samples/checks/js/create-check.js" language="js" from="// Submit the transaction" before="// Get transaction result" /%}
|
||||
|
||||
|
||||
## 4. Wait for validation
|
||||
### 3. Confirm transaction result
|
||||
|
||||
{% partial file="/docs/_snippets/wait-for-validation.md" /%}
|
||||
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.
|
||||
|
||||
{% admonition type="success" name="Tip" %}The `submitAndWait()` method in xrpl.js only returns when the transaction's result is final, so you can assume that the transaction is validated if it returns a result code of `tesSUCCESS`.{% /admonition %}
|
||||
|
||||
## 5. Confirm final result
|
||||
To cash or cancel the Check later, you'll need the Check ID. You can find this in the transaction's metadata by looking for a `CreatedNode` entry with a `LedgerEntryType` of `"Check"`. This indicates that the transaction created a [Check ledger entry](../../../../references/protocol/ledger-data/ledger-entry-types/check.md). The `LedgerIndex` of this object is the ID of the Check. This should be a [hash][] value such as `84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9`.
|
||||
|
||||
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](../../../../references/protocol/ledger-data/ledger-entry-types/check.md). The `LedgerIndex` of this object is the ID of the Check. In the following example, the Check's ID is `84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9`.
|
||||
|
||||
### Example Request
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/getCreateTx.js" language="" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="WebSocket" %}
|
||||
{% code-snippet file="/_code-samples/checks/websocket/tx-create-req.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-create-req.sh" language="bash" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
### Example Response
|
||||
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="ripple-lib 1.x" %}
|
||||
{% code-snippet file="/_code-samples/checks/js/get-create-tx-resp.txt" language="" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="WebSocket" %}
|
||||
{% code-snippet file="/_code-samples/checks/websocket/tx-create-resp.json" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Commandline" %}
|
||||
{% code-snippet file="/_code-samples/checks/cli/tx-create-resp.txt" language="json" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
At this point, it is up to the recipient to cash the Check.
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
|
||||
@@ -19,7 +19,7 @@ This example shows how to:
|
||||
|
||||
Checks offer another option for transferring funds between accounts. Checks have two particular advantages.
|
||||
|
||||
1. You can use a check to send funds to another account without first creating a trust line - the trust line is created automatically when the receiver chooses to accept the funds.
|
||||
1. You can use a check to send [tokens](../../../concepts/tokens/index.md) to someone who has not already created a trust line. The trust line is created automatically when the receiver chooses to accept the funds.
|
||||
2. 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.
|
||||
|
||||
|
||||
@@ -27,9 +27,11 @@ Checks offer another option for transferring funds between accounts. Checks have
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Clone or download the [Modular Tutorial Samples](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/quickstart/js/).
|
||||
Clone or download the {% repo-link path="_code-samples/quickstart/js/" %}Modular Tutorial Samples{% /repo-link %}.
|
||||
|
||||
{% admonition type="info" name="Note" %}Without the Quickstart Samples, you will not be able to try the examples that follow. {% /admonition %}
|
||||
{% admonition type="info" name="Note" %}
|
||||
Without the Modular Tutorial Samples, you will not be able to try the examples that follow.
|
||||
{% /admonition %}
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -73,7 +75,7 @@ To send a check for an issued currency token from the Standby account to the Ope
|
||||
|
||||
### Get Checks
|
||||
|
||||
Click **Get Checks** to get a list of the current checks you have sent or received. To uniquely identify a check (for existence, when cashing a check), capture the _index_ value for the check.
|
||||
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.
|
||||
|
||||
[](/docs/img/quickstart-checks5.png)
|
||||
|
||||
@@ -103,7 +105,7 @@ Click **Get Balances** to get a list of obligations and assets for each account.
|
||||
|
||||
To cancel a check you have previously sent to another account.
|
||||
|
||||
1. Enter the **Check ID** (**index** value).
|
||||
1. Enter the **Check ID** (`index` value).
|
||||
2. Click **Cancel Check**.
|
||||
|
||||
[](/docs/img/quickstart-checks8.png)
|
||||
@@ -111,7 +113,7 @@ To cancel a check you have previously sent to another account.
|
||||
|
||||
# Code Walkthrough
|
||||
|
||||
You can download the [Quickstart Samples](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/quickstart/js/) in the source repository for this website.
|
||||
You can download the {% repo-link path="_code-samples/quickstart/js/" %}Modular Tutorial Samples{% /repo-link %} in the source repository for this website.
|
||||
|
||||
## ripplex10-check.js
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ Checks are a straightforward, familiar, and flexible way to transfer funds when
|
||||
|
||||
While this method is the simplest, it doesn't guarantee the funds. Checks are deferred payments, meaning funds aren't moved until the moment you try to cash the check. It's possible for the sending account to not have the necessary funds at the time the check is cashed, which can cause delays or other headaches, depending on your business.
|
||||
|
||||
See: [Use Checks](../../tutorials/how-tos/use-specialized-payment-types/use-checks/use-checks.md).
|
||||
See: [Use Checks](../../tutorials/how-tos/use-specialized-payment-types/use-checks/index.md).
|
||||
|
||||
|
||||
### Escrow
|
||||
|
||||
Reference in New Issue
Block a user