## Add a topup

Add funds to your test merchant balance. This simulates an incoming bank
transfer settling into your account, letting you build up a balance so you can
exercise other endpoints such as sending payouts.

Optionally supply a `virtual_account_number` to simulate the transfer
arriving into one of your virtual accounts.

This endpoint is only available to test merchant accounts. Live merchants are
funded through real bank transfers and cannot top up their balance through the
API.

The topup settles immediately, so the funds are available in your balance as
soon as this call returns.

## Endpoint signature

```http
POST https://api.reservepay.com/merchants/add-topup HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  amount: string,
  virtual_account_number: string?,
  transaction_id: string?,
  sender_account_name: string?,
  sender_account_number: string?,
  sender_bank_code: string?,
}
```

Returns: string

## Request arguments

### `amount` (string)

**Required**. The topup amount in the smallest currency unit (e.g. satang). For example,
use 10000 for 100 THB. Must be a positive integer.

### `virtual_account_number` (string)

_Optional_. An optional bank-assigned virtual account number belonging to your
merchant account. When supplied, the topup is recorded against that
virtual account, simulating a transfer arriving into it.

### `transaction_id` (string)

_Optional_. An optional bank transaction reference to record against the topup.

### `sender_account_name` (string)

_Optional_. An optional name of the sender's bank account.

### `sender_account_number` (string)

_Optional_. An optional sender's bank account number.

### `sender_bank_code` (string)

_Optional_. An optional sender's 3-digit bank code.

## Errors specific to this endpoint

### `NOT_ALLOWED`

Topups can only be added to test merchant accounts. This error occurs when
the authenticated merchant is a live account.

### `NOT_FOUND`

This error occurs when a `virtual_account_number` is supplied but no
virtual account with that number exists in your merchant account.

## Errors common to all endpoints

### `UNHANDLED_ERROR`

This error occurs when the server encounters an unexpected internal error that
it cannot handle gracefully. This typically happens due to bugs, infrastructure
issues, or edge cases that weren't anticipated during development.

### `INVALID_ARGUMENTS`

This error occurs when the request contains invalid or missing parameters.
Common cases include missing required fields, or values that don't match the
expected format or type.

### `BAD_VERSION`

This error occurs when making requests to an API version that does not exist.
This commonly happens when using an outdated SDK or when the API version
specified in the request URL is incorrect.