If you're building global payments infrastructure, you don't need a lecture on why real-time matters. You need to know what it takes to implement it: the API patterns, the funding models, the compliance paths, and the operational details that determine whether your integration ships in days or drags on for months.
This guide covers how to build real-time payment capabilities for global disbursements with Lightspark Grid—from architecture decisions through production deployment.
What Grid Actually Does
Grid is a payments platform that lets you automate global disbursements through a single API. It handles the complexity you'd otherwise build yourself: FX conversion, payment routing, local rail delivery, and compliance infrastructure. No more manual work stitching together regional payment solutions or managing multiple banking relationships.
The core value proposition:
- 65 countries with local instant payment methods (PIX, SEPA Instant, UPI, Faster Payments, SPEI, FedNow, and more)
- Real-time settlement 24/7/365—no batch processing, no banking hours
- Automatic routing across fiat rails and Bitcoin settlement, whichever is faster and cheaper
- Built-in compliance with hosted KYC/KYB or bring-your-own options
Grid connects to 14,000+ banks, mobile money providers, and digital wallets globally. Recipients receive local currency in their bank accounts—they don't interact with Bitcoin unless they choose to.
The Payment Flow
Every payout through Grid follows the same pattern—a streamlined workflow that eliminates the manual work typically required for cross-border payments:
That's it. Grid handles FX, routing, blockchain settlement (when optimal), and local rail delivery automatically.
Step 1: Funding Your Account
Grid supports two funding models to match your cash flow preferences:
Prefunded accounts: Deposit funds into your internal account via ACH, SEPA Instant, wire transfer, or Lightning. When you execute a quote, funds debit instantly. Best for high-volume operations where you want swift execution without waiting for funding to clear.
Just-in-time (JIT) funding: Create a quote and receive payment instructions. Once Grid receives your funds, the payout executes automatically. Best for lower-volume use cases or when you don't want to maintain prefunded balances.
When your platform is created, you're automatically assigned an internal account. List your accounts to see balances and funding instructions:
Step 2: Creating a Quote
Quotes lock exchange rates and return exact pricing before you commit. You specify the source (your internal account), destination (recipient's external account), and amount.
The quote response includes:
- Exact sending and receiving amounts
- Locked exchange rate
- Itemized fees
- Expiration time (typically 1–15 minutes depending on payment type)
You can lock either the sending amount ("pay exactly $1,000") or the receiving amount ("recipient must receive exactly €900"). This matters for payroll and invoice payments where precision is required.
Step 3: Executing the Quote
For prefunded accounts, execute immediately:
For JIT funding, send funds to the payment instructions provided in the quote. Grid executes automatically when funds arrive.
For one-off payments to new recipients, you can combine account creation and quote execution in a single call using externalAccountDetails:
Step 4: Handling Webhooks
Grid sends webhooks for payment lifecycle events. A completed payout webhook looks like:
Implement webhook signature verification for security. See the webhooks guide for implementation details.
Setting Up Recipients
Before sending payouts, you need to configure recipient accounts. Grid supports external accounts for bank accounts and digital wallets across all supported regions. The onboarding process for recipients is straightforward—you provide account details, Grid validates them.
Bank Accounts by Region
United States:
Europe (SEPA):
Brazil (PIX):
Mexico (SPEI):
India (UPI):
Grid validates account formats and checks account status before allowing payments. Only ACTIVE accounts can receive funds.
Crypto and Digital Wallets
For Bitcoin or stablecoin payouts to digital wallets:
This is useful for rewards programs, crypto-native recipients, or when recipients prefer to receive value in Bitcoin.
Compliance: Two Paths
Grid offers flexibility based on your regulatory status, streamlining the onboarding process for both you and your recipients.
Hosted KYC/KYB
For non-regulated platforms, Grid handles identity verification. Users complete verification through Grid's hosted flow, and you inherit the compliance stack. This dramatically reduces time-to-launch—you're not building or maintaining compliance infrastructure.
Bring Your Own
For regulated entities (banks, licensed fintechs), you handle KYC/KYB through your existing processes. Grid accepts your verified customers. This path makes sense if you already have compliance infrastructure and want to maintain control.
Rewards Exception
For rewards and payouts, only the paying entity needs KYB verification. You can send Bitcoin to any wallet address without requiring recipient KYC—useful for cashback programs, creator payouts, and promotional campaigns where recipient identity verification would kill conversion.
Country and Rail Coverage
Grid routes cross-border payments through local instant rails where available:
Bitcoin and stablecoin transactions work globally with no geographic restrictions.
Key rails by country:
- US: ACH, Wire Transfer, RTP, FedNow
- UK: Faster Payments
- Brazil: PIX
- Mexico: SPEI
- India: UPI, IMPS
- Singapore: PayNow, FAST
- Europe (32 countries): SEPA, SEPA Instant
Grid automatically selects the optimal rail based on speed, cost, and availability.
Testing in Sandbox
Grid's sandbox environment mirrors production behavior. You can test your entire payout workflows before going live:
- Receiver resolution and validation
- Quote creation with real exchange rates and pricing
- Funding instructions and payment flows
- Settlement status changes
- Webhook delivery and handling
- End-to-end payout flows
No real funds move in sandbox. Use it to validate your integration before going live.
Common Use Cases
Global Contractor Payments
Flow: Your platform funds its internal account → creates quotes for each contractor → executes payouts → contractors receive local currency via instant rails.
Lock the receiving amount when contractors have agreed rates in their local currency. Use the description field for invoice references and reconciliation. This automates what would otherwise require manual work across multiple payment solutions.
Marketplace Seller Payouts
Flow: Marketplace holds funds in internal account → releases to sellers when orders complete → sellers receive funds in seconds.
Consider batching quotes for efficiency if you're processing many disbursements simultaneously. Grid handles each as a discrete transaction for reconciliation, improving your cash flow visibility.
Payroll
Flow: Company funds internal account monthly → creates quotes with locked receiving amounts → executes on pay date → employees receive exact local currency amounts.
The locked receiving amount feature is critical here—employees expect precise amounts regardless of FX fluctuations between when you budget and when you pay. Grid lets you automate global payroll workflows without building regional payment integrations.
Bitcoin Rewards
Flow: Platform funds USD internal account → creates quote to convert USD to BTC → sends to recipient's Spark wallet.
Bitcoin transfers to Spark wallets complete in seconds. No recipient KYC required—only your platform needs KYB verification.
Getting Started
- Review the documentation: Start with the Payouts & B2B guide for the full API reference
- Test in sandbox: Use the Postman collection to explore endpoints
- Check the GitHub repo: The API specification is open-source
- Get credentials: Contact the team to discuss your use case and get production access
The integration is straightforward if you've worked with payment APIs before. The difference is what happens after you call the API: recipients get funds in seconds instead of days, you pay less in fees, and you don't manage the complexity of 65 different local payment systems. Grid streamlines global payments into a single integration—so you can focus on your product instead of payments plumbing.
