---
title: "Simulate payment send to test receiving an UMA payment"
method: POST
path: "/sandbox/uma/receive"
tags: ["Sandbox"]
---

# Simulate payment send to test receiving an UMA payment

`POST /sandbox/uma/receive`

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.

## Request body

- SandboxUmaReceiveRequest
  - `senderUmaAddress` string, required — UMA address of the sender from the sandbox
  - `receiverUmaAddress` string — UMA address of the receiver (optional if customerId is provided)
  - `customerId` string — System ID of the receiver (optional if receiverUmaAddress is provided)
  - `receivingCurrencyCode` string, required — The currency code for the receiving amount
  - `receivingCurrencyAmount` integer, required — The amount to be received in the smallest unit of the currency (eg. cents)

## Response `200`

Payment triggered successfully

- IncomingTransaction
  - `id` string, required — Unique identifier for the transaction
  - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `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 |
  - `type` 'INCOMING', required — Type of transaction (incoming payment or outgoing payment)
  - `destination` union, required
    - AccountTransactionDestination — Destination account details
      - `destinationType` 'ACCOUNT', required
      - `accountId` string, required — Destination account identifier
    - UmaAddressTransactionDestination — UMA address destination details
      - `destinationType` 'UMA_ADDRESS', required
      - `umaAddress` string, required — UMA address of the recipient
  - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming)
  - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming)
  - `settledAt` string, date-time — When the payment was or will be settled
  - `createdAt` string, date-time — When the transaction was created
  - `updatedAt` string, date-time — When the transaction was last updated
  - `agentId` string — If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions.
  - `description` string — Optional memo or description for the payment
  - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
  - `source` union
    - AccountTransactionSource — Source account details
      - `sourceType` 'ACCOUNT', required
      - `accountId` string, required — Source account identifier
    - UmaAddressTransactionSource — UMA address source details
      - `sourceType` 'UMA_ADDRESS', required
      - `umaAddress` string, required — UMA address of the sender
    - RealtimeFundingTransactionSource — Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.).
      - `sourceType` 'REALTIME_FUNDING', required
      - `customerId` string — The customer on whose behalf the transaction was initiated.
      - `currency` string, required — Currency code for the funding source
  - `receivedAmount` CurrencyAmount, required
    - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
    - `currency` Currency, required
      - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
      - `name` string — Full name of the currency
      - `symbol` string — Symbol of the currency
      - `decimals` integer — Number of decimal places for the currency
  - `fees` integer — The total fees available from the receive quote in the smallest unit of the receiving currency (eg. cents).
  - `reconciliationInstructions` ReconciliationInstructions
    - `reference` string — Unique reference code to include with the payment to match it with the correct incoming transaction, when available.
    - `transactionHash` string — Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available.
  - `rateDetails` IncomingRateDetails — Details about the rate and fees for an incoming transaction. Note: `gridApiFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.
    - `gridApiMultiplier` number, double, required — The underlying multiplier from the mSATS to the receiving currency, including variable fees.
    - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents).
    - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount.
    - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate.
  - `failureReason` 'LNURLP_FAILED' | 'PAY_REQUEST_FAILED' | 'PAYMENT_APPROVAL_WEBHOOK_ERROR' | 'PAYMENT_APPROVAL_TIMED_OUT' | 'OFFRAMP_FAILED' | 'MISSING_MANDATORY_PAYEE_DATA' | 'QUOTE_EXPIRED' | 'QUOTE_EXECUTION_FAILED' — 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.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - request was made with a production platform token
- `404` — Sender or receiver not found
- `500` — Internal service error

## Changes

- **2026-05-28** `d0bce562bffd` — 1 breaking, 6 warning, 3 info
  - the response property `allOf[subschema #2]/reconciliationInstructions/reference` became optional for the status `200`
  - added the new `REQUEST_ID_MISSING` enum value to the `code` response property for the response status `401`
  - added the new `UMA_NOT_FOUND` enum value to the `code` response property for the response status `404`
  - added the new `WALLET_SIGNATURE_BODY_MISMATCH` enum value to the `code` response property for the response status `401`
  - …6 more
- **2026-04-27** `5b8a8161eeb3` — 8 warning, 13 info
  - added the new `DATA_MISMATCH` enum value to the `code` response property for the response status `400`
  - added the new `EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS` enum value to the `code` response property for the response status `400`
  - added the new `EXPIRED` enum value to the `code` response property for the response status `400`
  - added the new `INCOMPLETE` enum value to the `code` response property for the response status `400`
  - …17 more
- **2026-03-03** `efe0d983985f` — 23 breaking, 34 info
  - the response's body type/format changed from ``/`` to `object`/`` for status `400`
  - the response's body type/format changed from ``/`` to `object`/`` for status `401`
  - the response's body type/format changed from ``/`` to `object`/`` for status `403`
  - the response's body type/format changed from ``/`` to `object`/`` for status `404`
  - …53 more
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/sandbox/uma/receive/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/d0bce562bffd/schema)