API product catalogTreasury, Cash Management & FX Settlement

Request top-up

Treasury, Cash Management & FX Settlement

POST

/topup

Request top-up

Sandbox availablecreateTopup

Notifies MyStocks that you have sent a wire transfer to top up your master wallet. An admin confirms the wire receipt and credits your wallet (typically within 1 business day). Provide your wire transfer reference in paymentReference so we can match the incoming funds. paymentReference is unique per partner after normalization; duplicate references return 409. Sandbox: the request auto-approves instantly — the master wallet is credited in the same call and topup.confirmed fires, so the funding webhook path is fully testable. Production requests stay PENDING until the remittance is confirmed.

Parameters

This endpoint has no path or query parameters.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Unique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.

Example: dep_user42_1743152580

Request body

amountnumberRequired

USD amount to top up. Must be positive.

Example: 10000

paymentReferencestringRequired

Your wire transfer reference or payment ID. Unique per partner after normalization; duplicate references return 409.

Example: "WIRE-2026-05-001"

paymentMethodstring

Payment method, e.g. SWIFT wire, SEPA, ACH.

Example: "SWIFT wire"

notesstring

Optional note to the MyStocks operations team.

Response fields

messagestring

topupIdstring

Response codes

201Top-up request received.

Request reference

Sandbox available

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/topup

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "topupId": {
      "type": "string"
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/topup' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 10000,
  "paymentReference": "WIRE-2026-06-001",
  "paymentMethod": "SWIFT wire",
  "notes": "Monthly master wallet top-up"
}'

GET /topup

Corporate Actions & Shareholder Governance