---
title: "Initiate a bulk payout"
method: POST
path: "/batch-payout"
tags: ["Payout"]
---

# Initiate a bulk payout

`POST /batch-payout`

Use this endpoint to send a bulk payout. After payment is completed merchant webhook is called to notify status 
of each transation. For security reason, we do not allow merchant to generate permission for this end point, please contact us
 in order to get a secret key for testing bulk payout on sandbox.

## Query parameters

- `payment_type` 'wave_money' | 'orange_money' | 'maxit' | 'mtn_money' | 'free_money' | 'moov' | 'mobicash' | 'togocell' | 'bictorys' | 'card', required — The type parameter allows to select the payout service provider. E.g mtn_money, orange_money, wave_money, move_money
- `country_code` 'SN' | 'CI' | 'ML', required — Country Code of the beneficiaries

## Headers

- `X-Batch-Reference` string
- `idempotency-key` string, uuid
- `X-Amzn-Trace-Id` string

## Request body

- BulkPayoutObjectRequest[]
  - `amount` number, double, required — This is the amount to be sent to the customer.
  - `currency` string, required — The currency to use.
  - `country` string — The iSO country code of the phone number used for payout. This field is mandatory except for card payment
  - `customerId` string, uuid — Optional. Unique Id of the customer. If provided, customer object below is ignored.
  - `customerObject` CustomerObject
    - `id` string, uuid — unique uuid of the customer
    - `name` string — customer's full name
    - `phone` string — customer's mobile phone number.
    - `email` string — the email of the customer
    - `address` string — Full street address, which MAY include house number, street name, Post Office Box, etc
    - `city` string — City or locality component.
    - `postalCode` string — Zip code or postal code component.
    - `country` string, required — ISO3166-1 alpha-2 two letter, uppercase.
    - `locale` string — User locale, language is lower case. Country in upper case
    - `createdAt` string — The date time that record was created in our system.
    - `updatedAt` string — The date time that record was updated in our system.
  - `transactionType` 'payment' | 'transfer' | 'refund' | 'settlement' — type of transaction
  - `paymentReason` string — An optional message with a payment reason that is shown to customers in the payment receipt
  - `merchantReference` string — reference passed by client in the request

## Response `202`

The batch payout transaction is initiated.

- BatchPayoutObjectResponse
  - `id` string — Unique identifier of the batch payout transaction

## Other responses

- `400` — Bad Request
- `401` — The caller is unauthenticated
- `403` — Access rights not sufficient
- `500` — Internal Server Error.

---

[API](https://skmtc.dev/bictorys/apis/pay.md) · [All operations](https://skmtc.dev/bictorys/apis/pay/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bictorys/pay/revisions/b85cce14340b/schema)