API product catalogTreasury, Cash Management & FX Settlement

Request payout

Treasury, Cash Management & FX Settlement

POST

/payout

Request payout

Sandbox unsupportedcreatePayout

Requests a cash withdrawal from your master wallet to a bank account. An admin reviews and processes payouts within 2 business days. The requested amount is reserved immediately from your wallet balance. Sandbox payout creation is unsupported and returns HTTP 422 because virtual funds cannot be paid out.

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 to withdraw. Must not exceed master wallet balance.

Example: 5000

bankDetailsobjectRequired

bankDetails.bankNamestringRequired

Name of the receiving bank.

Example: "Equity Bank Kenya"

bankDetails.accountNamestringRequired

Account holder name.

Example: "ACME Fintech Ltd"

bankDetails.accountNumberstringRequired

Bank account number or IBAN.

Example: "0123456789"

bankDetails.swiftCodestring

SWIFT/BIC code for international wires.

Example: "EQBLKENA"

notesstring

Optional note to the MyStocks team.

Response fields

messagestring

payoutIdstring

Response codes

201Payout request submitted.

400Insufficient master wallet balance.

422Payout requests are not available in sandbox; no funds are moved.

Request reference

Sandbox unsupported

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

https://mystocks.africa/api/v1/partner/payout

Open in API Tester API Reference

Response schema

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

curl -X POST 'https://mystocks.africa/api/v1/partner/payout' \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 5000,
  "bankDetails": {
    "bankName": "Equity Bank Kenya",
    "accountName": "ACME Fintech Ltd",
    "accountNumber": "0123456789",
    "swiftCode": "EQBLKENA"
  },
  "notes": "Monthly payout"
}'

GET /payout

GET /topup