Look up an UMA address for payment

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/receiver/uma/{receiverUmaAddress} \
  --header 'Authorization: Basic <encoded-value>'

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 umaLookupResponse = await client.receiver.lookupUma('receiverUmaAddress');

console.log(umaLookupResponse);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.receiver.ReceiverLookupUmaParams
import com.lightspark.grid.models.receiver.UmaLookupResponse

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

    val umaLookupResponse: UmaLookupResponse = client.receiver().lookupUma("receiverUmaAddress")
}

{
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "supportedCurrencies": [
    {
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      },
      "estimatedExchangeRate": 1.08,
      "min": 1,
      "max": 1000000,
      "minSendingAmount": 100,
      "maxSendingAmount": 500000
    }
  ],
  "lookupId": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
  "receiverUmaAddress": "$receiver@uma.domain",
  "requiredPayerDataFields": [
    {
      "name": "FULL_NAME",
      "mandatory": true
    }
  ]
}

{
  "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": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 412,
  "code": "UNSUPPORTED_UMA_VERSION",
  "message": "<string>",
  "details": {}
}

{
  "status": 424,
  "code": "PAYREQ_REQUEST_FAILED",
  "message": "<string>",
  "details": {}
}

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

GET

receiver

uma

{receiverUmaAddress}

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/receiver/uma/{receiverUmaAddress} \
  --header 'Authorization: Basic <encoded-value>'

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 umaLookupResponse = await client.receiver.lookupUma('receiverUmaAddress');

console.log(umaLookupResponse);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.receiver.ReceiverLookupUmaParams
import com.lightspark.grid.models.receiver.UmaLookupResponse

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

    val umaLookupResponse: UmaLookupResponse = client.receiver().lookupUma("receiverUmaAddress")
}

{
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "supportedCurrencies": [
    {
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      },
      "estimatedExchangeRate": 1.08,
      "min": 1,
      "max": 1000000,
      "minSendingAmount": 100,
      "maxSendingAmount": 500000
    }
  ],
  "lookupId": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
  "receiverUmaAddress": "$receiver@uma.domain",
  "requiredPayerDataFields": [
    {
      "name": "FULL_NAME",
      "mandatory": true
    }
  ]
}

{
  "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": 404,
  "code": "TRANSACTION_NOT_FOUND",
  "message": "<string>",
  "details": {}
}

{
  "status": 412,
  "code": "UNSUPPORTED_UMA_VERSION",
  "message": "<string>",
  "details": {}
}

{
  "status": 424,
  "code": "PAYREQ_REQUEST_FAILED",
  "message": "<string>",
  "details": {}
}

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

Authorizations

Authorization

string

header

required

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

Path Parameters

receiverUmaAddress

string

required

UMA address of the intended recipient

Query Parameters

senderUmaAddress

string

UMA address of the sender (optional if customerId is provided)

customerId

string

System ID of the sender (optional if senderUmaAddress is provided)

sendingCurrency

string

Currency code the sender will send from (e.g., USD). Selects which of the sender's configured currencies the response is priced against: it is echoed back as the response's sendingCurrency, and the minSendingAmount/maxSendingAmount bounds are denominated in its smallest unit. Defaults to the sender's default currency.

Response

Successful lookup

sendingCurrency

object

required

The currency the payment is sent from — the sender's default, or the one named by the sendingCurrency query parameter. Every estimatedExchangeRate in supportedCurrencies converts from this currency, and any minSendingAmount/maxSendingAmount is denominated in its smallest unit.

Show child attributes

supportedCurrencies

object[]

required

List of currencies supported by the receiving account

Show child attributes

lookupId

string

required

Unique identifier for the lookup. Needed in the subsequent create quote request.

Example:

"Lookup:019542f5-b3e7-1d02-0000-000000000009"

receiverUmaAddress

string

required

The UMA address that was looked up

Example:

"$receiver@uma.domain"

requiredPayerDataFields

object[]

Fields required by the receiving institution about the payer before payment can be completed

Show child attributes

Using the API

API documentation

Authorizations

Path Parameters

Query Parameters

Response