[NCE-917] Update docs for prepaid cards

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.pnpm-store

docs.json

@@ -79,6 +79,7 @@
                 "icon": "credit-card",
                 "pages": [
                   "features/prepaid-visa/introduction",
+                  "features/prepaid-visa/spend-controls",
                   "features/prepaid-visa/support"
                 ]
               }

features/prepaid-visa/introduction.mdx

@@ -11,20 +11,21 @@ Runa Prepaid Cards are instantly delivered, digital Visa prepaid cards that reci
 - **Two prepaid options**: Enable both the Runa Reward Card and the Runa Reload Card for your business needs
 
 <Info>
-  To get access to Prepaid Visa Cards, please reach out to your Account Manager or
-  email support@runa.io.
+  To get access to Prepaid Visa Cards, please reach out to your Account Manager
+  or email support@runa.io.
 </Info>
 
 ## Card types
 
-| | Runa Reload Card | Runa Reward Card |
-|---|---|---|
-| **Type** | Reloadable | Single-load |
-| **Expiry** | 47 months from first activation | 3, 6, or 12 months from first activation |
-| **Product code** | `VISARL-USD` | `VISASL-3M-USD`, `VISASL-6M-USD`, `VISASL-12M-USD` |
+|                  | Runa Reload Card                | Runa Reward Card                                   |
+| ---------------- | ------------------------------- | -------------------------------------------------- |
+| **Type**         | Reloadable                      | Single-load                                        |
+| **Expiry**       | 47 months from first activation | 3, 6, or 12 months from first activation           |
+| **Product code** | `VISARL-USD`                    | `VISASL-3M-USD`, `VISASL-6M-USD`, `VISASL-12M-USD` |
 
 <Warning>
-  For Reload Cards, recipients must use the same email address the card was originally sent to. Future top-ups will fail if a different email is used.
+  For Reload Cards, recipients must use the same email address the card was
+  originally sent to. Future top-ups will fail if a different email is used.
 </Warning>
 
 ## Getting started
@@ -72,6 +73,10 @@ In the example above we used the `EMAIL` distribution method to send the card to
 
 - You can also use the `PAYOUT_LINK` distribution method to receive a link in the API response and handle distribution yourself.
 
+## Controlling where a card can be spent
+
+You can restrict where a prepaid Visa card can be spent by attaching a Runa-authored spend rule template to the card. See [Card spend controls](/features/prepaid-visa/spend-controls) for details and a worked example.
+
 ## Reloading a Prepaid Visa Card
 
 For Reload Cards, you can use the `RECIPIENT` distribution method to enable automatic top-ups. Specify a unique `recipient_reference` to identify the recipient. For subsequent orders, use the same `recipient_reference` and we will automatically reload the existing card.

features/prepaid-visa/spend-controls.mdx

@@ -0,0 +1,54 @@
+---
+title: "Card spend controls"
+description: "Limit which merchants a Prepaid Visa Card can be used for"
+icon: "shield-check"
+---
+
+You can control where a prepaid Visa card can be spent by attaching a **Runa-authored spend rule template** to the card. A template bundles a set of restrictions — such as Merchant Category Code (MCC) allow/deny lists — that are applied to the issued card.
+
+## Attaching a template
+
+To attach a template, add a `usage_config` object to the `SINGLE` product and set its `spend_rules_template_id` to the identifier of the template you want to apply.
+
+```http title="Example Prepaid Visa Card order with a spend rule template" icon="globe" expandable
+POST https://api.runa.io/v2/order
+Content-Type: application/json
+X-Api-Key: <your API key>
+
+{
+    "payment_method": {
+        "type": "ACCOUNT_BALANCE",
+        "currency": "USD"
+    },
+    "items": [
+        {
+            "face_value": 10,
+            "distribution_method": {
+                "type": "EMAIL",
+                "email_address": "<your recipient's email address>"
+            },
+            "products": {
+                "type": "SINGLE",
+                "value": "VISASL-3M-USD",
+                "usage_config": {
+                    "spend_rules_template_id": "PSR-01HW3CXZJD5K9PMNRTV0Y4QF7B"
+                }
+            }
+        }
+    ]
+}
+```
+
+When you set `usage_config` on an order, it is returned in the [order details](/reference/2024-02-05/endpoint/orders/get) so you can confirm which template was applied.
+
+<Info>
+  Spend rule templates are authored by Runa. A single template is applied per
+  card, with multiple restrictions bundled inside it. Template identifiers are
+  immutable — any change ships as a new template with a new ID. To request a
+  template, reach out to your Account Manager or email support@runa.io.
+</Info>
+
+<Note>
+  `usage_config` only applies to prepaid Visa cards. If you set it on any other
+  product it is ignored.
+</Note>

reference/2024-02-05/openapi.json

@@ -864,7 +864,7 @@
                 "$ref": "#/components/schemas/MultipleProduct"
               },
               {
-                "$ref": "#/components/schemas/SingleProduct"
+                "$ref": "#/components/schemas/SingleProductWithUsageConfig"
               },
               {
                 "$ref": "#/components/schemas/PayoutSelectionTemplateDetailed"
@@ -1268,7 +1268,7 @@
             "description": "Choose `SINGLE` if you want the end user to redeem the face value on a single specific product. Choose `MULTIPLE` if the end user can choose to spend the face value across multiple products.",
             "oneOf": [
               {
-                "$ref": "#/components/schemas/SingleProduct"
+                "$ref": "#/components/schemas/SingleProductWithUsageConfig"
               },
               {
                 "$ref": "#/components/schemas/MultipleProduct"
@@ -1587,6 +1587,50 @@
         "enum": ["SINGLE"],
         "description": "Single product. When only one product code is provided."
       },
+      "SingleProductWithUsageConfig": {
+        "title": "Single",
+        "required": ["type", "value"],
+        "type": "object",
+        "example": {
+          "type": "SINGLE",
+          "value": "AMZ-US"
+        },
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/SingleProductType"
+          },
+          "value": {
+            "title": "Value",
+            "description": "The code for the product the end user will get when redeeming their payout link.",
+            "minLength": 1,
+            "example": "AMZ-US",
+            "type": "string"
+          },
+          "usage_config": {
+            "description": "Optional. **Only applicable to prepaid Visa cards.** Attaches an MCC-rules template to the issued card. Ignored for all other products. See [Card spend controls](/features/prepaid-visa/spend-controls) for a worked example. When set on a prepaid Visa card order, it is returned in the order details.",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ProductUsageConfig"
+              }
+            ]
+          }
+        },
+        "description": "Single product. The end user will be able to redeem the payout link for this specific product."
+      },
+      "ProductUsageConfig": {
+        "title": "ProductUsageConfig",
+        "type": "object",
+        "description": "Additional configuration applied to the issued product. Only applicable to prepaid Visa cards.",
+        "properties": {
+          "spend_rules_template_id": {
+            "title": "MCC rules template ID",
+            "description": "Identifier of a Runa-authored MCC-rules template applied to the issued card.\n\nOnly applicable to prepaid Visa cards. A single template is applied per card, with multiple restrictions bundled inside that one template. Template identifiers are immutable — changes ship as a new template with a new ID.",
+            "type": "string",
+            "pattern": "^PSR-[0-9A-HJKMNP-TV-Z]{26}$",
+            "example": "PSR-01HW3CXZJD5K9PMNRTV0Y4QF7B"
+          }
+        }
+      },
       "MultipleProduct": {
         "title": "Multiple",
         "required": ["type", "values"],