POST
/
merchants
/
accounts
/
topup
cURL
curl -X POST "https://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"
  }'
{
  "transactionReferenceNumber": "CBPC73IQ5U2E",
  "beneficiaryAccountNumber": 12346198,
  "beneficiaryName": "MERCHANT SANDBOX",
  "beneficiaryCurrencyCode": "MWK",
  "sourceAccountNumber": "5271306",
  "sourceCustomerName": "ANGEL BAULENI",
  "sourceReferenceNumber": "JF260209114N",
  "sourceCurrencyCode": "MWK",
  "connectorName": "National Bank of Malawi",
  "amountSent": 50000,
  "amountReceived": 49500,
  "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",
  "dateCreated": "2026-02-09T15:12:52.8020476+02:00",
  "responseCode": "S100",
  "responseMessage": "Successful transaction"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer , where is your access token.

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)

​
transactionReferenceNumber
string

Unique reference number for the transaction

Example:

"CBPC73IQ5U2E"

​
beneficiaryAccountNumber
integer

Account number of the beneficiary/merchant

Example:

12346198

​
beneficiaryName
string

Name of the beneficiary account

Example:

"MERCHANT SANDBOX"

​
amountReceived
number<decimal>

Net amount received after fees (amountSent - transactionFee)

Example:

49500

​
beneficiaryCurrencyCode
string

Currency code of the beneficiary

Example:

"MWK"

​
sourceAccountNumber
string

Source account number

Example:

"5271306"

​
sourceCustomerName
string

Name of the source customer

Example:

"ANGEL BAULENI"

​
sourceReferenceNumber
string

Reference number from the source system

Example:

"JF260209114N"

​
sourceCurrencyCode
string

Currency code of the source amount

Example:

"MWK"

​
connectorName
string

The name of the payment connector

Example:

"National Bank of Malawi"

​
amountSent
number<decimal>

Total amount sent in the transaction

Example:

50000

​
transactionFee
number<decimal>

Fee charged for the transaction

Example:

500

​
transactionDescription
string

Description of the transaction

Example:

"Fake Merchant Account Topup"

​
transactionDate
string<date-time>

Date and time of the transaction

Example:

"2026-02-09T15:12:52.8020476+02:00"

​
valueDate
string<date-time>

Value date of the transaction

Example:

"2026-02-09T15:12:52.8020476+02:00"

​
transactionCode
string

Transaction code

Example:

"BAM"

​
transactionTypeName
string

Type/description of the transaction

Example:

"Account To Merchant"

​
transactionStatusCode
string

Status code of the transaction (e.g., 'S' for Success)

Example:

"S"

​
transactionStatusName
string

Human-readable status description

Example:

"Success"

​
bridgeReferenceNumber
string

Bridge reference number for the transaction

Example:

"019c4288-9342-7ebd-a947-6d97d4da77ed"

​
dateCreated
string<date-time>

Date and time when the transaction was created

Example:

"2026-02-09T15:12:52.8020476+02:00"

​
responseCode
string

Unified response code from the payment system

Example:

"S100"

​
responseMessage
string

Response description from the payment system

Example:

"Successful transaction"