Platform Configuration

Update platform configuration

Changed on

Update platform configuration settings. cardConfigs can establish platform-level caps on a single card transaction, on spend during one UTC calendar day, and on the number of transactions during one UTC calendar day. Grid enforces the lower of each platform cap and its corresponding card-specific value without replacing the card-specific value. Daily limits reset at 00:00 UTC.

patch/config

Request

  • Base URL: https://api.lightspark.com/grid/2025-10-13
  • URL: https://api.lightspark.com/grid/2025-10-13/config
  • Auth: HTTP basic

Request body

umaDomainstring
webhookEndpointstring

Example request

{
  "umaDomain": "mycompany.com",
  "webhookEndpoint": "https://api.mycompany.com/webhooks/uma",
  "supportedCurrencies": [
    {
      "currencyCode": "USD",
      "minAmount": 100,
      "maxAmount": 1000000,
      "requiredCounterpartyFields": [
        {
          "name": "FULL_NAME",
          "mandatory": true
        },
        {
          "name": "BIRTH_DATE",
          "mandatory": true
        },
        {
          "name": "NATIONALITY",
          "mandatory": true
        }
      ],
      "providerRequiredCustomerFields": [
        "NATIONALITY",
        "BIRTH_DATE"
      ],
      "providerRequiredCounterpartyCustomerFields": [
        "FULL_NAME",
        "COUNTRY_OF_RESIDENCE"
      ],
      "enabledTransactionTypes": [
        "OUTGOING",
        "INCOMING"
      ]
    }
  ],
  "embeddedWalletConfig": {
    "appName": "Acme Wallet",
    "otpLength": 6,
    "expirationSeconds": 300,
    "sendFromEmailAddress": "noreply@acme.com",
    "sendFromEmailSenderName": "Acme Notifications",
    "replyToEmailAddress": "support@acme.com",
    "logoUrl": "https://acme.com/logo.png"
  },
  "cardTokenization2faConfig": {
    "displayName": "Acme",
    "logoUrl": "https://acme.com/card-email-logo.png",
    "email": {
      "fromAddress": "cards@acme.com",
      "fromName": "Acme Cards",
      "replyToAddress": "support@acme.com",
      "subject": "Your Acme card verification code",
      "bodyText": "Use this code to finish adding your Acme card to your digital wallet."
    },
    "sms": {
      "templateSid": "HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "bodyText": "Use this code to finish adding your Acme card to your digital wallet."
    }
  },
  "cardConfigs": {
    "maxSpendPerTransaction": 10000,
    "maxSpendPerDay": 50000,
    "maxTransactionsPerDay": 50,
    "panRevealCssUrl": "https://acme.com/card-reveal.css"
  },
  "feeConfigs": [
    {
      "feeType": "CROSS_CURRENCY_TRANSACTION",
      "variableFeeBps": 30,
      "fixedFee": {
        "amount": 100,
        "currency": "USD"
      },
      "sourceCurrency": "USD"
    }
  ]
}

Response

Configuration updated successfully

idstring

System-generated unique identifier

umaDomainstring

UMA domain for this platform

proxyUmaSubdomainstring

The subdomain that incoming requests will be proxied to

webhookEndpointstring

URL where webhook notifications will be sent

isRegulatedFinancialInstitutionboolean

Whether the platform is a regulated financial institution. This is used to determine if the platform's customers must be KYC/KYB'd by Lightspark via the KYC link flow. This can only be set by Lightspark during platform creation.

createdAtstring date-time

Creation timestamp

updatedAtstring date-time

Last update timestamp

Example response

{
  "id": "PlatformConfig:019542f5-b3e7-1d02-0000-000000000003",
  "umaDomain": "platform.uma.domain",
  "proxyUmaSubdomain": "platform",
  "webhookEndpoint": "https://api.mycompany.com/webhooks/uma",
  "supportedCurrencies": [
    {
      "currencyCode": "USD",
      "minAmount": 100,
      "maxAmount": 1000000,
      "requiredCounterpartyFields": [
        {
          "name": "FULL_NAME",
          "mandatory": true
        },
        {
          "name": "BIRTH_DATE",
          "mandatory": true
        },
        {
          "name": "NATIONALITY",
          "mandatory": true
        }
      ],
      "providerRequiredCustomerFields": [
        "NATIONALITY",
        "BIRTH_DATE"
      ],
      "providerRequiredCounterpartyCustomerFields": [
        "FULL_NAME",
        "COUNTRY_OF_RESIDENCE"
      ],
      "enabledTransactionTypes": [
        "OUTGOING",
        "INCOMING"
      ]
    }
  ],
  "embeddedWalletConfig": {
    "appName": "Acme Wallet",
    "otpLength": 6,
    "expirationSeconds": 300,
    "sendFromEmailAddress": "noreply@acme.com",
    "sendFromEmailSenderName": "Acme Notifications",
    "replyToEmailAddress": "support@acme.com",
    "logoUrl": "https://acme.com/logo.png"
  },
  "cardTokenization2faConfig": {
    "displayName": "Acme",
    "logoUrl": "https://acme.com/card-email-logo.png",
    "email": {
      "fromAddress": "cards@acme.com",
      "fromName": "Acme Cards",
      "replyToAddress": "support@acme.com",
      "subject": "Your Acme card verification code",
      "bodyText": "Use this code to finish adding your Acme card to your digital wallet."
    },
    "sms": {
      "templateSid": "HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "bodyText": "Use this code to finish adding your Acme card to your digital wallet."
    }
  },
  "cardConfigs": {
    "maxSpendPerTransaction": 10000,
    "maxSpendPerDay": 50000,
    "maxTransactionsPerDay": 50,
    "panRevealCssUrl": "https://acme.com/card-reveal.css"
  },
  "feeConfigs": [
    {
      "feeType": "CROSS_CURRENCY_TRANSACTION",
      "variableFeeBps": 30,
      "fixedFee": {
        "amount": 100,
        "currency": "USD"
      },
      "sourceCurrency": "USD"
    }
  ],
  "createdAt": "2025-06-15T12:30:45Z",
  "updatedAt": "2025-06-15T12:30:45Z"
}

Changes

  • 556180e5b2aeRevision changes
    • warning

      added the new ACH_SAME_DAY enum value to the /////// response property for the response status

    • info

      added the new optional request property /

    • info

      added the new ACH_SAME_DAY enum value to the request property ///////

    • info

      added the optional property / to the response with the status

  • 3966e5d38aadRevision changes
    • breaking

      added the pattern ^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$ to the request property

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      the request property's maxLength was set to 200

    • warning

      added the new INSUFFICIENT_FUNDS enum value to the response property for the response status

    • warning

      added the new QUOTE_EXPIRED enum value to the response property for the response status

    • warning

      added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status

    • warning

      added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status

    • warning

      added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status

    • warning

      added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status

    • warning

      added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status

    • warning

      added the new UNRECOGNIZED_MANDATORY_COUNTERPARTY_DATA_KEY enum value to the response property for the response status

    • info

      the response's property pattern ^[^\u0000-\u001f\u007f]*$ was added for the status

    • info

      the response's property pattern ^[^\u0000-\u001f\u007f]*$ was added for the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status