> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcarbon.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Payout
> Initiate a payout to a beneficiary account.
## Overview
This endpoint allows you to initiate a payout to a beneficiary account by providing the necessary details such as amount, source account, and beneficiary information.
Before creating a payout, you must validate the beneficiary bank account using the [Resolve Account](/api-reference/banks/resolve-account) endpoint to ensure the account details are correct.
The minimum payout amount is ₦200.
### Request
**Method:** `POST`\
**URL:** `/v1/payouts`
#### Parameters
| Name | In | Type | Required | Description |
| -------------- | ------ | -------- | -------- | --------------------------- |
| `x-carbon-key` | Header | `string` | Yes | API key for authentication. |
#### Request Body
| Field | Type | Required | Description |
| ---------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `amount` | number | Yes | Amount to be paid out in kobo (minimum: 20000 = ₦200) |
| `source.account_number` | string | Yes | Source account number for the payout |
| `beneficiary.bank_code` | string | Yes | Bank code of the beneficiary's bank |
| `beneficiary.bank_name` | string | Yes | Name of the beneficiary's bank |
| `beneficiary.account_number` | string | Yes | Beneficiary's account number (must be validated using [/api-reference/banks/resolve-account](/api-reference/banks/resolve-account)) |
| `beneficiary.account_name` | string | Yes | Beneficiary's account name (obtained from resolve account response) |
| `reference` | string | Yes | Unique reference for this payout request (max 30 characters) |
| `meta_data` | object | No | Additional metadata for the transaction |
| `remark` | string | Yes | Description or note for the payout |
The `reference` field must be unique for each new payout request. Using a duplicate reference will result in an error.
**Example Reference Formats:**
* `PAYOUT_USER123_20260119`
* `PAY_INV_456789`
* `SALARY_EMP001_JAN26`
```json theme={null}
{
"amount": 15000,
"source": {
"account_number": "1234567890"
},
"beneficiary": {
"bank_code": "565",
"bank_name": "CARBON",
"account_number": "9876543210",
"account_name": "John Doe"
},
"reference": "PAYOUT_USER123_20260119",
"meta_data": {},
"remark": "Payment for services"
}
```
### Response
**Status Code:** `200 OK`\
**Content-Type:** `application/json`
#### Example Response
```json theme={null}
{
"status": "success",
"message": "Payout was initiated successfully",
"data": {
"amount": 15000,
"total": 15000,
"fee": 0,
"reference": "PAYOUT_USER123_20260119",
"beneficiary": {
"bank_code": "565",
"bank_name": "CARBON",
"account_number": "9876543210",
"account_name": "John Doe"
}
}
}
```
## OpenAPI
````yaml POST /v1/payouts
openapi: 3.0.0
info:
title: Carbon Business API
description: >-
## Welcome to our API Developer Documentation
Carbon aims to unlock the full potential of your business with a
feature-rich account designed for growth.
## Integrations
We aim to provide our APIs for developers and businesses to offer financial
services to their existing customer base through REST APIs without doing the
heavy lifting. Our API has predictable resource-oriented URLs, accepts
form-encoded request bodies, returns JSON-encoded responses, and uses
standard HTTP response codes, authentication, and verbs.
### Authentication
`Authorization : API Key`
Header
`x-carbon-key : value`
`x-carbon-key` can be generated via developer page on Carbon Business
| Environment | URL |
| --- | --- |
| Live | |
| Sandbox |
[https://carbonapistagingsecure.getcarbon.co/baas/api](https://carbonapistagingsecure.getcarbon.co/baas/api)
|
### **Handling Errors**
We use the conventional HTTP response codes to indicate the success or
failure of an API request.
Codes in the 2xx range indicate success. Codes in the 4xx range indicate an
error that failed given the information provided (e.g., a required parameter
was omitted, etc.). Codes in the 5xx range indicate an error with our
servers.
| Error | Description |
| --- | --- |
| 400 - Bad Request | The request was unacceptable, often due to missing a
required parameter. |
| 401 - Unauthorized | Not a valid API key was provided. |
| 402 - Request Failed | The parameters were valid but the request failed. |
| 403 - Forbidden | The API key doesn't have permission to perform the
request. |
| 404 - Not Found | The requested resource doesn't exist. |
| 429 - Too Many Requests | Too many requests hit the API |
| 500, 502, 503, 504 - Server Errors | System Error |
version: 1.0.0
servers:
- url: https://carbonapistagingsecure.getcarbon.co/baas/api
description: >-
Replace {{base_url}} with your API base URL (e.g.,
https://api.example.com)
security:
- apikeyAuth: []
tags:
- name: Accounts
description: >-
Virtual accounts are generated account details (account number and bank)
that allow Carbon Business merchants to receive payments from customers
via NGN bank transfer. This is currently only available in naira (NGN).
Virtual accounts are either dynamic (temporary) or static (permanent). A
dynamic account number expires after handling a transaction, while a
static account number doesn't expire.
**Static Account**
Creating static accounts can be useful when receiving recurring payments
through bank transfers. The process involves generating a static virtual
account with customer information. Once payment is made, we will send you
a webhook notification, which you can then manage.
**Dynamic Account**
Creating dynamic accounts can be useful when receiving one-time payments
through bank transfers. The process involves generating a dynamic virtual
account with a set amount for the customer during checkout. Once payment
is made, we will send you a webhook notification, which you can then
manage.
Key things you can do with these endpoints:
- Create an account
- Retreive an account
- Verify Transaction
- Retreive a list of transactions
- name: Accounts > Transactions
- name: Banks
description: |-
- Get a list of banks and financial institutions
- Verify/resolve account details
- name: Customers
description: >-
This collection contains a set of API endpoints to manage customer-related
operations for an application. The endpoints allow for creating a new
customer, retrieving a list of all customers, and fetching details of a
single customer.
- Create Customer
- Fetch Customer/Customers
- name: Payout
description: |-
- Make Transfer
- Verify Transfer
- name: Status
description: '- Service Health check'
- name: Verification
- name: Webhook
description: |-
## EVENTS
`account.incoming-transaction`
``` json
{
"event": "account.incoming-transaction",
"data": {
"id": "string",
"amount": "float",
"currency": "string",
"transactionType": "string",
"entryDate": "datetime",
"uniqueRef": "string",
"account": {
"id": "string",
"bankAccount": {
"accountName": "string",
"accountNumber": "string",
"bank": {
"code": "string",
"name": "string"
}
},
"static": boolean,
"currency": "string",
"clientId": "string"
}
}
}
```
`account.outgoing-transaction`
``` json
{
"event": "account.outgoing-transaction",
"data": {
"id": "string",
"amount": "float",
"currency": "string",
"transactionType": "string",
"entryDate": "datetime",
"uniqueRef": "string",
"account": {
"id": "string",
"bankAccount": {
"accountName": "string",
"accountNumber": "string",
"bank": {
"code": "string",
"name": "string"
}
},
"static": boolean,
"currency": "string",
"clientId": "string"
}
}
}
```
- name: Loans
description: >-
Partner lending API. Enables fintech partners to originate business loans
for their end-customers.
- Enroll customers for lending and trigger KYC
- Submit loan applications and supporting documents
- Manage offer acceptance, disbursement account, and post-offer steps
- Charge repayments and retrieve repayment schedules
paths:
/v1/payouts:
post:
tags:
- Payout
summary: Payout
description: >-
This HTTP POST request is used to initiate a payout. The request body
should include the amount in naira, source account number, beneficiary
bank code, bank name, beneficiary account number, beneficiary account
name, reference, meta data, and a remark.
### Request Body
- `amount` (number): The amount in naira.
- `source.account_number` (string): The account number of the source.
- `beneficiary.bank_code` (string): The bank code of the beneficiary.
- `beneficiary.bank_name` (string): The name of the beneficiary's bank.
- `beneficiary.account_number` (string): The account number of the
beneficiary.
- `beneficiary.account_name` (string): The name of the beneficiary's
account.
- `reference` (string): A reference for the payout.
- `meta_data` (object): Additional meta data for the payout.
- `remark` (string): A remark for the payout.
### Response
- `status` (string): The status of the payout.
- `message` (string): A message related to the payout status.
- `data.amount` (number): The amount processed.
- `data.total` (number): The total amount processed.
- `data.fee` (number): The fee charged for the payout.
- `data.reference` (string): The reference for the payout.
- `data.beneficiary.bank_code` (string): The bank code of the
beneficiary.
- `data.beneficiary.bank_name` (string): The name of the beneficiary's
bank.
- `data.beneficiary.account_number` (string): The account number of the
beneficiary.
- `data.beneficiary.account_name` (string): The name of the
beneficiary's account.
parameters:
- name: x-carbon-key
in: header
schema:
type: string
required: true
example: '{{access_token}}'
requestBody:
description: Provide the required values for the request body.
required: true
content:
application/json:
schema:
type: object
required:
- amount
- source
- beneficiary
- reference
- meta_data
- remark
properties:
amount:
type: number
description: Provide amount
source:
type: object
properties:
account_number:
type: string
description: Provide source account number
beneficiary:
type: object
properties:
bank_code:
type: string
description: Provide bank code
bank_name:
type: string
description: Provide bank name
account_number:
type: string
description: Provide account number
account_name:
type: string
description: Provide account name
reference:
type: string
description: Provide reference
meta_data:
type: object
additionalProperties: true
remark:
type: string
description: Provide remark
example:
amount: Provide amount
source:
account_number: Provide source account number
beneficiary:
bank_code: Provide bank code
bank_name: Provide bank name
account_number: Provide account number
account_name: Provide account name
reference: Provide reference
meta_data: {}
remark: Provide remark
responses:
'200':
description: OK
headers:
Content-Security-Policy:
schema:
type: string
example: >-
default-src 'self';base-uri 'self';font-src 'self' https:
data:;form-action 'self';frame-ancestors 'self';img-src 'self'
data:;object-src 'none';script-src 'self';script-src-attr
'none';style-src 'self' https:
'unsafe-inline';upgrade-insecure-requests
Cross-Origin-Opener-Policy:
schema:
type: string
example: same-origin
Cross-Origin-Resource-Policy:
schema:
type: string
example: same-origin
Origin-Agent-Cluster:
schema:
type: string
example: '?1'
Referrer-Policy:
schema:
type: string
example: no-referrer
Strict-Transport-Security:
schema:
type: string
example: max-age=15552000; includeSubDomains
X-Content-Type-Options:
schema:
type: string
example: nosniff
X-DNS-Prefetch-Control:
schema:
type: string
example: 'off'
X-Download-Options:
schema:
type: string
example: noopen
X-Frame-Options:
schema:
type: string
example: SAMEORIGIN
X-Permitted-Cross-Domain-Policies:
schema:
type: string
example: none
X-XSS-Protection:
schema:
type: integer
example: '0'
RateLimit-Policy:
schema:
type: string
example: 100;w=900
RateLimit-Limit:
schema:
type: integer
example: '100'
RateLimit-Remaining:
schema:
type: integer
example: '96'
RateLimit-Reset:
schema:
type: integer
example: '710'
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
Content-Length:
schema:
type: integer
example: '270'
ETag:
schema:
type: string
example: W/"10e-YUIIfsONxfLdjp6y4ZDxpD/gqpA"
Date:
schema:
type: string
example: Fri, 22 Mar 2024 19:53:50 GMT
Connection:
schema:
type: string
example: keep-alive
Keep-Alive:
schema:
type: string
example: timeout=5
content:
application/json:
schema:
type: object
example:
status: success
message: payout was initiated successfully
data:
amount: 150
total: 175
fee: 25
reference: '204041344312337'
beneficiary:
bank_code: '057'
bank_name: Dummy Bank
account_number: '32324546565'
account_name: Test User
components:
securitySchemes:
apikeyAuth:
type: apiKey
in: header
name: apikey
description: Provide your API key in the 'apikey' header.
````