Receiving Payments

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:

Configure UMA, supported currencies, and required counterparty fields in Platform Configuration
Create customers and capture any provider-required user fields in Creating Customers
Set up and verify webhooks in Webhooks

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:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
  "type": "INCOMING_PAYMENT.PENDING",
  "timestamp": "2023-08-15T14:32:00Z",
  "data": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "status": "PENDING",
    "type": "INCOMING",
    "source": {
      "sourceType": "UMA_ADDRESS",
      "umaAddress": "$mary.sender@thelessgoodbank.com"
    },
    "receivedAmount": {
      "amount": 50000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "9f84e0c2a72c4fa",
    "description": "Payment for services",
    "counterpartyInformation": {
      "FULL_NAME": "Mary Sender",
      "BIRTH_DATE": "1985-06-15"
    },
    "reconciliationInstructions": {
      "reference": "REF-123456789"
    },
    "requestedReceiverCustomerInfoFields": [
      { "name": "COUNTRY_OF_RESIDENCE", "mandatory": true },
      { "name": "FULL_NAME", "mandatory": true },
      { "name": "NATIONALITY", "mandatory": false }
    ]
  }
}

The counterpartyInformation object contains PII about the sender, provided by their FI, based on your configured requiredCounterpartyFields. If present, requestedReceiverCustomerInfoFields lists information needed about your customer to proceed. Provide those fields when approving. You can approve or reject the payment synchronously (recommended) or asynchronously:

Option 1: Synchronous (recommended)

To approve the payment synchronously, respond with a 200 OK status:

If the requestedReceiverCustomerInfoFields array was present in the webhook request and contained mandatory fields, your 200 OK response must include a JSON body containing a receiverCustomerInfo object. This object should contain the key-value pairs for the information fields that were requested.
If requestedReceiverCustomerInfoFields 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:

{
  "receiverCustomerInfo": {
    "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:

Return a 202 Accepted response to acknowledge receipt of the webhook
Process the payment asynchronously
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 '{
    "receiverCustomerInfo": {
      "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. The envelope id is distinct from the INCOMING_PAYMENT.PENDING delivery above — use it for idempotent deduplication.

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000008",
  "type": "INCOMING_PAYMENT.COMPLETED",
  "timestamp": "2023-08-15T14:32:00Z",
  "data": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "status": "COMPLETED",
    "type": "INCOMING",
    "source": {
      "sourceType": "UMA_ADDRESS",
      "umaAddress": "$mary.sender@thelessgoodbank.com"
    },
    "receivedAmount": {
      "amount": 50000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "9f84e0c2a72c4fa",
    "settledAt": "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"
    }
  }
}

On completion, the received funds are immediately credited to the account associated with the UMA customer. By default, funds land in the customer’s primary internal account. However, you can also set an external account as the default UMA deposit account for the customer, which will cause incoming UMA payments to be deposited into that external account instead. This is useful for customers who prefer to receive UMA payments into a specific bank account directly, for example. To set an external account as the default UMA deposit account for a customer, you can set the defaultUmaDepositAccount flag to true when creating the external account.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers/external-accounts" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "currency": "USD",
    "accountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "9876543210",
      "routingNumber": "123456789",
      "accountCategory": "CHECKING",
      "bankName": "Chase Bank"
    },
    "defaultUmaDepositAccount": true
  }'

Test the inbound flow

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

Overview

Onboarding

Managing accounts

Sending & receiving payments

Global Accounts

Platform tools

Receive webhook for initiated payment

Option 1: Synchronous (recommended)

Option 2: Asynchronous Processing

Receive completion notification and credit

Test the inbound flow

​Receive webhook for initiated payment

​Option 1: Synchronous (recommended)

​Option 2: Asynchronous Processing

​Receive completion notification and credit

​Test the inbound flow

Receive webhook for initiated payment

Option 1: Synchronous (recommended)

Option 2: Asynchronous Processing

Receive completion notification and credit

Test the inbound flow