> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Charge a user a custom fee

<Info>
  **Read the guides before using this page**

  To use this endpoint properly, make sure you are up to date on our [managing users](/docs/managing-users) guides.
</Info>

This endpoint applies one-time custom charges to individual users (like card setup fees, administrative charges, or other ad-hoc fees).

## Rain-managed vs Partner-managed programs

**Rain-managed programs:** Custom charges are automatically processed and applied directly to the user's balance. No additional ledgering required on your side.

**Partner-managed programs:** You typically handle fees through your own ledgering system. This API provides an alternative for one-off charges when needed.

<Warning>
  **Charges apply after authorization**

  Custom charges are applied after the authorization process, which means users may go negative if their balance is insufficient to cover the charge.
</Warning>

<Info>
  **FX/XB fees are handled differently**

  Foreign exchange (FX) and cross-border (XB) fees are configured at the tenant level and included during authorization. See [Pricing and fees](/docs/pricing-and-fees) for more information.
</Info>

## Example

```javascript theme={null}
// Apply a \$5 card setup fee when a user requests a new card
const charge = await rain.createUserCharge({
  userId: "user_123",
  amount: 500, // \$5.00 in cents
  description: "Card setup fee",
  idempotencyKey: "setup_fee_user_123_card_456"
});
```

<Tip>
  **Best practices**

  Always use idempotency keys to prevent duplicate charges. Provide clear descriptions for charges to help with user support. Monitor user balances to avoid excessive negative balances, and consider notifying users before applying charges when possible.
</Tip>


## OpenAPI

````yaml post /issuing/users/{userId}/charges
openapi: 3.0.3
info:
  title: Issuing API
  description: This is the specification for Rain's Issuing API.
  termsOfService: https://www.rain.xyz/legal/authorized-user-terms
  contact:
    email: support@rain.xyz
  version: 1.3.0
servers:
  - url: https://api-dev.rain.xyz/v1
    description: Sandbox server
  - url: https://api.rain.xyz/v1
    description: Production server
security: []
tags:
  - name: paymentRoutes
    description: >-
      **Endpoint Migration:** The `/v1/automations` endpoints have been renamed
      to `/v1/payment-routes`. The old `/v1/automations` paths remain available
      as deprecated aliases during migration. Update your integrations to use
      `/v1/payment-routes` as the deprecated endpoints will be removed in a
      future release.
  - name: simulate
    description: >-
      Transaction simulation endpoints for testing integration flows in
      non-production environments. These endpoints let you trigger transaction
      events programmatically to automate integration tests and verify webhook
      handling without depending on external systems or staging real deposits.
      **Sandbox only** — all simulation endpoints return `404 Not Found` in
      production.
  - name: raindrops
    description: >-
      Rewards and points management endpoints. Custom API keys need
      `raindrops:read`/`raindrops:write` for general rewards endpoints and
      `raindrops-travel:read`/`raindrops-travel:write` for travel redemption
      endpoints.
    x-group: rewards
paths:
  /issuing/users/{userId}/charges:
    post:
      tags:
        - users
      summary: Charge a user a custom fee
      operationId: createUserCharge
      parameters:
        - name: userId
          in: path
          description: Id of the user to create a custom fee charge for
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Description of the custom fee charge
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssuingChargeCreateChargeBody'
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuingChargeCreateChargeResponse'
        '401':
          description: Invalid authorization
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    IssuingChargeCreateChargeBody:
      type: object
      required:
        - amount
        - description
      properties:
        amount:
          type: integer
          minimum: 1
          description: The amount of the charge, in cents
        description:
          type: string
          description: The description of the charge
    IssuingChargeCreateChargeResponse:
      type: object
      required:
        - id
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: The id of the charge
        createdAt:
          type: string
          format: date-time
          description: The time at which the charge was created
        amount:
          type: integer
          minimum: 1
          description: The amount of the charge, in cents
        description:
          type: string
          description: The description of the charge
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Api-Key
      in: header

````