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/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 057252f..359e40d 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,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. diff --git a/features/prepaid-visa/spend-controls.mdx b/features/prepaid-visa/spend-controls.mdx new file mode 100644 index 0000000..e3a2b9f --- /dev/null +++ b/features/prepaid-visa/spend-controls.mdx @@ -0,0 +1,56 @@ +--- +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: + +{ + "payment_method": { + "type": "ACCOUNT_BALANCE", + "currency": "USD" + }, + "items": [ + { + "face_value": 10, + "distribution_method": { + "type": "EMAIL", + "email_address": "" + }, + "products": { + "type": "SINGLE", + "value": "VISASL-3M-USD", + "usage_config": { + "spend_rules_template_id": "" + } + } + } + ] +} +``` + +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. + + + 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. + + + + `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 aa8ac37..be6c268 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" + }, + "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/UsageConfig" + } + ] + } + }, + "description": "Single product. The end user will be able to redeem the payout link for this specific product." + }, + "UsageConfig": { + "title": "UsageConfig", + "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 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-XXXXXXXXXXXXXXXXXXXXXXXXXX" + } + } + }, "MultipleProduct": { "title": "Multiple", "required": ["type", "values"],