Airtm

Airtm Payouts API

# Payouts Send money to recipients worldwide through their Airtm accounts. Payouts use a secure two-step process to prevent accidental payments. ## How Payouts Work ### Two-Step Process 1. **Create** - Validates recipient and reserves funds 2. **Commit** - Actually sends the money This prevents accidental payments and allows for approval workflows. ### One-Step Option Set `commit: true` when creating to skip the manual commit step for automated workflows. ## Integration Workflows ### Standard Two-Step Create payout → Review details → Commit when approved ### Automated Processing Create with `commit: true` for immediate processing

Documentation GitHub OpenAPI

Operations 7

POST /payouts Create a payout #

GET /payouts List payouts #

GET /payouts/{id} Get a single payout #

DELETE /payouts/{id} Cancel a pending payout #

GET /payouts/by-code/{code} Get a single payout by code #

GET /payouts/{id}/events Get the events for a single payout #

POST /payouts/{id}/commit Commit a payout #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/airtm-payouts-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Airtm Enterprise API V2 Payouts API
  version: 1.155.0
  description: '# Introduction


    The Airtm Enterprise API enables organizations to send and receive payments globally through a simple REST API.'
  contact:
    name: Airtm Enterprise
    email: enterprise@airtm.com
    url: https://www.airtm.com
servers:
- url: https://api.enterprise.airtm.com/v2
- url: https://api.stg.enterprise.airtm.com/v2
tags:
- name: Payouts
  description: '# Payouts


    Send money to recipients worldwide through their Airtm accounts.'
paths:
  /payouts:
    post:
      operationId: CreatePayout
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: 'This endpoint allows you to create a payout instruction. In the request body, information about

        the payout such as the recipient''s email, description, amount, and any URLs needed for confirmation

        or failure redirects should be provided.


        Upon successful creation, the API returns a response containing the details of the newly created

        payout, including a unique ID.


        > [!tip]

        > After making a call to this endpoint, no money is moved yet. To finish moving the money to a

        > user, you must call the `POST /v2/payouts/:id/commit` endpoint with the id from this response.

        > Alternatively, you may pass `commit: true` to do the payout in a single API call.'
      summary: Create a payout
      tags:
      - Payouts
      security:
      - basicAuth: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
    get:
      operationId: ListPayouts
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_PayoutResponse_'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      summary: List payouts
      tags:
      - Payouts
      security:
      - basicAuth: []
      parameters:
      - description: Gets results before the specified cursor.
        in: query
        name: before
        required: false
        schema:
          type: string
      - description: Gets results after the specified cursor.
        in: query
        name: after
        required: false
        schema:
          type: string
      - description: The maximum number of items to fetch.
        in: query
        name: perPage
        required: false
        schema:
          default: 100
          format: int32
          type: integer
          minimum: 10
          maximum: 1000
      - in: query
        name: status
        required: false
        schema:
          $ref: '#/components/schemas/PayoutStatus'
      - in: query
        name: bulkPayoutId
        required: false
        schema:
          type: string
  /payouts/{id}:
    get:
      operationId: GetPayout
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      summary: Get a single payout
      tags:
      - Payouts
      security:
      - basicAuth: []
      parameters:
      - description: The payout id
        in: path
        name: id
        required: true
        schema:
          type: string
    delete:
      operationId: CancelPayout
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: 'This endpoint allows users to cancel specific `CREATED` or `PENDING` individual payouts—those that:


        - have been created and committed but where the recipient is not ready to receive the payout.

        - have been created but have not yet been committed.


        Pending payouts will automatically cancel after 90 days (by default, other time periods are

        available in dashboard settings) from the creation date.


        Once canceled:


        - Funds are automatically returned to the enterprise''s balance.

        - The individual payout status is updated to `CANCELED`.

        - The response will include all relevant details of the canceled payout.


        Additional information about canceled payouts can be accessed through the Enterprise Portal'
      summary: Cancel a pending payout
      tags:
      - Payouts
      security:
      - basicAuth: []
      parameters:
      - description: The payout id
        in: path
        name: id
        required: true
        schema:
          type: string
  /payouts/by-code/{code}:
    get:
      operationId: GetPayoutByCode
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      summary: Get a single payout by code
      tags:
      - Payouts
      security:
      - basicAuth: []
      parameters:
      - in: path
        name: code
        required: true
        schema:
          type: string
  /payouts/{id}/events:
    get:
      operationId: GetPayoutEvents
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/OperationEvent'
                type: array
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: 'Every time a payout transitions to a new status, an event is created.

        This endpoint allows you to retrieve the events for a single payout.'
      summary: Get the events for a single payout
      tags:
      - Payouts
      security:
      - basicAuth: []
      parameters:
      - description: The payout id
        in: path
        name: id
        required: true
        schema:
          type: string
  /payouts/{id}/commit:
    post:
      operationId: CommitPayout
      responses:
        '204':
          description: Accepted
        default:
          description: Error
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 'Machine-friendly error code


                      See the API error code catalog in the documentation for the endpoint surface you are using.'
                    example: '415096'
                  message:
                    type: string
                    description: Human-readable error message
                    example: Invalid email address
                  data:
                    $ref: '#/components/schemas/Record_string.unknown_'
                    description: Additional data related to the error
                    example:
                      email: invalid@address
                required:
                - code
                - message
                type: object
      description: 'Once a payout is created, it needs to be committed. This is done with a POST request which

        takes a unique ID of the payout and commits it, meaning the payout is now ready to be

        processed.


        This endpoint would only respond with an empty 201.'
      summary: Commit a payout
      tags:
      - Payouts
      security:
      - basicAuth: []
      parameters:
      - description: The payout id
        in: path
        name: id
        required: true
        schema:
          type: string
