Sending Payments

Send payments between internal and external accounts, with automatic exchange rate handling when the currencies differ.

Overview

Every payment goes through POST /quotes, whether or not the currencies differ. A quote prices the transfer — the amounts, the fees, and, when the currencies differ, the exchange rate — and creates the transaction that carries the money. What varies is when you execute it:

In one request. Set immediatelyExecute and Grid creates and executes the quote together. Use this when you don’t need to put rate or fee details in front of your user before the money moves.
In two steps. Create the quote, show your user what the transfer will cost, then call execute before the quote expires. Use this whenever your UX surfaces rates or fees — which includes same-currency transfers, where there is no exchange rate but there can still be fees worth showing.

Either way the request shape is the same, and the payment rail is chosen from the destination account. The same endpoint sends to UMA addresses by giving the quote a UMA_ADDRESS destination. See Sending payments for that flow.

Prerequisites

Before sending payments, ensure you have:

An active internal account with sufficient balance
A verified external account for the destination
Valid API credentials with appropriate permissions
A webhook endpoint configured to receive payment status updates (recommended)

If you don’t have these set up yet, review the Internal Accounts and External Accounts guides first.

Send a payment

Get account IDs

Retrieve the internal account (source) and external account (destination) IDs:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Note the id fields from both the internal and external accounts you want to use.

Create the quote

Specify the source and destination accounts and the amount to lock:

cURL

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000,
    "remittanceInformation": "INV-12345",
    "description": "Payment for services - Invoice #1234"
  }'

Success (201 Created)

{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000025",
  "status": "PENDING",
  "createdAt": "2025-10-03T15:00:00Z",
  "expiresAt": "2025-10-03T15:15:00Z",
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
  },
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "receivingCurrency": {
    "code": "EUR",
    "name": "Euro",
    "symbol": "€",
    "decimals": 2
  },
  "totalSendingAmount": 10000,
  "totalReceivingAmount": 9200,
  "exchangeRate": 0.92,
  "feesIncluded": 50,
  "platformFeesIncluded": 0,
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
  "description": "Payment for services - Invoice #1234"
}

Same-currency transfers use this exact request. The two currencies simply match, and the quote comes back with an exchangeRate of 1 — the fee fields are still populated. Add "immediatelyExecute": true to create and execute in this one request and skip the next two steps.

Locked currency side determines which amount is fixed:

SENDING: Lock the sending amount (receiving amount calculated based on exchange rate)
RECEIVING: Lock the receiving amount (sending amount calculated based on exchange rate)

The paymentRail field is optional. If omitted, Grid selects a default rail for the destination. Specify a rail (e.g., ACH, WIRE, RTP, FEDNOW) when you need to control which payment network processes the transfer.

remittanceInformation is optional. Use it to send a reference that travels with the payment to the recipient (max 80 characters). This populates the ACH Addenda record, FedNow/RTP remittance information, or wire OBI field depending on the payment rail.

purposeOfPayment is optional. Some destinations require it, and some rails carry it on the payment itself.

Amounts are specified in the smallest unit of the currency (cents for USD, pence for GBP, etc.). For example, 12550 represents $125.50 USD.

Review the quote

Before executing, check that:

The exchange rate is acceptable
Fees are as expected
The receiving amount meets requirements
The quote hasn’t expired (check expiresAt)

Quote expiration depends on the corridor but is typically ~5 minutes or greater. If expired, create a new quote to get an updated exchange rate.

Skip this step by setting immediatelyExecute on the quote. A same-currency quote has no exchange rate to review, but check feesIncluded if your UX shows the customer what the transfer costs.

Execute the quote

Confirm and execute the quote to initiate the transfer:

cURL

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes/Quote:019542f5-b3e7-1d02-0000-000000000025/execute' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

The quote comes back with status PROCESSING and the same transactionId it carried at creation.

Once executed, the quote creates a transaction and the transfer begins processing. The transactionId can be used to track the payment.

Real-time funding sources: If your quote uses a real-time funding source (USDC, BTC, RTP, or FedNow), you don’t call the execute endpoint. Instead, send a payment to the account specified in the quote’s paymentInstructions. Grid detects the deposit and processes the transfer automatically.

Monitor completion

After execution, a transaction is created and progresses through PENDING → PROCESSING → COMPLETED or FAILED. You’ll receive OUTGOING_PAYMENT.<STATUS> webhooks as the transaction progresses:

