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

# Create external payments

> Records one or more external payments in a single batch (max 100). Each payment targets a recipient by `payeeEmail` or `recipientId`.



## OpenAPI

````yaml /api-reference/openapi.json post /external-payments
openapi: 3.1.0
info:
  title: Karat Payout API
  description: >-
    Your gateway to seamless, automated, and scalable payment solutions. The
    Karat Payout API lets you create recipients, send payouts, track payment
    status, manage tax documents, record external payments, and subscribe to
    webhook events.
  version: 1.0.0
servers:
  - url: https://payouts.api.trykarat.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Create and manage outgoing payouts to recipients.
  - name: Recipients
    description: Manage the payees you send payouts to.
  - name: Tax
    description: Retrieve recipient tax forms (W-9) and download links.
  - name: External Payments
    description: Record and manage payments made outside of Karat.
  - name: Webhooks
    description: Subscribe to event notifications for payout activity.
paths:
  /external-payments:
    post:
      tags:
        - External Payments
      summary: Create external payments
      description: >-
        Records one or more external payments in a single batch (max 100). Each
        payment targets a recipient by `payeeEmail` or `recipientId`.
      operationId: createExternalPayments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalPaymentsRequest'
            example:
              externalPayments:
                - recipientId: 9c1f7b2a-3d4e-4f5a-8b6c-1d2e3f4a5b6c
                  amount: 50000
                  description: Paid via PayPal
                  date: '2026-06-15'
                  paymentMethod: paypal
                  platform: Upwork
              idempotencyKey: ext-2026-06-15-001
      responses:
        '201':
          description: The external payments were created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      batchId:
                        type: string
                        format: uuid
                      payments:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            createdAt:
                              type: string
                              format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    CreateExternalPaymentsRequest:
      type: object
      required:
        - externalPayments
      properties:
        externalPayments:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ExternalPaymentInput'
        idempotencyKey:
          type: string
          description: Batch-level idempotency key.
    ExternalPaymentInput:
      type: object
      required:
        - amount
      description: A single external payment. Provide `payeeEmail` or `recipientId`.
      properties:
        payeeEmail:
          type: string
          format: email
        recipientId:
          type: string
          format: uuid
        amount:
          type: integer
          minimum: 1
          description: Amount in cents.
        description:
          type: string
        date:
          type: string
          format: date
          description: Payment date (YYYY-MM-DD). Defaults to today.
        paymentMethod:
          type: string
          description: How the payment was made, e.g. `paypal`, `wire`.
        platform:
          type: string
          description: Platform the payment originated from.
        idempotencyKey:
          type: string
          description: Per-payment idempotency key.
    Error:
      type: object
      description: Standard error envelope returned for all non-2xx responses.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
          required:
            - message
      required:
        - error
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: 'amount: amount must be positive'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Invalid api key
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Payment intent not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as a bearer token: `Authorization: Bearer <API_KEY>`.'

````