# Add Money to Brand Wallet

**Method:** `POST`

**Path:** `/api/pay/v1/add_money`

**Category:** Brand Wallet Payments

**Authentication:** Required

## Description

Adds money to a customer's brand wallet. Supports two modes:
- **GIFT_CARD** — Provide gift card number and PIN in `payment_option.gift_card_details`. Funds credited immediately.
- **CASH** — Provide `amount` and UPI payment details in `payment_option.upi_details`. Creates a parent ADD_MONEY order and child CHARGE order for UPI payment.


## Request Body

Content-Type: `application/json`

- `merchant_order_reference` (`string`) **required** — Unique reference for this add-money request
- `mode` (`GIFT_CARD | CASH`) **required** — Mode of adding money: - **GIFT_CARD** — Provide gift card number and PIN. Funds credited immediately. - **CASH** — Provide amount. Creates a UPI payment order. 
- `amount` (`object`) — Monetary amount with currency.
  - `value` (`integer`) **required** — Amount in the smallest currency unit (e.g., paisa for INR).
  - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

- `payment_option` (`object`) **required** — - For **GIFT_CARD** mode: provide `gift_card_details` with `gift_card_number` and `pin`. - For **CASH** mode: provide `upi_details` with UPI Collect or Intent details. 
  - `gift_card_details` (`object`)
    - `gift_card_number` (`string`) — Gift card number
    - `pin` (`string`) — Gift card PIN (exactly 6 digits)

  - `upi_details` (`object`) — UPI payment details. - For COLLECT flow: `txn_mode` = "COLLECT" and `payer.vpa` is required. - For INTENT flow (includes QR): `txn_mode` = "INTENT" and no payer needed. 
    - `txn_mode` (`COLLECT | INTENT`) **required** — UPI transaction mode.
    - `payer` (`object`) — UPI payer details. Required for COLLECT flow.
      - `vpa` (`string`) **required** — Virtual Payment Address (VPA) of the payer.



- `customer` (`object`) **required** — Customer information.
  - `email_id` (`string`) — Customer's email address.
  - `first_name` (`string`) — Customer's first name.
  - `last_name` (`string`) — Customer's last name.
  - `customer_id` (`string`) — Unique identifier of the customer.
  - `mobile_number` (`string`) — Customer's mobile number.
  - `country_code` (`string`) — Country code of the registered mobile number. Defaults to 91.
  - `billing_address` (`object`) — Physical address.
    - `address1` (`string`) — Address line 1.
    - `address2` (`string`) — Address line 2.
    - `address3` (`string`) — Address line 3.
    - `pincode` (`string`) — Postal/ZIP code.
    - `city` (`string`) — City name.
    - `state` (`string`) — State or province.
    - `country` (`string`) — Country name.
    - `full_name` (`string`) — Full name of the address holder.
    - `adddress_type` (`string`) — Type of address (e.g., Home, Office).
    - `address_category` (`billing | shipping`) — Category of the address.

  - `shipping_address` (`object`) — Physical address.
    - `address1` (`string`) — Address line 1.
    - `address2` (`string`) — Address line 2.
    - `address3` (`string`) — Address line 3.
    - `pincode` (`string`) — Postal/ZIP code.
    - `city` (`string`) — City name.
    - `state` (`string`) — State or province.
    - `country` (`string`) — Country name.
    - `full_name` (`string`) — Full name of the address holder.
    - `adddress_type` (`string`) — Type of address (e.g., Home, Office).
    - `address_category` (`billing | shipping`) — Category of the address.

  - `is_edit_customer_details_allowed` (`boolean`) — Whether the customer is allowed to edit their details.

- `merchant_metadata` (`object`) — Arbitrary key/value pairs attached to the order

### Example Request

```json
{
  "merchant_order_reference": "your_merchant_order_reference",
  "mode": "GIFT_CARD",
  "amount": {
    "value": 50000,
    "currency": "INR"
  },
  "payment_option": {
    "upi_details": {
      "txn_mode": "COLLECT",
      "payer": {
        "vpa": "kevinbob@okaxis"
      }
    }
  },
  "customer": {
    "email_id": "john@example.com",
    "first_name": "Kevin",
    "last_name": "Bob",
    "customer_id": "123456",
    "mobile_number": "9876543210",
    "country_code": "91",
    "billing_address": {
      "address1": "10 Downing Street Westminster London",
      "address2": "Oxford Street Westminster London",
      "address3": "Baker Street Westminster London",
      "pincode": "51524036",
      "city": "Westminster",
      "state": "Westminster",
      "country": "London",
      "full_name": "Kevin Bob",
      "adddress_type": "Home",
      "address_category": "billing"
    },
    "shipping_address": {
      "address1": "10 Downing Street Westminster London",
      "address2": "Oxford Street Westminster London",
      "address3": "Baker Street Westminster London",
      "pincode": "51524036",
      "city": "Westminster",
      "state": "Westminster",
      "country": "London",
      "full_name": "Kevin Bob",
      "adddress_type": "Home",
      "address_category": "billing"
    },
    "is_edit_customer_details_allowed": false
  }
}
```

## Responses

- `201` — Money added successfully.
- `400` — 
- `401` — 
- `422` — Unprocessable entity.
- `500` — 

---

Reference: https://localhost:3000/api/brand-wallet-payments/add-money-to-brand-wallet