{
  "type": "OUTGOING_PAYMENT.COMPLETED",
  "data": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
    "status": "COMPLETED",
    "type": "OUTGOING",
    "direction": "DEBIT",
    "sentAmount": {
      "amount": 10000,
      "currency": { "code": "USD", "symbol": "$", "decimals": 2 }
    },
    "receivedAmount": {
      "amount": 9200,
      "currency": { "code": "EUR", "symbol": "€", "decimals": 2 }
    },
    "exchangeRate": 0.92,
    "settledAt": "2025-10-03T15:30:00Z",
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000025"
  },
  "timestamp": "2025-10-03T15:31:00Z"
}

If a transaction fails, Grid initiates a refund automatically. You’ll receive OUTGOING_PAYMENT.REFUND_PENDING followed by OUTGOING_PAYMENT.REFUND_COMPLETED or OUTGOING_PAYMENT.REFUND_FAILED. The transaction’s refund object tracks the refund status and reference.

For the full state diagram, refund object details, and all webhook scenarios (including bank returns and manual cancellations), see the Transaction Lifecycle guide.

Transaction statuses

Status	Description
`PENDING`	Quote created, awaiting execution
`PROCESSING`	Quote executed, transfer in progress through the payment rail
`COMPLETED`	Transfer successfully completed
`FAILED`	Transfer failed — accompanied by a `failureReason`, and a refund is initiated automatically (track via the `refund` object)
`EXPIRED`	Quote wasn’t executed before the expiry window

For the full state diagram including refund tracking and edge cases, see the Transaction Lifecycle guide.

Checking Payment Status

Configure a webhook endpoint to receive real-time notifications when payment status changes:

app.post("/webhooks/grid", (req, res) => {
  const { type, data } = req.body;

  switch (type) {
    case "OUTGOING_PAYMENT.COMPLETED":
      console.log(`Payment ${data.id} completed at ${data.settledAt}`);
      // Update your database, notify customer
      break;

    case "OUTGOING_PAYMENT.FAILED":
      console.log(`Payment ${data.id} failed: ${data.failureReason}`);
      // Handle failure, notify customer — refund webhook follows
      break;

    case "OUTGOING_PAYMENT.PROCESSING":
      console.log(`Payment ${data.id} is processing`);
      // Optional: Update UI to show processing state
      break;

    case "OUTGOING_PAYMENT.REFUND_COMPLETED":
      console.log(`Payment ${data.id} refund completed`);
      // Update your records with refund details
      break;

    case "OUTGOING_PAYMENT.REFUND_FAILED":
      console.log(`Payment ${data.id} refund failed`);
      // Alert your team — may require manual resolution
      break;
  }

  res.status(200).json({ received: true });
});

See the Webhooks guide for complete webhook implementation details including signature verification.

Best Practices

Handle quote expiration gracefully

Quote expiration depends on the corridor (typically ~5 minutes or greater). Always check expiration before executing:

async function executeQuoteWithCheck(quoteId) {
  const quote = await getQuote(quoteId);

  if (new Date(quote.expiresAt) < new Date()) {
    // Quote expired, create a new one
    const newQuote = await createQuote({
      source: quote.source,
      destination: quote.destination,
      lockedCurrencySide: quote.lockedCurrencySide,
      lockedCurrencyAmount: quote.lockedCurrencyAmount,
    });

    return executeQuote(newQuote.id);
  }

  return executeQuote(quoteId);
}

Include descriptive payment references

Always include meaningful descriptions to help with reconciliation:

const description = [
  `Invoice #${invoiceId}`,
  `Customer: ${customerName}`,
  `Date: ${new Date().toISOString().split("T")[0]}`,
].join(" | ");

await createQuote({
  // ... other fields
  description: description,
});

This makes it easier to match payments in your accounting system and provides context when reviewing transactions.

Store transaction IDs in your system

Always save transaction and quote IDs for audit trails and support:

const quote = await createQuote(quoteData);

// Save to your database immediately
await db.payments.create({
  quoteId: quote.id,
  customerId: customer.id,
  amount: quote.totalSendingAmount,
  currency: quote.sendingCurrency.code,
  status: "pending",
  createdAt: new Date(),
});

const execution = await executeQuote(quote.id);

// Update with transaction ID
await db.payments.update(
  { quoteId: quote.id },
  { transactionId: execution.transactionId, status: "processing" }
);

Overview

Onboarding

Managing accounts

Global Accounts

Platform tools

Sending Payments

Overview

Prerequisites

Send a payment

Transaction statuses

Checking Payment Status

Best Practices

Next Steps

​Overview

​Prerequisites

​Send a payment

​Transaction statuses

​Checking Payment Status

​Best Practices

​Next Steps

Overview

Prerequisites

Send a payment

Transaction statuses

Checking Payment Status

Best Practices

Next Steps