Skip to main content
POST
/
v1
/
payouts
/
merchant-fee-charge
Merchant Fee Charge
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/payouts/merchant-fee-charge \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "amount": 10,
  "description": "Fee Charge of N100",
  "sourceAccountId": "0340899287",
  "targetAccountId": "6009490194"
}
'
{
  "status": "success",
  "message": "Merchant fee charge processed successful...",
  "data": {
    "success": true,
    "message": "Successful",
    "statusCode": "00",
    "transaction": {
      "wasReversed": false,
      "amount": 1000,
      "description": "Fee Charge of N100",
      "category": "Fund Transfer",
      "uniqueRef": "177383661255062352",
      "internalRef": "1406812",
      "transactionType": "DEBIT",
      "entryDate": "2026-03-18T12:23:41.015+0000",
      "internal": true,
      "accountId": "0340899287"
    }
  }
}

​
Overview

This endpoint processes a merchant fee charge by debiting a source account and crediting a target account for the specified amount.

​
Request

Method: POST URL: /v1/payouts/merchant-fee-charge

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.

​
Request Body

FieldTypeRequiredDescription
amountnumberYesAmount in Naira. Must be a positive value.
sourceAccountIdstringYesSource account number to be debited.
targetAccountIdstringYesTarget account number to be credited.
descriptionstringNoOptional narration/description for the fee charge.
{
  "amount": 10,
  "description": "Fee Charge of N100",
  "sourceAccountId": "0340899287",
  "targetAccountId": "6009490194"
}

​
Response

Status Code: 201 Created Content-Type: application/json

​
Example Response

{
  "status": "success",
  "message": "Merchant fee charge processed successful...",
  "data": {
    "success": true,
    "message": "Successful",
    "statusCode": "00",
    "transaction": {
      "wasReversed": false,
      "amount": 1000,
      "description": "Fee Charge of N100",
      "category": "Fund Transfer",
      "uniqueRef": "177383661255062352",
      "internalRef": "1406812",
      "transactionType": "DEBIT",
      "entryDate": "2026-03-18T12:23:41.015+0000",
      "internal": true,
      "accountId": "0340899287"
    }
  }
}

​
Response Fields

FieldTypeDescription
statusstringOverall request status (success)
messagestringHuman-readable result message
data.successbooleanWhether the fee charge was processed successfully
data.statusCodestringBusiness status code (00 = success)
data.transaction.uniqueRefstringUnique transaction reference for reconciliation
data.transaction.internalRefstringInternal reference for support lookups
data.transaction.amountnumberAmount processed (in kobo)
data.transaction.transactionTypestringDirection of the transaction (DEBIT)
data.transaction.accountIdstringThe source account that was debited
data.statusCode: "00" indicates a successful transaction. Use data.transaction.uniqueRef and data.transaction.internalRef for reconciliation and support.

​
Error Responses

Status Code: 400 Bad Request A 400 response indicates the request was invalid — for example, missing required fields, invalid account identifiers, or an invalid amount. 
{
  "status": "failed",
  "message": "invalid source account"
}

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Body

application/json

Provide the required values for the request body.

​
amount
number
required

Amount in Naira. Must be a positive value.

Example:

10

​
sourceAccountId
string
required

Source account number to be debited.

Example:

"0340899287"

​
targetAccountId
string
required

Target account number to be credited.

Example:

"6009490194"

​
description
string

Optional narration/description for the fee charge.

Example:

"Fee Charge of N100"

Response

Created

The response is of type object.