Add order and checkout order endpoint documentation

src/StoreApi/README.md

@@ -66,7 +66,9 @@ Available resources in the Store API are listed below, with links to more detail
 |                                                              | `GET`, `POST`, `PUT`, `DELETE` | [`/wc/store/v1/cart/items/:key`](docs/cart-items.md#single-cart-item)                         |
 | [`Cart Coupons`](docs/cart-coupons.md)                       | `GET`, `POST`, `DELETE`        | [`/wc/store/v1/cart/coupons`](docs/cart-coupons.md#list-cart-coupons)                         |
 |                                                              | `GET`, `DELETE`                | [`/wc/store/v1/cart/coupon/:code`](docs/cart-coupons.md#single-cart-coupon)                   |
-| [`Checkout`](docs/checkout.md)                               | `GET`, `POST`                  | [`/wc/store/v1/checkout`](docs/checkout.md)                                                   |
+| [`Checkout`](docs/checkout.md)                               | `GET`, `POST`                  | [`/wc/store/v1/checkout`](docs/checkout.md)     
+| [`Checkout order`](docs/checkout-order.md)                   | `POST`                         | [`/wc/store/v1/checkout/:id`](docs/checkout-order.md)                                             |
+| [`Order`](docs/order.md)                                     | `GET`                          | [`/wc/store/v1/order/:id`](docs/order.md)  
 | [`Products`](docs/products.md)                               | `GET`                          | [`/wc/store/v1/products`](docs/products.md#list-products)                                     |
 |                                                              | `GET`                          | [`/wc/store/v1/products/:id`](docs/products.md#single-product)                                |
 | [`Product Collection Data`](docs/product-collection-data.md) | `GET`                          | [`/wc/store/v1/products/collection-data`](docs/product-collection-data.md)                    |

src/StoreApi/docs/cart.md

@@ -2,10 +2,11 @@
 
 ## Table of Contents <!-- omit in toc -->
 
+
+-   [Get Cart](#get-cart)
 -   [Responses](#responses)
     -   [Cart Response](#cart-response)
     -   [Error Response](#error-response)
--   [Get Cart](#get-cart)
 -   [Add Item](#add-item)
 -   [Remove Item](#remove-item)
 -   [Update Item](#update-item)
@@ -18,6 +19,21 @@ The cart API returns the current state of the cart for the current session or lo
 
 All POST endpoints require [Nonce Tokens](nonce-tokens.md) and return the updated state of the full cart once complete.
 
+
+## Get Cart
+
+```http
+GET /cart
+```
+
+There are no parameters required for this endpoint.
+
+```sh
+curl "https://example-store.com/wp-json/wc/store/v1/cart"
+```
+
+Returns the full cart object response (see [Cart Response](#cart-response)).
+
 ## Responses
 
 All endpoints under `/cart` (listed in this doc) return responses in the same format; a cart object which includes cart items, applied coupons, shipping addresses and rates, and non-sensitive customer data.
@@ -378,20 +394,6 @@ Some error responses indicate conflicts (error 409), for example, when an item c
 
 This allows the client to remain in sync with the cart data without additional requests, should the cart change or become outdated.
 
-## Get Cart
-
-```http
-GET /cart
-```
-
-There are no parameters required for this endpoint.
-
-```sh
-curl "https://example-store.com/wp-json/wc/store/v1/cart"
-```
-
-Returns the full cart object response (see [Cart Response](#cart-response)).
-
 ## Add Item
 
 Add an item to the cart and return the full cart response, or an error.

src/StoreApi/docs/checkout-order.md

@@ -0,0 +1,167 @@
+# Checkout order API <!-- omit in toc -->
+
+## Table of Contents <!-- omit in toc -->
+
+-   [Process Order and Payment](#process-order-and-payment)
+-   [Payment Data](#payment-data)
+
+The checkout order API facilitates the processing of existing orders and handling payments.
+
+All checkout order endpoints require [Nonce Tokens](nonce-tokens.md).
+
+## Process Order and Payment
+
+Accepts the final chosen payment method, and any additional payment data, then attempts payment and
+returns the result.
+
+This endpoint will return an error unless a valid [Nonce Token](nonce-tokens.md) is provided.
+
+```http
+POST /wc/store/v1/checkout/{ORDER_ID}
+```
+
+| Attribute          | Type   | Required | Description                                                         |
+| :----------------- | :----- | :------: | :------------------------------------------------------------------ |
+| `key`              | string |   Yes    | The key for the order verification.                                 |
+| `billing_email`    | string |   No     | The email address used to verify guest orders.                      |
+| `billing_address`  | object |   Yes    | Object of updated billing address data for the customer.            |
+| `shipping_address` | object |   Yes    | Object of updated shipping address data for the customer.           |
+| `payment_method`   | string |   Yes    | The ID of the payment method being used to process the payment.     |
+| `payment_data`     | array  |    No    | Data to pass through to the payment method when processing payment. |
+
+```sh
+curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/checkout/{ORDER_ID} -d '{"key":"wc_order_oFmQYREzh9Tfv","billing_email":"[email protected]","payment_method":"cheque","billing_address":{...},"shipping_address":{...}'
+```
+
+**Example request:**
+
+```json
+{
+	"key": "wc_order_oFmQYREzh9Tfv",
+	"billing_email": "[email protected]",
+	"billing_address": {
+		"first_name": "Peter",
+		"last_name": "Venkman",
+		"company": "",
+		"address_1": "550 Central Park West",
+		"address_2": "Corner Penthouse Spook Central",
+		"city": "New York",
+		"state": "NY",
+		"postcode": "10023",
+		"country": "US",
+		"email": "[email protected]",
+		"phone": "555-2368"
+	},
+	"shipping_address": {
+		"first_name": "Peter",
+		"last_name": "Venkman",
+		"company": "",
+		"address_1": "550 Central Park West",
+		"address_2": "Corner Penthouse Spook Central",
+		"city": "New York",
+		"state": "NY",
+		"postcode": "10023",
+		"country": "US",
+		"phone": "555-2368"
+	},
+	"payment_method": "cheque",
+	"payment_data": []
+}
+```
+
+**Example response:**
+
+```json
+{
+	"order_id": 146,
+	"status": "on-hold",
+	"order_key": "wc_order_oFmQYREzh9Tfv",
+	"customer_note": "",
+	"customer_id": 1,
+	"billing_address": {
+		"first_name": "Peter",
+		"last_name": "Venkman",
+		"company": "",
+		"address_1": "550 Central Park West",
+		"address_2": "Corner Penthouse Spook Central",
+		"city": "New York",
+		"state": "NY",
+		"postcode": "10023",
+		"country": "US",
+		"email": "[email protected]",
+		"phone": "555-2368"
+	},
+	"shipping_address": {
+		"first_name": "Peter",
+		"last_name": "Venkman",
+		"company": "",
+		"address_1": "550 Central Park West",
+		"address_2": "Corner Penthouse Spook Central",
+		"city": "New York",
+		"state": "NY",
+		"postcode": "10023",
+		"country": "US",
+		"phone": "555-2368"
+	},
+	"payment_method": "cheque",
+	"payment_result": {
+		"payment_status": "success",
+		"payment_details": [],
+		"redirect_url": "https://local.wordpress.test/block-checkout/order-received/146/?key=wc_order_VPffqyvgWVqWL"
+	}
+}
+```
+
+## Payment Data
+
+There are many payment gateways available for merchants to use, and each one will be expecting different `payment_data`. We cannot comprehensively list all expected requests for all payment gateways, and we would recommend reaching out to the authors of the payment gateway plugins you're working with for further information.
+
+An example of the payment data sent to the Checkout Order endpoint when using the [WooCommerce Stripe Payment Gateway](https://wordpress.org/plugins/woocommerce-gateway-stripe/) is shown below.
+
+For further information on generating a `stripe_source` please check [the Stripe documentation](https://stripe.com/docs).
+
+```json
+{
+	"payment_data": [
+		{
+			"key": "stripe_source",
+			"value": "src_xxxxxxxxxxxxx"
+		},
+		{
+			"key": "billing_email",
+			"value": "[email protected]"
+		},
+		{
+			"key": "billing_first_name",
+			"value": "Jane"
+		},
+		{
+			"key": "billing_last_name",
+			"value": "Doe"
+		},
+		{
+			"key": "paymentMethod",
+			"value": "stripe"
+		},
+		{
+			"key": "paymentRequestType",
+			"value": "cc"
+		},
+		{
+			"key": "wc-stripe-new-payment-method",
+			"value": true
+		}
+	]
+}
+```
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./src/StoreApi/docs/checkout-order.md)
+
+<!-- /FEEDBACK -->
+