# Finance · My account

Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md
## GET /client/finance/wallet

**Get my wallet**

`operationId: FinanceClientController_getMyWallet`

The signed-in recipient's wallet, with its transaction history and a summary — the read behind an "earnings" page.

`balance` includes any funds under hold; `availableBalance` is what can actually be withdrawn. Show the second figure when telling someone what they can request.

#### Signature

```http
GET /client/finance/wallet () -> The caller's wallet, transactions and summary
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- A recipient who has never been credited has no wallet yet and gets a `404` — treat that as a zero balance in a UI, not an error.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |
| `404` | — | Wallet not found | The caller has no wallet, **or** the wallet found does not belong to them. | A wallet is created when the first earning is credited. The same `404` covers both cases deliberately, so it cannot be used to detect another party's wallet. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `GET /client/finance/payouts`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The caller's wallet, transactions and summary |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Wallet not found — The caller has no wallet, **or** the wallet found does not belong to them. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /client/finance/payouts

**Get my payouts**

`operationId: FinanceClientController_getMyPayouts`

The caller's own payout history, with optional status filtering and paging.

#### Signature

```http
GET /client/finance/payouts (status?: string, page?: integer, pageSize?: integer) -> A page of the caller's payouts
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `GET /client/finance/payouts/{payoutId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `status` | query | "pending" \| "approved" \| "processing" \| "completed" \| "failed" \| "cancelled" | — |  |
| `page` | query | integer | — |  |
| `pageSize` | query | integer | — |  |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | A page of the caller's payouts |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /client/finance/payouts/{payoutId}

**Get one of my payouts**

`operationId: FinanceClientController_getMyPayout`

Fetches one of the caller's payouts, including its status and — once paid — the external reference for the transfer.

#### Signature

```http
GET /client/finance/payouts/{payoutId} (payoutId: string) -> The payout
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Another recipient's payout returns `404`, not `403` — existence is never confirmed to a caller who does not own it.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |
| `404` | — | Payout not found | No payout has that id, **or** it belongs to someone else. | Both cases return the same `404` by design. List your own payouts with `GET /client/finance/payouts`. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `GET /client/finance/payouts`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `payoutId` | path | string | yes | Payout id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The payout |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Payout not found — No payout has that id, **or** it belongs to someone else. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /client/finance/payouts/request

**Request a payout**

`operationId: FinanceClientController_requestPayout`

Requests a withdrawal from the caller's own wallet. The payout starts `pending` and waits for approval — requesting does not move money.

Name a `methodId` to be paid to a specific destination, or omit it to use the default method.

The same rules as the operator endpoint apply: the amount must sit within the available balance and inside the wallet's minimum, maximum and daily limits, and the chosen method must exist and be enabled.

#### Signature

```http
POST /client/finance/payouts/request (body) -> The created payout, pending approval
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Requesting is not the same as being paid. The payout must be approved, processed and completed before money arrives.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |
| `404` | — | Wallet not found | The caller has no wallet, **or** the wallet found does not belong to them. | A wallet is created when the first earning is credited. The same `404` covers both cases deliberately, so it cannot be used to detect another party's wallet. |
| `400` | — | Insufficient available balance (<n>, need <n>) | The amount exceeds `availableBalance`. Held funds do not count towards it. | Show `availableBalance`, not `balance`, as the withdrawable figure. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `GET /client/finance/payout-methods`
- `GET /client/finance/payouts`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

How much to withdraw, and where to.

```json
{
  "amount": 500
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The created payout, pending approval |
| `400` | Insufficient available balance (<n>, need <n>) — The amount exceeds `availableBalance`. Held funds do not count towards it. |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Wallet not found — The caller has no wallet, **or** the wallet found does not belong to them. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## PUT /client/finance/payout-settings

**Update my payout settings**

`operationId: FinanceClientController_updatePayoutSettings`

Updates the caller's own payout preferences — such as an automatic payout schedule or a preferred destination.

Platform-imposed limits (minimum, maximum, daily cap) are set by the operator through `PUT /finance/wallets/{walletId}/payout-settings` and are not raised from here.

#### Signature

```http
PUT /client/finance/payout-settings (body) -> The updated settings
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |
| `404` | — | Wallet not found | The caller has no wallet, **or** the wallet found does not belong to them. | A wallet is created when the first earning is credited. The same `404` covers both cases deliberately, so it cannot be used to detect another party's wallet. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `PUT /finance/wallets/{walletId}/payout-settings`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The settings to change.

```json
{
  "autoPayoutEnabled": true,
  "autoPayoutThreshold": 100,
  "defaultMethodId": "PM-4821"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The updated settings |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `404` | Wallet not found — The caller has no wallet, **or** the wallet found does not belong to them. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## GET /client/finance/payout-methods

**Get my payout methods**

`operationId: FinanceClientController_getPayoutMethods`

The caller's configured payout destinations — bank account, PayPal, Venmo, Cash App, debit card or crypto.

Sensitive details are stored but are not returned in full; expect masked values such as a last-four rather than a complete account number.

#### Signature

```http
GET /client/finance/payout-methods () -> The caller's payout methods
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- A method with `status: "pending"` has not been verified yet and may be refused at payout time.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `POST /client/finance/payout-methods`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The caller's payout methods |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /client/finance/payout-methods

**Add a payout method**

`operationId: FinanceClientController_addPayoutMethod`

Adds a destination the caller can be paid to. **`type` decides which detail block is read** — send the block matching the type and leave the others out:

| `type` | Block | Key fields |
| --- | --- | --- |
| `bank` | `bank` | `routingNumber`, `accountNumber`, `accountHolderName` |
| `debit_card` | `debitCard` | `token`, `last4`, expiry |
| `paypal` | `paypal` | `email` |
| `venmo` | `venmo` | `handle` or `phoneNumber` |
| `cashapp` | `cashapp` | `cashtag` or `phoneNumber` |
| `crypto` | `crypto` | `currency`, `address`, `network` |

Set `isDefault` to make it the destination used when a payout request names no method. A new method typically starts `pending` until verified.

#### Signature

```http
POST /client/finance/payout-methods (body) -> The created payout method
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Blocks that do not match `type` are ignored rather than rejected — sending the wrong one gives a method with no usable details.
- For crypto, the `network` must match the address. A mismatch sends funds somewhere unrecoverable.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `PUT /client/finance/payout-methods/{methodId}/default`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The destination to add. Send only the block matching `type`.

```json
{
  "type": "bank",
  "label": "Chase checking",
  "isDefault": true,
  "bank": {
    "bankName": "Chase",
    "accountType": "checking",
    "routingNumber": "021000021",
    "accountNumber": "000123456789",
    "accountHolderName": "Ada Lovelace",
    "accountHolderType": "individual"
  }
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The created payout method |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## PUT /client/finance/payout-methods/{methodId}

**Update a payout method**

`operationId: FinanceClientController_updatePayoutMethod`

Updates a method's label, default flag or status. The banking details themselves cannot be edited here — remove the method and add a new one to change an account number.

#### Signature

```http
PUT /client/finance/payout-methods/{methodId} (methodId: string, body) -> The updated method
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Account details are immutable. Add a replacement method and remove the old one.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `DELETE /client/finance/payout-methods/{methodId}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `methodId` | path | string | yes | Payout method id. |

### Request body

What to change.

```json
{
  "label": "Chase checking (personal)"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The updated method |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## DELETE /client/finance/payout-methods/{methodId}

**Remove a payout method**

`operationId: FinanceClientController_removePayoutMethod`

Deletes a payout destination.

Removing the default leaves the caller without one, and a later payout request that names no method will fail — set a new default first. To stop using a method temporarily, set its status to `disabled` instead.

#### Signature

```http
DELETE /client/finance/payout-methods/{methodId} (methodId: string) -> Confirmation of the removal
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Notes

- Pending payouts already routed to this method are not re-routed by removing it.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `PUT /client/finance/payout-methods/{methodId}/default`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `methodId` | path | string | yes | Payout method id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | Confirmation of the removal |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

Example response:

```json
{
  "success": true
}
```

## PUT /client/finance/payout-methods/{methodId}/default

**Set the default payout method**

`operationId: FinanceClientController_setDefaultPayoutMethod`

Makes one method the default, used whenever a payout request names none. Setting a new default clears the flag on the previous one.

#### Signature

```http
PUT /client/finance/payout-methods/{methodId}/default (methodId: string) -> The updated method
```

#### Access

Requires a bearer JWT (`Authorization: Bearer <token>`).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `401` | — | Not authenticated | No signed-in customer or user could be resolved from the request. | Sign in. Every endpoint here is scoped to the caller and none work anonymously. |

Plus the standard platform errors: `403`, `429`, `500`.

#### See also

- `GET /client/finance/payout-methods`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `methodId` | path | string | yes | Payout method id. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The updated method |
| `401` | Not authenticated — No signed-in customer or user could be resolved from the request. |
| `403` | You do not have permission to perform this action — The caller is authenticated but lacks the role required by the endpoint, or is acting on another org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |