Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard.
openapi: 3.1.0
info:
title: Grid Agent Management Platform Configuration API
description: 'API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/.
'
version: '2025-10-13'
contact:
name: Lightspark Support
email: support@lightspark.com
license:
name: Proprietary
url: https://lightspark.com/terms
servers:
- url: https://api.lightspark.com/grid/2025-10-13
description: Production server
security:
- BasicAuth: []
- AgentAuth: []
tags:
- name: Platform Configuration
description: Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard.
paths:
/config:
get:
summary: Get platform configuration
description: Retrieve the current platform configuration
operationId: getPlatformConfig
tags:
- Platform Configuration
security:
- BasicAuth: []
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformConfig'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
patch:
summary: Update platform configuration
description: Update the platform configuration settings
operationId: updatePlatformConfig
tags:
- Platform Configuration
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformConfigUpdateRequest'
example:
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
responses:
'200':
description: Configuration updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformConfig'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: Not implemented
content:
application/json:
schema:
$ref: '#/components/schemas/Error501'
components:
schemas:
EmbeddedWalletConfig:
type: object
description: 'Per-platform embedded-wallet configuration. Controls branding and OTP
behavior for the email sent when a customer authenticates with an
EMAIL_OTP credential. Fields omitted from a request are left unchanged.
'
properties:
appName:
type: string
maxLength: 255
description: App name displayed in the default OTP email template.
example: Acme Wallet
otpLength:
type: integer
minimum: 4
maximum: 12
description: 'Number of digits / characters in the OTP code. Defaults to 6 when
not set.
'
example: 6
alphanumeric:
type: boolean
description: 'If true, OTP includes letters in addition to digits. Defaults to
numeric-only when not set.
'
example: false
expirationSeconds:
type: integer
minimum: 1
maximum: 86400
description: 'OTP validity window in seconds. Defaults to 300 when not set.
'
example: 300
sendFromEmailAddress:
type: string
format: email
maxLength: 255
description: Custom sender email address for OTP emails.
example: noreply@acme.com
sendFromEmailSenderName:
type: string
maxLength: 255
description: 'Custom sender display name. Defaults to "Notifications" when not set.
'
example: Acme Notifications
replyToEmailAddress:
type: string
format: email
maxLength: 255
description: Custom reply-to email address for OTP emails.
example: support@acme.com
logoUrl:
type: string
format: uri
maxLength: 512
description: URL to a PNG logo for the OTP email. Resized to 340x124px.
example: https://acme.com/logo.png
Error501:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 501
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY | Unrecognized mandatory payee data key |
| NOT_IMPLEMENTED | Feature not implemented |
'
enum:
- UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY
- NOT_IMPLEMENTED
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
TransactionType:
type: string
enum:
- INCOMING
- OUTGOING
description: Type of transaction (incoming payment or outgoing payment)
Error401:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 401
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| UNAUTHORIZED | Issue with API credentials |
| INVALID_SIGNATURE | Signature header is invalid |
| WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied |
| WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) |
| WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received |
| WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential |
| REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) |
'
enum:
- UNAUTHORIZED
- INVALID_SIGNATURE
- WALLET_SIGNATURE_MISSING
- WALLET_SIGNATURE_MALFORMED
- WALLET_SIGNATURE_BODY_MISMATCH
- WALLET_SIGNATURE_INVALID
- REQUEST_ID_MISSING
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
Error400:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 400
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| INVALID_INPUT | Invalid input provided |
| MISSING_MANDATORY_USER_INFO | Required customer information is missing |
| INVITATION_ALREADY_CLAIMED | Invitation has already been claimed |
| INVITATIONS_NOT_CONFIGURED | Invitations are not configured |
| INVALID_UMA_ADDRESS | UMA address format is invalid |
| INVITATION_CANCELLED | Invitation has been cancelled |
| QUOTE_REQUEST_FAILED | An issue occurred during the quote process; this is retryable |
| INVALID_PAYREQ_RESPONSE | Counterparty Payreq response was invalid |
| INVALID_RECEIVER | Receiver is invalid |
| PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response |
| CERT_CHAIN_INVALID | Counterparty certificate chain is invalid |
| CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired |
| INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid |
| MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing |
| SENDER_NOT_ACCEPTED | Sender is not accepted |
| AMOUNT_OUT_OF_RANGE | Amount is out of range |
| INVALID_CURRENCY | Currency is invalid |
| INVALID_TIMESTAMP | Timestamp is invalid |
| INVALID_NONCE | Nonce is invalid |
| INVALID_REQUEST_FORMAT | Request format is invalid |
| INVALID_BANK_ACCOUNT | Bank account is invalid |
| SELF_PAYMENT | Self payment not allowed |
| LOOKUP_REQUEST_FAILED | Lookup request failed |
| PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response |
| INVALID_AMOUNT | Amount is invalid |
| WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set |
| WEBHOOK_DELIVERY_ERROR | Webhook delivery error |
| LOW_QUALITY | Document quality too low to process |
| DATA_MISMATCH | Document details don''t match provided information |
| EXPIRED | Document has expired |
| SUSPECTED_FRAUD | Document suspected of being forged or edited |
| UNSUITABLE_DOCUMENT | Document type is not accepted or not supported |
| INCOMPLETE | Document is missing pages or sides |
| EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time |
| SMS_OTP_CREDENTIAL_ALREADY_EXISTS | An SMS_OTP credential is already registered on the target internal account; only one SMS OTP credential is supported per internal account at this time |
| PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account |
| STABLECOIN_PROVIDER_ACCOUNT_INVALID | The stablecoin provider account link is not usable |
| STABLECOIN_PROVIDER_ACCOUNT_REVOKED | The stablecoin provider account link has been revoked |
| STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED | Multiple active provider account links exist; pass `stablecoinProviderAccountId` to select one |
'
enum:
- INVALID_INPUT
- MISSING_MANDATORY_USER_INFO
- INVITATION_ALREADY_CLAIMED
- INVITATIONS_NOT_CONFIGURED
- INVALID_UMA_ADDRESS
- INVITATION_CANCELLED
- QUOTE_REQUEST_FAILED
- INVALID_PAYREQ_RESPONSE
- INVALID_RECEIVER
- PARSE_PAYREQ_RESPONSE_ERROR
- CERT_CHAIN_INVALID
- CERT_CHAIN_EXPIRED
- INVALID_PUBKEY_FORMAT
- MISSING_REQUIRED_UMA_PARAMETERS
- SENDER_NOT_ACCEPTED
- AMOUNT_OUT_OF_RANGE
- INVALID_CURRENCY
- INVALID_TIMESTAMP
- INVALID_NONCE
- INVALID_REQUEST_FORMAT
- INVALID_BANK_ACCOUNT
- SELF_PAYMENT
- LOOKUP_REQUEST_FAILED
- PARSE_LNURLP_RESPONSE_ERROR
- INVALID_AMOUNT
- WEBHOOK_ENDPOINT_NOT_SET
- WEBHOOK_DELIVERY_ERROR
- LOW_QUALITY
- DATA_MISMATCH
- EXPIRED
- SUSPECTED_FRAUD
- UNSUITABLE_DOCUMENT
- INCOMPLETE
- EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS
- SMS_OTP_CREDENTIAL_ALREADY_EXISTS
- PASSKEY_CREDENTIAL_ALREADY_EXISTS
- STABLECOIN_PROVIDER_ACCOUNT_INVALID
- STABLECOIN_PROVIDER_ACCOUNT_REVOKED
- STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
PlatformConfigUpdateRequest:
type: object
properties:
umaDomain:
type: string
example: mycompany.com
webhookEndpoint:
type: string
example: https://api.mycompany.com/webhooks/uma
supportedCurrencies:
type: array
items:
$ref: '#/components/schemas/PlatformCurrencyConfig'
embeddedWalletConfig:
$ref: '#/components/schemas/EmbeddedWalletConfig'
description: '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.
'
CounterpartyFieldDefinition:
type: object
properties:
name:
$ref: '#/components/schemas/CustomerInfoFieldName'
mandatory:
type: boolean
description: Whether the field is mandatory
example: true
required:
- name
- mandatory
PlatformCurrencyConfig:
type: object
properties:
currencyCode:
type: string
description: Three-letter currency code (ISO 4217)
example: USD
minAmount:
type: integer
format: int64
description: Minimum amount that can be sent in the smallest unit of this currency
minimum: 0
example: 100
maxAmount:
type: integer
format: int64
description: Maximum amount that can be sent in the smallest unit of this currency
minimum: 0
example: 1000000
requiredCounterpartyFields:
type: array
items:
$ref: '#/components/schemas/CounterpartyFieldDefinition'
description: List of fields which the platform requires from the counterparty institutions about counterparty customers. Platforms can set mandatory to false if the platform does not require the field, but would like to have it available. Some fields may be required by the underlying UMA provider.
example:
- name: FULL_NAME
mandatory: true
- name: BIRTH_DATE
mandatory: true
- name: NATIONALITY
mandatory: true
providerRequiredCustomerFields:
type: array
items:
$ref: '#/components/schemas/CustomerInfoFieldName'
description: List of customer info field names that are required by the underlying UMA provider when creating a customer for this currency. These fields must be supplied when creating or updating a customer if this currency is intended to be used by that customer. If no fields are required, this field is omitted.
readOnly: true
example:
- NATIONALITY
- BIRTH_DATE
providerRequiredCounterpartyCustomerFields:
type: array
items:
$ref: '#/components/schemas/CustomerInfoFieldName'
description: List of fields that are required by the underlying UMA provider for this currency. If the counterparty does not provide these fields, quote requests will fail.
readOnly: true
example:
- FULL_NAME
- COUNTRY_OF_RESIDENCE
enabledTransactionTypes:
type: array
items:
$ref: '#/components/schemas/TransactionType'
description: List of transaction types that are enabled for this currency.
example:
- OUTGOING
- INCOMING
required:
- currencyCode
- minAmount
- maxAmount
- requiredCounterpartyFields
- enabledTransactionTypes
Error500:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 500
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| GRID_SWITCH_ERROR | Grid switch error |
| INTERNAL_ERROR | Internal server or UMA error |
'
enum:
- GRID_SWITCH_ERROR
- INTERNAL_ERROR
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
PlatformConfig:
type: object
properties:
id:
type: string
description: System-generated unique identifier
readOnly: true
example: PlatformConfig:019542f5-b3e7-1d02-0000-000000000003
umaDomain:
type: string
description: UMA domain for this platform
example: platform.uma.domain
proxyUmaSubdomain:
type: string
description: The subdomain that incoming requests will be proxied to
example: platform
webhookEndpoint:
type: string
description: URL where webhook notifications will be sent
example: https://api.mycompany.com/webhooks/uma
supportedCurrencies:
type: array
items:
$ref: '#/components/schemas/PlatformCurrencyConfig'
description: 'List of currencies supported by the platform. This is what the platform''s
customers are able to hold, send, and receive.
'
isRegulatedFinancialInstitution:
type: boolean
description: '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:
$ref: '#/components/schemas/EmbeddedWalletConfig'
description: 'Embedded-wallet branding and OTP settings for this platform. Present
only when the platform has configured embedded-wallet support;
omitted otherwise.
'
createdAt:
type: string
format: date-time
description: Creation timestamp
readOnly: true
example: '2025-06-15T12:30:45Z'
updatedAt:
type: string
format: date-time
description: Last update timestamp
readOnly: true
example: '2025-06-15T12:30:45Z'
CustomerInfoFieldName:
type: string
enum:
- FULL_NAME
- BIRTH_DATE
- NATIONALITY
- PHONE_NUMBER
- EMAIL
- POSTAL_ADDRESS
- TAX_ID
- REGISTRATION_NUMBER
- USER_TYPE
- COUNTRY_OF_RESIDENCE
- ACCOUNT_IDENTIFIER
- FI_LEGAL_ENTITY_NAME
- FI_ADDRESS
- PURPOSE_OF_PAYMENT
- ULTIMATE_INSTITUTION_COUNTRY
- IDENTIFIER
- BUSINESS_TYPE
- COMPANY_LEGAL_NAME
- ID_TYPE
- ID_NUMBER
description: Name of a type of field containing info about a platform's customer or counterparty customer.
example: FULL_NAME
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: API token authentication using format `<api token id>:<api client secret>`
AgentAuth:
type: http
scheme: bearer
description: 'Bearer token authentication for agent-scoped endpoints. The token is the `accessToken` returned when redeeming a device code via `POST /agents/device-codes/{code}/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent''s associated customer and subject to the agent''s policy.'
WebhookSignature:
type: apiKey
in: header
name: X-Grid-Signature
description: 'Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid.
To verify the signature:
1. Get the Grid public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash
If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
'