POST
/
merchants
/
accounts
/
topup
cURL
curl -X POST "https://dev.api.onekhusa.com/sandbox/v1/merchants/accounts/topup" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  -d '{
    "merchantAccountNumber": 35253486,
    "connectorId": 550044,
    "topupAmount": 1000000.00,
    "createdBy": "johndoe@example.com"
  }'
{
  "beneficiary": {
    "accountNumber": 12346198,
    "accountName": "MERCHANT SANDBOX",
    "amountReceived": 49500,
    "currencyCode": "MWK"
  },
  "source": {
    "accountNumber": "5271306",
    "customerName": "ANGEL BAULENI",
    "amountSent": 50000,
    "currencyCode": "MWK",
    "sourceReferenceNumber": "JF260209114N",
    "connectorId": 212188,
    "connectorName": "National Bank of Malawi"
  },
  "transaction": {
    "transactionReferenceNumber": "CBPC73IQ5U2E",
    "transactionFee": 500,
    "transactionDescription": "Fake Merchant Account Topup",
    "transactionDate": "2026-02-09T15:12:52.8020476+02:00",
    "valueDate": "2026-02-09T15:12:52.8020476+02:00",
    "transactionCode": "BAM",
    "transactionTypeName": "Account To Merchant",
    "transactionStatusCode": "S",
    "transactionStatusName": "Success",
    "bridgeReferenceNumber": "019c4288-9342-7ebd-a947-6d97d4da77ed",
    "responseCode": "S100",
    "responseMessage": "Successful transaction"
  }
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer Token, Where accessToken is the access token used to authenticate the request.

Headers

Accept-Language
string
default:en

Preferred language for the response

Body

application/json
merchantAccountNumber
integer
required

Required string length: 8

Required range: 10000000 <= x <= 99999999
Example:

35253486

connectorId
integer
required

The connector ID for the transaction. See Get Connectors for available values.

Example:

550044

topupAmount
number<decimal>
required

The amount to add to the merchant's balance

Required range: 0.01 <= x <= 5000000000
Example:

1000000

createdBy
string<email>
required

Email address of the user initiating the topup

Example:

"johndoe@example.com"

Response

200 - application/json

Success Response (200)

beneficiary
object

Details of the beneficiary receiving the funds

source
object

Details of the source sending the funds

transaction
object

Core transaction details and metadata

statusCode
integer

Overall API response status code

Example:

0