> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payvessel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Transfer

> Initiate multiple wallet transfers in a single batch

Use this endpoint to **send multiple payouts from your business wallet in one request**. Each transfer in the batch debits your wallet and credits a different beneficiary account.

<Warning>
  Bulk transfers are powerful: always validate input (bank codes, account numbers, amounts) before sending a batch, and use unique references for each row.
</Warning>

### Sandbox

```bash theme={null}
curl -X POST "https://sandbox.payvessel.com/pms/api/external/request/wallet/bulk-transfer/" \
  -H "api-key: YOUR_SANDBOX_API_KEY" \
  -H "api-secret: YOUR_SANDBOX_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"batch_reference":"PAYROLL_2026_03","transfers":[{"amount":"15000.00","account_number":"0123456789","bank_code":"999991","account_name":"John Doe","narration":"Salary March","reference":"PAYROLL_001"}]}'
```

## Endpoint

<Badge variant="success">**POST**</Badge> `/pms/api/external/request/wallet/bulk-transfer/`

## Request Body

<ParamField body="batch_reference" type="string" required>
  Unique reference for this bulk batch (for reconciliation)

  <Warning>Must be unique across all your bulk transfers</Warning>
</ParamField>

<ParamField body="transfers" type="array" required>
  List of individual transfers in the batch

  <Expandable title="Transfer Object">
    <ParamField body="transfers[].amount" type="string" required>
      Amount to send for this transfer in the smallest currency unit (e.g. `"15000.00"`)
    </ParamField>

    <ParamField body="transfers[].account_number" type="string" required>
      Destination bank account number
    </ParamField>

    <ParamField body="transfers[].bank_code" type="string" required>
      Destination bank code (see bank list endpoint for available codes)
    </ParamField>

    <ParamField body="transfers[].account_name" type="string">
      Optional account name for your own records
    </ParamField>

    <ParamField body="transfers[].narration" type="string">
      Description that may appear on the beneficiary's statement
    </ParamField>

    <ParamField body="transfers[].reference" type="string" required>
      Unique reference for this specific transfer in the batch

      <Warning>Must be unique across all transfers in this batch</Warning>
    </ParamField>
  </Expandable>
</ParamField>

### Example request

```json theme={null}
{
  "batch_reference": "PAYROLL_2026_03",
  "transfers": [
    {
      "amount": "15000.00",
      "account_number": "0123456789",
      "bank_code": "999991",
      "account_name": "John Doe",
      "narration": "March salary",
      "reference": "PAYROLL_2026_03_EMP001"
    },
    {
      "amount": "20000.00",
      "account_number": "0987654321",
      "bank_code": "120001",
      "account_name": "Jane Smith",
      "narration": "March salary",
      "reference": "PAYROLL_2026_03_EMP002"
    }
  ]
}
```

### Example cURL

```bash theme={null}
curl -X POST "https://api.payvessel.com/pms/api/external/request/wallet/bulk-transfer/" \
  -H "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_reference": "PAYROLL_2026_03",
    "transfers": [
      {
        "amount": "15000.00",
        "account_number": "0123456789",
        "bank_code": "999991",
        "account_name": "John Doe",
        "narration": "March salary",
        "reference": "PAYROLL_2026_03_EMP001"
      },
      {
        "amount": "20000.00",
        "account_number": "0987654321",
        "bank_code": "120001",
        "account_name": "Jane Smith",
        "narration": "March salary",
        "reference": "PAYROLL_2026_03_EMP002"
      }
    ]
  }'
```

## Response

On success you receive high‑level information about the batch:

```json theme={null}
{
  "status": true,
  "message": "Bulk transfer initiated",
  "data": {
    "batch_reference": "PAYROLL_2026_03",
    "total_count": 2,
    "successful_count": 2,
    "failed_count": 0,
    "total_amount": "35000.00"
  }
}
```

For detailed per‑transfer status, use the **transfer status** and **wallet transactions** endpoints.


## OpenAPI

````yaml POST /pms/api/external/request/wallet/bulk-transfer/
openapi: 3.1.0
info:
  title: PayVessel API
  description: >-
    PayVessel API for accepting payments, sending money, verifying identities,
    and managing wallets
  version: 1.0.0
servers:
  - url: https://api.payvessel.com
  - url: https://sandbox.payvessel.com
security:
  - {}
paths:
  /pms/api/external/request/wallet/bulk-transfer/:
    post:
      tags:
        - Transfers
      summary: Bulk Transfer
      description: Initiate multiple wallet transfers in a single batch
      parameters:
        - name: api-key
          in: header
          description: Your Payvessel public API key
          required: true
          schema:
            type: string
        - name: api-secret
          in: header
          description: Your Payvessel secret
          required: true
          schema:
            type: string
        - name: Content-Type
          in: header
          description: Request content type
          required: true
          schema:
            type: string
            enum:
              - application/json
          example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkTransferRequest'
            example:
              batch_reference: PAYROLL_2026_03
              transfers:
                - amount: '15000.00'
                  account_number: '0123456789'
                  bank_code: '999991'
                  account_name: John Doe
                  narration: March salary
                  reference: PAYROLL_2026_03_EMP001
      responses:
        '200':
          description: Bulk transfer initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTransferResponse'
components:
  schemas:
    BulkTransferRequest:
      type: object
      required:
        - batch_reference
        - transfers
      properties:
        batch_reference:
          type: string
          description: Unique reference for the bulk batch
        transfers:
          type: array
          items:
            type: object
            required:
              - amount
              - account_number
              - bank_code
              - reference
            properties:
              amount:
                type: string
                description: Amount for this transfer
              account_number:
                type: string
                description: Destination account number
              bank_code:
                type: string
                description: Destination bank code
              account_name:
                type: string
                description: Optional account name
              narration:
                type: string
                description: Transfer description
              reference:
                type: string
                description: Unique reference for this transfer
    BulkTransferResponse:
      type: object
      properties:
        status:
          type: boolean
          description: Request status
        message:
          type: string
          description: Response message
        data:
          type: object
          description: Bulk transfer result data

````