wip

_transactions.md

@@ -293,43 +293,50 @@ A webpage for 3DSecure confirmation for the user to interact with.
 }
 ```
 
-When creating a transaction, it may be required to send additional information
-regarding the beneficiary and purpose of the transaction.
+When creating a transaction, it may be required to send additional information regarding the beneficiary and purpose of the transaction.
 This is required if **both** the following conditions are met:
 
-- The transaction is either a withdrawal to an external account (crypto networks, SEPA bank accounts, etc.) or a transfer to another user; and
-- The transaction amount is over _$3000 USD_ (or over $1000 USD, if the origin user is from Arizona, United States).
+- The transaction is either a withdrawal to an external account (crypto networks, SEPA bank accounts, etc.) or a transfer to another user (invites included);
+- The transaction amount is over _$3000 USD_ (or over _$1000 USD_, if the origin user is from Arizona, United States).
+
+To obtain the transaction beneficiary requirements (or validate the `beneficiary` object) use the `?validate=true` query parameter when creating the quote. This will generate a validation error if any required beneficiary information is missing. Otherwise, the transaction will fail at the commit step with a similar error message.
+
+Parameter | Description
+--------- | -----------
+beneficiary | The transaction beneficiary information. See [Beneficiary](#beneficiary).
+purpose | The reason for the transaction (only for transactions which relationship is not set to myself).
+
+### Beneficiary
+
+This beneficiary field has the following properties:
+
+Parameter | Description
+--------- | -----------
+address | The transaction beneficiary address information. See [Address](#address).
+name | The beneficiary full name.
+relationship | Reflects the beneficiary's relationship to the transaction originator. Possible values are `business`, `child`, `co_worker`, `friend`, `myself`, `parent`, `sibling`. It must always be filled whenever beneficiary information is required.
+The other parameters can be omitted if Uphold is already in possession of the data.
+(e.g. if the transaction is to an existing Uphold user, or the `relationship` is set to "myself").
+
+### Address
+
+Property | Required | Description
+-------- |--------- | -----------
+city | yes | The city.
+country | yes | The country.
+line1 | yes | The primary address information.
+line2 | no | The additional information if necessary.
+state | yes | The state or province
+zipCode | yes | The postal/zip code
 
 <aside class="notice">
   The threshold value is calculated from the <a href="#normalized">normalized</a> USD amount of the transaction,
   which can differ from the amount specified in the <code>denomination.amount</code> field
   if the transaction implies a currency conversion.
 </aside>
 <aside class="notice">
-  Note: ACH withdrawals are <b>not required</b> to send beneficiary information,
-  since we only support personal bank accounts, so the beneficiary (ACH account holder)
-  is assumed to be the Uphold user who added that account.
+  Note: ACH withdrawals do <b>not require</b> the beneficiary information to be sent. We only support personal bank accounts therefore the beneficiary (ACH account holder) is assumed to be the Uphold user who added that account.
 </aside>
-
-The beneficiary information should be provided in the `beneficiary` object of the request payload.
-The `beneficiary.relationship` field must always be filled whenever beneficiary information is required.
-The other fields can be omitted if the data is already present in the Uphold platform
-(e.g. if the transaction is to an existing Uphold user, or the `beneficiary.relationship` is set to "myself").
-
-The `relationship` field is a string reflecting the beneficiary's relationship to the transaction originator.
-Two particular types of transactions are recognized by the platform:
-business transactions (indicated by a `relationship` field with the value `business`)
-and personal transactions (indicated by the values `child`, `co_worker`, `friend`, `parent`, or `sibling`).
-The value `myself` can also be used when applicable.
-
-Depending on the conditions of the transaction, additional fields may be required — namely, the beneficiary `name` and `address` (with subfields `city`, `country`, `line1`, `line2`, `state`, `zipCode`),
-as well as a `purpose` object indicating the reason for the transaction.
-
-To obtain the beneficiary requirements (or validate the `beneficiary` object) when preparing a transaction,
-use the `?validate=true` parameter in the query string of the request to create a transaction.
-This will generate a validation error if any required beneficiary information is missing.
-Otherwise, the transaction will fail at the commit step with a similar error message.
-
 <aside class="notice">
   Please note that at this moment, even with the <code>validate=true</code> parameter,
   the validation is only performed if a <code>beneficiary</code> object is passed.