> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickpesa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Lipa Namba Payout
> Sends a payout to a Lipa Namba or TanQR.
Create requests are limited to one per merchant every **60 seconds**. Re-submitting earlier returns an error with the remaining wait time.
Create often returns `AUTHORIZED`. That means the payout was accepted, not that it has settled. Poll [payout status](/api-reference/disbursement/lipa-namba-payout/querying-for-payouts) or listen for webhooks until `SUCCESS` or `REFUNDED`.
## OpenAPI
````yaml api-reference/disbursement/lipa-namba-payout/openapi.json POST /payouts/create-lipa-namba-payout
openapi: 3.0.1
info:
title: CORE API OpenAPI Specification
description: This is the API documentation for the ClickPesa CORE API
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.clickpesa.com/third-parties
security:
- bearerAuth: []
paths:
/payouts/create-lipa-namba-payout:
post:
tags:
- Payouts
- Create
description: Sends a payout to a Lipa Namba or TanQR.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LipaNambaPayoutRequest'
responses:
'200':
description: Create Lipa Namba payout response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLipaNambaPayoutResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'401':
description: Invalid or Expired Token
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'409':
description: Conflict Error
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
components:
schemas:
LipaNambaPayoutRequest:
type: object
required:
- amount
- orderReference
- currency
properties:
amount:
type: number
description: Your payout amount
currency:
type: string
enum:
- TZS
- USD
description: >-
Account currency to pay out from (TZS or USD). Recipient receives
TZS.
orderReference:
type: string
description: Your unique Order reference
lipaNamba:
type: string
description: >-
Recipient Lipa Namba (merchant code). Required if `qrCode` is not
sent. Do not send with `qrCode`.
example: '48001268'
providerCode:
type: string
description: >-
Required when `lipaNamba` is provided. Use a `providerCode` from
[Retrieve Lipa Namba
Providers](/api-reference/disbursement/lipa-namba-payout/list-lipa-namba-providers).
example: '503'
qrCode:
type: string
description: >-
Full TanQR string. Must include `tz.go.bot.tips`. Required if
`lipaNamba` is not sent. Do not send with `lipaNamba`.
checksum:
type: string
description: >-
If enabled, this is the generated checksum of the payload. Refer to
the [documentation](/home/checksum) for more details.
CreateLipaNambaPayoutResponse:
type: object
properties:
updatedAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
id:
type: string
orderReference:
type: string
description: Your unique order reference
amount:
type: string
description: Total amount deducted from your account balance (includes fee)
example: '10100.00'
currency:
type: string
example: TZS
fee:
type: string
description: Transaction fee deducted from source currency (included in amount)
example: '100.00'
exchanged:
type: boolean
description: >-
Indicates if currency conversion was applied (true when source
currency differs from receiving currency)
example: true
exchange:
type: object
description: Exchange rate details (only present when exchanged is true)
properties:
sourceCurrency:
type: string
description: Source currency for the exchange
example: USD
targetCurrency:
type: string
description: Target currency for the exchange
example: TZS
sourceAmount:
type: number
description: Amount in source currency
example: 1000
rate:
type: number
description: Exchange rate used for conversion
example: 2500
status:
type: string
enum:
- AUTHORIZED
- PROCESSING
- SUCCESS
- FAILED
- REFUNDED
- REVERSED
channel:
type: string
enum:
- TIPS LIPA NAMBA
channelProvider:
type: string
example: Vodacom M-Pesa
order:
type: object
properties:
amount:
type: string
description: Amount added during order creation/payload
example: '10000.00'
currency:
type: string
example: TZS
beneficiary:
type: object
properties:
accountNumber:
type: string
example: '48001268'
accountName:
type: string
description: Beneficiary name from Lipa Namba lookup
example: ACME TRADERS LTD
clientId:
type: string
description: Application Client ID associated with the payout
ValidationError:
type: object
properties:
message:
type: string
enum:
- Valid Client ID is required
- >-
Application has no access to PAYOUT API feature. Enable it on your
application.
- >-
Invalid Order Reference, should only contain alphanumeric
characters and cannot be blank
- lipaNamba or qrCode is required
- Provide either lipaNamba or qrCode, not both
- providerCode is required when lipaNamba is provided
- >-
Lipa Namba beneficiary name could not be resolved. Preview is
required before payout.
- 'Insufficient balance: available balance is {balance} TZS'
- >-
Payout request is already in progress, please retry after
{remaining time} seconds
example: lipaNamba or qrCode is required
UnauthorizedError:
type: object
properties:
message:
type: string
description: Unauthorized Error
example: Unauthorized
ConflictError:
type: object
properties:
message:
type: string
description: Conflict message when an order reference is already used
example: >-
Order reference {Your reference} already used: Create a different
reference
InternalServerError:
type: object
properties:
message:
type: string
description: Internal Server Error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authorization header containing the JWT access token returned from the
generate token endpoint. The token already includes the Bearer prefix.
Example: `Authorization: Bearer eyJhbGciOi...`
bearerFormat: JWT
````