Skip to content
Reference
/
/
Initiate draft payout

Initiate draft payout

Request

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

Initiate draft payout

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

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

business_idstringrequired

Business identifier for the request

Bodyapplication/json
sourcestring

Selected payout source wallet ID

Example:"T312007"
source_namestring

Selected payout source wallet name

Example:"OCHOA"
curl -i -X PATCH \
  'https://developer.boyahq.com/_mock/v2/openapi/payments/{batch_no}/initiate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -H 'org_wallet_ref: string' \
  -d '{
    "source": "T312007",
    "source_name": "OCHOA"
  }'

Responses

Payout initiated 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"
}