> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update wallet balance

> This endpoint is used to debit or credit a wallet balance. It supports internal wallet adjustments such as payouts, refunds, top-ups, or manual balance corrections.

## Endpoint

```json theme={null}
POST /wallets/transactions
```

## Description

Use this endpoint to create a transaction that either **adds funds to a wallet (credit)** or **removes funds from a wallet (debit)**. The wallet balance is updated immediately upon successful processing.

## Request Body

```json theme={null}
{
  "amount": 500,
  "description": "Customer payout",
  "type": "debit",
  "wallet_id": "3d2e3f3e-3b3c-4907-a4fd-e241203440d7"
}
```

***

## Request Fields

| Field         | Type          | Required | Description                             |
| :------------ | :------------ | :------- | :-------------------------------------- |
| `wallet_id`   | string (UUID) | Yes      | Wallet to be debited or credited        |
| `amount`      | number        | Yes      | Transaction amount (in wallet currency) |
| `type`        | string        | Yes      | Transaction type: `debit` or `credit`   |
| `description` | string        | No       | Reason or note for the transaction      |

***

## Supported Transaction Types

| Type     | Description                           |
| :------- | :------------------------------------ |
| `credit` | Adds funds to the wallet balance      |
| `debit`  | Removes funds from the wallet balance |

***

## Response

### Success Response (200 OK)

```json theme={null}
{
  "data": {
    "transaction_id": "transaction_id",
    "wallet_id": "wallet_id",
    "type": "debit",
    "amount": 500,
    "balance_after": 1500,
    "created_at": "2025-07-24T10:15:30Z"
  }
}
```

***

## Common Errors

| Status Code | Description                    |
| :---------- | :----------------------------- |
| `400`       | Invalid request                |
| `401`       | Unauthorized                   |
| `404`       | Wallet not found               |
| `409`       | Insufficient balance for debit |
| `422`       | Invalid transaction type       |

***

## Notes & Best Practices

* Ensure the wallet is **active** before initiating a transaction.
* Debits will fail if the wallet balance is insufficient.
* Use clear and descriptive transaction descriptions for auditing.
* Avoid using this endpoint for external payments; use dedicated payout or funding endpoints instead.

***

## Common Use Cases

* Customer payouts
* Refunds
* Wallet top-ups
* Internal balance adjustments