| 1 | ## Overview |
| 2 | SplitRoute is a payment processing API for Nano cryptocurrency that enables instant revenue sharing and payment distribution. |
| 3 | Create invoices, split payments among multiple recipients, and automate payouts. |
| 4 | |
| 5 | \``` |
| 6 | Key Benefits: |
| 7 | - Split payments instantly to creators, partners & teams |
| 8 | - Up to 10x cheaper than PayPal & Stripe |
| 9 | - Payouts in under 1 minute |
| 10 | - Unlimited recipients |
| 11 | \``` |
| 12 | |
| 13 | ## Authentication |
| 14 | |
| 15 | All authenticated endpoints require an API key in the header: |
| 16 | |
| 17 | \```http |
| 18 | X-API-Key: your_api_key_here |
| 19 | \``` |
| 20 | |
| 21 | ### API Key Tiers |
| 22 | |
| 23 | | Tier | Rate Limit | Features | |
| 24 | |------|------------|----------| |
| 25 | | No AUTH | 1000 requests/hour shared | Basic features | |
| 26 | | FREE | 1000 requests/hour | Higher limits, Custom Dashboard | |
| 27 | | BASIC | 2000 requests/hour | Higher limits, Custom Dashboard | |
| 28 | | PRO | 5000 requests/hour | Higher limits, advanced features | |
| 29 | | ENTERPRISE | 20000 requests/hour | Custom limits, priority support | |
| 30 | |
| 31 | ### Register for a Free API Key |
| 32 | |
| 33 | \``` |
| 34 | POST /api/v1/api-keys/register |
| 35 | |
| 36 | Request: |
| 37 | { |
| 38 | "email": "[email protected]", |
| 39 | "name": "your.key.name" |
| 40 | } |
| 41 | |
| 42 | Response: |
| 43 | { |
| 44 | "key": "SR_SECRET_d069a1d9a53ff1a77296d0223eb000ac", |
| 45 | "name": "your.key.name", |
| 46 | "tier": "FREE", |
| 47 | "status": "ACTIVE", |
| 48 | "rate_limit_per_hour": 1000, |
| 49 | "remaining_invoices": -1, |
| 50 | "created_at": "2025-03-25T19:06:33.107954Z", |
| 51 | "expires_at": "2124-03-01T19:06:33.107943Z", |
| 52 | "is_active": true |
| 53 | } |
| 54 | \``` |
| 55 | |
| 56 | ### Upgrade to Paid Tier |
| 57 | |
| 58 | \``` |
| 59 | POST /api/v1/api-keys/purchase |
| 60 | |
| 61 | Headers: |
| 62 | X-API-Key: your_current_api_key |
| 63 | |
| 64 | Request: |
| 65 | { |
| 66 | "tier": "BASIC", #PRO | ENTERPRISE |
| 67 | "billing_period": "monthly" #annual |
| 68 | } |
| 69 | |
| 70 | |
| 71 | Response: Invoice object to pay for the upgrade |
| 72 | \``` |
| 73 | |
| 74 | ## Core Endpoints |
| 75 | |
| 76 | ### Create an Invoice |
| 77 | |
| 78 | \``` |
| 79 | POST /api/v1/invoices |
| 80 | |
| 81 | Headers: |
| 82 | X-API-Key: your_api_key (optional for free tier) |
| 83 | |
| 84 | Request: |
| 85 | { |
| 86 | "nominal_amount": 29.9, |
| 87 | "nominal_currency": "EUR", |
| 88 | "destinations": [ |
| 89 | { |
| 90 | "account": "nano_123...", |
| 91 | "primary": true #only 1 primary allowed. |
| 92 | }, |
| 93 | { |
| 94 | "account": "nano_26qjv4lmg2s", |
| 95 | "percentage": 10, |
| 96 | "description": "Platform fee" #optional |
| 97 | }, |
| 98 | { |
| 99 | "account": "nano_3r7j5yfe2py", |
| 100 | "nominal_amount": 5 |
| 101 | } |
| 102 | ], |
| 103 | "show_qr": true, #optional |
| 104 | "webhook_url": "https://www.example.com/webhook", #optional |
| 105 | "webhook_secret": "your_webhook_secret", #optional |
| 106 | "reference": "custom-order-id" #optional |
| 107 | "simulate": false #optional |
| 108 | } |
| 109 | |
| 110 | Response: |
| 111 | { |
| 112 | "invoice_id": "INV_2025_03_d43d2995c143be1b59df", |
| 113 | "secret_id": "INV_SECRET_27b6888c19fa0a83d01da", |
| 114 | "account_address": "nano_1simu1ation0...", |
| 115 | "nominal_currency": "EUR", |
| 116 | "formatted_currency": "XNO", |
| 117 | "required": { |
| 118 | "unit_amount": "30567346000000000000000000000000", |
| 119 | "formatted_amount": "30.567346", |
| 120 | "nominal_amount": "29.9" |
| 121 | }, |
| 122 | "received": { |
| 123 | "unit_amount": "0", |
| 124 | "formatted_amount": "0", |
| 125 | "nominal_amount": "0" |
| 126 | }, |
| 127 | "exchange_rate": "0.978168", |
| 128 | "expires_at": "2025-03-25T19:29:10.159811Z", |
| 129 | "destinations": [ |
| 130 | { |
| 131 | "type": "primary", |
| 132 | "account": "nano_123...", |
| 133 | "unit_amount": "22246178670000000000000000000000", |
| 134 | "formatted_amount": "22.24617867", |
| 135 | "nominal_amount": "21.760" |
| 136 | }, |
| 137 | { |
| 138 | "type": "percentage", |
| 139 | "account": "nano_26qjv4lmg2s", |
| 140 | "unit_amount": "3056734600000000000000000000000", |
| 141 | "formatted_amount": "3.0567346", |
| 142 | "nominal_amount": "2.990", |
| 143 | "description": "Platform fee" |
| 144 | }, |
| 145 | { |
| 146 | "type": "fixed", |
| 147 | "account": "nano_3r7j5yfe2py", |
| 148 | "unit_amount": "5111596000000000000000000000000", |
| 149 | "formatted_amount": "5.111596", |
| 150 | "nominal_amount": "5.000" |
| 151 | }, |
| 152 | { |
| 153 | "type": "service_fee", |
| 154 | "account": "nano_1nowapi9w5hx3d4wb9swa88p8dd7tsf8xsycob3owy855sai6j9zuyztjzdj", |
| 155 | "unit_amount": "152836730000000000000000000000", |
| 156 | "formatted_amount": "0.15283673", |
| 157 | "nominal_amount": "0.149", |
| 158 | "description": "Service fee" |
| 159 | } |
| 160 | ], |
| 161 | "service_fee_rate": "0.50", |
| 162 | "show_qr": true, |
| 163 | "is_simulation": true, |
| 164 | "is_pending": false, |
| 165 | "is_paid": false, |
| 166 | "is_forwarded": false, |
| 167 | "is_done": false, |
| 168 | "is_expired": false, |
| 169 | "is_overpaid": false, |
| 170 | "qr_code": "base64_string_with_encoded_qr-code", |
| 171 | "uri_rfc_8905": "payto:nano/nano_1simu1ation00...?amount=30567346000000000000000000000000", |
| 172 | "uri_nano": "nano:nano_1simu1ation00...?amount=30567346000000000000000000000000" |
| 173 | } |
| 174 | \``` |
| 175 | |
| 176 | ### Get Invoice by ID |
| 177 | |
| 178 | \``` |
| 179 | GET /api/v1/invoices/{invoice_id} |
| 180 | |
| 181 | Response: Same as create invoice response |
| 182 | \``` |
| 183 | |
| 184 | ### Get Invoice by Secret ID |
| 185 | |
| 186 | \``` |
| 187 | GET /api/v1/invoices/secret/{secret_id} |
| 188 | |
| 189 | Response: Same as create invoice response |
| 190 | \``` |
| 191 | |
| 192 | ### Get Supported Currencies |
| 193 | |
| 194 | \``` |
| 195 | GET /api/v1/currencies |
| 196 | |
| 197 | Response: |
| 198 | [ |
| 199 | { |
| 200 | "code": "USD", |
| 201 | "name": "US Dollar", |
| 202 | "is_fiat": true, |
| 203 | "decimal_places": 6, |
| 204 | "min_amount": "0.000001", |
| 205 | "max_amount": "25000.00" |
| 206 | }, |
| 207 | { |
| 208 | "code": "EUR", |
| 209 | "name": "Euro", |
| 210 | ... |
| 211 | }, |
| 212 | { |
| 213 | "code": "XNO", |
| 214 | "name": "Nano", |
| 215 | "is_fiat": false, |
| 216 | ... |
| 217 | } |
| 218 | ] |
| 219 | \``` |
| 220 | |
| 221 | ## Payment Distribution Types |
| 222 | |
| 223 | When creating an invoice, you can specify multiple payment destinations: |
| 224 | |
| 225 | ### 1. Primary Destination |
| 226 | Receives remaining funds after other distributions are processed: |
| 227 | \```json |
| 228 | { |
| 229 | "account": "nano_1abc...", |
| 230 | "primary": true, |
| 231 | "description": "Main recipient" |
| 232 | } |
| 233 | \``` |
| 234 | |
| 235 | ### 2. Percentage-Based Distribution |
| 236 | Receives a specified percentage of the total amount: |
| 237 | \```json |
| 238 | { |
| 239 | "account": "nano_1def...", |
| 240 | "percentage": 25.5, |
| 241 | "description": "Partner fee (25.5%)" |
| 242 | } |
| 243 | \``` |
| 244 | |
| 245 | ### 3. Fixed Amount Distribution |
| 246 | Receives a specific amount, regardless of the total invoice amount: |
| 247 | \```json |
| 248 | { |
| 249 | "account": "nano_1ghi...", |
| 250 | "amount": 5.00, |
| 251 | "description": "Platform fee ($5.00)" |
| 252 | } |
| 253 | \``` |
| 254 | |
| 255 | ### Example Distribution |
| 256 | |
| 257 | \```json |
| 258 | { |
| 259 | "nominal_amount": 100.00, |
| 260 | "nominal_currency": "USD", |
| 261 | "destinations": [ |
| 262 | { |
| 263 | "account": "nano_1abc...", |
| 264 | "primary": true, |
| 265 | "description": "Main recipient" |
| 266 | }, |
| 267 | { |
| 268 | "account": "nano_2def...", |
| 269 | "percentage": 20, |
| 270 | "description": "Partner (20%)" |
| 271 | }, |
| 272 | { |
| 273 | "account": "nano_3ghi...", |
| 274 | "amount": 10.00, |
| 275 | "description": "Fixed fee ($10.00)" |
| 276 | } |
| 277 | ] |
| 278 | } |
| 279 | \``` |
| 280 | |
| 281 | Would distribute as: |
| 282 | 1. Service fee: 0.5% ($0.50) for free tier |
| 283 | 2. Fixed amount: $10.00 |
| 284 | 3. Percentage (20%): $20.00 |
| 285 | 4. Primary destination: $69.50 (remaining amount) |
| 286 | |
| 287 | ## Invoice Lifecycle |
| 288 | |
| 289 | The typical lifecycle of an invoice follows these steps: |
| 290 | |
| 291 | 1. **Created**: Invoice is created and ready to receive payment (all status flags are false initially) |
| 292 | 2. **Pending**: Invoice has received a partial payment (is_pending = true) |
| 293 | 3. **Paid**: Full payment has been received and confirmed (is_paid = true) |
| 294 | 4. **Forwarded**: Funds have been distributed to the specified destinations (is_forwarded = true) |
| 295 | 5. **Done**: Invoice processing is complete (is_done = true) |
| 296 | 6. **Expired**: Invoice has expired without being fully paid (is_expired = true, alternative end state) |
| 297 | |
| 298 | ## Real-time Payment Monitoring |
| 299 | |
| 300 | ### WebSocket Connection |
| 301 | |
| 302 | The WebSocket API allows you to receive real-time updates about invoice status changes and payment events. |
| 303 | |
| 304 | #### Connecting to the WebSocket |
| 305 | |
| 306 | To connect to the WebSocket for a specific invoice, use the following URL: |
| 307 | |
| 308 | `wss://api.splitroute.com/api/v1/ws/invoices/{invoice_id}` |
| 309 | |
| 310 | Replace `{invoice_id}` with the ID of the invoice you want to monitor (e.g., INV_2025_03_d43d2995c143be1b59df). |
| 311 | |
| 312 | #### Message Format |
| 313 | |
| 314 | Messages sent through the WebSocket are in JSON format with a standardized structure: |
| 315 | |
| 316 | \```json |
| 317 | { |
| 318 | "timestamp": "2025-03-31T09:18:11.897603+00:00", |
| 319 | "message_type": "invoice", |
| 320 | "category": "updated", |
| 321 | "payload": { |
| 322 | "id": "INV_2025_03_62fcb6bc256f6fad7622", |
| 323 | "timestamp": "2025-03-31T09:18:11.890364+00:00", |
| 324 | "event_type": "invoice.paid", |
| 325 | "unit_amount": "2000000000000000000000000", |
| 326 | "formatted_amount": "0.000002", |
| 327 | "nominal_amount": "0.000002", |
| 328 | "is_paid": true, |
| 329 | "is_expired": false, |
| 330 | "currency": "EUR", |
| 331 | "exchange_rate": "0.8221560000" |
| 332 | } |
| 333 | } |
| 334 | \``` |
| 335 | |
| 336 | #### Event Types and Categories |
| 337 | |
| 338 | The WebSocket API sends events in the following categories: |
| 339 | |
| 340 | | Category | Description | |
| 341 | |----------|-------------| |
| 342 | | `updated` | Invoice has been updated | |
| 343 | | `completed` | Invoice processing is complete | |
| 344 | | `failed` | Invoice has failed or expired | |
| 345 | | `payment` | Payment has been confirmed | |
| 346 | |
| 347 | ##### Available Event Types |
| 348 | |
| 349 | The following specific event types can be received through the WebSocket: |
| 350 | |
| 351 | | Event | Description | |
| 352 | |-------|-------------| |
| 353 | | `invoice.created` | Invoice has been created | |
| 354 | | `invoice.paid` | Payment has been received | |
| 355 | | `invoice.expired` | Invoice has expired without payment | |
| 356 | | `invoice.forwarded` | Funds have been forwarded (if using forward_account) | |
| 357 | | `invoice.done` | Invoice processing is complete | |
| 358 | | `payment.confirmed` | A payment transaction has been confirmed | |
| 359 | |
| 360 | #### Example JavaScript Implementation |
| 361 | |
| 362 | \```javascript |
| 363 | const invoiceId = 'INV_2025_03_d1447da3e9ff90cd3822'; |
| 364 | const socket = new WebSocket(`wss://api.splitroute.com/api/v1/ws/invoices/${invoiceId}`); |
| 365 | |
| 366 | socket.onopen = function(e) { |
| 367 | console.log('Connected to WebSocket'); |
| 368 | }; |
| 369 | |
| 370 | socket.onmessage = function(event) { |
| 371 | const message = JSON.parse(event.data); |
| 372 | console.log(`Received message type: ${message.message_type}, category: ${message.category}`); |
| 373 | |
| 374 | // Check for invoice payment |
| 375 | if (message.payload.event_type === 'invoice.paid') { |
| 376 | console.log('Invoice has been paid!'); |
| 377 | console.log(`Received amount (formatted): ${message.payload.formatted_amount}`); |
| 378 | // Update your UI or take other actions |
| 379 | } |
| 380 | |
| 381 | // Check for invoice completion |
| 382 | if (message.category === 'completed') { |
| 383 | console.log('Invoice processing completed'); |
| 384 | // Close the connection as we're done |
| 385 | socket.close(); |
| 386 | } |
| 387 | }; |
| 388 | |
| 389 | socket.onclose = function(event) { |
| 390 | if (event.wasClean) { |
| 391 | console.log(`Connection closed cleanly, code=${event.code} reason=${event.reason}`); |
| 392 | } else { |
| 393 | console.log('Connection died'); |
| 394 | } |
| 395 | }; |
| 396 | |
| 397 | socket.onerror = function(error) { |
| 398 | console.log(`WebSocket error: ${error.message}`); |
| 399 | }; |
| 400 | \``` |
| 401 | |
| 402 | #### Connection Limits |
| 403 | |
| 404 | - Each invoice can have up to 5 simultaneous WebSocket connections |
| 405 | - Connections will be automatically closed after 15 minutes (900 seconds) of inactivity |
| 406 | - If an invoice is marked as done or expired, all connections will be closed after a 5-minute grace period |
| 407 | |
| 408 | ### Webhook Integration |
| 409 | |
| 410 | When creating an invoice, include webhook details: |
| 411 | |
| 412 | \```json |
| 413 | { |
| 414 | "webhook_url": "https://your-server.com/webhook", |
| 415 | "webhook_secret": "your_webhook_secret" |
| 416 | } |
| 417 | \``` |
| 418 | |
| 419 | Webhook events: |
| 420 | - `invoice.created` - Invoice has been created |
| 421 | - `invoice.paid` - Payment has been received |
| 422 | - `invoice.expired` - Invoice has expired without payment |
| 423 | - `invoice.forwarded` - Funds have been forwarded |
| 424 | - `invoice.done` - Invoice processing is complete |
| 425 | |
| 426 | Webhook notifications include a signature header for verification: |
| 427 | \``` |
| 428 | X-Webhook-Signature: signature |
| 429 | X-Webhook-Timestamp: timestamp |
| 430 | \``` |
| 431 | |
| 432 | ## Error Handling |
| 433 | |
| 434 | Error responses follow this format: |
| 435 | |
| 436 | \```json |
| 437 | { |
| 438 | "error": "error_code", |
| 439 | "message": "Human-readable error message", |
| 440 | "details": { |
| 441 | "field": "Additional information about the error" |
| 442 | } |
| 443 | } |
| 444 | \``` |
| 445 | |
| 446 | Common status codes: |
| 447 | - `200 OK` - Success |
| 448 | - `400 Bad Request` - Invalid request |
| 449 | - `401 Unauthorized` - Authentication failed |
| 450 | - `429 Too Many Requests` - Rate limit exceeded |
| 451 | |
| 452 | Rate limit headers: |
| 453 | \``` |
| 454 | X-RateLimit-Limit: 60 |
| 455 | X-RateLimit-Remaining: 58 |
| 456 | X-RateLimit-Reset: 1609459200 |
| 457 | \``` |
| 458 | |
| 459 | ## Base URL |
| 460 | |
| 461 | \``` |
| 462 | https://api.splitroute.com |
| 463 | \``` |
| 464 | |
| 465 | ## Implementation Example |
| 466 | |
| 467 | \```javascript |
| 468 | // Create an invoice |
| 469 | async function createInvoice() { |
| 470 | const response = await fetch('https://api.splitroute.com/api/v1/invoices', { |
| 471 | method: 'POST', |
| 472 | headers: { |
| 473 | 'Content-Type': 'application/json', |
| 474 | 'X-API-Key': 'your_api_key' |
| 475 | }, |
| 476 | body: JSON.stringify({ |
| 477 | nominal_amount: 10.00, |
| 478 | nominal_currency: 'USD', |
| 479 | destinations: [ |
| 480 | { |
| 481 | account: 'nano_1abc...', |
| 482 | primary: true |
| 483 | }, |
| 484 | { |
| 485 | account: 'nano_2def...', |
| 486 | percentage: 20, |
| 487 | description: 'Partner (20%)' |
| 488 | } |
| 489 | ], |
| 490 | reference: 'example-invoice' |
| 491 | }) |
| 492 | }); |
| 493 | |
| 494 | const invoice = await response.json(); |
| 495 | |
| 496 | // Connect to WebSocket for real-time updates |
| 497 | const socket = new WebSocket(`wss://api.splitroute.com/api/v1/ws/invoices/${invoice.invoice_id}`); |
| 498 | |
| 499 | socket.onmessage = function(event) { |
| 500 | const message = JSON.parse(event.data); |
| 501 | |
| 502 | // Handle different event types |
| 503 | switch(message.payload.event_type) { |
| 504 | case 'invoice.paid': |
| 505 | console.log('Invoice has been paid!'); |
| 506 | console.log(`Amount received: ${message.payload.formatted_amount}`); |
| 507 | // Update your system to reflect payment |
| 508 | break; |
| 509 | case 'invoice.forwarded': |
| 510 | console.log('Payment has been forwarded to destinations'); |
| 511 | break; |
| 512 | case 'invoice.done': |
| 513 | console.log('Invoice processing is complete'); |
| 514 | socket.close(); |
| 515 | break; |
| 516 | case 'invoice.expired': |
| 517 | console.log('Invoice has expired without full payment'); |
| 518 | socket.close(); |
| 519 | break; |
| 520 | } |
| 521 | }; |
| 522 | |
| 523 | return invoice; |
| 524 | } |
| 525 | \``` |
