Airtm's Payments API is a tool for your organization to programmatically pay and get paid using Airtm. Organizations of all sizes use Airtm to receive payments from their users and distribute payments, either in bulk, or one at a time to employees, contractors, freelancers, and donation recipients around the world.

If you have a business or non-profit and would like to partner with Airtm, please contact our Airtm Partnerships team to get your Airtm Enterprise Partner account set up.

Contact Airtm Partnerships Team

Not a programmer?

Try out our API Explorer to create, test and implement these endpoints without programming knowledge.

Airtm supports two different environments for developers, a Sandbox environment and the Production environment.

Callback IPs

Many of our endpoints offer callbacks to inform your app about a successful or failed operation. To make sure you can receive those callbacks, you often need to whitelist those IPs that the callbacks originate from. Here is an overview of those IPs:

The Purchases endpoint of the Airtm Payments API is designed to handle all operations related to purchases made by users on the platform. This section of the API is key to any e-commerce or online business that enables users to buy products or services.

Here's an explanation of typical operations that might be associated with a Purchases endpoint:

Create Purchase

This is a POST request used to initiate a new purchase. In the request body, you would usually provide information such as the user's email, the items being purchased (with their quantities and per-item cost), a description, and possibly URLs for redirection in the event of successful confirmation or failure of the transaction. On successful creation, the API will return a response containing the details of the newly created purchase, including a unique ID.

Get Purchase Detail

A GET request used to fetch the details of a specific purchase. By supplying the unique ID of the purchase, you can retrieve all associated details, such as its status, the items purchased, the total amount, and the buyer's information.

Checkout Operation

Once a purchase has been created, it generally needs to be checked out to complete the transaction. This is done by using the endpoint /checkout that returns a page where a user can access the purchase.

Possible statuses

The Payouts endpoint of the Payments API is intended to manage all operations related to payouts - from creation, through the commitment of a payout, to fetching payout details. Payouts refer to the payments made to recipient user's Airtm accounts. Our payouts creation process follows an asynchronous process.

Here's a breakdown of typical operations associated with a Payouts endpoint:

Create payout

This is a POST request that is used to create a new payout instruction. In the request body, information about the payout such as the recipient's email, description of the payout, the 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 instruction, including a unique ID.

Commit payout

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 also typically return a response containing details of the payout, including its status (which should now reflect that it has been committed).

One-step payout

This endpoint is a combination of the Create Payout and the Commit Payout endpoints. If you want to do a payout in just one API call instead of a two-step process outlined in Create / Commit Payout, you can now use this one-step endpoint.

The usage is exactly the same as the Create payout endpoint at POST /payouts with the only difference being that the second step (commit payout) will immediately be executed and there is no need to make a call to the commit endpoint.

Get Payout Event

This endpoint populates whenever either a Success URI or Failure URI are called; this information helps track the status and whatever is happening with the committed Payout.

Possible Statuses

The Operations endpoint contains all the transactions related to movements between Airtm accounts. Purchases, Pay-ins, Payouts, and Payments all fall under the category of Operations. To get all information on any Purchase, Pay-in, Payout, or Payment, you need to call the Operations endpoint.

An operation is an abstraction of the more specific entities: purchase and payout. Operations are used when referring to all of the transactions within an account. This schema also applies to the other responses under /operations.

This endpoint will return an operation corresponding to the specified ID. Fields may differ depending on operation_type field, which can be purchase or payout.

For payout operations, the status included in the response can be either committed or completed depending on wether the payout execution has finished or still being carried out. Committed status will eventually move to completed. Completed payouts will populate the airtm_operation_hash related to the completed transaction

This endpoint is used to issue bulk payments (payouts) to be processed in a single request.

New Bulk Payment

The endpoint to create the bulk payment. You'll receive a response with the id of the bulk payment, and the processing will start asynchronously after you receive the response. You can check in with the progress of your ongoing bulk payment with any of the endpoints described further down this section.

Bulk Payments Details

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 been processed yet. Once that has happened, the status will switch to DONE.

Failed Payments

This endpoint allows you to see the parts of your bulk payment that could not be processed. There is no way to re-start them other than to create a new bulk payment. There may be unlikely occurrences where some errors may not be clear or only contain an error code. Please reach out to support@airtm.com, we are eager to improve the API or explain why a payment cannot be processed.

Bulk Payments History

Endpoint to receive all bulk payments associated with your account.

Bulk Payments by ID

This endpoint will get the status of all payments in an existing bulk payment. This will allow you to find out which payments succeeded, which are still pending, or which may have failed.

Cancel pending Payments

This endpoint enables users to 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. Once canceled, funds are automatically restituted to user's Airtm balance, and individual payout status are updated to canceled.

For bulk payments

For individual payments within the bulk payments

Keep in mind individual payment items inside a bulk payment can have different statuses.

Retrieve the current status of any user's account by providing their email. The endpoint It is primarily used to verify the account’s ability to receive payments before initiating a transaction. Additionally, it offers a tool for identity validation, ensuring that the registered full name of the account holder matches the records of the API user, helping to minimize payment errors

Parameters