PP-12141: Improve API request examples (#952)

* Improves some API examples * Minor fixes * Changes from @charleemg review * Update source/optional_features/welsh_language/index.html.md.erb Co-authored-by: ChristinaKyriakou <[email protected]> * Changes based on @ChristinaKyriakou review * Removes needless parameter from an example --------- Co-authored-by: ChristinaKyriakou <[email protected]>
alphagov · Feb 21, 2024 · 6af0d3f · 6af0d3f
1 parent 39f8d5f
commit 6af0d3f
Show file tree

Hide file tree

Showing 6 changed files with 95 additions and 66 deletions.
diff --git a/source/delayed_capture/index.html.md.erb b/source/delayed_capture/index.html.md.erb
@@ -18,27 +18,36 @@ You cannot use delayed capture for:
 * payments made with [payment links](https://www.payments.service.gov.uk/govuk-payment-pages/)
 * [recurring payments](/recurring_payments)
 
-To use this feature, include `"delayed_capture": true` in the body of a [Create new payment](/making_payments/#creating-a-payment) request.
+To use this feature, include `"delayed_capture": true` in the body of your [request to create a new payment](/making_payments/#creating-a-payment).
 
-The user experience matches the current payment flow. Once your user selects
-__Confirm__ on the __Confirm your details__ page:
+This example request creates a £50 parking fine that the service can capture at a later point because it includes the `delayed_capture` parameter:
 
-- the [payment status](/api_reference/#payment-status-lifecycle) will change to `capturable`
-- your service can make a request to the
-`POST /v1/payments/{PAYMENT_ID}/capture` endpoint to send a delayed capture
-request
+`POST /v1/payments`
 
-Your service must send the delayed capture request within 120 hours (5 days) of creating the payment, regardless of how long your user takes to complete the payment flow. If you do not, [the payment will expire](/payment_flow/#6-your-user-confirms-payment).
+```json
+{
+  "amount": 5000,
+  "reference" : "LE2504",
+  "description": "Pay a penalty charge notice (PCN)",
+  "return_url": "https://your.service.gov.uk/completed",
+  "delayed_capture": true
+}
+```
+
+Your paying user will follow the standard payment flow. After your user selects __Confirm__ on the __Confirm your details__ page:
+
+- the [payment's status](/api_reference/#payment-status-lifecycle) will change to `capturable`
+- you can make a request to the `POST /v1/payments/{PAYMENT_ID}/capture` endpoint when you want to capture the delayed
 
-If you've turned on payment confirmation emails, GOV.UK Pay will send a
-payment confirmation email to your user once we've received and processed your service’s capture request.
+You must send the delayed capture request within 120 hours (5 days) of creating the payment, regardless of when your user completes the payment flow. If you do not, [the payment will expire](/payment_flow/#6-your-user-confirms-payment).
+
+If you've turned on payment confirmation emails, GOV.UK Pay will send a payment confirmation email to your user. We'll send this email once we've received and processed your service’s capture request.
 
 You can see definitions and possible values of every parameter and attribute for this endpoint in our [API reference](/api_reference/capture_payment_reference). You can also view [possible responses to your capture request](/api_reference/#responses).
 
 ## See the capture URL for a payment
 
-If a payment is available for capture, you can see its capture URL in
-responses to API requests. For example:
+If a payment is available for capture, you can see its capture URL in responses to API requests. For example:
 
 * `GET /v1/payments`
 * `GET /v1/payments/{PAYMENT_ID}`
@@ -47,9 +56,9 @@ Replace ``{PAYMENT_ID}`` with the ID of the payment you want to see the capture
 
 The `_links` object will contain:
 
-```
+```json
 "capture": {
-"href": "https://publicapi.payments.service.gov.uk/v1/payments/{PAYMENT_ID}/capture",
+    "href": "https://publicapi.payments.service.gov.uk/v1/payments/{PAYMENT_ID}/capture",
     "method": "POST"
     }
 ```

diff --git a/source/making_payments/index.html.md.erb b/source/making_payments/index.html.md.erb
@@ -34,38 +34,20 @@ You must send the following parameters in your request body when creating a paym
 
 This example request creates a £145 council tax payment:
 
-```javascript
+```json
 {
   "amount": 14500,
   "reference" : "12345",
   "description": "Pay your council tax",
-  "return_url": "https://your.service.gov.uk/completed",
-  "delayed_capture": false,
-  "metadata": {
-    "ledger_code": "AB100",
-    "an_internal_reference_number": 200
-  },
-  "email": "[email protected]",
-  "prefilled_cardholder_details": {
-    "cardholder_name": "Sherlock Holmes",
-    "billing_address": {
-        "line1": "221 Baker Street",
-        "line2": "Flat b",
-        "postcode": "NW1 6XE",
-        "city": "London",
-        "country": "GB"
-    }
-  },
-  "language": "en",
-  ...
+  "return_url": "https://your.service.gov.uk/completed"
 }
 ```
 
 Depending on your integration, you can also:
 
 * [delay taking a payment](/delayed_capture)
 * [prefill some of the fields on the user's payment page](/optional_features/prefill_user_details/)
-* [add custom metadata to a payment](/reporting/#add-additional-information-your-users-will-not-be-able-to-see-39-custom-metadata-39-or-39-reporting-columns-39)
+* [add custom metadata to a payment](/reporting/#add-more-information-to-a-payment-39-custom-metadata-39-or-39-reporting-columns-39)
 * [use Welsh on your payment pages](/optional_features/welsh_language/)
 * [take the payment over the phone](/moto_payments)
 

diff --git a/source/optional_features/prefill_user_details/index.html.md.erb b/source/optional_features/prefill_user_details/index.html.md.erb
@@ -16,37 +16,43 @@ To prefill fields, include the following optional parameters in the API request
 - `email`
 - `prefilled_cardholder_details` - with optional `cardholder_name` and `billing_address` parameters
 
-For example:
-
-```javascript
-"email": "[email protected]",
-"prefilled_cardholder_details": {
-  "cardholder_name": "Sherlock Holmes",
-  "billing_address": {
+This example request creates a £100 fine and prefills the user's email address, billing address, and the cardholder name:
+
+```json
+{
+  "amount": 10000,
+  "reference" : "54321",
+  "description": "Pay a fine you've been issued.",
+  "return_url": "https://your.service.gov.uk/completed",
+  "email": "[email protected]",
+  "prefilled_cardholder_details": {
+    "cardholder_name": "Sherlock Holmes",
+    "billing_address": {
       "line1": "221 Baker Street",
       "line2": "Flat b",
       "postcode": "NW1 6XE",
       "city": "London",
       "country": "GB"
+    }
   }
 }
 ```
 
-All the parameters in `billing_address` are optional, and these parameters' values must be no longer than:
+All the parameters in `billing_address` are optional and must have values no longer than:
 
 - 254 characters for `email`
 - 255 characters for `cardholder_name`
 - 255 characters each for `line1`, `line2` and `city` in `billing_address`
 - 25 characters for `postcode` in `billing_address`
 
-If you include the `country` parameter, it must be an <a href="https://www.iso.org/obp/ui/#search/code/" target="_blank">ISO 3166-1 alpha-2 code</a>. If the parameter is invalid or missing, the __Country or territory__ field on the payment page will default to 'United Kingdom'.
+The `country` parameter must be an <a href="https://www.iso.org/obp/ui/#search/code/" target="_blank">ISO 3166-1 alpha-2 code</a>. If you do not include `country` or send an invalid value, the __Country or territory__ field on the payment page will default to 'United Kingdom'.
 
 ## Data collected by your GOV.UK Pay admin account
 
 After your user completes their payment, your GOV.UK Pay account will collect your user's:
 
 - email address - even if you've turned off user email address collection
 - cardholder name
-- billing address - you can only see this by [using the API to get information about a payment](/reporting/#get-information-about-a-single-payment)
+- billing address - you can only see this by [using the API to get information about a payment](/api_reference/single_payment_reference)
 
 If your user does not complete their payment, your GOV.UK Pay account will still collect the `billing_address` value. This will happen even if you've chosen not to collect your users' billing addresses.
diff --git a/source/optional_features/welsh_language/index.html.md.erb b/source/optional_features/welsh_language/index.html.md.erb
@@ -7,23 +7,46 @@ weight: 5220
 
 # Use Welsh on your payment pages
 
-GOV.UK Pay supports Welsh-language payment pages.
+GOV.UK Pay supports Welsh language payment pages.
 
 You can also [create payment links in Welsh](https://www.payments.service.gov.uk/govuk-payment-pages/).
 
-To use Welsh, include `"language": "cy"` in the API request when you [create a new payment](/making_payments/#creating-a-payment). Your users will see Welsh text on the payment pages as they complete the [payment flow](/payment_flow).  If you do not specify a language,
-GOV.UK Pay will default to using English-language payment pages.
+To use Welsh, include `"language": "cy"` in the API request when you [create a new payment](/making_payments/#creating-a-payment).
 
-To add a Welsh service name to your service, sign in to the [GOV.UK Pay admin tool](https://selfservice.payments.service.gov.uk/login) and select **Edit name**.
+This example request creates a £50 fine that will use Welsh language payment pages:
 
-If you add a Welsh service name to your service, your users will see this on Welsh-language
-payment pages instead of the English service name.
+`POST /v1/payments`
 
-When your user makes a payment, they will also see a
-[`description`](/payment_flow/#4-your-user-enters-their-payment-details). If you use Welsh-language
-payment pages, you may also want to use Welsh text in the
-`description`.
+```json
+{
+  "amount": 5000,
+  "reference" : "WA5678",
+  "description": "Talu dirwy.",
+  "return_url": "https://your.service.gov.uk/completed",
+  "language": "cy"
+}
+```
 
-GOV.UK Pay does not automatically translate emails into Welsh. If you want to send your own emails in Welsh, stop GOV.UK Pay sending emails by [selecting an account in the GOV.UK Pay admin tool](https://selfservice.payments.service.gov.uk/my-services) and selecting **Settings**.
+If you do not include the `language` parameter in your request, GOV.UK Pay defaults to English language payment pages.
+
+Your users see a [description of the payment](/payment_flow/#4-your-user-enters-their-payment-details) when they pay. If you use Welsh language payment pages, you may also want to use Welsh text in the `description`.
+
+GOV.UK Pay does not automatically translate emails into Welsh. If you want to send your own emails in Welsh, stop GOV.UK Pay sending emails:
+
+1. Sign in to [the GOV.UK Pay admin tool](https://selfservice.payments.service.gov.uk/my-services).
+1. Select your service from the **Overview** page.
+1. Select **Settings**.
+1. Change **Payment confirmation emails** to **Off**.
 
 [Contact us](/support_contact_and_more_information/) if you'd like us to develop a feature to automatically translate emails into Welsh.
+
+## Add a Welsh service name
+
+You can show a Welsh service name on payments that use Welsh language payment pages. 
+
+Sign in to [the GOV.UK Pay admin tool](https://selfservice.payments.service.gov.uk/login) and select **Edit name** next to the service you want to add a Welsh name to.
+
+Your users will see:
+
+* the Welsh service name when making payments with Welsh language payment pages
+* the English service name when making payments with English language payment pages
diff --git a/source/quick_start_guide/index.html.md.erb b/source/quick_start_guide/index.html.md.erb
@@ -94,7 +94,7 @@ This is an example API request and request body to create a new payment for a pa
 
 ```POST /v1/payments```
 
-```javascript
+```json
 {
 "amount": 12000,
 "reference": "12345",

diff --git a/source/reporting/index.html.md.erb b/source/reporting/index.html.md.erb
@@ -90,7 +90,7 @@ You can use the GOV.UK Pay API to:
 
 #### Get information about a single payment
 
-Use the following API request to get information about a single payment:
+Use the following endpoint to get information about a single payment:
 
 `GET /v1/payments/{PAYMENT_ID}`
 
@@ -399,19 +399,28 @@ You can use custom metadata to add more information to new payments when creatin
 
 Paying users cannot see metadata while they're making a payment.
 
-Include a `metadata` object in the body of your request to [create a new payment](/making_payments/#take-a-payment), for example:
+Include a `metadata` object in the body of your request to [create a new payment](/api_reference/create_a_payment_reference). 
 
-```javascript
-"metadata": {
-   "ledger_code": "AB100",
-   "an_internal_reference_number": 200,
-...
+This example request creates a payment for a £100 fine and adds a ledger code and an internal reference number as metadata:
+
+`POST /v1/payments`
+
+```json
+{
+  "amount": 10000,
+  "reference" : "WA5678",
+  "description": "Pay a fine for a late tax filing.",
+  "return_url": "https://your.service.gov.uk/completed",
+  "metadata": {
+    "ledger_code": "AB100",
+    "an_internal_reference_number": 200
+  }
 }
 ```
 
-The `metadata` object must contain between 1 and 10 parameters.
+The `metadata` object must contain between 1 and 10 parameters as key-value pairs.
 
-Each parameter key must be a unique case-insensitive string between 1 and 30 characters long. If 2 or more keys are identical, the API will remove all but one of the identical keys from the `metadata` object.
+Each parameter key must be a unique, case-insensitive string between 1 and 30 characters long. If 2 or more keys are identical, the API will remove all but one of the identical keys from the `metadata` object.
 
 The data type of each parameter value must be either a: