Sign in

v33

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-05-28103497709.6 KB
Sandbox

Simulate payment send to test receiving an UMA payment

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 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'CREATED' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED' required

Status of a payment transaction.

StatusDescription
CREATEDInitial lookup has been created
PENDINGQuote has been created
PROCESSINGFunding has been received and payment initiated
COMPLETEDCross border payment has been received, converted and payment has been sent to the offramp network
REJECTEDReceiving institution or wallet rejected payment, payment has been refunded
FAILEDAn error occurred during payment
REFUNDEDPayment was unable to complete and refunded
EXPIREDQuote has expired
type'INCOMING' required

Type of transaction (incoming payment or outgoing payment)

customerIdstring required

System ID of the customer (sender for outgoing, recipient for incoming)

platformCustomerIdstring required

Platform-specific ID of the customer (sender for outgoing, recipient for incoming)

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

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

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 receiving currency (eg. cents).

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.

Example response

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "destination": {
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
  },
  "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",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "description": "Payment for invoice #1234",
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "fees": 10,
  "reconciliationInstructions": {
    "reference": "UMA-Q12345-REF",
    "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
  },
  "rateDetails": {
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  }
}