From c8761d44f057052cd87b2e6779a4095dad470625 Mon Sep 17 00:00:00 2001 From: Angel Date: Mon, 15 Jun 2026 10:55:10 +0300 Subject: [PATCH 1/7] [NCE-917] Update docs for prepaid cards --- .gitignore | 2 + features/prepaid-visa/introduction.mdx | 66 ++++++++++++++++++++++---- reference/2024-02-05/openapi.json | 48 ++++++++++++++++++- 3 files changed, 106 insertions(+), 10 deletions(-) diff --git a/.gitignore b/.gitignore index e69de29..532bef0 100644 --- a/.gitignore +++ b/.gitignore @@ -0,0 +1,2 @@ +node_modules +.pnpm-store \ No newline at end of file diff --git a/features/prepaid-visa/introduction.mdx b/features/prepaid-visa/introduction.mdx index 057252f..22d50d5 100644 --- a/features/prepaid-visa/introduction.mdx +++ b/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 - 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. ## 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` | - 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. ## Getting started @@ -72,6 +73,55 @@ 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. +## Attaching an MCC-rules template + +You can control where a prepaid Visa card can be spent by attaching a **Runa-authored MCC-rules 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. + +To attach a template, add a `product_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 an MCC-rules template" icon="globe" expandable +POST https://api.runa.io/v2/order +Content-Type: application/json +X-Api-Key: + +{ + "payment_method": { + "type": "ACCOUNT_BALANCE", + "currency": "USD" + }, + "items": [ + { + "face_value": 10, + "distribution_method": { + "type": "EMAIL", + "email_address": "" + }, + "products": { + "type": "SINGLE", + "value": "VISASL-3M-USD", + "product_usage_config": { + "spend_rules_template_id": "PSR-01HW3CXZJD5K9PMNRTV0Y4QF7B" + } + } + } + ] +} +``` + +When you set `product_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. + + + 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. + + + + `product_usage_config` only applies to prepaid Visa cards. If you set it on + any other product it is ignored. + + ## 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. diff --git a/reference/2024-02-05/openapi.json b/reference/2024-02-05/openapi.json index aa8ac37..ce2673f 100644 --- a/reference/2024-02-05/openapi.json +++ b/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" + }, + "product_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 [Using Prepaid Visa Cards](/features/prepaid-visa/introduction#attaching-an-mcc-rules-template) for a worked example. When it was 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"], From 1c4d1e91bbbe009b0bb8c2e16f3f0d1ec6de73f6 Mon Sep 17 00:00:00 2001 From: Angel Date: Mon, 15 Jun 2026 13:24:19 +0300 Subject: [PATCH 2/7] Adjust wording --- reference/2024-02-05/openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/2024-02-05/openapi.json b/reference/2024-02-05/openapi.json index ce2673f..605240e 100644 --- a/reference/2024-02-05/openapi.json +++ b/reference/2024-02-05/openapi.json @@ -1607,7 +1607,7 @@ "type": "string" }, "product_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 [Using Prepaid Visa Cards](/features/prepaid-visa/introduction#attaching-an-mcc-rules-template) for a worked example. When it was set on a prepaid Visa card order, it is returned in the order details.", + "description": "Optional. **Only applicable to prepaid Visa cards.** Attaches an MCC-rules template to the issued card. Ignored for all other products. See [Using Prepaid Visa Cards](/features/prepaid-visa/introduction#attaching-an-mcc-rules-template) for a worked example. When set on a prepaid Visa card order, it is returned in the order details.", "allOf": [ { "$ref": "#/components/schemas/ProductUsageConfig" From a57b2136f828cd3f7052147fe14ec878bdaf9c1a Mon Sep 17 00:00:00 2001 From: Angel Date: Mon, 15 Jun 2026 15:55:12 +0300 Subject: [PATCH 3/7] Create a new section --- docs.json | 1 + features/prepaid-visa/introduction.mdx | 49 +-------------------- features/prepaid-visa/spend-controls.mdx | 54 ++++++++++++++++++++++++ reference/2024-02-05/openapi.json | 2 +- 4 files changed, 58 insertions(+), 48 deletions(-) create mode 100644 features/prepaid-visa/spend-controls.mdx diff --git a/docs.json b/docs.json index 9d8e30e..5aa19cc 100644 --- a/docs.json +++ b/docs.json @@ -79,6 +79,7 @@ "icon": "credit-card", "pages": [ "features/prepaid-visa/introduction", + "features/prepaid-visa/spend-controls", "features/prepaid-visa/support" ] } diff --git a/features/prepaid-visa/introduction.mdx b/features/prepaid-visa/introduction.mdx index 22d50d5..359e40d 100644 --- a/features/prepaid-visa/introduction.mdx +++ b/features/prepaid-visa/introduction.mdx @@ -73,54 +73,9 @@ 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. -## Attaching an MCC-rules template +## Controlling where a card can be spent -You can control where a prepaid Visa card can be spent by attaching a **Runa-authored MCC-rules 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. - -To attach a template, add a `product_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 an MCC-rules template" icon="globe" expandable -POST https://api.runa.io/v2/order -Content-Type: application/json -X-Api-Key: - -{ - "payment_method": { - "type": "ACCOUNT_BALANCE", - "currency": "USD" - }, - "items": [ - { - "face_value": 10, - "distribution_method": { - "type": "EMAIL", - "email_address": "" - }, - "products": { - "type": "SINGLE", - "value": "VISASL-3M-USD", - "product_usage_config": { - "spend_rules_template_id": "PSR-01HW3CXZJD5K9PMNRTV0Y4QF7B" - } - } - } - ] -} -``` - -When you set `product_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. - - - 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. - - - - `product_usage_config` only applies to prepaid Visa cards. If you set it on - any other product it is ignored. - +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 diff --git a/features/prepaid-visa/spend-controls.mdx b/features/prepaid-visa/spend-controls.mdx new file mode 100644 index 0000000..101109b --- /dev/null +++ b/features/prepaid-visa/spend-controls.mdx @@ -0,0 +1,54 @@ +--- +title: "Card spend controls" +description: "Restrict where a prepaid Visa card can be spent using Runa-authored spend rule templates (Merchant Category Code (MCC) allow/deny lists)." +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 `product_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: + +{ + "payment_method": { + "type": "ACCOUNT_BALANCE", + "currency": "USD" + }, + "items": [ + { + "face_value": 10, + "distribution_method": { + "type": "EMAIL", + "email_address": "" + }, + "products": { + "type": "SINGLE", + "value": "VISASL-3M-USD", + "product_usage_config": { + "spend_rules_template_id": "PSR-01HW3CXZJD5K9PMNRTV0Y4QF7B" + } + } + } + ] +} +``` + +When you set `product_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. + + + 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. + + + + `product_usage_config` only applies to prepaid Visa cards. If you set it on + any other product it is ignored. + diff --git a/reference/2024-02-05/openapi.json b/reference/2024-02-05/openapi.json index 605240e..7523961 100644 --- a/reference/2024-02-05/openapi.json +++ b/reference/2024-02-05/openapi.json @@ -1607,7 +1607,7 @@ "type": "string" }, "product_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 [Using Prepaid Visa Cards](/features/prepaid-visa/introduction#attaching-an-mcc-rules-template) for a worked example. When set on a prepaid Visa card order, it is returned in the order details.", + "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" From 0a398eeb254881622cf8affd375528b0d3a87dae Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 17 Jun 2026 10:06:15 +0300 Subject: [PATCH 4/7] Change the description of card spend controls --- features/prepaid-visa/spend-controls.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/features/prepaid-visa/spend-controls.mdx b/features/prepaid-visa/spend-controls.mdx index 101109b..878c753 100644 --- a/features/prepaid-visa/spend-controls.mdx +++ b/features/prepaid-visa/spend-controls.mdx @@ -1,6 +1,6 @@ --- title: "Card spend controls" -description: "Restrict where a prepaid Visa card can be spent using Runa-authored spend rule templates (Merchant Category Code (MCC) allow/deny lists)." +description: "Limit which merchants a Prepaid Visa Card can be used for" icon: "shield-check" --- From 60fa1a33bd00b116b85b5bbb0d24160572d22dd9 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 17 Jun 2026 10:11:46 +0300 Subject: [PATCH 5/7] Rename to usage_config --- features/prepaid-visa/spend-controls.mdx | 10 +++++----- reference/2024-02-05/openapi.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/features/prepaid-visa/spend-controls.mdx b/features/prepaid-visa/spend-controls.mdx index 878c753..9fed606 100644 --- a/features/prepaid-visa/spend-controls.mdx +++ b/features/prepaid-visa/spend-controls.mdx @@ -8,7 +8,7 @@ You can control where a prepaid Visa card can be spent by attaching a **Runa-aut ## Attaching a template -To attach a template, add a `product_usage_config` object to the `SINGLE` product and set its `spend_rules_template_id` to the identifier of the template you want to apply. +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 @@ -30,7 +30,7 @@ X-Api-Key: "products": { "type": "SINGLE", "value": "VISASL-3M-USD", - "product_usage_config": { + "usage_config": { "spend_rules_template_id": "PSR-01HW3CXZJD5K9PMNRTV0Y4QF7B" } } @@ -39,7 +39,7 @@ X-Api-Key: } ``` -When you set `product_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. +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. Spend rule templates are authored by Runa. A single template is applied per @@ -49,6 +49,6 @@ When you set `product_usage_config` on an order, it is returned in the [order de - `product_usage_config` only applies to prepaid Visa cards. If you set it on - any other product it is ignored. + `usage_config` only applies to prepaid Visa cards. If you set it on any other + product it is ignored. diff --git a/reference/2024-02-05/openapi.json b/reference/2024-02-05/openapi.json index 7523961..5225438 100644 --- a/reference/2024-02-05/openapi.json +++ b/reference/2024-02-05/openapi.json @@ -1606,7 +1606,7 @@ "example": "AMZ-US", "type": "string" }, - "product_usage_config": { + "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": [ { From 63ae4d7914e483334696c6830e1aed2a62086261 Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 18 Jun 2026 15:44:51 +0300 Subject: [PATCH 6/7] Change to usageConfig --- reference/2024-02-05/openapi.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/2024-02-05/openapi.json b/reference/2024-02-05/openapi.json index 5225438..0a8090c 100644 --- a/reference/2024-02-05/openapi.json +++ b/reference/2024-02-05/openapi.json @@ -1610,15 +1610,15 @@ "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" + "$ref": "#/components/schemas/UsageConfig" } ] } }, "description": "Single product. The end user will be able to redeem the payout link for this specific product." }, - "ProductUsageConfig": { - "title": "ProductUsageConfig", + "UsageConfig": { + "title": "UsageConfig", "type": "object", "description": "Additional configuration applied to the issued product. Only applicable to prepaid Visa cards.", "properties": { From 5cb9b8ef395bedb66d933afd7a4f1ceb1cec6e23 Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 18 Jun 2026 17:03:54 +0300 Subject: [PATCH 7/7] Update docs --- features/prepaid-visa/spend-controls.mdx | 10 ++++++---- reference/2024-02-05/openapi.json | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/features/prepaid-visa/spend-controls.mdx b/features/prepaid-visa/spend-controls.mdx index 9fed606..ab3bace 100644 --- a/features/prepaid-visa/spend-controls.mdx +++ b/features/prepaid-visa/spend-controls.mdx @@ -42,10 +42,12 @@ X-Api-Key: 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. - 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. + A spend rule template defines the spending pattern enforced on a card, based + on MCC rules — each rule either allows or blocks transactions for a given + merchant category. Multiple rules can be bundled into a single template, and + one template is applied per card. Templates are authored by Runa. If you have + a business case that needs one, reach out to your Account Manager or email + support@runa.io — we'll create the template for you. diff --git a/reference/2024-02-05/openapi.json b/reference/2024-02-05/openapi.json index 0a8090c..7b151da 100644 --- a/reference/2024-02-05/openapi.json +++ b/reference/2024-02-05/openapi.json @@ -1624,7 +1624,7 @@ "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.", + "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 rules that either allows or blocks transactions for a given merchant category bundled inside that one template.", "type": "string", "pattern": "^PSR-[0-9A-HJKMNP-TV-Z]{26}$", "example": "PSR-01HW3CXZJD5K9PMNRTV0Y4QF7B"