Airtm

Airtm Purchases / Payins API

## Overview The Payins endpoint (also known as Purchases) enables your organization to accept payments from users for products, services, or any other transactions. This endpoint is essential for e-commerce platforms, service providers, and any business that needs to collect payments from customers through the Airtm platform. ## What are Payins? Payins represent incoming payments to your enterprise account. When a user makes a purchase or payment to your organization, it creates a payin operation that can be tracked and managed through this endpoint. ### Key Features - **Flexible Payment Processing** - Accept payments for various products and services - **Multi-Currency Support** - Process payments in different currencies - **Real-Time Status Updates** - Track payment progress in real-time - **Secure Checkout Process** - Redirect users to secure Airtm payment pages - **Webhook Integration** - Receive instant notifications on payment status changes - **Reference Code Tracking** - Link payments to your internal order systems ## Payment Flow 1. **Create Purchase** - Your system creates a purchase request with payment details 2. **User Checkout** - User is redirected to Airtm's secure checkout page 3. **Authentication** - User logs into their Airtm account to complete payment 4. **Processing** - Payment is processed and status updates are provided 5. **Completion** - Payment is completed and funds are transferred to your account ## Status Management ### Purchase Status Values | Status | Final? | Description | | ----------- | ------ | ------------------------------------------------- | | `created` | No | Purchase created, awaiting user payment | | `confirmed` | Yes | Payment completed successfully, funds transferred | | `canceled` | Yes | User canceled the purchase, no funds transferred | | `failed` | Yes | Payment processing failed | > [!TIP] > Implement case-insensitive status comparisons in your code to handle potential variations.

GitHub OpenAPI

Operations 2

POST purchases Create purchase #
GET purchases Get purchase #

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-purchases-payins-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-purchases-payins-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-purchases-payins-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Airtm Enterprise API V1 Purchases / Payins 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: Purchases / Payins
  description: '## Overview


    The Payins endpoint (also known as Purchases) enables your organization to accept payments from users for products, services, or any other transactions.'
paths:
  purchases:
    post:
      security:
      - basicAuth: []
      tags:
      - Purchases / Payins
      summary: Create purchase
      description: 'This endpoint will allow you to create a Purchase (Pay-in). In order to

        complete a Purchase, it must first be created, then the user must be

        directed to the Airtm website to confirm/checkout the Purchase, at which

        time they will be redirected to a URL of your choosing. See “Usage”

        below.


        We will redirect the user to either `confirmation_uri` or `cancel_uri`

        with code as query parameter so you can process the Purchase as being

        either confirmed or cancelled.


        ## Usage


        1. Create a Purchase via an HTTP POST.


        2. Extract the id from the response, and redirect user to:

        https://`/checkout/:id` User will be redirected for

        authentication as necessary.


        3. User will confirm or cancel purchase from Airtm’s website.


        4. If confirmed, money will be transferred from user’s Airtm wallet, to

        partner''s Airtm wallet, and redirected to the provided

        `confirmation_uri`. If canceled, no money will be transferred, and the

        user will be redirected to the provided cancel\_uri.


        Upon confirmation, or cancellation the purchase will be considered

        completed, and the URL residing at /checkout/:id will no longer

        function. Therefore, if you wish to complete an identical Purchase, you

        will need to create a new Purchase, and be provisioned a new id for that

        Purchase.


        The `confirmation_uri` attribute should not be used for transaction

        completeness verification, if the URI was requested, it doesn''t mean the

        transaction was completed successfully. If the `callback_uri` attribute

        is provided, we will POST the purchase JSON to it after the purchase is

        completed, either if it was confirmed, canceled or failed. In case

        `callback_uri` attribute is NOT provided, we recommend checking the

        transaction status using `GET /operations/:id` before any external

        movement.


        > [!tip]

        > The way to emit a purchase refund is to create a payout from your Airtm

        > Partner account and then commit it, this will move money from your Airtm

        > account to your user''s Airtm account.'
      operationId: Purchases _ Payins_purchases-payins/create-purchase
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique id of the transaction
                    example: 5201de5f-03e6-43e1-ba36-bebaf3f429f6
                    format: uuid
                  status:
                    type: string
                    description: 'Status of the request, can be ''created'', ''processing'',

                      ''canceled'' or ''confirmed''.

                      '
                    example: created
                  amount:
                    type: Number
                    description: 'The total amount in USD of the purchase. This value must

                      correctly correspond to the sum of the amounts associated

                      with each purchase item.

                      '
                    example: '15.00'
                    format: float
                  description:
                    type: string
                    description: 'A text string describing the purchase. This text is

                      displayed to the user when they are confirming the

                      transaction.

                      '
                    example: Purchase test
                  confirmation_uri:
                    type: string
                    description: 'A URL to redirect the user to when they confirm the

                      transaction.

                      '
                    example: https://your.site/confirm
                    format: uri
                  cancel_uri:
                    type: string
                    description: 'A URL to redirect the user to when they cancel the

                      transaction.

                      '
                    example: https://your.site/cancel
                    format: uri
                  code:
                    type: string
                    description: 'An arbitrary string of the partner’s choosing. Used to

                      identify and correlate Airtm purchases with partner

                      records. Must be unique.

                      '
                    example: ExternalIdentifier01
                  airtm_operation_id:
                    type: string
                    description: Airtm's internal unique id number for the operation.
                  created_at:
                    type: string
                    description: Datetime when the transaction was created.
                    example: '2022-05-25T00:34:30.641Z'
                    format: date-time
                  updated_at:
                    type: string
                    description: 'Datetime of the latest change in status of the

                      transaction.

                      '
                    example: '2022-05-25T00:34:30.641Z'
                    format: date-time
                  airtm_user_id:
                    type: string
                    description: 'User id of the user that completed one purchase. '
                    format: uuid
                  airtm_user_email:
                    type: string
                    description: Email of the user that completed one purchase.
                    format: email
                  operation_type:
                    type: string
                    description: Operation type, always 'purchase'.
                    example: purchase
                  failure_uri:
                    type: string
                    description: 'An endpoint / webhook on your servers which we will POST

                      the Puchase JSON to when we''re unable to process the

                      Purchase.

                      '
                  failure_reason:
                    type: string
                    description: This populates with the reason the operation failed.
                  callback_uri:
                    type: string
                    description: 'An endpoint / webhook on your server which we will POST

                      the purchase JSON to when the purchase is completed.

                      '
                    example: https://your.site/callback
                  airtm_operation_hash:
                    type: string
                    description: 'Unique hash for the Purchase operation within the Airtm

                      system.

                      '
        '403':
          description: Duplicated Code
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: ''
                    example: '352014'
                  message:
                    type: string
                    description: ''
                    example: A purchase with this code already exists
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: ''
                    example: 500
                  message:
                    type: string
                    description: ''
                    example: Internal server error
      requestBody:
        description: Request body
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: 'An arbitrary string of the partner’s choosing. Used to

                    identify and correlate Airtm purchases with partner records.

                    Must be unique.

                    '
                  example: ExternalIdentifier01
                description:
                  type: string
                  description: 'A text string describing the purchase. This text is

                    displayed to the user when they are confirming the

                    transaction.

                    '
                  example: Test purchase
                cancel_uri:
                  type: string
                  description: 'A URL to redirect the user to when they cancel the

                    transaction.

                    '
                  example: https://your.site/cancel
                  format: uri
                confirmation_uri:
                  type: string
                  description: 'A URL to redirect the user to when they confirm the

                    transaction.

                    '
                  example: https://your.site/confirm
                  format: uri
                callback_uri:
                  type: string
                  description: 'An endpoint/webhook on your server which we will POST the

                    purchase JSON to when the purchase is completed.

                    '
                  example: https://your.site/callback
                  format: uri
                failure_uri:
                  type: string
                  description: 'An endpoint / webhook on your servers which we will POST the

                    Puchase JSON to when we''re unable to process the Purchase.

                    '
                  example: https://your.site/failure
                  format: uri
                amount:
                  type: number
                  description: 'The total amount in USD of the purchase. This value must

                    correctly correspond to the sum of the amounts associated

                    with each purchase item.

                    '
                  example: 15
                items:
                  type: array
                  description: An array of the items being purchased/bought.
                  items:
                    type: object
                    properties:
                      description:
                        type: string
                        description: ''
                        example: test item 2
                      amount:
                        type: number
                        description: ''
                        example: 3
                      quantity:
                        type: number
                        description: ''
                        example: 1
                    required:
                    - quantity
              required:
              - code
              - description
              - amount
              - items
    get:
      security:
      - basicAuth: []
      tags:
      - Purchases / Payins
      summary: Get purchase
      description: 'You can either use this endpoint or the /operations with the ‘type’

        parameter as ‘purchase’ in the endpoint to get the list of all

        purchases.'
      operationId: Purchases _ Payins_purchases-payins/get-purchase
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  currentPage:
                    type: number
                    description: Page currently displayed.
                    example: 1
                  lastPage:
                    type: number
                    description: Number of pages available.
                    example: 1
                  perPage:
                    type: number
                    description: Number of items per page displayed in the response.
                    example: 10
                  total:
                    type: number
                    description: Total operations retrieved.
                    example: 1
                  from:
                    type: number
                    description: Number of first operation retrieved.
                    example: 1
                  to:
                    type: number
                    description: Number of last operation retrieved.
                    example: 1
                  data:
                    type: array
                    description: 'An array of items retrieved, contains all operations

                      available requested, limited by the ''perPage'' parameter.

                      '
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Payment unique identifier.
                          example: f782702e-e4fe-46b7-8ef1-de8b70a50587
                        partner_id:
                          type: string
                          description: ID of the partner that created the purchase.
                          example: 2c3e7d5e-0cfb-411f-9e34-78ba4d3b8ce7
                        status:
                          type: string
                          description: 'The status of the operation. Please refer to the

                            Purchases and Payments endpoints to see possible

                            statuses.

                            '
                          example: created
                        amount:
                          type: string
                          description: Amount in USD that was transacted in the operation.
                          example: '15.00'
                        description:
                          type: string
                          description: 'A text string describing the purchase. This text is

                            displayed to the user when they are confirming the

                            transaction.

                            '
                          example: Test purchase
                        confirmation_uri:
                          type: string
                          description: 'An available URL on partner''s servers to redirect

                            (purchase) or POST (payout) to, when the payment is

                            completed.

                            '
                          example: https://your.site/confirm
                        cancel_uri:
                          type: string
                          description: 'An available URL on partner''s servers to redirect

                            the user to when they cancel a purchase.

                            '
                          example: https://your.site/cancel
                        code:
                          type: string
                          description: 'An arbitrary string of the partner’s choosing. Used

                            to identify and correlate Airtm purchases with

                            partner records. Must be a unique.

                            '
                          example: ExternalIdentifier01
                        airtm_operation_id:
                          type: 'null'
                          description: The ID of the operation on Airtm platform.
                          example: ''
                        created_at:
                          type: string
                          description: The datetime the operation was created.
                          example: '2023-06-08T15:30:58.887Z'
                        updated_at:
                          type: string
                          description: The datetime the operation was last modified.
                          example: '2023-06-08T15:30:58.887Z'
                        airtm_user_id:
                          type: 'null'
                          description: The ID of the user involved in the payout/purchase
                          example: ''
                        airtm_user_email:
                          type: 'null'
                          description: 'The email of the user involved in the

                            payout/purchase in Airtm.

                            '
                          example: ''
                        operation_type:
                          type: string
                          description: Type of operation, will always be 'purchase'.
                          example: purchase
                        failure_uri:
                          type: 'null'
                          description: 'An available URL on partner''s servers to POST when

                            payout fails.

                            '
                          example: ''
                        failure_reason:
                          type: 'null'
                          description: This populates with the reason the operation failed.
                          example: ''
                        callback_uri:
                          type: string
                          description: 'An endpoint / webhook on your server which we will

                            POST the purchase JSON to when the purchase is

                            completed.

                            '
                          example: https://your.site/callback
                        airtm_operation_hash:
                          type: 'null'
                          description: 'Unique hash for the payout operation within the

                            AirTM system.

                            '
                          example: ''
                      required: []
        '403':
          description: Forbidden
          content:
            application/html:
              schema:
                type: object
                properties:
                  raw:
                    type: String
                    description: ''
                    example: '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

                      <HTML><HEAD><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">

                      <TITLE>ERROR: The request could not be satisfied</TITLE>

                      </HEAD><BODY>

                      <H1>403 ERROR</H1>

                      <H2>The request could not be satisfied.</H2>

                      <HR noshade size="1px">

                      Request blocked.

                      We can''t connect to the server for this app or website at this time. There might be too much traffic or a configuration error. Try again later, or contact the app or website owner.

                      <BR clear="all">

                      If you provide content to customers through CloudFront, you can find steps to troubleshoot and help prevent this error by reviewing the CloudFront documentation.

                      <BR clear="all">

                      <HR noshade size="1px">

                      <PRE>

                      Generated by cloudfront (CloudFront)

                      Request ID: dXlTEB0QOsMHTVtAcDttXa8VxSYBx9HsPSfzJxHh3lwqgYKy6AQmiw==

                      </PRE>

                      <ADDRESS>

                      </ADDRESS>

                      </BODY></HTML>'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: ''
                    example: 500
                  message:
                    type: string
                    description: ''
                    example: Internal server error
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic