--- title: "Create a wallet for a user" method: POST path: "/wallet/{user_token}" tags: ["Wallet"] --- # Create a wallet for a user `POST /wallet/{user_token}` ## Request - Base URL: `https://api.masspay.io/v1.0.0` - URL: `https://api.masspay.io/v1.0.0/wallet/{user_token}` - Auth: one of: - API key in header `Authorization` - API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) This **POST** endpoint creates a new wallet for the user with the specified `user_token`, in the requested currency.
To use this endpoint, you need to provide the `user_token` as a required parameter in the URL Path and the `currency_code` as a JSON parameter in the Request Body. The `currency_code` must be an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD`, `EUR` or `MXN`. The user must belong to the authenticated client.
Optionally, `fee_wallet_token` nominates one of your client wallets, in the same currency, as the wallet that pays the fees of payouts funded from the new wallet, so the payee receives the full amount.
A user can hold at most one wallet per currency, so the operation is idempotent: if the user already has a wallet in the requested currency, that existing wallet is returned unchanged with a `200` status code instead of `201`, and its `balance` reflects the current balance. If the existing wallet has a different fee-paying configuration than the requested `fee_wallet_token`, the request is rejected with a `409` status code and nothing is changed.
Newly created wallets start with a zero balance and can be funded through loads, pay-ins or wallet transfers. The response has the same shape as the wallets returned by the **GET** operation on this resource. ## Headers - `Idempotency-Key` string ## Request body - UserWalletCreateReq: Request body for creating a wallet for a user. The wallet may nominate one of your client wallets to pay the fees of payouts funded from it. - `currency_code` string, required: Currency the wallet is denominated in, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Case-insensitive. - `fee_wallet_token` string: Optional. Token of one of your client wallets (`clnt_wlt_` prefix) that will pay the fees of payouts funded from the new user wallet, so the payee receives the full amount. The client wallet must be owned by the authenticated client and denominated in the same `currency_code` as the new wallet. When omitted, the payee pays the fees from the wallet balance. ## Response `200` The user already has a wallet in the requested currency; the existing wallet is returned and nothing is created. - WalletCreateResp: The wallet created by a wallet creation request, or the owner's existing wallet in that currency when one already existed. User wallets carry the same fields as the wallets returned by the user wallet listing. - `token` string, required: Prefixed wallet identifier. User wallets use the `usr_wlt_` prefix and client wallets use the `clnt_wlt_` prefix. - `type` 'USER_FUNDS' | 'CLIENT_FUNDS', required: Type of wallet: `USER_FUNDS` when created for a user, `CLIENT_FUNDS` when created for the client account. - `user_token` string: Token representing the user who owns the wallet. Present only for `USER_FUNDS` wallets. - `currency_code` string, required: Currency the wallet balance is stored in, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. - `balance` number, required: The wallet's current balance in `currency_code`. Zero for a newly created wallet. - `active` boolean, required: An indicator whether the wallet is active. - `client_paying_fees` boolean, required: An indicator whether the fees for payouts using this wallet are paid by a client wallet. If false, the user pays the fees. Always false for `CLIENT_FUNDS` wallets. - `fee_wallet_token` string: Token of your client wallet that pays the fees for payouts using this wallet. Present only when `client_paying_fees` is true and the fee-paying wallet belongs to the authenticated client. ## Other responses - `201`: Successfully created. - `400`: Bad request. - `401`: Unauthorized. - `403`: Forbidden. - `404`: Not found. The `user_token` does not belong to a user of the authenticated client, or the `fee_wallet_token` is not a client wallet of the authenticated client. - `405`: Method Not Allowed. - `409`: Conflict. The user already has a wallet in this currency whose fee-paying wallet differs from `fee_wallet_token`; nothing was changed. - `500`: Internal server error. - `504`: Gateway Time-out. ## Changes - **2026-11-03** `f9fa41b7c45c`: 1 info - endpoint added [Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/wallet/:user_token/post.md) --- [API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)