WeSplit Partner API
Integrate bill splitting into your platform with our powerful API
Demo Splits
Create Split from Payment
/api/splits
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/demoApi',
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. The splitId is in the URL path.
{
"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. The splitId is in the URL path.
{
"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 real HTTP webhook notifications to your endpoint when split events occur. Configure your webhook URL to receive events.
Configure Webhook URL
Register your endpoint URL to receive webhook events.
{
"url": "https://your-app.com/webhooks/wesplit",
"secret": "your_webhook_secret"
}
Events
| Event | Trigger | Payload |
|---|---|---|
split.created | Split is created via API | Split ID, amount, merchant, metadata |
split.participant_added | Participant invited to a split | Participant ID, email, amount owed, invite link |
split.participant_paid | Payment recorded for a participant | Payment amount, TX signature, remaining amount, split status |
split.funded | All shares collected (fully funded) | Split ID, total amount, participant count |
Delivery Headers
Content-Type: application/json X-WeSplit-Signature: t=timestamp,v1=hmac_signature X-WeSplit-Event: split.created User-Agent: WeSplit-Webhooks/1.0
Webhook Event Log
Retrieve the server-side webhook delivery log. Each event includes delivery status (delivered, failed, no_url).
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