---
title: "Dev-only: simulate an inbound wire onto the merchant refund account via the merchant's fake cross-border provider. Refused in production. Refused if the merchant is not enrolled with a fake provider, so it can never trigger a real TransferMate call."
method: POST
path: "/api/v1/admin/dev/merchants/{merchantId}/refund-account/simulate-top-up"
tags: ["Merchants", "Admin", "Dev"]
---

# Dev-only: simulate an inbound wire onto the merchant refund account via the merchant's fake cross-border provider. Refused in production. Refused if the merchant is not enrolled with a fake provider, so it can never trigger a real TransferMate call.

`POST /api/v1/admin/dev/merchants/{merchantId}/refund-account/simulate-top-up`

## Request

- Base URL: `https://core.quidkey.com`
- URL: `https://core.quidkey.com/api/v1/admin/dev/merchants/{merchantId}/refund-account/simulate-top-up`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/banqzinc/apis/quidkey-api/docs/api/v1/admin/dev/merchants/:merchantId/refund-account/simulate-top-up/post.ts> (a function with typed inputs; its response is checked against the schema)

Dev-only: simulate an inbound wire onto the merchant refund account via the merchant's fake cross-border provider. Refused in production. Refused if the merchant is not enrolled with a fake provider, so it can never trigger a real TransferMate call.

## Path parameters

- `merchantId` string, uuid, required

## Request body

- DevMerchantSimulateRefundTopUpInput
  - `amount` number, required: Decimal amount to credit (account currency)
  - `currency` string, required: ISO 4217 currency of the merchant refund account to credit
  - `reference` string: Payer reference shown on the activity row
  - `payer` string: Payer display name shown on the activity row
  - `description` string: Free-text description
  - `provider` string: Optional provider name to scope the top-up to (e.g. "transfermate" vs "fake-transfermate" on envs where both are fake-backed).

## Response `200`

Success

- DevMerchantSimulateRefundTopUpResponse
  - `success` boolean, required: Indicates if the request was successful
  - `data` object, required
    - `merchantId` string, uuid, required
    - `bankAccountId` string, uuid, required
    - `userBankId` string, required
    - `currency` string, required
    - `amount` string, required
    - `reference` string

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

## Changes

- **2026-06-17** `b372e7d5563d`: 1 info
  - endpoint added
- **2025-11-02** `919eb7a392aa`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/banqzinc/apis/quidkey-api/changes/api/v1/admin/dev/merchants/:merchantId/refund-account/simulate-top-up/post.md)

---

[API](https://skmtc.dev/banqzinc/apis/quidkey-api.md) - [All operations](https://skmtc.dev/banqzinc/apis/quidkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/banqzinc/apis/quidkey-api/revisions/f86d2bdbcb08?raw)