Bulk Payout Operations

Send money to multiple recipients in a single batch operation via Wave B2P. Process up to 100 recipients per batch with a minimum amount of 100 GMD per recipient.

INFO

For API key requests, no OTP is required. For session-based requests (web dashboard), you must complete the OTP flow first.

Send Bulk Payouts

Send money to multiple recipients in a single batch operation.

Endpoint: POST /v1/payouts/recipients/send-bulk

Authentication: Required

Request Body:

Field	Type	Required	Description
`payouts`	array	Yes	Array of payout items (max 100)
`payouts[].recipient_id`	string	Yes	ID of the recipient
`payouts[].amount`	string	Yes	Amount to send (minimum 100 GMD)
`payouts[].description`	string	No	Optional payment description

Example:

HTTP

TypeScript

Python

Success Response (201 Created):

{
  "data": {
    "id": "batch_abc123",
    "organization_id": "org_xyz789",
    "total_amount": "2250.00",
    "total_count": 3,
    "successful_count": 0,
    "failed_count": 0,
    "pending_count": 3,
    "status": "pending",
    "payouts": [
      {
        "id": "rp_001",
        "recipient_id": "rec_abc123",
        "amount": "500.00",
        "status": "pending",
        "error_message": null
      },
      {
        "id": "rp_002",
        "recipient_id": "rec_def456",
        "amount": "750.00",
        "status": "pending",
        "error_message": null
      },
      {
        "id": "rp_003",
        "recipient_id": "rec_ghi789",
        "amount": "1000.00",
        "status": "pending",
        "error_message": null
      }
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "completed_at": null
  }
}

Error (400 Bad Request):

{
  "error": "Insufficient balance. Available: 1500.00 GMD, Required: 2250.00 GMD"
}

{
  "error": "Invalid amount for recipient rec_abc123. Minimum: 100 GMD"
}

{
  "error": "Recipient rec_def456 is inactive"
}

Error (401 Unauthorized):

{
  "error": "Invalid API key"
}

Get Bulk Payout Batch

Retrieve the status and details of a bulk payout batch, including individual payout statuses.

Endpoint: GET /v1/payouts/recipients/batches/{id}

Authentication: Required

URL Parameters:

Name	Type	Required	Description
`id`	string	Yes	Batch ID

Example:

HTTP

TypeScript

Python

Success Response (200 OK):

{
  "data": {
    "id": "batch_abc123",
    "organization_id": "org_xyz789",
    "total_amount": "2250.00",
    "total_count": 3,
    "successful_count": 2,
    "failed_count": 1,
    "pending_count": 0,
    "status": "partially_completed",
    "payouts": [
      {
        "id": "rp_001",
        "recipient_id": "rec_abc123",
        "amount": "500.00",
        "status": "completed",
        "error_message": null
      },
      {
        "id": "rp_002",
        "recipient_id": "rec_def456",
        "amount": "750.00",
        "status": "completed",
        "error_message": null
      },
      {
        "id": "rp_003",
        "recipient_id": "rec_ghi789",
        "amount": "1000.00",
        "status": "failed",
        "error_message": "Recipient phone number invalid"
      }
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "completed_at": "2024-01-15T10:05:30Z"
  }
}

Error (404 Not Found):

{
  "error": "Batch not found"
}

Error (401 Unauthorized):

{
  "error": "Invalid API key"
}

Batch Status Values

Status	Description
`pending`	Batch created, waiting to process
`processing`	Currently processing payouts
`completed`	All payouts completed successfully
`partially_completed`	Some payouts succeeded, some failed
`failed`	All payouts failed

Upload CSV for Bulk Payouts

Upload a CSV file containing recipient payout data. The file will be validated and stored for processing.

INFO

CSV Format Requirements:

Maximum file size: 5MB

Maximum 1000 rows

Required columns: recipient_id, amount

Optional column: description

Endpoint: POST /v1/payouts/recipients/send-bulk/upload-csv

Authentication: Required

Request Body:

The request must use multipart/form-data encoding.

Field	Type	Required	Description
`file`	binary	Yes	CSV file containing payout data

CSV Format Example

recipient_id,amount,description
rec_abc123,500.00,Monthly payment
rec_def456,750.00,Bonus payment
rec_ghi789,1000.00,Commission
rec_jkl012,500.00,Monthly payment
rec_mno345,250.00,Partial payment

Example:

HTTP

TypeScript

Python

Success Response (200 OK):

{
  "data": {
    "upload_id": "upload_xyz789",
    "rows_count": 45,
    "total_amount": "22500.00",
    "validation_errors": [],
    "expires_at": "2024-01-15T11:00:00Z"
  }
}

Success with Validation Errors (200 OK):

{
  "data": {
    "upload_id": "upload_xyz789",
    "rows_count": 43,
    "total_amount": "21500.00",
    "validation_errors": [
      {
        "row": 5,
        "field": "amount",
        "error": "Invalid amount format. Must be a decimal number"
      },
      {
        "row": 12,
        "field": "recipient_id",
        "error": "Recipient not found"
      }
    ],
    "expires_at": "2024-01-15T11:00:00Z"
  }
}

Error (400 Bad Request):

{
  "error": "File size exceeds 5MB limit"
}

{
  "error": "CSV exceeds maximum of 1000 rows"
}

{
  "error": "Invalid CSV format. Missing required column: recipient_id"
}

Error (401 Unauthorized):

{
  "error": "Invalid API key"
}

Process CSV Bulk Payouts

Process a previously uploaded CSV file to create bulk payouts.

INFO

For API key requests, no OTP is required. For session-based requests (web dashboard), you must complete the OTP flow first.

Endpoint: POST /v1/payouts/recipients/send-bulk/csv

Authentication: Required

Request Body:

Field	Type	Required	Description
`upload_id`	string	Yes	ID returned from the CSV upload endpoint

Example:

HTTP

TypeScript

Python

Success Response (201 Created):

{
  "data": {
    "id": "batch_csv123",
    "organization_id": "org_xyz789",
    "total_amount": "22500.00",
    "total_count": 45,
    "successful_count": 0,
    "failed_count": 0,
    "pending_count": 45,
    "status": "pending",
    "payouts": [
      {
        "id": "rp_001",
        "recipient_id": "rec_abc123",
        "amount": "500.00",
        "status": "pending",
        "error_message": null
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": null
  }
}

Error (400 Bad Request):

{
  "error": "Upload has expired. Please upload the CSV again"
}

{
  "error": "Insufficient balance. Available: 10000.00 GMD, Required: 22500.00 GMD"
}

Error (404 Not Found):

{
  "error": "Upload not found"
}

Error (401 Unauthorized):

{
  "error": "Invalid API key"
}

Send Bulk Payouts by Type

Send the same amount to all recipients of a specific type (e.g., all employees, all vendors). Useful for monthly salary payments, bonuses, or uniform distributions.

INFO

For API key requests, no OTP is required. For session-based requests (web dashboard), you must complete the OTP flow first.

Endpoint: POST /v1/payouts/recipients/send-bulk/by-type

Authentication: Required

Request Body:

Field	Type	Required	Description
`recipient_type`	string	Yes	Type of recipients to send to (e.g., "employee", "vendor")
`amount_per_recipient`	string	Yes	Amount to send to each recipient (minimum 100 GMD)
`description`	string	No	Optional payment description

Example:

HTTP

TypeScript

Python

Success Response (201 Created):

{
  "data": {
    "id": "batch_type123",
    "organization_id": "org_xyz789",
    "total_amount": "30000.00",
    "total_count": 30,
    "successful_count": 0,
    "failed_count": 0,
    "pending_count": 30,
    "status": "pending",
    "payouts": [
      {
        "id": "rp_001",
        "recipient_id": "rec_emp001",
        "amount": "1000.00",
        "status": "pending",
        "error_message": null
      },
      {
        "id": "rp_002",
        "recipient_id": "rec_emp002",
        "amount": "1000.00",
        "status": "pending",
        "error_message": null
      }
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "completed_at": null
  }
}

Error (400 Bad Request):

{
  "error": "No active recipients found with type: contractor"
}

{
  "error": "Insufficient balance. Available: 15000.00 GMD, Required: 30000.00 GMD"
}

{
  "error": "Invalid amount. Minimum: 100 GMD"
}

Error (401 Unauthorized):

{
  "error": "Invalid API key"
}

Use Cases

Monthly salary payments: Send uniform salary to all employees

Bonus distributions: Pay bonuses to all active vendors

Uniform distributions: Send the same amount to a specific category

Best Practices

1. Check Balance Before Bulk Operations

Always verify your payout balance before initiating bulk operations:

TypeScript

Python

2. Monitor Batch Status

Poll the batch status endpoint to track progress:

TypeScript

Python

3. Handle Validation Errors in CSV Uploads

Always check for validation errors after uploading a CSV:

TypeScript

Python

4. Retry Failed Payouts

After a batch completes, identify and retry failed payouts:

TypeScript

Python

5. Use Appropriate Bulk Method

Choose the right bulk payout method for your use case:

Method	Use Case	Best For
`sendBulkPayouts`	Variable amounts per recipient	Custom payment amounts, mixed purposes
`uploadBulkPayoutCSV` + `processBulkPayoutCSV`	Large batches from spreadsheets	100+ recipients, data from external systems
`sendBulkPayoutsByType`	Same amount to all recipients of a type	Uniform distributions, monthly salaries

Currency Information

All payout operations use GMD (Gambian Dalasi) exclusively. The Jokoor platform does not support multi-currency operations.

Minimum payout amount: 100 GMD

All amounts must be formatted as decimal strings (e.g., "500.00")

No currency conversion is available

Support

For questions or issues with payout operations:

Email: support@jokoor.com

Documentation: https://docs.jokoor.com

Status: https://status.jokoor.com

Bulk Payout Operations

Send Bulk Payouts#

Get Bulk Payout Batch#

Batch Status Values#

Upload CSV for Bulk Payouts#

CSV Format Example#

Process CSV Bulk Payouts#

Send Bulk Payouts by Type#

Use Cases#

Best Practices#

1. Check Balance Before Bulk Operations#

2. Monitor Batch Status#

3. Handle Validation Errors in CSV Uploads#

4. Retry Failed Payouts#

5. Use Appropriate Bulk Method#

Currency Information#

Support#

Send Bulk Payouts

Get Bulk Payout Batch

Batch Status Values

Upload CSV for Bulk Payouts

CSV Format Example

Process CSV Bulk Payouts

Send Bulk Payouts by Type

Use Cases

Best Practices

1. Check Balance Before Bulk Operations

2. Monitor Batch Status

3. Handle Validation Errors in CSV Uploads

4. Retry Failed Payouts

5. Use Appropriate Bulk Method

Currency Information

Support