From 2ff42696c40c737b8ca0ec3aeda25d22022845b3 Mon Sep 17 00:00:00 2001
From: Waldir Pimenta <waldir.pimenta@uphold.com>
Date: Thu, 24 Sep 2020 15:07:25 +0100
Subject: [PATCH] Document beneficiary information for transactions

---
 _transactions.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 170 insertions(+), 1 deletion(-)

diff --git a/_transactions.md b/_transactions.md
index 542d66a..32db52d 100644
--- a/_transactions.md
+++ b/_transactions.md
@@ -167,7 +167,7 @@ An optional parameter `message` can also be sent which will overwrite the value
 Once the transaction is committed, its status will change to `processing`.
 
 <aside class="notice">
-  This must be done within the time window specified (in miliseconds) by the <a href="#parameters"><code>params.ttl</code></a> field of the transaction object.
+  This must be done within the time window specified (in milliseconds) by the <a href="#parameters"><code>params.ttl</code></a> field of the transaction object.
   Attempting to commit a transaction past this timeframe results in a <a href="#errors">404 HTTP error</a>.
 </aside>
 <aside class="notice">
@@ -267,6 +267,175 @@ url        | The URL of the 3DSecure confirmation request.
 
 A webpage for 3DSecure confirmation for the user to interact with.
 
+## Beneficiary Information
+
+> Example of a transaction creation payload including `beneficiary` and `purpose` fields:
+
+```json
+{
+  "beneficiary": {
+    "relationship": "child",
+    "name": "Foo",
+    "address": {
+      "line1": "Bar",
+      "zipCode": "12345",
+      "city": "Braga",
+      "country": "PT",
+      "state": "PT-03"
+    }
+  },
+  "purpose": "donations",
+  "denomination": {
+    "amount": "3000",
+    "currency": "USD"
+  },
+  "destination": "invite-user@gmail.com"
+}
+```
+
+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 a withdrawal to either 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).
+
+The beneficiary information should be provided in the `beneficiary` object of the request payload.
+The `beneficiary.relationship` field must always be filled in in these cases.
+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 can be any descriptive string that accurately reflects the beneficiary's relationship to the transaction originator.
+Two particular types of transactions are recognized by the platform:
+business transactions (indicated by a the value `business`)
+and personal transactions (indicated by the values `child`, `co_worker`, `friend`, `parent`, or `sibling`).
+The special 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 correctness of beneficiary information) before attempting to commit 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.
+</aside>
+
+> Example of a transaction that will generate a validation error for missing beneficiary information:
+
+```bash
+curl 'https://api-sandbox.uphold.com/v0/me/cards/<card-id>/transactions?validate=true' \
+  -H 'authorization: Bearer <bearer-token>' \
+  -H 'content-type: application/json' \
+  -d '{ "beneficiary": {}, "denomination": { "amount": "3000", "currency": "USD" }, "destination": "invite-user@gmail.com" }'
+```
+
+> The above request would result in the following validation error:
+
+```json
+{
+  "code": "validation_failed",
+  "errors": {
+    "beneficiary": {
+      "code": "validation_failed",
+      "errors": {
+        "relationship": [
+          {
+            "code": "required",
+            "message": "This value is required"
+          }
+        ],
+        "address": [
+          {
+            "code": "required",
+            "message": "This value is required"
+          }
+        ],
+        "name": [
+          {
+            "code": "required",
+            "message": "This value is required"
+          }
+        ]
+      }
+    },
+    "purpose": [
+      {
+        "code": "required",
+        "message": "This value is required"
+      }
+    ]
+  }
+}
+```
+
+> Example of including the beneficiary information when creating an uncommitted transaction (i.e. quote), alongside the remaining transaction data:
+
+```bash
+curl 'https://api-sandbox.uphold.com/v0/me/cards/<card-id>/transactions' \
+  -H 'authorization: Bearer <bearer-token>' \
+  -H 'content-type: application/json' \
+  -d '{ "beneficiary": { "relationship": "child", "name": "Foo", "address": { "line1": "Bar", "zipCode": "12345", "city": "Braga", "country": "PT", "state": "PT-03" } }, "purpose": "donations", "denomination": { "amount": "3000", "currency": "USD" }, "destination": "invite-user@gmail.com" }'
+```
+
+> Example of adding the beneficiary information when committing a previously created transaction:
+
+```bash
+curl 'https://api-sandbox.uphold.com/v0/me/cards/<card-id>/transactions/<transaction-id>/commit' \
+  -H 'authorization: Bearer <bearer-token>' \
+  -H 'content-type: application/json' \
+  -d '{ "beneficiary": { "relationship": "child", "name": "Foo", "address": { "line1": "Bar", "zipCode": "12345", "city": "Braga", "country": "PT", "state": "PT-03" } }, "purpose": "donations" }'
+```
+
+> In both cases, incomplete beneficiary information will be reported in a format similar to this:
+
+```json
+{
+  "code": "validation_failed",
+  "errors": {
+    "beneficiary": {
+      "code": "validation_failed",
+      "errors": {
+        "name": [
+          {
+            "code": "required",
+            "message": "This value is required"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+> Invalid beneficiary information will be reported like this:
+
+```json
+{
+  "code": "validation_failed",
+  "errors": {
+    "beneficiary": {
+      "code": "validation_failed",
+      "errors": {
+        "name": [
+          {
+            "code": "invalid_beneficiary",
+            "message": "The provided beneficiary is invalid"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+The beneficiary information can be passed either when creating an uncommitted transaction (i.e. a quote)
+or when [committing it](#step-2-commit-transaction).
+
 ## Cancel a Transaction
 
 ```bash