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

# Withdraw from the card balance

> Money leaves the card balance to the customer's Endl account or to an external wallet — for individuals and businesses only, not employees.

A withdrawal is `pending` until the money leaves the card balance, then `card_withdrawal.completed` is sent, or `card_withdrawal.failed`.

<Warning>
**External withdrawals are not final yet.** The destination may become a registered recipient (`rec_`) instead of a raw address, and may not be available at launch.
</Warning>



## OpenAPI

````yaml api-reference/endl-cards-api.json POST /api/v0/cards/{customerId}/withdrawals
openapi: 3.1.0
info:
  title: Endl Cards API
  version: '0'
  description: >-
    Issue virtual cards to your customers: enrol the customer, fund the card
    balance, issue cards, show card details securely, and follow every
    transaction by webhook.


    Paths are under `/api/v0`. The key must carry the **`cards`** permission.
    **This API is not final yet** — see [what may still
    change](/api-reference/cards/introduction#not-final-yet).
servers:
  - url: https://api-sandbox.endl.io
    description: Sandbox
security:
  - apiKey: []
tags:
  - name: Enrolment
  - name: Cardholders
  - name: Cards
  - name: Card details
  - name: Transactions and balance
  - name: Deposits
  - name: Withdrawals
paths:
  /api/v0/cards/{customerId}/withdrawals:
    post:
      tags:
        - Withdrawals
      summary: Withdraw from the card balance
      description: >-
        Money leaves the card balance to the customer's Endl account or to an
        external wallet — for individuals and businesses only, not employees.


        A withdrawal is `pending` until the money leaves the card balance, then
        `card_withdrawal.completed` is sent, or `card_withdrawal.failed`.


        <Warning>

        **External withdrawals are not final yet.** The destination may become a
        registered recipient (`rec_`) instead of a raw address, and may not be
        available at launch.

        </Warning>
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CustomerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - chain
                - destination
              properties:
                amount:
                  allOf:
                    - $ref: '#/components/schemas/Money'
                  description: At most the `available` balance.
                chain:
                  type: string
                  description: The chain to receive it on.
                destination:
                  type: object
                  description: Exactly one of the two.
                  properties:
                    walletId:
                      type: string
                      description: The customer's Endl wallet (`wlt_`).
                    address:
                      type: string
                      description: An external wallet address.
            example:
              amount:
                amount: '200.00'
                currency: USD
              chain: base
              destination:
                walletId: wlt_3Kd8...
      responses:
        '201':
          description: The withdrawal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Withdrawal'
              example:
                withdrawalId: cwd_2Rt5...
                customerId: cus_1Xb7...
                amount:
                  amount: '200.00'
                  currency: USD
                chain: base
                destination:
                  walletId: wlt_3Kd8...
                transactionHash: null
                fees: []
                status: pending
                failureReason: null
                createdAt: '2026-10-16T10:00:00Z'
                completedAt: null
        '400':
          description: >-
            A request field is missing or invalid.


            The customer type can't do this. Withdrawals are for individuals and
            businesses only.


            The wallet isn't the customer's, or its chain isn't supported.


            The withdrawal address is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: |-
            The API key lacks the `cards` permission.

            The customer isn't enrolled, or the enrolment isn't `active`.

            The withdrawal address was refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |-
            Not enough funds in the card balance.

            The `Idempotency-Key` was reused with a different body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    ApiVersion:
      name: Api-Version
      in: header
      required: true
      description: >-
        The API version this request targets. `2026-09.1`. See
        [Versioning](/api-reference/versioning).
      schema:
        type: string
        pattern: ^\d{4}-\d{2}\.\d+$
        default: 2026-09.1
      example: 2026-09.1
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        1 to 64 characters. Required on every POST that creates something. A
        repeat returns the first result; the same key with a different body
        returns `409`.
      schema:
        type: string
        minLength: 1
        maxLength: 64
    CustomerId:
      name: customerId
      in: path
      required: true
      description: An individual, a business or an employee (`cus_`).
      schema:
        type: string
        example: cus_1Xb7...
  schemas:
    Money:
      type: object
      required:
        - amount
        - currency
      description: A decimal string and a currency code.
      properties:
        amount:
          type: string
          description: Decimal string, e.g. `"42.99"`.
          example: '42.99'
        currency:
          type: string
          description: Currency code, e.g. `USD`.
          example: USD
    Withdrawal:
      type: object
      properties:
        withdrawalId:
          type: string
          example: cwd_2Rt5...
        customerId:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
        chain:
          type: string
        destination:
          type: object
          properties:
            walletId:
              type: string
            address:
              type: string
        transactionHash:
          type:
            - string
            - 'null'
        fees:
          type: array
          items:
            $ref: '#/components/schemas/Fee'
          description: Endl fees on this withdrawal.
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
        failureReason:
          description: Why the withdrawal failed; `null` otherwise.
        createdAt:
          type: string
          format: date-time
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
    Error:
      type: object
      description: >-
        The standard Endl error body. `errors[].code` is an `ERRCRD_` code —
        **the code numbers are not final yet** — and `field` names the request
        field when one is at fault.
      properties:
        code:
          type: integer
        message:
          type: string
        status:
          type: string
          enum:
            - ERROR
        data:
          type: 'null'
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type:
                  - string
                  - 'null'
    Fee:
      type: object
      description: >-
        An Endl fee. The `fees` shape is final; the fee **amounts** are not
        final yet.
      properties:
        type:
          type: string
          example: transaction_fee
        amount:
          $ref: '#/components/schemas/Money'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Api-Key
      description: Partner API key. Must carry the `cards` permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.