Sandbox

Simulate payment send to test receiving an UMA payment

Changed on Sep 23, 2026

Simulate sending payment from an sandbox uma address to a platform customer to test payment receive. This endpoint is only for the sandbox environment and will fail for production platforms/keys.

post/sandbox/uma/receive

Request

Base URL: https://api.lightspark.com/grid/2025-10-13
URL: https://api.lightspark.com/grid/2025-10-13/sandbox/uma/receive
Auth: HTTP basic

Request body

senderUmaAddressstring required

UMA address of the sender from the sandbox

receiverUmaAddressstring

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

customerIdstring

System ID of the receiver (optional if receiverUmaAddress is provided)

receivingCurrencyCodestring required

The currency code for the receiving amount

receivingCurrencyAmountinteger required

The amount to be received in the smallest unit of the currency (eg. cents)

Example request

{
  "senderUmaAddress": "$success.usd@sandbox.grid.uma.money",
  "receiverUmaAddress": "$receiver@uma.domain",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "receivingCurrencyCode": "USD",
  "receivingCurrencyAmount": 1000
}

Response

Payment triggered successfully

idstring required

Unique identifier for the transaction

Status of a payment transaction.

Status	Description
CREATED	Initial lookup has been created
PENDING	Quote has been created
PENDING_AUTHORIZATION	Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch GET /quotes/{quoteId} using the transaction's quoteId, then authorize its scaChallenge via POST /quotes/{quoteId}/authorize.
PROCESSING	Funding has been received and payment initiated
COMPLETED	Cross border payment has been received, converted and payment has been sent to the offramp network
REJECTED	Receiving institution or wallet rejected payment, payment has been refunded
FAILED	An error occurred during payment
REFUNDED	Payment was unable to complete and refunded
EXPIRED	Quote has expired

pendingReason'COUNTERPARTY_DECLARATION_REQUIRED' | 'WALLET_VERIFICATION_REQUIRED' | 'COUNTERPARTY_INFORMATION_REQUIRED' | 'COMPLIANCE_REVIEW'

Why a transaction is pending.

Reason	Description
COUNTERPARTY_DECLARATION_REQUIRED	The customer must declare who controls the sending wallet.
WALLET_VERIFICATION_REQUIRED	The customer must verify ownership of the sending wallet.
COUNTERPARTY_INFORMATION_REQUIRED	Information about the sender is required.
COMPLIANCE_REVIEW	The customer's action is complete and the deposit remains under compliance review.

type'INCOMING' required

Type of transaction

direction'CREDIT' | 'DEBIT' required

Whether the transaction credits (funds in) or debits (funds out) the customer's account. Independent of type: an incoming transaction is normally a CREDIT, but an inbound ACH pull, for example, is an INCOMING transaction with a DEBIT direction.

customerIdstring required

System ID of the customer this transaction belongs to

platformCustomerIdstring required

Platform-specific ID of the customer this transaction belongs to

settledAtstring date-time

When the payment was or will be settled

createdAtstring date-time

When the transaction was created

updatedAtstring date-time

When the transaction was last updated

receiptDeliveryConfirmedAtstring date-time

The time at which the platform confirmed delivery of the receipt to their customer.

agentIdstring

If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions.

descriptionstring

Optional memo or description for the payment

exchangeRatenumber

Number of sending currency units per receiving currency unit. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate.

quoteIdstring

The ID of the quote that was used to trigger this payment

counterpartyInformationCounterpartyInformation

Additional information about the counterparty, if available and relevant to the transaction and platform.

feesinteger

The total fees available from the receive quote in the smallest unit of the sending currency (eg. cents).

Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider's side or Grid's. Failed collections are returned to the sender per the collection provider's process. A payment that settled into a rule-based account but could not be swept to the destination of the account's rule fails with one of the SWEEP_* reasons. A rule-based account never holds a balance, so the funds are moved to the account holder's own account in the same currency. SWEEP_AMOUNT_OUT_OF_RANGE means the amount was outside the band the corridor to the destination can carry — the rule's minimumAmount and maximumAmount give the current band — and SWEEP_QUOTE_FAILED that Grid could not price it. A sweep that was priced and then failed on the way to settlement reports QUOTE_EXECUTION_FAILED, the same as any other payment.

Example response

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "destination": {
    "destinationType": "ACCOUNT",
    "currency": "EUR",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "settledAt": "2025-08-15T14:30:00Z",
  "createdAt": "2025-08-15T14:25:18Z",
  "updatedAt": "2025-08-15T14:30:00Z",
  "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "description": "Payment for invoice #1234",
  "sentAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "exchangeRate": 1.08,
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "refund": {
    "reference": "UMA-Q12345-REFUND",
    "initiatedAt": "2025-08-15T14:30:00Z",
    "settledAt": "2025-08-15T14:35:00Z",
    "status": "COMPLETED",
    "reason": "TRANSACTION_FAILED"
  },
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "source": {
    "sourceType": "ACCOUNT",
    "currency": "USD",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "fees": 10,
  "reconciliationInstructions": {
    "reference": "UMA-Q12345-REF",
    "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
  }
}

Changes

Sep 23, 2026556180e5b2ae Revision changes
- warning
  added the new ACH_SAME_DAY enum value to the //////// response property for the response status
Sep 15, 20263966e5d38aad Revision changes
- 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
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- warning
  added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CUSTOMER_NOT_VERIFIED enum value to the response property for the response status
- warning
  added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_FUNDS enum value to the response property for the response status
- warning
  added the new NOT_FOUND enum value to the response property for the response status
- warning
  added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status
- warning
  added the new PLATFORM_NOT_FOUND 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 REQUEST_NOT_FOUND enum value to the response property for the response status
- warning
  added the new SANCTION_BLOCKED enum value to the response property for the response status
- warning
  added the new SESSION_NOT_FOUND 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_FOUND 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_FOUND 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_FOUND 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 VERIFICATION_NOT_FOUND enum value to the response property for the response 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
- info
  added the required property to the response with the status

Operation history (14 revisions)