Skip to main content
This quickstart guides you through a regulated FI sending an individual customer payment from the US to a bank account in Mexico using just-in-time funding.

​
Understanding Entity Mapping for Remittances

In this guide, the entities map as follows:
Entity TypeWho They AreIn This Example
PlatformYour remittance serviceYour money transfer app
CustomerBoth sender and recipientAlice (sender in US), Carlos (recipient in Mexico)
External AccountBank accounts for funding/receivingAlice’s US bank (funding), Carlos’s Mexican bank (receiving funds)
Flow: Alice (customer) funds a transfer from her external account → to Carlos (also a customer) → who receives funds in his external bank account. Alternatively, Alice could send directly to Carlos’s UMA address if he has one.

​
Get API credentials

Create a Sandbox API credentialsin the dashboard, then set environment variables for local use. 
export GRID_BASE_URL="https://api.lightspark.com/grid/2025-10-13"
export GRID_CLIENT_ID="YOUR_SANDBOX_CLIENT_ID"
export GRID_CLIENT_SECRET="YOUR_SANDBOX_CLIENT_SECRET"
Use Basic Auth in cURL with -u "$GRID_CLIENT_ID:$GRID_API_SECRET".

​
Create a customer

Register a customer who will send the payment. You can provide your own UMA handle or let the system generate one. 
curl -sS -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "platformCustomerId": "cust_7b3c5a89d2f1e0",
    "customerType": "INDIVIDUAL",
    "umaAddress": "$alice@yourapp.example",
    "fullName": "Alice Smith",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'
Response: 
{
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "customerType": "INDIVIDUAL",
  "umaAddress": "$alice@yourapp.example",
  "platformCustomerId": "cust_7b3c5a89d2f1e0"
}

​
Create an external receiving bank account (CLABE in MX)

Add a beneficiary account in Mexico using their CLABE. We attach it to the same customer for this example. 
curl -sS -X POST "https://api.lightspark.com/grid/2025-10-13/customers/external-accounts" \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "MXN",
    "platformAccountId": "mx_beneficiary_001",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "accountInfo": {
      "accountType": "CLABE",
      "clabeNumber": "123456789012345678",
      "bankName": "BBVA Mexico",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Carlos Pérez",
        "birthDate": "1985-03-15",
        "nationality": "MX",
        "address": {
          "line1": "Av. Reforma 123",
          "city": "Ciudad de México",
          "state": "CDMX",
          "postalCode": "06600",
          "country": "MX"
        }
      }
    }
  }'
Response: 
{
  "id": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "currency": "MXN",
  "status": "ACTIVE",
  "platformAccountId": "mx_beneficiary_001",
  "accountInfo": {
    "accountType": "CLABE",
    "clabeNumber": "123456789012345678",
    "bankName": "BBVA Mexico",
    "beneficiary": {
      "beneficiaryType": "INDIVIDUAL",
      "fullName": "Carlos Pérez",
      "birthDate": "1985-03-15",
      "nationality": "MX",
      "address": {
        "line1": "Av. Reforma 123",
        "city": "Ciudad de México",
        "state": "CDMX",
        "postalCode": "06600",
        "country": "MX"
      }
    }
  }
}

​
Create a quote (just‑in‑time funding)

Quote a transfer of 100 USD from the customer to the MXN CLABE account. The quote returns the exchange rate, fees, and paymentInstructions to fund in real time. 
curl -sS -X POST "https://api.lightspark.com/grid/2025-10-13/quotes" \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "umaAddress": "$alice@yourapp.example",
      "currency": "USD"
    },
    "destination": {
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "currency": "MXN"
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000,
    "description": "Remittance to MX beneficiary"
  }'
Response: 
{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "exchangeRate": 16.85,
  "fees": { "amount": 50, "currency": { "code": "USD", "decimals": 2 } },
  "paymentInstructions": {
    "reference": "UMA-Q12345-REF",
    "bankAccountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "987654321",
      "routingNumber": "123456789",
      "accountCategory": "CHECKING",
      "bankName": "Example Bank"
    }
  },
  "status": "PENDING"
}

​
Fund the quote (Sandbox simulation)

In production, you would trigger a real‑time push on a local instant rail (e.g., RTP, SPEI, SEPA Instant) to the provided bankAccountInfo using the exact reference. In Sandbox, you can mock funding using the simulate send endpoint. 
curl -sS -X POST "https://api.lightspark.com/grid/2025-10-13/sandbox/send" \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "UMA-Q12345-REF",
    "currencyCode": "USD",
    "currencyAmount": 10000
  }'
Response: 
{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
  "status": "PROCESSING",
  "type": "OUTGOING",
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
}

​
Handle the outgoing payment webhook

Implement a webhook endpoint to receive status updates as the payment moves from pending to completed (or failed). Verify the X-Grid-Signature header using the public key provided during onboarding. Webhook event: 
{
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "status": "COMPLETED",
    "type": "OUTGOING",
    "senderUmaAddress": "$alice@yourapp.example",
    "receivedAmount": { "amount": 9706, "currency": { "code": "MXN", "decimals": 2 } },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "paymentInstructions": {
      "reference": "UMA-Q12345-REF"
    }
  },
  "timestamp": "2025-01-15T14:32:00Z",
  "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
  "type": "OUTGOING_PAYMENT"
}
⌘I