diff --git a/docs/financial/PaymentAPI.md b/docs/financial/PaymentAPI.md
index 38eb41ea80b0bee8381ace02aacf36e327aa3c98..fe86e57e1009405502a4a36d60d736c2db1c6ead 100644
--- a/docs/financial/PaymentAPI.md
+++ b/docs/financial/PaymentAPI.md
@@ -11,10 +11,10 @@ It is now best practice to use the Payment.create API call.
 
 Note that paymentprocessor.pay handles the communication with a payment processor to instigate a payment. Similarly, paymentprocessor.refund handles the communication with a payment processor to instigate a refund.
 
-After a contribution has been created, for example using the best practice Order.create api call, use the Payment API to:
+After a contribution has been created, for example using the best practice Order.create API call, use the Payment.create API action to
 
-- record a full payment
-- record a partial payment or subsequent payment
-- record that a payment was cancelled (not the same as cancelling the whole contribution)
-- record the refund of a payment
+* record a payment against the contribution - either fully or partially paying the contribution amount
+* record a refund against the contribution
+
+Use the Payment.cancel api to reverse a refunded payment.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index b02ea360eb881eaf0926f215d63fae498ed4211c..b4df2b11e843bd77119f79c52bf304b1f30a88c3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -32,7 +32,8 @@ pages:
   - Release Process: core/release-process.md
 - Financial:
   - Overview: financial/overview.md
-  - OrderAPI: financial/OrderAPI.md
+  - Order API: financial/OrderAPI.md
+  - Payments API: financial/PaymentAPI.md
 - Extensions:
   - Basics: extensions/index.md
   - Packaging Options: extensions/packaging.md