components:
  schemas:
    PayoutStatus:
      description: "The current status of the payout.\n\n- `CREATED`: The payout instruction has been registered and is awaiting you to call the commit endpoint.\n- `COMMITTED`: The payout was committed and is in the process of being executed.\n- `PENDING`: Funds have been placed in escrow and waiting for the recipient to take the following action to complete the payout\n  1. If a new user, create an Airtm account.\n  2. If a user receiving an amount taking them over the $1,000 inflow threshold requiring KYC.\n  3. If a US user, complete KYC and configure payment method.\n- `COMPLETED`: The payout has been completed successfully, funds have been credited to the customer's account.\n- `CANCELED`: Payout has been canceled and funds have been returned to your account.\n- `FAILED`: The payout has failed and funds have been returned to your account.\n- `ERROR`: A temporary error state. Payouts in this state should be fixed and retried until they reach a final state (COMPLETED or CANCELED)."
      enum:
      - BRIDGE_COMPLETED
      - BRIDGE_CREATED
      - BRIDGE_FAILED
      - BRIDGE_MAX_RETRIES_REACHED
      - BRIDGE_USER_SIGNUP_PENDING
      - CANCELED
      - CANCEL_REQUESTED
      - COMMITTED
      - COMPLETED
      - COSMOEM_COMPLETED
      - CREATED
      - ERROR
      - FAILED
      - PENDING
      - PENDING_SIGNATURE
      - SIGNED
      - PENDING_USER_ACTION
      - PROCESSING
      type: string
      x-enum-varnames:
      - BRIDGE_COMPLETED
      - BRIDGE_CREATED
      - BRIDGE_FAILED
      - BRIDGE_MAX_RETRIES_REACHED
      - BRIDGE_USER_SIGNUP_PENDING
      - CANCELED
      - CANCEL_REQUESTED
      - COMMITTED
      - COMPLETED
      - COSMOEM_COMPLETED
      - CREATED
      - ERROR
      - FAILED
      - PENDING
      - PENDING_SIGNATURE
      - SIGNED
      - PENDING_USER_ACTION
      - PROCESSING
    PayinStatus:
      description: 'The current status of the payin


        - `CREATED`: The payin has been created but not yet confirmed.

        - `CONFIRMED`: The payin has been confirmed and is ready for processing.

        - `CANCELED`: The payin has been canceled by the user or system.

        - `PROCESSING`: The payin is currently being processed.

        - `FAILED`: The payin has failed due to an error.

        - `BRIDGE_FAILED`: The payin has failed due to an error in Bridge.

        - `BRIDGE_CANCELED`: The payin has been canceled due to an error in Bridge.'
      enum:
      - CREATED
      - CONFIRMED
      - CANCELED
      - PROCESSING
      - FAILED
      - BRIDGE_FAILED
      - BRIDGE_CANCELED
      type: string
      x-enum-varnames:
      - CREATED
      - CONFIRMED
      - CANCELED
      - PROCESSING
      - FAILED
      - BRIDGE_FAILED
      - BRIDGE_CANCELED
    Record_string.unknown_:
      properties: {}
      additionalProperties: {}
      type: object
      description: Construct a type with a set of properties K of type T
    CreatePayoutRequest:
      properties:
        airtmUserEmail:
          $ref: '#/components/schemas/Email'
          description: The recipient's email address that is associated with their Airtm account
        amount:
          type: number
          format: double
          description: The payment amount in USD.
          minimum: 0.01
        commit:
          type: boolean
          description: 'Immediately commit the payout.


            If `true`, the payout will be committed immediately after creation. Use this if you want to

            create a payout in just one API call instead of a two-step process outlined in the Create / Commit

            process.'
          default: false
        code:
          type: string
          description: 'A unique code used to identify the payout.

            Populate this value with the identifier on your system.


            > [!important]

            > It must be unique across all existing payouts.'
        enterpriseFee:
          type: number
          format: double
          description: The enterprise fee to apply to the payout
          minimum: 0
        notes:
          type: string
          description: 'An arbitrary string describing the payment.

            This information is displayed to the recipient.

            It''s recommended that the string summarizes the purpose of the payment.'
        internalNote:
          type: string
          description: The description of the payout; visible to internal users
        requireIdVerified:
          type: boolean
          description: Set this to true to require that the recipient is ID-verified
          default: false
      required:
      - airtmUserEmail
      - amount
      - notes
      type: object
      additionalProperties: false
    KycInformation:
      description: 'Represents the user''s KYC information for a payout.


        > [!TIP]

        > Only available in `payout.completed` webhook and only if ID verification is enabled in your account.

        > If you want access to this information, please contact [enterprise@airtm.io](mailto:enterprise@airtm.io)

        Represents the user''s KYC information for a payout.


        > [!TIP]

        > Only available in `payout.completed` webhook and only if ID verification is enabled in your account.

        > If you want access to this information, please contact [enterprise@airtm.io](mailto:enterprise@airtm.io)'
      properties:
        fullName:
          type:
          - string
          - 'null'
        birthDate:
          type:
          - string
          - 'null'
        identificationNumber:
          type:
          - string
          - 'null'
        countryCode:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
      required:
      - fullName
      - birthDate
      - identificationNumber
      - countryCode
      type: object
      additionalProperties: false
    Paginated_PayoutResponse_:
      description: Represents a paginated collection of items.
      properties:
        items:
          items:
            $ref: '#/components/schemas/PayoutResponse'
          type: array
          description: The items in the current page.
        startCursor:
          type: string
          description: The cursor for the first item in the current page.
        endCursor:
          type: string
          description: The cursor for the last item in the current page.
      required:
      - items
      type: object
      additionalProperties: false
    OperationEvent:
      properties:
        updatedAt:
          type: string
          format: date-time
          description: Date when the event was last updated.
        createdAt:
          type: string
          format: date-time
          description: Date when the event was created.
        metadata:
          properties:
            transitionMessage:
              type: string
            transitionCode:
              type: string
          type: object
          description: Metadata associated with the event.
        availableBalance:
          type:
          - number
          - 'null'
          format: double
          description: Available balance for the enterprise.
          example: 12345.67
        fboBalance:
          type:
          - number
          - 'null'
          format: double
          description: Total balance available in the FBO account.
          example: 12345.67
        pendingBalance:
          type:
          - number
          - 'null'
          format: double
          description: Balance that is committed in pending payouts.
          example: 123.45
        newStatus:
          anyOf:
          - $ref: '#/components/schemas/PayoutStatus'
          - $ref: '#/components/schemas/PayinStatus'
          description: New status of the operation.
        previousStatus:
          anyOf:
          - $ref: '#/components/schemas/PayoutStatus'
          - $ref: '#/components/schemas/PayinStatus'
          description: Previous status of the operation.
        eventType:
          type: string
          description: Type of the event.
        operationType:
          type: string
          description: 'Type of the operation associated with the event.


            It could be either ''PAYOUT'' or ''PAYIN''.'
        operationId:
          type: string
          description: Unique identifier for the operation associated with the event.
          format: uuid
        userId:
          type: string
          description: Unique identifier for the user associated with the event.
          format: uuid
        id:
          type: string
          description: Unique identifier for the event.
          format: uuid
      required:
      - updatedAt
      - createdAt
      - metadata
      - newStatus
      - previousStatus
      - eventType
      - operationType
      - operationId
      - userId
      - id
      type: object
      description: An operation event is generated when a payin or payout transitions status.
    PayoutResponse:
      description: Represents a Payout Object
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
          description: This is the unique identifier for the payout.
        bulkPayoutId:
          $ref: '#/components/schemas/Uuid'
          description: The identifier of the bulk payout that created this payout.
        hash:
          type: string
          description: Unique hash for the payout operation within the Airtm system.
        code:
          type: string
          description: A unique code used to identify the payout.
        airtmUserId:
          $ref: '#/components/schemas/Uuid'
          description: This is the unique identifier for the AirTM user associated with this payout.
        airtmUserEmail:
          $ref: '#/components/schemas/Email'
          description: This is the email of the Airtm user associated with this payout.
        requireIdVerified:
          type: boolean
          description: Whether the recipient must be ID-verified to receive the funds
          default: false
        notes:
          type: string
          description: An arbitrary string describing the payment. This information is displayed to the recipient.
        internalNote:
          type: string
          description: The description of the payout; visible to internal users
        status:
          $ref: '#/components/schemas/PayoutStatus'
        grossAmount:
          type: number
          format: double
          description: amount originally intended for the payout
          example: 10
        amount:
          type: number
          format: double
          description: amount to be deducted from the enterprise account (grossAmount - enterpriseFee)
          example: 9.5
        netAmount:
          type: number
          format: double
          description: amount received by the user (grossAmount - enterpriseFee - airtmFee)
          example: 9
        airtmFee:
          type: number
          format: double
          description: The airtm fee applied to the payout
          example: 0.5
        enterpriseFee:
          type: number
          format: double
          description: The enterprise fee applied to the payout
          example: 0.5
        reasonCode:
          type: string
          description: Machine-friendly code relating to the reason why the payout has the current status
          example: 522443
        reasonDescription:
          type: string
          description: Human-readable message describing the reason why the payout has the current status
        kycInformation:
          $ref: '#/components/schemas/KycInformation'
        createdAt:
          type: string
          format: date-time
          description: Timestamp of when the payout was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the last update made to the payout.
      required:
      - id
      - airtmUserId
      - airtmUserEmail
      - status
      - grossAmount
      - amount
      - netAmount
      - createdAt
      - updatedAt
      type: object
      additionalProperties: false
    Email:
      type: string
      pattern: ^(.+)@(.+)$
    Uuid:
      type: string
      format: uuid
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-tagGroups:
- name: Payout Operations
  tags:
  - Payouts
  - Bulk Payouts
  - Users
- name: Payin Operations
  tags:
  - Payins
- name: Account
  tags:
  - Me
  - Deposits
  - Reports
- name: Direct Withdrawal
  tags:
  - External Bank Account
  - External Crypto Account
  - Withdrawals
- name: Webhooks
  tags:
  - Webhooks