Create Bulk Transactions

​

Request Body

​

Response

​

Synchronous Response (run_async: false)

​

Asynchronous Response (run_async: true)

​

Error Response

{
  "batch_id": "batch_a1b2c3d4e5f6",
  "status": "applied",
  "transaction_count": 3
}

curl -X POST https://api.blnkfinance.com/transactions/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "transactions": [
      {
        "amount": 100.00,
        "reference": "batch-txn-001",
        "currency": "USD",
        "description": "Payment 1",
        "source": "bln_src123",
        "destination": "bln_dst456"
      },
      {
        "amount": 200.00,
        "reference": "batch-txn-002",
        "currency": "USD",
        "description": "Payment 2",
        "source": "bln_src123",
        "destination": "bln_dst789"
      }
    ],
    "run_async": false
  }'

​

Synchronous vs Asynchronous Processing

​

Synchronous Mode (run_async: false)

• Small batches (<100 transactions)
• Immediate confirmation needed
• Atomic operations required

• API waits for all transactions to complete
• Returns final status and count
• Supports atomic transactions
• Request may take longer for large batches

• 201 Created - All transactions successful
• 400 Bad Request - Validation or processing error

​

Asynchronous Mode (run_async: true)

• Large batches (>100 transactions)
• Background processing acceptable
• Non-atomic operations

• Returns immediately with batch ID
• Processes transactions in background
• Does not support atomic operations
• Maximum 100 concurrent async batches

• 202 Accepted - Batch queued for processing
• 400 Bad Request - Invalid request body

​

Atomic Transactions

1. All transactions are validated first
2. All transactions are processed
3. If any transaction fails:
   • All successful transactions are rolled back
   • Entire batch is rejected
   • Error details are returned

​

Example Atomic Batch

{
  "transactions": [
    {"amount": 100, "reference": "step1", ...},
    {"amount": 50, "reference": "step2", ...},
    {"amount": 25, "reference": "step3", ...}
  ],
  "atomic": true,
  "run_async": false
}

• Transaction “step1” is rolled back
• Transaction “step3” is not processed
• No balance changes occur
• Error response includes failure details

​

Batch Limits

​

Concurrency Limits

• Async batches: Maximum 100 concurrent
• Async transactions: Maximum 20 concurrent processors

​

Batch Size Recommendations

• Synchronous: Up to 100 transactions
• Asynchronous: Up to 10,000 transactions
• Atomic: Up to 50 transactions (to ensure fast rollback)

​

Transaction Object Structure

{
  "amount": 100.00,
  "precise_amount": "10000",  // Alternative to amount
  "reference": "unique-ref",  // Required, must be unique
  "currency": "USD",          // Required
  "description": "...",       // Required
  "source": "bln_xxx",        // Required (or sources)
  "destination": "bln_yyy",   // Required (or destinations)
  "precision": 100,
  "rate": 1.0,
  "allow_overdraft": false,
  "overdraft_limit": 0,
  "scheduled_for": "2024-01-20T10:00:00+00:00",
  "sources": [...],           // For multi-source
  "destinations": [...],      // For multi-destination
  "meta_data": {}
}

​

Error Handling

​

Validation Errors

{
  "error": "Invalid request body: transactions is required"
}

​

Processing Errors (Synchronous)

{
  "error": "transaction failed: insufficient balance in bln_src123",
  "batch_id": "batch_abc123"
}

​

Processing Errors (Asynchronous)

1. Logged to system logs
2. Sent via webhooks (if configured)
3. Recorded in transaction status

​

Best Practices

1. Use unique references - Each transaction needs a unique reference for idempotency
2. Choose the right mode:
   • Synchronous for <100 transactions or when atomic is needed
   • Asynchronous for large batches
3. Handle atomic carefully - Only use atomic mode when all transactions must succeed together
4. Monitor async batches - Use batch_id to track progress via webhooks or polling
5. Batch similar transactions - Group transactions by currency, type, or operation for better performance
6. Set appropriate timeouts - Synchronous requests may take time for large batches

​

Use Cases

​

Payroll Processing

{
  "transactions": [
    {"amount": 5000, "reference": "salary-emp001", "destination": "emp001_account", ...},
    {"amount": 4500, "reference": "salary-emp002", "destination": "emp002_account", ...}
  ],
  "atomic": true,
  "run_async": false
}

​

Mass Payouts

{
  "transactions": [
    {"amount": 10, "reference": "payout-001", ...},
    {"amount": 25, "reference": "payout-002", ...}
    // ... thousands more
  ],
  "run_async": true
}

​

Card Authorization Batch

{
  "transactions": [
    {"amount": 50, "reference": "auth-001", ...},
    {"amount": 75, "reference": "auth-002", ...}
  ],
  "inflight": true,
  "run_async": false
}