Update platform configuration

Update platform configuration settings. Configure platform-wide card velocity limits through POST /card-velocity-limits without cardId. cardConfigs contains card presentation, authentication, risk, and merchant category settings. Set cardConfigs.allowedMccs and cardConfigs.blockedMccs to restrict new authorizations on this platform’s cards where Grid makes authorization decisions. Card restrictions and Lightspark’s controls also apply.

Set cardConfigs.pinTargetOrigin to the canonical HTTPS origin of your frontend before calling GET /cards/{id}/pin-entry-url. Omit the field to preserve its value or set it to null to clear it.

Set cardConfigs.realTimeAuthorization to enable real-time card authorization: Grid sends a CARD_AUTHORIZATION.REQUEST decision request to your webhookEndpoint for each card authorization.

PATCH /config

Update platform configuration

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/config \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "umaDomain": "mycompany.com",
  "webhookEndpoint": "https://api.mycompany.com/webhooks/uma",
  "supportedCurrencies": [
    {
      "currencyCode": "USD",
      "minAmount": 100,
      "maxAmount": 1000000,
      "enabledTransactionTypes": [
        "OUTGOING",
        "INCOMING"
      ],
      "requiredCounterpartyFields": [
        {
          "name": "FULL_NAME",
          "mandatory": true
        },
        {
          "name": "NATIONALITY",
          "mandatory": true
        },
        {
          "name": "BIRTH_DATE",
          "mandatory": true
        }
      ]
    }
  ],
  "embeddedWalletConfig": {
    "appName": "Acme Wallet",
    "sendFromEmailAddress": "[e-mail]",
    "sendFromEmailSenderName": "Acme Notifications",
    "replyToEmailAddress": "[e-mail]",
    "logoUrl": "https://acme.com/logo.png"
  },
  "cardTokenization2faConfig": {
    "displayName": "Acme",
    "logoUrl": "https://acme.com/card-email-logo.png",
    "email": {
      "fromAddress": "[e-mail]",
      "fromName": "Acme Cards",
      "replyToAddress": "[e-mail]",
      "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": {
    "pinTargetOrigin": "https://app.example.com",
    "realTimeAuthorization": {
      "timeoutBehavior": "DECLINE"
    }
  }
}
'

200

{
  "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
        }
      ],
      "enabledTransactionTypes": [
        "OUTGOING",
        "INCOMING"
      ],
      "providerRequiredCustomerFields": [
        "NATIONALITY",
        "BIRTH_DATE"
      ],
      "providerRequiredCounterpartyCustomerFields": [
        "FULL_NAME",
        "COUNTRY_OF_RESIDENCE"
      ]
    }
  ],
  "isRegulatedFinancialInstitution": false,
  "embeddedWalletConfig": {
    "appName": "Acme Wallet",
    "otpLength": 6,
    "alphanumeric": false,
    "expirationSeconds": 300,
    "sendFromEmailAddress": "[e-mail]",
    "sendFromEmailSenderName": "Acme Notifications",
    "replyToEmailAddress": "[e-mail]",
    "logoUrl": "https://acme.com/logo.png"
  },
  "cardTokenization2faConfig": {
    "displayName": "Acme",
    "logoUrl": "https://acme.com/card-email-logo.png",
    "email": {
      "fromAddress": "[e-mail]",
      "fromName": "Acme Cards",
      "replyToAddress": "[e-mail]",
      "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": {
    "pinTargetOrigin": "https://app.example.com",
    "maxNetworkRiskScore": 700,
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "panRevealCssUrl": "https://acme.com/card-reveal.css",
    "realTimeAuthorization": {
      "timeoutBehavior": "DECLINE"
    }
  },
  "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"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Body

application/json

umaDomain · string

Maximum string length: 200

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])?)*$

Example:

"mycompany.com"

webhookEndpoint · string

Example:

"https://api.mycompany.com/webhooks/uma"

supportedCurrencies · object[]

Show child attributes

embeddedWalletConfig · object

Update or create the embedded-wallet configuration for this platform. Fields omitted from the nested object are left unchanged. Omit this field at the top level to leave the embedded-wallet configuration unchanged entirely.

Show child attributes

cardTokenization2faConfig · object

Update card-tokenization authentication branding and delivery settings. Fields omitted from the nested object are left unchanged. Changes apply to subsequent delivery attempts.

Show child attributes

cardConfigs · object

Update platform-level card settings. Fields omitted from the nested object are left unchanged. Set each limit within its documented range, or send null to clear it. Set pinTargetOrigin to configure the website that hosts PIN-entry iframes, or supply null to clear it. Omit this field at the top level to leave all card settings unchanged.

Show child attributes

feeConfigs · object[]

Merge-by-key upsert of platform fee configs. A cross-currency transaction fee config is keyed by (feeType, sourceCurrency) and a rail fee config by (feeType, rail, direction, originator). Setting variable and fixed fees to 0 for an existing config deactivates it. Omit this field to leave fee configs unchanged.

A fee charged for a cross-currency transaction. There can be at most one cross-currency transaction fee config for a given source currency. The fee will apply to all cross-currency transactions that originate in the source currency.

Option 1

Option 2

Show child attributes

Response

200

application/json

Configuration updated successfully

id · string

System-generated unique identifier

Example:

"PlatformConfig:019542f5-b3e7-1d02-0000-000000000003"

umaDomain · string

UMA domain for this platform

Maximum string length: 200

Pattern: ^[^\u0000-\u001f\u007f]*$

Example:

"platform.uma.domain"

proxyUmaSubdomain · string

The subdomain that incoming requests will be proxied to

Maximum string length: 200

Pattern: ^[^\u0000-\u001f\u007f]*$

Example:

"platform"

webhookEndpoint · string

URL where webhook notifications will be sent

Example:

"https://api.mycompany.com/webhooks/uma"

supportedCurrencies · object[]

List of currencies supported by the platform. This is what the platform's customers are able to hold, send, and receive.

Show child attributes

isRegulatedFinancialInstitution · boolean

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.

Example:

false

embeddedWalletConfig · object

Embedded-wallet branding and OTP settings for this platform. Present only when the platform has configured embedded-wallet support; omitted otherwise.

Show child attributes

cardTokenization2faConfig · object

Branding and sender configuration for card-tokenization authentication messages. This configuration is independent of embedded-wallet support.

Show child attributes

cardConfigs · object

Platform-level settings for cards issued by this platform.

Show child attributes

feeConfigs · object[]

Platform-collected fees that should be added on top of Grid-collected fees. Contains every currently-active fee config for the platform.

A fee charged for a cross-currency transaction. There can be at most one cross-currency transaction fee config for a given source currency. The fee will apply to all cross-currency transactions that originate in the source currency.

Option 1

Option 2

Show child attributes

createdAt · string<date-time>

Creation timestamp

Example:

"2025-06-15T12:30:45Z"

updatedAt · string<date-time>

Last update timestamp

Example:

"2025-06-15T12:30:45Z"