diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 9beb0ec97..8e1e0cb18 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -8895,6 +8895,90 @@ components: maxLength: 512 description: URL to a PNG logo for the OTP email. Resized to 340x124px. example: https://acme.com/logo.png + TransactionFeeEventType: + type: string + enum: + - CROSS_CURRENCY_TRANSACTION + - TRANSFER_OUT_TRANSACTION + description: | + The kind of transaction this fee applies to. + + - `CROSS_CURRENCY_TRANSACTION` — fee charged on a cross-currency Grid send + (source currency differs from destination currency). + - `TRANSFER_OUT_TRANSACTION` — fee charged on a Grid Transfer Out + operation. + + Note: only `CROSS_CURRENCY_TRANSACTION` is accepted by `PATCH /config` + today. Reads always return the full set, so configurations created by + Lightspark operators (e.g. Transfer Out rows) are still visible. + example: CROSS_CURRENCY_TRANSACTION + Currency: + type: object + properties: + code: + type: string + description: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) + example: USD + name: + type: string + description: Full name of the currency + example: United States Dollar + symbol: + type: string + description: Symbol of the currency + example: $ + decimals: + type: integer + description: Number of decimal places for the currency + minimum: 0 + example: 2 + CurrencyAmount: + type: object + required: + - amount + - currency + properties: + amount: + type: integer + format: int64 + description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) + example: 12550 + currency: + $ref: '#/components/schemas/Currency' + TransactionFeeConfig: + type: object + description: 'Platform-collected transaction fee charged on top of corridor fees. Keyed uniquely by `(feeEventType, sourceCurrency)` within a platform. To deactivate a fee, send the same key with `variableFeeBps: 0` and `fixedFee.amount: 0`.' + properties: + id: + type: string + description: System-generated unique identifier. + readOnly: true + example: TransactionFeeConfig:019542f5-b3e7-1d02-0000-000000000007 + feeEventType: + $ref: '#/components/schemas/TransactionFeeEventType' + sourceCurrency: + type: string + description: ISO 4217 (fiat) or ticker (crypto) code of the source-side currency this fee applies to. Cross-currency fees are charged in the sending side's currency. + example: USD + variableFeeBps: + type: integer + minimum: 0 + maximum: 10000 + description: Variable fee in basis points (1 bps = 0.01%). Multiplied by the transaction's source-currency amount. + example: 25 + fixedFee: + $ref: '#/components/schemas/CurrencyAmount' + description: Fixed fee charged per transaction, in the smallest unit of `sourceCurrency`. `fixedFee.currency.code` must match `sourceCurrency`. + isActive: + type: boolean + description: Whether this row is currently active. Reads return only active rows unless explicitly filtered otherwise. + readOnly: true + example: true + required: + - feeEventType + - sourceCurrency + - variableFeeBps + - fixedFee PlatformConfig: type: object properties: @@ -8936,6 +9020,15 @@ components: Embedded-wallet branding and OTP settings for this platform. Present only when the platform has configured embedded-wallet support; omitted otherwise. + transactionFeeConfigs: + type: array + items: + $ref: '#/components/schemas/TransactionFeeConfig' + description: | + Platform-collected transaction fees, keyed uniquely by + `(feeEventType, sourceCurrency)`. Returned in reads regardless of + `feeEventType` so that operator-created rows (e.g. Transfer Out) are + visible even before the corresponding write path is enabled. createdAt: type: string format: date-time @@ -9036,6 +9129,18 @@ components: Fields omitted from the nested object are left unchanged. Omit this field at the top level to leave the embedded-wallet configuration unchanged entirely. + transactionFeeConfigs: + type: array + items: + $ref: '#/components/schemas/TransactionFeeConfig' + description: | + Merge-by-key upsert of platform transaction fee configs. Each item is + keyed by `(feeEventType, sourceCurrency)`. To deactivate a fee, send + the same key with `variableFeeBps: 0` and `fixedFee.amount: 0`. Only + `feeEventType: CROSS_CURRENCY_TRANSACTION` and `sourceCurrency: USD` + are accepted by this endpoint today; other values return a 400 error. + Omit this field at the top level to leave all transaction fee configs + unchanged. Error400: type: object required: @@ -9168,26 +9273,6 @@ components: type: object description: Additional error details additionalProperties: true - Currency: - type: object - properties: - code: - type: string - description: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - example: USD - name: - type: string - description: Full name of the currency - example: United States Dollar - symbol: - type: string - description: Symbol of the currency - example: $ - decimals: - type: integer - description: Number of decimal places for the currency - minimum: 0 - example: 2 PaymentRail: type: string enum: @@ -10350,19 +10435,6 @@ components: - `CLOSED`: The account cannot send or receive payments. A customer can initiate the closing of an internal account, after which the account transitions to this status. - `FROZEN`: The account cannot send or receive payments. Grid may freeze an account in response to compliance or fraud signals; payments are blocked while the account remains frozen. example: ACTIVE - CurrencyAmount: - type: object - required: - - amount - - currency - properties: - amount: - type: integer - format: int64 - description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - example: 12550 - currency: - $ref: '#/components/schemas/Currency' PaymentAccountType: type: string enum: @@ -17227,6 +17299,12 @@ components: description: The fees associated with the quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 + platformFees: + type: integer + format: int64 + description: The portion of `fees` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `fees`. + minimum: 0 + example: 5 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Reconciliation details for this transaction, including crypto transaction hash when available. @@ -17813,6 +17891,12 @@ components: description: 'The fees associated with the quote in the smallest unit of the sending currency (eg. cents). Note: this value may fluctuate between quotes — some underlying fee components are defined in the receiving currency, so their equivalent in the sending currency moves with the FX rate. The fees shown here are locked only for the lifetime of this quote.' minimum: 0 example: 10 + platformFeesIncluded: + type: integer + format: int64 + description: The portion of `feesIncluded` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `feesIncluded`. + minimum: 0 + example: 5 paymentInstructions: type: array description: Payment instructions for executing the payment. This is not required when using an internal account source. diff --git a/openapi.yaml b/openapi.yaml index 9beb0ec97..8e1e0cb18 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -8895,6 +8895,90 @@ components: maxLength: 512 description: URL to a PNG logo for the OTP email. Resized to 340x124px. example: https://acme.com/logo.png + TransactionFeeEventType: + type: string + enum: + - CROSS_CURRENCY_TRANSACTION + - TRANSFER_OUT_TRANSACTION + description: | + The kind of transaction this fee applies to. + + - `CROSS_CURRENCY_TRANSACTION` — fee charged on a cross-currency Grid send + (source currency differs from destination currency). + - `TRANSFER_OUT_TRANSACTION` — fee charged on a Grid Transfer Out + operation. + + Note: only `CROSS_CURRENCY_TRANSACTION` is accepted by `PATCH /config` + today. Reads always return the full set, so configurations created by + Lightspark operators (e.g. Transfer Out rows) are still visible. + example: CROSS_CURRENCY_TRANSACTION + Currency: + type: object + properties: + code: + type: string + description: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) + example: USD + name: + type: string + description: Full name of the currency + example: United States Dollar + symbol: + type: string + description: Symbol of the currency + example: $ + decimals: + type: integer + description: Number of decimal places for the currency + minimum: 0 + example: 2 + CurrencyAmount: + type: object + required: + - amount + - currency + properties: + amount: + type: integer + format: int64 + description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) + example: 12550 + currency: + $ref: '#/components/schemas/Currency' + TransactionFeeConfig: + type: object + description: 'Platform-collected transaction fee charged on top of corridor fees. Keyed uniquely by `(feeEventType, sourceCurrency)` within a platform. To deactivate a fee, send the same key with `variableFeeBps: 0` and `fixedFee.amount: 0`.' + properties: + id: + type: string + description: System-generated unique identifier. + readOnly: true + example: TransactionFeeConfig:019542f5-b3e7-1d02-0000-000000000007 + feeEventType: + $ref: '#/components/schemas/TransactionFeeEventType' + sourceCurrency: + type: string + description: ISO 4217 (fiat) or ticker (crypto) code of the source-side currency this fee applies to. Cross-currency fees are charged in the sending side's currency. + example: USD + variableFeeBps: + type: integer + minimum: 0 + maximum: 10000 + description: Variable fee in basis points (1 bps = 0.01%). Multiplied by the transaction's source-currency amount. + example: 25 + fixedFee: + $ref: '#/components/schemas/CurrencyAmount' + description: Fixed fee charged per transaction, in the smallest unit of `sourceCurrency`. `fixedFee.currency.code` must match `sourceCurrency`. + isActive: + type: boolean + description: Whether this row is currently active. Reads return only active rows unless explicitly filtered otherwise. + readOnly: true + example: true + required: + - feeEventType + - sourceCurrency + - variableFeeBps + - fixedFee PlatformConfig: type: object properties: @@ -8936,6 +9020,15 @@ components: Embedded-wallet branding and OTP settings for this platform. Present only when the platform has configured embedded-wallet support; omitted otherwise. + transactionFeeConfigs: + type: array + items: + $ref: '#/components/schemas/TransactionFeeConfig' + description: | + Platform-collected transaction fees, keyed uniquely by + `(feeEventType, sourceCurrency)`. Returned in reads regardless of + `feeEventType` so that operator-created rows (e.g. Transfer Out) are + visible even before the corresponding write path is enabled. createdAt: type: string format: date-time @@ -9036,6 +9129,18 @@ components: Fields omitted from the nested object are left unchanged. Omit this field at the top level to leave the embedded-wallet configuration unchanged entirely. + transactionFeeConfigs: + type: array + items: + $ref: '#/components/schemas/TransactionFeeConfig' + description: | + Merge-by-key upsert of platform transaction fee configs. Each item is + keyed by `(feeEventType, sourceCurrency)`. To deactivate a fee, send + the same key with `variableFeeBps: 0` and `fixedFee.amount: 0`. Only + `feeEventType: CROSS_CURRENCY_TRANSACTION` and `sourceCurrency: USD` + are accepted by this endpoint today; other values return a 400 error. + Omit this field at the top level to leave all transaction fee configs + unchanged. Error400: type: object required: @@ -9168,26 +9273,6 @@ components: type: object description: Additional error details additionalProperties: true - Currency: - type: object - properties: - code: - type: string - description: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - example: USD - name: - type: string - description: Full name of the currency - example: United States Dollar - symbol: - type: string - description: Symbol of the currency - example: $ - decimals: - type: integer - description: Number of decimal places for the currency - minimum: 0 - example: 2 PaymentRail: type: string enum: @@ -10350,19 +10435,6 @@ components: - `CLOSED`: The account cannot send or receive payments. A customer can initiate the closing of an internal account, after which the account transitions to this status. - `FROZEN`: The account cannot send or receive payments. Grid may freeze an account in response to compliance or fraud signals; payments are blocked while the account remains frozen. example: ACTIVE - CurrencyAmount: - type: object - required: - - amount - - currency - properties: - amount: - type: integer - format: int64 - description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) - example: 12550 - currency: - $ref: '#/components/schemas/Currency' PaymentAccountType: type: string enum: @@ -17227,6 +17299,12 @@ components: description: The fees associated with the quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 + platformFees: + type: integer + format: int64 + description: The portion of `fees` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `fees`. + minimum: 0 + example: 5 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Reconciliation details for this transaction, including crypto transaction hash when available. @@ -17813,6 +17891,12 @@ components: description: 'The fees associated with the quote in the smallest unit of the sending currency (eg. cents). Note: this value may fluctuate between quotes — some underlying fee components are defined in the receiving currency, so their equivalent in the sending currency moves with the FX rate. The fees shown here are locked only for the lifetime of this quote.' minimum: 0 example: 10 + platformFeesIncluded: + type: integer + format: int64 + description: The portion of `feesIncluded` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `feesIncluded`. + minimum: 0 + example: 5 paymentInstructions: type: array description: Payment instructions for executing the payment. This is not required when using an internal account source. diff --git a/openapi/components/schemas/config/PlatformConfig.yaml b/openapi/components/schemas/config/PlatformConfig.yaml index a1a0cd90f..80766083e 100644 --- a/openapi/components/schemas/config/PlatformConfig.yaml +++ b/openapi/components/schemas/config/PlatformConfig.yaml @@ -38,6 +38,15 @@ properties: Embedded-wallet branding and OTP settings for this platform. Present only when the platform has configured embedded-wallet support; omitted otherwise. + transactionFeeConfigs: + type: array + items: + $ref: ./TransactionFeeConfig.yaml + description: | + Platform-collected transaction fees, keyed uniquely by + `(feeEventType, sourceCurrency)`. Returned in reads regardless of + `feeEventType` so that operator-created rows (e.g. Transfer Out) are + visible even before the corresponding write path is enabled. createdAt: type: string format: date-time diff --git a/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml b/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml index 9222e4c18..ac4e6fd10 100644 --- a/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml +++ b/openapi/components/schemas/config/PlatformConfigUpdateRequest.yaml @@ -17,3 +17,15 @@ properties: Fields omitted from the nested object are left unchanged. Omit this field at the top level to leave the embedded-wallet configuration unchanged entirely. + transactionFeeConfigs: + type: array + items: + $ref: ./TransactionFeeConfig.yaml + description: | + Merge-by-key upsert of platform transaction fee configs. Each item is + keyed by `(feeEventType, sourceCurrency)`. To deactivate a fee, send + the same key with `variableFeeBps: 0` and `fixedFee.amount: 0`. Only + `feeEventType: CROSS_CURRENCY_TRANSACTION` and `sourceCurrency: USD` + are accepted by this endpoint today; other values return a 400 error. + Omit this field at the top level to leave all transaction fee configs + unchanged. diff --git a/openapi/components/schemas/config/TransactionFeeConfig.yaml b/openapi/components/schemas/config/TransactionFeeConfig.yaml new file mode 100644 index 000000000..e3a4e21e4 --- /dev/null +++ b/openapi/components/schemas/config/TransactionFeeConfig.yaml @@ -0,0 +1,46 @@ +type: object +description: >- + Platform-collected transaction fee charged on top of corridor fees. Keyed + uniquely by `(feeEventType, sourceCurrency)` within a platform. To + deactivate a fee, send the same key with `variableFeeBps: 0` and + `fixedFee.amount: 0`. +properties: + id: + type: string + description: System-generated unique identifier. + readOnly: true + example: TransactionFeeConfig:019542f5-b3e7-1d02-0000-000000000007 + feeEventType: + $ref: ./TransactionFeeEventType.yaml + sourceCurrency: + type: string + description: >- + ISO 4217 (fiat) or ticker (crypto) code of the source-side currency this + fee applies to. Cross-currency fees are charged in the sending side's + currency. + example: USD + variableFeeBps: + type: integer + minimum: 0 + maximum: 10000 + description: >- + Variable fee in basis points (1 bps = 0.01%). Multiplied by the + transaction's source-currency amount. + example: 25 + fixedFee: + $ref: ../common/CurrencyAmount.yaml + description: >- + Fixed fee charged per transaction, in the smallest unit of + `sourceCurrency`. `fixedFee.currency.code` must match `sourceCurrency`. + isActive: + type: boolean + description: >- + Whether this row is currently active. Reads return only active rows + unless explicitly filtered otherwise. + readOnly: true + example: true +required: + - feeEventType + - sourceCurrency + - variableFeeBps + - fixedFee diff --git a/openapi/components/schemas/config/TransactionFeeEventType.yaml b/openapi/components/schemas/config/TransactionFeeEventType.yaml new file mode 100644 index 000000000..0a44a2573 --- /dev/null +++ b/openapi/components/schemas/config/TransactionFeeEventType.yaml @@ -0,0 +1,16 @@ +type: string +enum: + - CROSS_CURRENCY_TRANSACTION + - TRANSFER_OUT_TRANSACTION +description: | + The kind of transaction this fee applies to. + + - `CROSS_CURRENCY_TRANSACTION` — fee charged on a cross-currency Grid send + (source currency differs from destination currency). + - `TRANSFER_OUT_TRANSACTION` — fee charged on a Grid Transfer Out + operation. + + Note: only `CROSS_CURRENCY_TRANSACTION` is accepted by `PATCH /config` + today. Reads always return the full set, so configurations created by + Lightspark operators (e.g. Transfer Out rows) are still visible. +example: CROSS_CURRENCY_TRANSACTION diff --git a/openapi/components/schemas/quotes/Quote.yaml b/openapi/components/schemas/quotes/Quote.yaml index aee147bbc..a021c0aad 100644 --- a/openapi/components/schemas/quotes/Quote.yaml +++ b/openapi/components/schemas/quotes/Quote.yaml @@ -87,6 +87,16 @@ properties: The fees shown here are locked only for the lifetime of this quote. minimum: 0 example: 10 + platformFeesIncluded: + type: integer + format: int64 + description: >- + The portion of `feesIncluded` collected by the platform + (platform-configured transaction fees), in the smallest unit of the + sending currency. 0 when the platform has no applicable fee configured. + Already included in `feesIncluded`. + minimum: 0 + example: 5 paymentInstructions: type: array description: Payment instructions for executing the payment. This is not required when using an internal account source. diff --git a/openapi/components/schemas/transactions/OutgoingTransaction.yaml b/openapi/components/schemas/transactions/OutgoingTransaction.yaml index b6ff7eb16..26571ff1c 100644 --- a/openapi/components/schemas/transactions/OutgoingTransaction.yaml +++ b/openapi/components/schemas/transactions/OutgoingTransaction.yaml @@ -34,6 +34,16 @@ allOf: currency (eg. cents). minimum: 0 example: 10 + platformFees: + type: integer + format: int64 + description: >- + The portion of `fees` collected by the platform (platform-configured + transaction fees), in the smallest unit of the sending currency. 0 + when the platform has no applicable fee configured. Already included + in `fees`. + minimum: 0 + example: 5 reconciliationInstructions: $ref: ../common/ReconciliationInstructions.yaml description: >-