Skip to main content
This guide explains how to enable your customers to receive UMA payments. When an external sender initiates a payment to your customer’s UMA address, the Grid API requests the counterparty fields you defined in your platform configuration. You can review the counterparty and transaction details for risk before approving the payment.
Before you begin, make sure you:

​
Receive webhook for initiated payment

When someone initiates a payment to one of your users’ UMA addresses, you’ll receive a webhook call with a pending transaction: 
{
  "transaction": {
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "status": "PENDING",
    "type": "INCOMING",
    "senderUmaAddress": "$mary.sender@thelessgoodbank.com",
    "receiverUmaAddress": "$john.receiver@thegoodbank.com",
    "receivedAmount": {
      "amount": 50000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "userId": "User:019542f5-b3e7-1d02-0000-000000000001",
    "platformUserId": "9f84e0c2a72c4fa",
    "description": "Payment for services",
    "counterpartyInformation": {
      "FULL_NAME": "Mary Sender",
      "BIRTH_DATE": "1985-06-15"
    },
    "reconciliationInstructions": {
      "reference": "REF-123456789"
    }
  },
  "requestedReceiverUserInfoFields": [
    { "name": "COUNTRY_OF_RESIDENCE", "mandatory": true },
    { "name": "FULL_NAME", "mandatory": true },
    { "name": "NATIONALITY", "mandatory": false }
  ],
  "timestamp": "2023-08-15T14:32:00Z",
  "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
  "type": "INCOMING_PAYMENT"
}
The counterpartyInformation object contains PII about the sender, provided by their FI, based on your configured requiredCounterpartyFields. If present, requestedReceiverUserInfoFields lists information needed about your user to proceed. Provide those fields when approving. You can approve or reject the payment synchronously (recommended) or asynchronously: To approve the payment synchronously, respond with a 200 OK status:
  • If the requestedReceiverUserInfoFields array was present in the webhook request and contained mandatory fields, your 200 OK response must include a JSON body containing a receiverUserInfo object. This object should contain the key-value pairs for the information fields that were requested.
  • If requestedReceiverUserInfoFields was not present, was empty, or contained only non-mandatory fields for which you have no information, your 200 OK response can have an empty body.
Example 200 OK response body when information was requested and provided: 
{
  "receiverUserInfo": {
    "COUNTRY_OF_RESIDENCE": "US",
    "FULL_NAME": "John Receiver"
  }
}
To reject the payment, respond with a 403 Forbidden status and a JSON body with the following fields: 
{
  "code": "payment_rejected",
  "message": "Payment rejected due to compliance policy",
  "details": {
    "reason": "failed_counterparty_check",
    "rejectionReason": "User is in a restricted jurisdiction"
  }
}

​
Option 2: Asynchronous Processing

If your platform’s architecture requires asynchronous processing before approving or rejecting the payment, you can:
  1. Return a 202 Accepted response to acknowledge receipt of the webhook
  2. Process the payment asynchronously
  3. Call either the /transactions/{transactionId}/approve or /transactions/{transactionId}/reject endpoint within 5 seconds
Example of approving asynchronously: 
curl -X POST "https://api.lightspark.com/grid/2025-10-13/transactions/Transaction:019542f5-b3e7-1d02-0000-000000000005/approve" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverUserInfo": {
      "COUNTRY_OF_RESIDENCE": "US",
      "FULL_NAME": "John Receiver"
    }
  }'
Example of rejecting asynchronously: 
curl -X POST "https://api.lightspark.com/grid/2025-10-13/transactions/Transaction:019542f5-b3e7-1d02-0000-000000000005/reject" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "RESTRICTED_JURISDICTION"
  }'
If you choose the asynchronous path, you must call the approve/reject endpoint within 5 seconds, or the payment will be automatically rejected.

​
Receive completion notification and credit

When the payment completes, you’ll receive another webhook notifying you of the completion: 
{
  "transaction": {
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "status": "COMPLETED",
    "type": "INCOMING",
    "senderUmaAddress": "$mary.sender@thelessgoodbank.com",
    "receiverUmaAddress": "$john.receiver@thegoodbank.com",
    "receivedAmount": {
      "amount": 50000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "userId": "User:019542f5-b3e7-1d02-0000-000000000001",
    "platformUserId": "9f84e0c2a72c4fa",
    "settlementTime": "2023-08-15T14:30:00Z",
    "createdAt": "2023-08-15T14:25:18Z",
    "description": "Payment for services",
    "counterpartyInformation": {
      "FULL_NAME": "Mary Sender",
      "BIRTH_DATE": "1985-06-15"
    },
    "reconciliationInstructions": {
      "reference": "REF-123456789"
    }
  },
  "timestamp": "2023-08-15T14:32:00Z",
  "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
  "type": "INCOMING_PAYMENT"
}
On completion, the received funds are immediately credited to the account associated with the UMA customer.

​
Test the inbound flow

Use the UMA Test Wallet to send a regtest payment to your customer’s UMA address.
⌘I