WeSplit Partner API
Integrate bill splitting into your platform with our powerful API
Demo Splits
Create Split from Payment
/createSplitFromPayment
Split Details
pendingParticipants
Record Payment
Simulates POST /payParticipantShare
Payment History
Split Status
Data from GET /getSplitStatus
Total Amount
Completion
Participant Balances
WeSplit Partner API
Integrate bill splitting functionality into your platform. The API allows you to create splits, invite participants, process payments, and track split status.
Integration Flow
Visual walkthrough of a complete WeSplit integration. Click any step or use the controls to navigate.
Configuration
const API_CONFIG = {
baseUrl: 'https://us-central1-wesplit-35186.cloudfunctions.net',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
Endpoints
1. Create Split from Payment
Creates a split from payment/order data. First call in the integration flow.
{
"email": "customer@example.com",
"invoiceId": "INV-12345",
"amount": 100.00,
"currency": "USD",
"merchant": {
"name": "Merchant Name",
"address": "123 Main St",
"phone": "+1234567890"
},
"transactionDate": "2025-02-04T10:00:00Z",
"source": "partner_name",
"items": [
{ "name": "Product Name", "price": 50.00, "quantity": 2 }
],
"metadata": {
"treasuryWallet": "YOUR_TREASURY_WALLET",
"orderId": "ORD-1234567890",
"webhookUrl": "https://your-app.com/webhooks/wesplit",
"webhookSecret": "your_webhook_secret",
"paymentThreshold": 1.0,
"callbackUrl": "https://your-app.com/orders/ORD-1234567890"
}
}
Response:
{
"success": true,
"data": {
"userId": "user_firebase_id",
"userEmail": "customer@example.com",
"walletAddress": "solana_wallet_address",
"splitId": "split_1234567890_abc",
"billId": "bill_1234567890",
"splitStatus": "pending",
"totalAmount": 100.00,
"currency": "USDC",
"createdAt": "2025-02-04T10:00:00Z"
},
"redirectUrl": "https://your-app.com/orders/..."
}
2. Batch Invite Participants
Invite multiple participants to a split with automatic email notifications.
{
"splitId": "split_1234567890_abc",
"inviterId": "user_id_of_creator",
"inviterName": "John Doe",
"participants": [
{ "email": "user1@example.com", "name": "User One", "amountOwed": 33.33 },
{ "email": "user2@example.com", "name": "User Two", "amountOwed": 33.33 }
],
"sendNotifications": true
}
Response:
{
"success": true,
"results": {
"addedExisting": [...],
"pendingInvites": [
{
"email": "new@example.com",
"inviteLink": "https://deeplinks.wesplit.io/join-split?invite=..."
}
],
"alreadyParticipant": [],
"failed": []
},
"summary": {
"total": 2,
"addedExisting": 1,
"pendingInvites": 1
}
}
3. Pay Participant Share
Record a participant's payment. Uses atomic transactions for race condition prevention.
{
"splitId": "split_1234567890_abc",
"participantId": "user_id_of_payer",
"amount": 33.33,
"currency": "USDC",
"transactionSignature": "5j7s8K9l2m3n4o5p..."
}
Response:
{
"success": true,
"transactionSignature": "5j7s8K9l...",
"amountPaid": 33.33,
"remainingAmount": 0,
"splitStatus": "funded",
"isFullyFunded": true,
"redirectUrl": "https://your-app.com/orders/ORD-1234567890"
}
4. Get Split Status
Get current status of a split including all participants and payment progress.
{
"success": true,
"split": {
"id": "split_1234567890_abc",
"title": "Order ORD-1234567890",
"status": "funded",
"splitType": "spend",
"totalAmount": 100.00,
"currency": "USDC",
"amountCollected": 100.00,
"remainingAmount": 0,
"completionPercentage": "100.00",
"participantsCount": 3,
"participantsPaid": 3,
"participants": [
{
"userId": "user_id_1",
"email": "user1@example.com",
"name": "User One",
"amountOwed": 33.33,
"amountPaid": 33.33,
"status": "paid"
}
]
}
}
5. Search Known Users
Search for existing WeSplit users by email, name, or wallet address.
{
"success": true,
"users": [
{
"userId": "user_id_1",
"email": "john@example.com",
"name": "John Doe",
"walletAddress": "14NMWDU..."
}
],
"total": 1
}
6. Match Users by Email
Cross-reference emails with WeSplit's user database.
{
"emails": ["user1@example.com", "user2@example.com"],
"splitId": "split_1234567890_abc"
}
Response:
{
"success": true,
"matched": {
"existingUsers": [
{ "email": "user1@example.com", "userId": "wesplit_user_id", "hasWallet": true }
],
"newUsers": [
{ "email": "user2@example.com", "inviteLink": "https://deeplinks.wesplit.io/..." }
]
},
"stats": { "totalEmails": 2, "existingCount": 1, "newCount": 1 }
}
Status Values
Split Status
| Status | Description |
|---|---|
pending | Waiting for wallet creation |
active | Participants can pay |
funded | Payment threshold met |
completed | Merchant paid |
cancelled | Split cancelled |
Participant Status
| Status | Description |
|---|---|
invited | Not yet accepted |
partial | Paid partially |
paid | Paid in full |
Error Handling
| Status Code | Error |
|---|---|
| 400 | Validation failed |
| 401 | Invalid API key |
| 404 | Split/Participant not found |
| 429 | Rate limit exceeded (100/15min) |
| 500 | Internal server error |
Webhooks
WeSplit sends webhook notifications to your endpoint when split events occur.
Events
split.created- Split createdsplit.participant_added- Participant invitedsplit.participant_paid- Payment recordedsplit.funded- Payment threshold met
Signature Header
X-WeSplit-Signature: t=timestamp,v1=hmac_signature
Currency Support
All amounts are auto-converted to USDC. Supported currencies:
USD, EUR, GBP, CAD, AUD, JPY, CHF, CNY, INR, BRL, MXN
Error Handling
Test how the API responds to invalid requests. Click any scenario to see the error response and handling code.
Try It Out
// Response will appear here