Payments article, payment types in ref

content/concepts/payment-system-basics/payments.md

@@ -0,0 +1,40 @@
+# Payments
+
+The basis of any financial system is _transferring value_: or, in one word, payments. The XRP Ledger supports a variety of ways to make payments, with different types specialized for various use cases. The most basic type of payment in the XRP Ledger is a direct XRP-to-XRP payment.
+
+## About Direct XRP-to-XRP Payments
+
+Generally, any address in the XRP Ledger can send XRP directly to any other address. The address on the receiving side is often called the _destination address_, and the address on the sending side is called the _source address_. To send XRP directly, the sender uses a [Payment transaction][], which can be as concise as the following:
+
+```json
+{
+  "TransactionType": "Payment",
+  "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
+  "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
+  "Amount": "13000000"
+}
+```
+
+These transaction instructions mean: Send a payment from rf1Bi... to ra5nK... delivering exactly 13 XRP. If the transaction is successfully processed, it does exactly that. Since it usually takes about 4 seconds for each new ledger version to become [validated](consensus.html), a successful transaction can be created, submitted, executed, and have a completely final outcome in 8 seconds or less, even if gets queued for the ledger version after the current in-progress one.
+
+**Caution:** The [Payment transaction type][Payment] can also be used for some more specialized kinds of payments, including [cross-currency payments](cross-currency-payments.html) and [partial payments](partial-payments.html). In the case of partial payments, it is possible that the `Amount` shows a large amount of XRP even if the transaction only delivered a very small amount. See [partial payments exploit](partial-payments.html#partial-payments-exploit) for how to avoid crediting a customer for the wrong amount.
+
+## Funding Accounts
+
+Any mathematically-valid address can receive a payment, even if the XRP Ledger has no record of that address existing beforehand, as long as the payment delivers enough XRP to meet the minimum [account reserve](reserves.html). If the payment would not deliver enough XRP, it fails.
+
+For more information, see [Accounts](accounts.html#creating-accounts).
+
+## Blocking Incoming Payments
+
+By default, any address can send XRP to any other address. This works well for many smart contracts and for making most transactions as smooth as possible. However, you may not want to be able to receive from unknown senders because of regulatory requirements. For example, you or your business might be required to prove that you do not receive money from economically-sanctioned countries, terrorists, or known criminals. In this case, you can enable the [DepositAuth setting](depositauth.html) to block incoming payments unless you approve the sender or individual payment before receiving funds (XRP or otherwise). For more information, see [DepositAuth](depositauth.html).
+
+The [`DisallowXRP` setting](accountset.html#blocking-incoming-transactions) is a related, softer limitation which is not natively enforced in the XRP Ledger. (Doing so strictly could cause an account to become "locked" if it ran out of XRP to pay for [transaction costs](transaction-cost.html).) Instead, client applications should enforce this setting (unless explicitly overridden with user intervention) to reduce cases of accidentally sending XRP to an address that primarily deals in [issued currencies](issued-currencies.html).
+
+## Source and Destination Tags
+
+***TODO: split off from gateway guide***
+
+## See Also
+
+***TODO***

content/references/rippled-api/transaction-formats/transaction-types/payment.md

@@ -1,7 +1,7 @@
 # Payment
 [[Source]<br>](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp "Source")
 
-A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.)
+A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.) This transaction type can be used for several [types of payments](#types-of-payments).
 
 Payments are also the only way to [create accounts](#creating-accounts).
 
@@ -37,6 +37,24 @@ Payments are also the only way to [create accounts](#creating-accounts).
 | SendMax        | [Currency Amount][]  | Amount            | _(Optional)_ Highest amount of source currency this transaction is allowed to cost, including [transfer fees](transfer-fees.html), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](transaction-cost.html). For non-XRP amounts, the nested field names MUST be lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. |
 | DeliverMin     | [Currency Amount][]  | Amount            | _(Optional)_ Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](partial-payments.html). For non-XRP amounts, the nested field names are lower-case. |
 
+## Types of Payments
+
+The Payment transaction type is a general-purpose tool that can represent several different types of abstract actions. You can identify the transaction type based on the transaction's fields, as described in the table below:
+
+| Payment type                              | `Amount`                        | `SendMax`                       | `Paths`          | `Address` = `Destination`? | Description |
+|:------------------------------------------|:--------------------------------|:--------------------------------|:-----------------|:--|
+| [Direct XRP-to-XRP Payment][]             | String (XRP)                    | Omitted                         | Omitted          | No | Transfers XRP directly from one account to another. Always delivers the exact amount. No fee applies other than the basic [transaction cost](transaction-cost.html). |
+| [Creating or redeeming issued currency][] | Object                          | Object (optional)               | Optional         | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](transfer-fees.html) and [freezes](freezes.html) do not apply when sending and redeeming directly. |
+| [Cross-currency Payment][]                | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send issued currency from one holder to another. The `Amount` and `SendMax` cannot _both_ be XRP. These payments [ripple through](rippling.html) the issuer and can take longer [paths](paths.html) through several intermediaries if the transaction specifies a path set. [Transfer fees](transfer-fees.html) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](decentralized-exchange.html) to connect between different currencies, or possibly even between currencies with the same currency code and different issuers. |
+| [Partial payments][]                      | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [tfPartialPayment flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. |
+| Currency conversion                       | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required         | Yes | Consumes offers in the [decentralized exchange](decentralized-exchange.html) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. The [Data API](data-api.html) tracks this type of transaction as an "exchange" and not a "payment". |
+
+[Direct XRP-to-XRP Payment]: payments.html
+[Creating or redeeming issued currency]: issued-currencies-overview.html
+[Cross-currency Payment]: cross-currency-payments.html
+[Partial payments]: partial-payments.html
+
+
 ## Special issuer Values for SendMax and Amount
 
 Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates a financial institution's [issuing address](issuing-and-operational-addresses.html). However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment.