Airtm

Airtm Bulk Payments API

## Overview Bulk Payments enable your organization to process multiple payouts simultaneously through a single API operation. This powerful feature is designed for businesses that need to send payments to large numbers of recipients efficiently, such as payroll processing, affiliate commissions, contractor payments, or distribution of rewards and bonuses. ## What are Bulk Payments? Bulk Payments allow you to upload a batch of payout instructions and process them all at once, rather than making individual API calls for each payment. This approach offers significant advantages in terms of efficiency, cost-effectiveness, and operational simplicity. ### Key Features - **High-Volume Processing** - Handle thousands of payments in a single operation - **Asynchronous Processing** - Non-blocking operations that scale with your needs - **Real-Time Progress Tracking** - Monitor batch processing status in real-time - **Detailed Reporting** - Comprehensive success and failure reporting - **Cost Efficiency** - Reduced API calls and processing overhead ### Use Cases - **Payroll Processing** - Monthly/weekly employee salary payments - **Contractor Payments** - Freelancer and contractor compensation - **Affiliate Commissions** - Partner and affiliate reward distribution - **Prize Distribution** - Contest and promotion prize payments - **Supplier Payments** - Vendor and supplier payment processing - **Refund Processing** - Bulk customer refund operations ## Bulk Payment Workflow ### 1. Preparation Phase - Validate recipient information - Calculate total amounts and fees - Ensure sufficient account balance ### 2. Upload Phase - Submit bulk payment request - Receive batch ID for tracking - System validates all entries - Initial status: `pending` ### 3. Processing Phase - Individual payments are processed asynchronously - Real-time status updates available - Status changes to `running` - Progress tracking via API ### 4. Completion Phase - All payments processed (success or failure) - Final status: `done` - Detailed reports available - Success and failure breakdowns provided ## Status Management ### Bulk Payment Status Values | Status | Description | Actions Available | | --------- | ---------------------------------------------------------- | ----------------------------------------- | | `pending` | The bulk payment was received but it has yet to be started | Cancel entire batch | | `running` | Individual payments being processed | Monitor progress, cancel pending payments | | `done` | All payments processed (success or failure) | View reports, download results | | `failed` | An error occurred during processing | check the errors endpoint |

GitHub OpenAPI

Operations 6

POST bulk-payments New bulk payment #
GET bulk-payments Get bulk payments history #
GET bulk-payments/{bulkPaymentId} Get bulk payments details #
GET bulk-payments/{bulkPaymentId}/errors Get failed bulk payments #
GET bulk-payments/{bulkPaymentId}/payments Get bulk payments by id #
POST bulk-payments/{bulkPaymentId}/payments/cancel Cancel pending bulk payments #

Documentation

📖
Documentation
https://docs.airtm.com/
📖
APIReference
https://docs.airtm.com/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/airtm/refs/heads/main/openapi/airtm-bulk-payments-api-openapi.yml

Other Resources

🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/airtm/refs/heads/main/asyncapi/airtm-webhooks.yml

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-bulk-payments-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

airtm-bulk-payments-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Airtm Enterprise API V1 Bulk Payments API
  version: 1.0.0
  description: '## Introduction


    Welcome to Airtm''s Enterprise Payments API - a comprehensive solution for programmatic payment processing that enables organizations worldwide to send and receive payments efficiently and securely.'
servers:
- url: https://payments.air-pay.io
- url: https://payments.static-stg.tests.airtm.org
tags:
- name: Bulk Payments
  description: '## Overview


    Bulk Payments enable your organization to process multiple payouts simultaneously through a single API operation.'
paths:
  bulk-payments:
    post:
      security:
      - basicAuth: []
      tags:
      - Bulk Payments
      summary: New bulk payment
      description: 'Create a new bulk payment. You will receive a response with the id of

        your bulk payment and the processing will start asynchronously after you

        receive your response. You can check in with the progress of your

        ongoing bulk payment with any of the endpoints described further down

        this section.'
      operationId: Bulk Payments_bulk-payments/new-bulk-payment
      parameters:
      - name: Content-Type
        in: header
        required: false
        schema:
          type: String
          example: application/json
          description: ''
          default: ''
        description: ''
      - name: Authorization
        in: header
        required: false
        schema:
          type: String
          example: Basic {your_token}
          description: ''
          default: ''
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: 'Unique identifier automatically generated on bulk payment

                      creation.

                      '
                    example: 938ab3e6-a8f7-4995-bb23-a09703fc3289
                    format: uuid
                  status:
                    type: string
                    description: 'Status of the bulk payment, please check the Possible

                      Statuses section in this endpoint''s summary.

                      '
                    example: RUNNING
                  payments:
                    type: object
                    description: ''
                    properties:
                      count:
                        type: number
                        description: Number of individual payments within the bulk payment.
                        example: 2
                    required: []
        '500':
          description: Invalid account status
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: ''
                    example: 'sender does not have a valid account status (currently

                      BANNED)

                      '
      requestBody:
        description: Request body
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                '0':
                  type: array
                  description: Single user information to receive the bulk payment.
                  items:
                    type: string
                    description: 'User''s Airtm email. If user does not have an Airtm account

                      with that email, if succeeded, the funds will move to a

                      GUEST account with that email and will be released once

                      the user creates an Airtm account with that email.

                      '
                    example: patrick@airtm.io
                    format: email
                '1':
                  type: object
                  description: ''
                  properties:
                    receiver_email:
                      type: string
                      description: ''
                      example: master@airtm.io
                    amount:
                      type: number
                      description: ''
                      example: 10
                    currency:
                      type: string
                      description: ''
                      example: USD
                    note:
                      type: string
                      description: ''
                      example: salary
                    internal_note:
                      type: string
                      description: ''
                      example: system number 45113-231
                  required: []
    get:
      security:
      - basicAuth: []
      tags:
      - Bulk Payments
      summary: Get bulk payments history
      description: 'Endpoint to get all bulk payments associated with your account. This

        will give you an overview of all the bulk payments you ever posted. This

        endpoint is paginated, so make sure to "flip through the pages" via the

        query parameter "page" if you need to get all the information.'
      operationId: Bulk Payments_bulk-payments/get-bulk-payments-history
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: String
          example: '1'
          description: Page number to get bulk payments information from.
          default: ''
        description: Page number to get bulk payments information from.
      - name: Accept
        in: header
        required: false
        schema:
          type: String
          example: application/json
          description: ''
          default: ''
        description: ''
      - name: Authorization
        in: header
        required: false
        schema:
          type: String
          example: Basic {your_token}
          description: ''
          default: ''
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  bulk_payments:
                    type: array
                    description: Array of bulk payments that were created by the partner.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: ''
                          example: 47b08782-20c1-4c8e-b7a5-1ca0b046af08
                        status:
                          type: string
                          description: ''
                          example: DONE
                        created_at:
                          type: string
                          description: ''
                          example: '2021-06-25T14:31:24.549Z'
                        payments:
                          type: object
                          description: ''
                          properties:
                            count:
                              type: number
                              description: ''
                              example: 4
                            completed:
                              type: number
                              description: ''
                              example: 4
                            failed:
                              type: string
                              description: ''
                              example: ''
                          required: []
                      required: []
                  count:
                    type: number
                    description: Number of bulk payments found.
                    example: 5
                  pages:
                    type: number
                    description: Number of pages with bulk payment information.
                    example: 1
                  currentPage:
                    type: number
                    description: Current page that the partner is exploring.
                    example: 1
  bulk-payments/{bulkPaymentId}:
    get:
      security:
      - basicAuth: []
      tags:
      - Bulk Payments
      summary: Get bulk payments details
      description: 'Endpoint to retrieve the details of an existing bulk payment. The status

        `RUNNING` is the default after you have posted your bulk payment. It

        means that the individual payments are being processed and not all of

        them have processed yet. Once that has happened, the status will switch

        to `DONE`.'
      operationId: Bulk Payments_bulk-payments/get-bulk-payments-details
      parameters:
      - name: bulkPaymentId
        in: path
        required: false
        schema:
          type: String
          example: ''
          description: ''
          default: ''
        description: ''
      - name: Content-Type
        in: header
        required: false
        schema:
          type: String
          example: application/json
          description: ''
          default: ''
        description: ''
      - name: Authorization
        in: header
        required: false
        schema:
          type: String
          example: Basic {your_token}
          description: ''
          default: ''
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: ID
                    example: 2fa2b192-e140-4b69-b842-db4a4ef63063
                  status:
                    type: string
                    description: 'Status of the bulk payment, please check the Possible

                      Statuses section in this endpoint''s summary.

                      '
                    example: DONE
                  payments:
                    type: object
                    description: ''
                    example:
                      count: 2
                      pending: 1
                    properties:
                      count:
                        type: number
                        description: Number of individual payments within the bulk payment.
                        example: 2
                      pending:
                        type: number
                        description: Number of individual payments in the PENDING status.
                        example: 1
                    required: []
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    properties: {}
                    required: []
                  code:
                    type: string
                    description: ''
                    example: '352017'
                  message:
                    type: string
                    description: ''
                    example: Bulk payment not found
                  displayToUser:
                    type: boolean
                    description: ''
                    example: false
  bulk-payments/{bulkPaymentId}/errors:
    get:
      security:
      - basicAuth: []
      tags:
      - Bulk Payments
      summary: Get failed bulk payments
      description: 'This endpoint allows you to see the parts of your bulk payment that

        could not be processed. There is no way to restart them other than to

        create a new bulk payment. There may be unlikely occurrences where some

        errors might not be clear or will only contain an error code. Please

        reach out to enterprise@airtm.com, we are eager to improve the API or

        explain why a payment cannot be processed.


        There is no way of restarting a failed payment. You must post a new bulk

        payment or contact support.


        This endpoint is paginated, so make sure to "flip through the pages" via

        the query parameter "page" if you need to get all the information.'
      operationId: Bulk Payments_bulk-payments/get-failed-bulk-payments
      parameters:
      - name: bulkPaymentId
        in: path
        required: false
        schema:
          type: String
          example: ''
          description: ''
          default: ''
        description: ''
      - name: Accept
        in: header
        required: false
        schema:
          type: String
          example: application/json
          description: ''
          default: ''
        description: ''
      - name: Authorization
        in: header
        required: false
        schema:
          type: String
          example: Basic {your_token}
          description: ''
          default: ''
        description: ''
      responses:
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    properties: {}
                    required: []
                  code:
                    type: string
                    description: ''
                    example: '352017'
                  message:
                    type: string
                    description: ''
                    example: Bulk payment not found
                  displayToUser:
                    type: boolean
                    description: ''
                    example: false
        200 - Failed payments:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    description: 'Response if some payments failed, divided in individual

                      payments to users.

                      '
                    items:
                      type: object
                      properties:
                        receiver_email:
                          type: string
                          description: ''
                          example: master@airtm.io
                        amount:
                          type: number
                          description: ''
                          example: 10
                        currency:
                          type: string
                          description: ''
                          example: USD
                        note:
                          type: string
                          description: ''
                          example: salary
                        internal_note:
                          type: string
                          description: ''
                          example: best
                        status:
                          type: string
                          description: ''
                          example: FAILED
                        error:
                          type: string
                          description: ''
                          example: 'The second party is not allowed to receive more

                            money

                            '
                      required: []
                  count:
                    type: number
                    description: Number of failed payments found.
                    example: 2
                  pages:
                    type: number
                    description: Number of pages with all the individual payments.
                    example: 1
                  currentPage:
                    type: number
                    description: Current page that the information is in.
                    example: 1
        200 - No failed payments:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    description: This is the response when no errors were found.
                    items: {}
                  count:
                    type: number
                    description: Number of failed payments found.
                  pages:
                    type: number
                    description: Number of pages.
                  currentPage:
                    type: number
                    description: Current page that the information is in.
                    example: 1
                  status:
                    type: string
                    description: Status of the payments displayed. Always FAILED.
                    example: FAILED
  bulk-payments/{bulkPaymentId}/payments:
    get:
      security:
      - basicAuth: []
      tags:
      - Bulk Payments
      summary: Get bulk payments by id
      description: 'Get the status of all payments in an existing bulk payment of yours.

        This will allow you to find out which payments succeeded, are still

        pending or may have failed. This endpoint is paginated, so make sure to

        "flip through the pages" via the query parameter "page" if you need to

        get all the information.'
      operationId: Bulk Payments_bulk-payments/get-bulk-payments-by-id
      parameters:
      - name: bulkPaymentId
        in: path
        required: false
        schema:
          type: String
          example: ''
          description: ID of the bulk payment to look into.
          default: ''
        description: ID of the bulk payment to look into.
      - name: page
        in: query
        required: false
        schema:
          type: String
          example: '1'
          description: ''
          default: ''
        description: ''
      - name: sort
        in: query
        required: false
        schema:
          type: String
          example: desc:amount,asc:internal_note
          description: ''
          default: ''
        description: ''
      - name: Accept
        in: header
        required: false
        schema:
          type: String
          example: application/json
          description: ''
          default: ''
        description: ''
      - name: Authorization
        in: header
        required: false
        schema:
          type: String
          example: Basic {your_token}
          description: ''
          default: ''
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    description: ''
                    items:
                      type: object
                      properties:
                        receiver_email:
                          type: string
                          description: ''
                          example: master@airtm.io
                        airtm_user_id:
                          type: string
                          description: ''
                          example: e5b6d935-916d-49c6-8347-d9a98331e2c0
                        amount:
                          type: number
                          description: ''
                          example: 10
                        currency:
                          type: string
                          description: ''
                          example: USD
                        note:
                          type: string
                          description: ''
                          example: salary
                        internal_note:
                          type: string
                          description: ''
                          example: system number 45113-231
                        status:
                          type: string
                          description: ''
                          example: PENDING
                        hash:
                          type: string
                          description: ''
                          example: 6BD5RK4DC3VH835F
                      required: []
                  count:
                    type: number
                    description: Number of individual payments found.
                    example: 2
                  pages:
                    type: number
                    description: Number of pages with all the individual payments.
                    example: 1
                  currentPage:
                    type: number
                    description: Current page that the partner is exploring.
                    example: 1
  bulk-payments/{bulkPaymentId}/payments/cancel:
    post:
      security:
      - basicAuth: []
      tags:
      - Bulk Payments
      summary: Cancel pending bulk payments
      description: 'This endpoint enables users to manually cancel specific or all `pending`

        individual payouts within a bulk payment. Users can input transaction

        `hash` IDs for specific pending payouts they wish to cancel, retrievable

        from the GET bulk payments by id. If no hash is included in the request

        body, the endpoint will cancel all pending payouts associated with the

        bulk payment. Pending payouts will automatically cancel after 90 days

        (by default, other time periods are avilable in dashboard settings) from

        the creation date. Once canceled, funds are automatically restituted to

        user''s Airtm balance, and individual payout status are updated to

        `canceled`.'
      operationId: Bulk Payments_bulk-payments/cancel-pending-payments-1
      parameters:
      - name: bulkPaymentId
        in: path
        required: false
        schema:
          type: String
          example: ''
          description: ''
          default: ''
        description: ''
      - name: Content-Type
        in: header
        required: false
        schema:
          type: String
          example: application/json
          description: ''
          default: ''
        description: ''
      - name: Authorization
        in: header
        required: false
        schema:
          type: String
          example: Basic {your_token}
          description: ''
          default: ''
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  successful:
                    type: array
                    description: ''
                    items:
                      type: string
                      description: ''
                      example: CADBEW460EXAMPLE
        '422':
          description: Bulk Payment ID not valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Description on standard bulk payment ID format.
                    example: Unprocessable entity
                  messages:
                    type: object
                    description: ''
                    properties:
                      id:
                        type: array
                        description: ''
                        items:
                          type: string
                          description: ''
                          example: 'id must match the following:

                            "/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/"

                            '
                    required: []
      requestBody:
        description: Request body
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentItems:
                  type: array
                  description: ''
                  items:
                    type: object
                    properties:
                      airtm_operation_hash:
                        type: string
                        description: ''
                        example: CADBEW460EXAMPLE
                    required: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic