From b5d84a975313bbbb76c16249620f7050ad7a7060 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 22 Jan 2016 16:52:25 -0800 Subject: [PATCH] gateway guide - clarification on partial payments in RippleAPI --- content/gateway_guide.md | 6 +++--- gateway_guide.html | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/gateway_guide.md b/content/gateway_guide.md index cb871dafc4..32d6212ace 100644 --- a/content/gateway_guide.md +++ b/content/gateway_guide.md @@ -368,7 +368,7 @@ Enable the [RequireDest](#requiredest) flag on your hot and cold wallet accounts ## DisallowXRP ## -The DisallowXRP flag is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around. +The DisallowXRP setting (`disallowIncomingXRP` in RippleAPI) is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around. An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP. @@ -724,8 +724,8 @@ The first requirement to bouncing payments is [robustly monitoring for incoming Second, you should send bounced payments as Partial Payments. Since other Ripple users can manipulate the cost of pathways between your accounts, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from an automated hot wallet or a human-operated warm wallet. -* To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](transactions.html#payment-flags) on the transaction. -* To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](rippleapi.html#payment) to `true`. +* To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](transactions.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field. +* To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](rippleapi.html#payment) to `true`. Set the `source.maxAmount` and `destination.amount` both equal to the amount you received. It is conventional that you take the `SourceTag` field from the incoming payment (`source.tag` in RippleAPI) and use that value as the `DestinationTag` field (`destination.tag` in RippleAPI) for the return payment. diff --git a/gateway_guide.html b/gateway_guide.html index 9f53c43f9f..e8074dee80 100644 --- a/gateway_guide.html +++ b/gateway_guide.html @@ -403,7 +403,7 @@

We recommend making a user interface to generate a destination tag on-demand when a user intends to send money to the gateway. Then, consider that destination tag valid only for a payment with the expected amount. Later, bounce any other transactions that reuse the same destination tag.

Enable the RequireDest flag on your hot and cold wallet accounts so that users must use a destination tag to indicate where funds should go when they send Ripple payments to your gateway.

DisallowXRP

-

The DisallowXRP flag is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around.

+

The DisallowXRP setting (disallowIncomingXRP in RippleAPI) is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around.

An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.

The following is an example of using a locally-hosted rippled's submit command to send an AccountSet transaction to enable the DisallowXRP flag:

Request:

@@ -687,8 +687,8 @@ Content-Type: application/json

The first requirement to bouncing payments is robustly monitoring for incoming payments. You do not want to accidentally refund a user for more than they sent you! (This is particularly important if your bounce process is automated.) The Partial Payment Flag Gateway Bulletin explains how to avoid a common problem.

Second, you should send bounced payments as Partial Payments. Since other Ripple users can manipulate the cost of pathways between your accounts, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from an automated hot wallet or a human-operated warm wallet.

It is conventional that you take the SourceTag field from the incoming payment (source.tag in RippleAPI) and use that value as the DestinationTag field (destination.tag in RippleAPI) for the return payment.

To prevent two systems from bouncing payments back and forth indefinitely, you can set a new Source Tag for the outgoing return payment. If you receive an unexpected payment whose Destination Tag matches the Source Tag of a return you sent, then do not bounce it back again.