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": "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
  }
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const platformConfig = await client.config.update({
  cardConfigs: {
    maxSpendPerTransaction: 10000,
    maxSpendPerDay: 50000,
    maxTransactionsPerDay: 50,
  },
  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.',
    },
  },
  embeddedWalletConfig: {
    appName: 'Acme Wallet',
    sendFromEmailAddress: 'noreply@acme.com',
    sendFromEmailSenderName: 'Acme Notifications',
    replyToEmailAddress: 'support@acme.com',
    logoUrl: 'https://acme.com/logo.png',
  },
  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 },
      ],
    },
  ],
  umaDomain: 'mycompany.com',
  webhookEndpoint: 'https://api.mycompany.com/webhooks/uma',
});

console.log(platformConfig.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.config.PlatformConfig
import com.lightspark.grid.models.config.PlatformConfigUpdateRequest

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: PlatformConfigUpdateRequest = PlatformConfigUpdateRequest.builder().build()
    val platformConfig: PlatformConfig = client.config().update(params)
}

{
  "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": "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
  },
  "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"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

{
  "status": 501,
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "message": "<string>",
  "details": {}
}

PATCH

config

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": "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
  }
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const platformConfig = await client.config.update({
  cardConfigs: {
    maxSpendPerTransaction: 10000,
    maxSpendPerDay: 50000,
    maxTransactionsPerDay: 50,
  },
  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.',
    },
  },
  embeddedWalletConfig: {
    appName: 'Acme Wallet',
    sendFromEmailAddress: 'noreply@acme.com',
    sendFromEmailSenderName: 'Acme Notifications',
    replyToEmailAddress: 'support@acme.com',
    logoUrl: 'https://acme.com/logo.png',
  },
  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 },
      ],
    },
  ],
  umaDomain: 'mycompany.com',
  webhookEndpoint: 'https://api.mycompany.com/webhooks/uma',
});

console.log(platformConfig.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.config.PlatformConfig
import com.lightspark.grid.models.config.PlatformConfigUpdateRequest

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: PlatformConfigUpdateRequest = PlatformConfigUpdateRequest.builder().build()
    val platformConfig: PlatformConfig = client.config().update(params)
}

{
  "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": "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
  },
  "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"
}

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "message": "<string>",
  "details": {}
}

{
  "status": 501,
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

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

Body

application/json

umaDomain

string

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. For any card limit, 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.

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

Configuration updated successfully

string

System-generated unique identifier

Example:

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

umaDomain

string

UMA domain for this platform

Example:

"platform.uma.domain"

proxyUmaSubdomain

string

The subdomain that incoming requests will be proxied to

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.

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"

Using the API

API documentation

Authorizations

Body

Response