diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 583e8dbc6..6bb3c355c 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -94,7 +94,7 @@ paths: $ref: '#/components/schemas/Error500' patch: summary: Update platform configuration - description: Update the platform configuration settings + description: Update platform configuration settings. Setting `cardConfigs.maxSpendPerTransaction` establishes a platform-level card cap; Grid enforces the lower of that cap and each card's configured `maxSpendPerTransaction` without replacing the card-specific value. operationId: updatePlatformConfig tags: - Platform Configuration @@ -141,6 +141,8 @@ paths: sms: templateSid: HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bodyText: Use this code to finish adding your Acme card to your digital wallet. + cardConfigs: + maxSpendPerTransaction: 10000 responses: '200': description: Configuration updated successfully @@ -8404,7 +8406,7 @@ paths: description: | Issue a new card for a cardholder. Every card must be bound to at least one funding source at create time. The cardholder must have KYC status `APPROVED` before a card can be issued; otherwise the request is rejected with `CARDHOLDER_KYC_NOT_APPROVED`. - An optional `maxSpendPerTransaction` value sets the largest amount a single card transaction may authorize. The limit is enforced by Grid for card programs where Grid makes the authorization decision, whether the card is funded by an Embedded Wallet account or custodial fiat. Omit it for no limit. The value is in the smallest unit of the card's currency. + An optional `maxSpendPerTransaction` value sets the card-specific cap on a single transaction. The limit is enforced by Grid for card programs where Grid makes the authorization decision, whether the card is funded by an Embedded Wallet account or custodial fiat. Omit it for no card-specific cap. If the platform config sets `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the card and platform values. Both values use the smallest unit of the card's currency. If any funding source is an Embedded Wallet internal account, the cardholder must authorize Grid to sign Spark token transactions for that card funding source by completing the delegated-key creation flow with `POST /auth/delegated-keys`. Until an active delegated key exists for that funding source, Authorization Decisioning cannot use it to fund card transactions. @@ -8605,7 +8607,7 @@ paths: - `state` transitions are limited to `ACTIVE ⇄ FROZEN` and `ACTIVE | FROZEN → CLOSED`. `CLOSED` is terminal and irreversible. Any other transition returns `409 INVALID_STATE_TRANSITION`. - `fundingSources`, when supplied, fully replaces the card's bound funding sources. Array order determines the priority Authorization Decisioning tries them in. Each id must belong to the cardholder and be denominated in the card's currency; the list must contain at least one source. `fundingSources` cannot be supplied alongside `state: CLOSED`. - - `maxSpendPerTransaction`, when supplied, replaces the card's application-enforced per-transaction limit. Supply a positive integer in the smallest unit of the card's currency to set it or null to clear it. Limits are supported only for card programs where Grid makes the authorization decision. `maxSpendPerTransaction` cannot be supplied alongside `state: CLOSED`. + - `maxSpendPerTransaction`, when supplied, replaces the card-specific per-transaction cap. Supply a positive integer in the smallest unit of the card's currency to set it or null to clear it. If the platform config sets `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the card and platform values. Limits are supported only for card programs where Grid makes the authorization decision. `maxSpendPerTransaction` cannot be supplied alongside `state: CLOSED`. This endpoint is authenticated by the platform credential alone and returns `200` directly. It deliberately does not use Grid's 202 → signed-retry pattern: that pattern signs with the session key of a credential on the owning internal account, so it models actions taken *by* the end user on their own credentials or funds. Freezing or closing a card is routinely an action taken *about* a user and without them present - fraud response, offboarding, an ops-driven freeze - and requiring the cardholder's signature would make exactly those cases impossible. Operations that expose sensitive card data (`POST /cards/{id}/reveal`, 3DS password retrieval) are SCA-railed instead, because there the cardholder is the party being served. @@ -11967,6 +11969,18 @@ components: $ref: '#/components/schemas/CardTokenization2FAEmailConfig' sms: $ref: '#/components/schemas/CardTokenization2FASmsConfig' + CardConfig: + type: object + description: Platform-level settings that apply to cards issued by the platform. + properties: + maxSpendPerTransaction: + anyOf: + - type: integer + format: int64 + minimum: 1 + - type: 'null' + description: Platform-level cap on a single transaction for every card whose authorization decisions are made by Grid. The value is interpreted in the smallest unit of each card's currency. Grid enforces the lower of this cap and the card's configured `maxSpendPerTransaction`; null means no platform-level cap. The cap applies to existing cards and to cards issued later. Provider-decided card programs are unaffected. + example: 10000 FeeType: type: string enum: @@ -12063,6 +12077,9 @@ components: description: | Branding and sender configuration for card-tokenization authentication messages. This configuration is independent of embedded-wallet support. + cardConfigs: + $ref: '#/components/schemas/CardConfig' + description: Platform-level settings for cards issued by this platform. feeConfigs: type: array items: @@ -12177,6 +12194,9 @@ components: Update card-tokenization authentication branding and delivery settings. Fields omitted from the nested object are left unchanged. Changes apply to subsequent delivery attempts. + cardConfigs: + $ref: '#/components/schemas/CardConfig' + description: Update platform-level card settings. Fields omitted from the nested object are left unchanged. For `maxSpendPerTransaction`, supply null to clear the platform cap or a positive integer to set it. Omit this field at the top level to leave all card settings unchanged. feeConfigs: type: array items: @@ -24430,7 +24450,7 @@ components: format: int64 minimum: 1 - type: 'null' - description: Largest amount a single card transaction may authorize, in the smallest unit of the card's `currency`. Null means the card has no application-enforced per-transaction limit. A transaction for exactly this amount is allowed. + description: Card-specific cap on a single transaction, in the smallest unit of the card's `currency`. Null means the card has no card-specific cap. When the platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two values without replacing this configured value. A transaction for exactly the effective limit is allowed. example: 5000 currency: type: string @@ -24512,7 +24532,7 @@ components: type: integer format: int64 minimum: 1 - description: Optional largest amount a single card transaction may authorize, in the smallest unit of the card currency derived from its funding sources. Omit this field for no limit. Supported only for card programs whose authorization decisions are made by Grid. A transaction for exactly this amount is allowed. + description: Optional card-specific cap on a single transaction, in the smallest unit of the card currency derived from its funding sources. Omit this field for no card-specific cap. When the platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two values. Supported only for card programs whose authorization decisions are made by Grid. A transaction for exactly the effective limit is allowed. example: 5000 CardUpdateRequest: type: object @@ -24541,7 +24561,7 @@ components: format: int64 minimum: 1 - type: 'null' - description: 'Replacement per-transaction spending limit for the card, in the smallest unit of its currency. Omit this field to leave the current limit unchanged, supply null to clear it, or supply a positive integer to set it. Supported only for card programs whose authorization decisions are made by Grid. Cannot be supplied alongside `state: CLOSED`.' + description: 'Replacement card-specific per-transaction cap, in the smallest unit of the card''s currency. Omit this field to leave the current cap unchanged, supply null to clear it, or supply a positive integer to set it. When the platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two values. Supported only for card programs whose authorization decisions are made by Grid. Cannot be supplied alongside `state: CLOSED`.' example: 10000 CardRevealResponse: type: object diff --git a/openapi.yaml b/openapi.yaml index 583e8dbc6..6bb3c355c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -94,7 +94,7 @@ paths: $ref: '#/components/schemas/Error500' patch: summary: Update platform configuration - description: Update the platform configuration settings + description: Update platform configuration settings. Setting `cardConfigs.maxSpendPerTransaction` establishes a platform-level card cap; Grid enforces the lower of that cap and each card's configured `maxSpendPerTransaction` without replacing the card-specific value. operationId: updatePlatformConfig tags: - Platform Configuration @@ -141,6 +141,8 @@ paths: sms: templateSid: HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bodyText: Use this code to finish adding your Acme card to your digital wallet. + cardConfigs: + maxSpendPerTransaction: 10000 responses: '200': description: Configuration updated successfully @@ -8404,7 +8406,7 @@ paths: description: | Issue a new card for a cardholder. Every card must be bound to at least one funding source at create time. The cardholder must have KYC status `APPROVED` before a card can be issued; otherwise the request is rejected with `CARDHOLDER_KYC_NOT_APPROVED`. - An optional `maxSpendPerTransaction` value sets the largest amount a single card transaction may authorize. The limit is enforced by Grid for card programs where Grid makes the authorization decision, whether the card is funded by an Embedded Wallet account or custodial fiat. Omit it for no limit. The value is in the smallest unit of the card's currency. + An optional `maxSpendPerTransaction` value sets the card-specific cap on a single transaction. The limit is enforced by Grid for card programs where Grid makes the authorization decision, whether the card is funded by an Embedded Wallet account or custodial fiat. Omit it for no card-specific cap. If the platform config sets `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the card and platform values. Both values use the smallest unit of the card's currency. If any funding source is an Embedded Wallet internal account, the cardholder must authorize Grid to sign Spark token transactions for that card funding source by completing the delegated-key creation flow with `POST /auth/delegated-keys`. Until an active delegated key exists for that funding source, Authorization Decisioning cannot use it to fund card transactions. @@ -8605,7 +8607,7 @@ paths: - `state` transitions are limited to `ACTIVE ⇄ FROZEN` and `ACTIVE | FROZEN → CLOSED`. `CLOSED` is terminal and irreversible. Any other transition returns `409 INVALID_STATE_TRANSITION`. - `fundingSources`, when supplied, fully replaces the card's bound funding sources. Array order determines the priority Authorization Decisioning tries them in. Each id must belong to the cardholder and be denominated in the card's currency; the list must contain at least one source. `fundingSources` cannot be supplied alongside `state: CLOSED`. - - `maxSpendPerTransaction`, when supplied, replaces the card's application-enforced per-transaction limit. Supply a positive integer in the smallest unit of the card's currency to set it or null to clear it. Limits are supported only for card programs where Grid makes the authorization decision. `maxSpendPerTransaction` cannot be supplied alongside `state: CLOSED`. + - `maxSpendPerTransaction`, when supplied, replaces the card-specific per-transaction cap. Supply a positive integer in the smallest unit of the card's currency to set it or null to clear it. If the platform config sets `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the card and platform values. Limits are supported only for card programs where Grid makes the authorization decision. `maxSpendPerTransaction` cannot be supplied alongside `state: CLOSED`. This endpoint is authenticated by the platform credential alone and returns `200` directly. It deliberately does not use Grid's 202 → signed-retry pattern: that pattern signs with the session key of a credential on the owning internal account, so it models actions taken *by* the end user on their own credentials or funds. Freezing or closing a card is routinely an action taken *about* a user and without them present - fraud response, offboarding, an ops-driven freeze - and requiring the cardholder's signature would make exactly those cases impossible. Operations that expose sensitive card data (`POST /cards/{id}/reveal`, 3DS password retrieval) are SCA-railed instead, because there the cardholder is the party being served. @@ -11967,6 +11969,18 @@ components: $ref: '#/components/schemas/CardTokenization2FAEmailConfig' sms: $ref: '#/components/schemas/CardTokenization2FASmsConfig' + CardConfig: + type: object + description: Platform-level settings that apply to cards issued by the platform. + properties: + maxSpendPerTransaction: + anyOf: + - type: integer + format: int64 + minimum: 1 + - type: 'null' + description: Platform-level cap on a single transaction for every card whose authorization decisions are made by Grid. The value is interpreted in the smallest unit of each card's currency. Grid enforces the lower of this cap and the card's configured `maxSpendPerTransaction`; null means no platform-level cap. The cap applies to existing cards and to cards issued later. Provider-decided card programs are unaffected. + example: 10000 FeeType: type: string enum: @@ -12063,6 +12077,9 @@ components: description: | Branding and sender configuration for card-tokenization authentication messages. This configuration is independent of embedded-wallet support. + cardConfigs: + $ref: '#/components/schemas/CardConfig' + description: Platform-level settings for cards issued by this platform. feeConfigs: type: array items: @@ -12177,6 +12194,9 @@ components: Update card-tokenization authentication branding and delivery settings. Fields omitted from the nested object are left unchanged. Changes apply to subsequent delivery attempts. + cardConfigs: + $ref: '#/components/schemas/CardConfig' + description: Update platform-level card settings. Fields omitted from the nested object are left unchanged. For `maxSpendPerTransaction`, supply null to clear the platform cap or a positive integer to set it. Omit this field at the top level to leave all card settings unchanged. feeConfigs: type: array items: @@ -24430,7 +24450,7 @@ components: format: int64 minimum: 1 - type: 'null' - description: Largest amount a single card transaction may authorize, in the smallest unit of the card's `currency`. Null means the card has no application-enforced per-transaction limit. A transaction for exactly this amount is allowed. + description: Card-specific cap on a single transaction, in the smallest unit of the card's `currency`. Null means the card has no card-specific cap. When the platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two values without replacing this configured value. A transaction for exactly the effective limit is allowed. example: 5000 currency: type: string @@ -24512,7 +24532,7 @@ components: type: integer format: int64 minimum: 1 - description: Optional largest amount a single card transaction may authorize, in the smallest unit of the card currency derived from its funding sources. Omit this field for no limit. Supported only for card programs whose authorization decisions are made by Grid. A transaction for exactly this amount is allowed. + description: Optional card-specific cap on a single transaction, in the smallest unit of the card currency derived from its funding sources. Omit this field for no card-specific cap. When the platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two values. Supported only for card programs whose authorization decisions are made by Grid. A transaction for exactly the effective limit is allowed. example: 5000 CardUpdateRequest: type: object @@ -24541,7 +24561,7 @@ components: format: int64 minimum: 1 - type: 'null' - description: 'Replacement per-transaction spending limit for the card, in the smallest unit of its currency. Omit this field to leave the current limit unchanged, supply null to clear it, or supply a positive integer to set it. Supported only for card programs whose authorization decisions are made by Grid. Cannot be supplied alongside `state: CLOSED`.' + description: 'Replacement card-specific per-transaction cap, in the smallest unit of the card''s currency. Omit this field to leave the current cap unchanged, supply null to clear it, or supply a positive integer to set it. When the platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two values. Supported only for card programs whose authorization decisions are made by Grid. Cannot be supplied alongside `state: CLOSED`.' example: 10000 CardRevealResponse: type: object diff --git a/openapi/components/schemas/cards/Card.yaml b/openapi/components/schemas/cards/Card.yaml index 222790703..f84c98ba2 100644 --- a/openapi/components/schemas/cards/Card.yaml +++ b/openapi/components/schemas/cards/Card.yaml @@ -69,10 +69,11 @@ properties: minimum: 1 - type: 'null' description: >- - Largest amount a single card transaction may authorize, in the smallest - unit of the card's `currency`. Null means the card has no - application-enforced per-transaction limit. A transaction for exactly - this amount is allowed. + Card-specific cap on a single transaction, in the smallest unit of the + card's `currency`. Null means the card has no card-specific cap. When the + platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid + enforces the lower of the two values without replacing this configured + value. A transaction for exactly the effective limit is allowed. example: 5000 currency: type: string diff --git a/openapi/components/schemas/cards/CardCreateRequest.yaml b/openapi/components/schemas/cards/CardCreateRequest.yaml index 32424b413..3c0a13515 100644 --- a/openapi/components/schemas/cards/CardCreateRequest.yaml +++ b/openapi/components/schemas/cards/CardCreateRequest.yaml @@ -48,9 +48,11 @@ properties: format: int64 minimum: 1 description: >- - Optional largest amount a single card transaction may authorize, in the - smallest unit of the card currency derived from its funding sources. - Omit this field for no limit. Supported only for card programs whose - authorization decisions are made by Grid. A transaction for exactly this - amount is allowed. + Optional card-specific cap on a single transaction, in the smallest unit + of the card currency derived from its funding sources. Omit this field + for no card-specific cap. When the platform config also supplies + `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two + values. Supported only for card programs whose authorization decisions + are made by Grid. A transaction for exactly the effective limit is + allowed. example: 5000 diff --git a/openapi/components/schemas/cards/CardUpdateRequest.yaml b/openapi/components/schemas/cards/CardUpdateRequest.yaml index 6f412736a..f4cd214c3 100644 --- a/openapi/components/schemas/cards/CardUpdateRequest.yaml +++ b/openapi/components/schemas/cards/CardUpdateRequest.yaml @@ -44,9 +44,11 @@ properties: minimum: 1 - type: 'null' description: >- - Replacement per-transaction spending limit for the card, in the smallest - unit of its currency. Omit this field to leave the current limit - unchanged, supply null to clear it, or supply a positive integer to set - it. Supported only for card programs whose authorization decisions are - made by Grid. Cannot be supplied alongside `state: CLOSED`. + Replacement card-specific per-transaction cap, in the smallest unit of + the card's currency. Omit this field to leave the current cap unchanged, + supply null to clear it, or supply a positive integer to set it. When the + platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid + enforces the lower of the two values. Supported only for card programs + whose authorization decisions are made by Grid. Cannot be supplied + alongside `state: CLOSED`. example: 10000 diff --git a/openapi/components/schemas/config/CardConfig.yaml b/openapi/components/schemas/config/CardConfig.yaml new file mode 100644 index 000000000..96b2b0ce7 --- /dev/null +++ b/openapi/components/schemas/config/CardConfig.yaml @@ -0,0 +1,17 @@ +type: object +description: Platform-level settings that apply to cards issued by the platform. +properties: + maxSpendPerTransaction: + anyOf: + - type: integer + format: int64 + minimum: 1 + - type: 'null' + description: >- + Platform-level cap on a single transaction for every card whose + authorization decisions are made by Grid. The value is interpreted in + the smallest unit of each card's currency. Grid enforces the lower of + this cap and the card's configured `maxSpendPerTransaction`; null means + no platform-level cap. The cap applies to existing cards and to cards + issued later. Provider-decided card programs are unaffected. + example: 10000 diff --git a/openapi/components/schemas/config/PlatformConfig.yaml b/openapi/components/schemas/config/PlatformConfig.yaml index e48cd1b6f..5fa942689 100644 --- a/openapi/components/schemas/config/PlatformConfig.yaml +++ b/openapi/components/schemas/config/PlatformConfig.yaml @@ -43,6 +43,9 @@ properties: description: | Branding and sender configuration for card-tokenization authentication messages. This configuration is independent of embedded-wallet support. + cardConfigs: + $ref: ./CardConfig.yaml + description: Platform-level settings for cards issued by this platform. feeConfigs: type: array items: diff --git a/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml b/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml index 96289dba5..9f5372396 100644 --- a/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml +++ b/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml @@ -23,6 +23,13 @@ properties: Update card-tokenization authentication branding and delivery settings. Fields omitted from the nested object are left unchanged. Changes apply to subsequent delivery attempts. + cardConfigs: + $ref: ./CardConfig.yaml + description: >- + Update platform-level card settings. Fields omitted from the nested + object are left unchanged. For `maxSpendPerTransaction`, supply null to + clear the platform cap or a positive integer to set it. Omit this field + at the top level to leave all card settings unchanged. feeConfigs: type: array items: diff --git a/openapi/paths/cards/cards.yaml b/openapi/paths/cards/cards.yaml index b8c17eef0..a0e4e3f77 100644 --- a/openapi/paths/cards/cards.yaml +++ b/openapi/paths/cards/cards.yaml @@ -7,11 +7,14 @@ post: with `CARDHOLDER_KYC_NOT_APPROVED`. - An optional `maxSpendPerTransaction` value sets the largest amount a single card - transaction may authorize. The limit is enforced by Grid for card programs - where Grid makes the authorization decision, whether the card is funded by - an Embedded Wallet account or custodial fiat. Omit it for no limit. The - value is in the smallest unit of the card's currency. + An optional `maxSpendPerTransaction` value sets the card-specific cap on a + single transaction. The limit is enforced by Grid for card programs where + Grid makes the authorization decision, whether the card is funded by an + Embedded Wallet account or custodial fiat. Omit it for no card-specific + cap. If the platform config sets + `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the card + and platform values. Both values use the smallest unit of the card's + currency. If any funding source is an Embedded Wallet internal account, the diff --git a/openapi/paths/cards/cards_{id}.yaml b/openapi/paths/cards/cards_{id}.yaml index dd0c18388..daad15b90 100644 --- a/openapi/paths/cards/cards_{id}.yaml +++ b/openapi/paths/cards/cards_{id}.yaml @@ -69,12 +69,13 @@ patch: one source. `fundingSources` cannot be supplied alongside `state: CLOSED`. - - `maxSpendPerTransaction`, when supplied, replaces the card's - application-enforced per-transaction limit. Supply a positive integer in - the smallest unit of the card's currency to set it or null to clear it. - Limits are supported only for card programs where Grid makes the - authorization decision. `maxSpendPerTransaction` cannot be supplied - alongside `state: CLOSED`. + - `maxSpendPerTransaction`, when supplied, replaces the card-specific + per-transaction cap. Supply a positive integer in the smallest unit of the + card's currency to set it or null to clear it. If the platform config sets + `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the card + and platform values. Limits are supported only for card programs where + Grid makes the authorization decision. `maxSpendPerTransaction` cannot be + supplied alongside `state: CLOSED`. This endpoint is authenticated by the platform credential alone and diff --git a/openapi/paths/platform/config.yaml b/openapi/paths/platform/config.yaml index 5774c63d3..e9fb7fd8f 100644 --- a/openapi/paths/platform/config.yaml +++ b/openapi/paths/platform/config.yaml @@ -27,7 +27,11 @@ get: $ref: ../../components/schemas/errors/Error500.yaml patch: summary: Update platform configuration - description: Update the platform configuration settings + description: >- + Update platform configuration settings. Setting + `cardConfigs.maxSpendPerTransaction` establishes a platform-level card + cap; Grid enforces the lower of that cap and each card's configured + `maxSpendPerTransaction` without replacing the card-specific value. operationId: updatePlatformConfig tags: - Platform Configuration @@ -74,6 +78,8 @@ patch: sms: templateSid: HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bodyText: Use this code to finish adding your Acme card to your digital wallet. + cardConfigs: + maxSpendPerTransaction: 10000 responses: '200': description: Configuration updated successfully