Skip to content
Reference
/
/
Create bulk payout

Create bulk payout

Request

🔒 Private label — contact sales. Requires a private-label entitlement on your API client.

Create bulk payout

Security
oauth2ClientCredentials(Required scopes: payments:write)
Headers
org_wallet_refstring

Organization wallet reference, defaults to "1" if not provided

business_idstringrequired

Business identifier for the request

Bodyapplication/jsonrequired
recordsArray of objects(PayoutRecordRequestV1Dto)required

Array of payout records (at least one required)

Example:
[
  {
    "name": "carol mwangi",
    "phone": 796725019,
    "email": "",
    "amount": 10,
    "description": "test",
    "team": "DE8832C7",
    "category_code": "P003",
    "payment_type": "mpesa",
    "bank_code": "",
    "receiver": 796725019,
    "account_no": "",
    "idno": "",
    "mpesa_number": 796725019,
    "tags": [],
    "country": "Kenya",
    "category_name": "General Materials"
  }
]
descriptionstringrequired

Batch description

Example:"test"
batchnostringrequired

Unique batch number

Example:"K8SpPERUGO9f"
accountrefnumberrequired

Account reference (org wallet)

Example:1
statusstringrequired

Batch status

Enum:"draft""pending"
Example:"draft"
initiator_idstringrequired

Initiator ID

Example:"28AFC4D3DD4A27BC077E204E"
team_codestringrequired

Team code

Example:"DE8832C7"
team_namestringrequired

Team name

Example:"Petty cash"
attachmentsArray of strings

File attachments

Example:
[]
allowDuplicatesbooleanrequired

Allow duplicate payments

Default:true
Example:true
countrystringrequired

Country

Default:"Kenya"
Example:"Kenya"
sourcestring

Selected payout source wallet ID

Example:"12007"
source_namestring

Selected payout source wallet name

Example:"Test Wallet"
curl -i -X POST \
  https://developer.boyahq.com/_mock/v2/openapi/payments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -H 'org_wallet_ref: string' \
  -d '{
    "records": [
      {
        "name": "carol mwangi",
        "phone": 796725019,
        "email": "",
        "amount": 10,
        "description": "test",
        "team": "DE8832C7",
        "category_code": "P003",
        "payment_type": "mpesa",
        "bank_code": "",
        "receiver": 796725019,
        "account_no": "",
        "idno": "",
        "mpesa_number": 796725019,
        "tags": [],
        "country": "Kenya",
        "category_name": "General Materials"
      }
    ],
    "description": "test",
    "batchno": "K8SpPERUGO9f",
    "accountref": 1,
    "status": "draft",
    "initiator_id": "28AFC4D3DD4A27BC077E204E",
    "team_code": "DE8832C7",
    "team_name": "Petty cash",
    "attachments": [],
    "allowDuplicates": true,
    "country": "Kenya",
    "source": "12007",
    "source_name": "Test Wallet"
  }'

Responses

Bulk payout batch created successfully

Bodyapplication/json
_idstring

Bulk payment MongoDB ID

batch_nostring

Unique batch number

typenumber

Payment batch type

recordsArray of objects(PaymentRecordV1Dto)

Individual payment records

notesstring

Batch notes

org_wallet_refstring

Organization wallet reference

currencystring

Currency code

Example:"KES"
mandate_requirednumber

Whether mandate is required

attachmentsArray of strings

File attachments

approversArray of objects(ApproverV1Dto)

Approvers for this batch

initiated_bystring

Name of person who initiated

initiated_by_idstring

ID of person who initiated

callbackURLstring

Callback URL for payment processing

initiated_onstring

Formatted initiation date

eventsArray of objects(EventV1Dto)

Activity and approval events

statusstring

Batch status

Enum:"pending""processed""failed""cancelled""draft"
budgetobject

Associated budget

collaboratorsArray of strings

Collaborator IDs

createdAtstring

Created timestamp

updatedAtstring

Updated timestamp

__vnumber

Version key

idstring

Alias for _id

feesnumber

Total fees

payout_amountnumber

Total payout amount

amountnumber

Total amount

initiated_by_namestring

Name of initiator (alias)

summaryobject(PaymentSummaryV1Dto)

Payment summary by type

recordsProcessednumber

Number of records processed

amountProcessednumber

Amount processed

recordsFailednumber

Number of failed records

sourcestring

Source wallet ID

source_namestring

Source wallet name

Response
{
  "_id": "string",
  "batch_no": "string",
  "type": 0,
  "records": [
    { … }
  ],
  "notes": "string",
  "org_wallet_ref": "string",
  "currency": "KES",
  "mandate_required": 0,
  "attachments": [
    "string"
  ],
  "approvers": [
    { … }
  ],
  "initiated_by": "string",
  "initiated_by_id": "string",
  "callbackURL": "string",
  "initiated_on": "string",
  "events": [
    { … }
  ],
  "status": "pending",
  "budget": {},
  "collaborators": [
    "string"
  ],
  "createdAt": "string",
  "updatedAt": "string",
  "__v": 0,
  "id": "string",
  "fees": 0,
  "payout_amount": 0,
  "amount": 0,
  "initiated_by_name": "string",
  "summary": {
    "mpesa": 0,
    "pochi": 0,
    "boya": 0,
    "bank": 0,
    "rtgs": 0,
    "till": 0,
    "airtime": 0,
    "paybill": 0,
    "xente": 0,
    "mtn": 0,
    "airtel": 0
  },
  "recordsProcessed": 0,
  "amountProcessed": 0,
  "recordsFailed": 0,
  "source": "string",
  "source_name": "string"
}