Introduction
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.
What made this section unhelpful for you?
What made this section unhelpful for you?
Authentication
Basic Auth
Every request to the Airtm Payments API must present proper authentication credentials in order to identify the partner making the request. To authenticate, you must transmit an HTTP Basic Authorization header where the username is the partner ID, and the password is the partner secret.
To compose this header manually, base64 encode a string conforming to the following format:
<API Key>:<secret Key>
To encode base64, you can use an online tool like https://www.base64encode.org
For example, a Partner with an ID of “123,” and who has been provisioned a secret of “abc” will base64 encode the string “123:abc” and transmit the following header: Authorization: Basic MTIzOmFiYw==
Most API clients will take care of this encoding automatically if you select Basic Auth.
You cannot use your Production API keys for the Sandbox environment. Please contact your Airtm representative or support@airtm.com for Sandbox API keys so that you can safely get familiar with our API before sending real money.
Security Considerations
Partners should be careful to only store credentials and connect to Airtm from secured and private servers. Partners should not share their access credentials with anyone. Partners should not connect to Airtm directly from a client, as this would expose their access credentials to the public, and put their account at risk.
What made this section unhelpful for you?
Hosts, Servers, and Ports
Airtm supports two different environments for developers, a Sandbox environment and the Production environment.
Sandbox | Production | |
Host | https://payments.static-stg.tests.airtm.org | https://payments.air-pay.io |
Port | 443 | 443 |
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:
Sandbox | Production |
3.229.5.186 | 34.223.198.111 |
3.229.158.255 | 34.223.166.175 |
52.72.100.238 | 34.223.169.181 |
18.207.25.189 | 35.155.119.51 |
100.25.93.6 | |
44.206.130.250 |
What made this section unhelpful for you?
Base URL
Production:
https://payments.air-pay.io
Sandbox:
https://payments.static-stg.tests.airtm.org
What made this section unhelpful for you?
Rate Limit
Airtm imposes a rate limit for each Partner. This limit is measured by requests per second. The current rate limit for all Partners is 10 requests/second. In the case that the limit is reached a 429
error is returned.
If your use case requires a higher limit, please contact partners@airtm.com
What made this section unhelpful for you?
Headers
The headers for your POSTs and GETs will always be:
Content-Type: application/json
Authorization: Basic {your_token}
Authorization mentioned above here: https://app.theneo.io/airtm/Payments API/authentication/
What made this section unhelpful for you?
Purchases / Payins
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
Status | Is it final? | Meaning |
created | No | The purchase was created and is awaiting action from the user. |
confirmed | Yes | Purchase has been completed and funds have been transferred. |
canceled | Yes | The user canceled the purchase. No funds were transferred. |
failed | Yes | An unlikely occurrence that something went wrong when we attempted to process the Purchase. Please contact support@airtm.com |
Endpoints
POST
GET
Payments / Payouts
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
Status | Is it final? | Meaning |
created | No | The payout instruction have been succesfully created and is awaiting you to call the commit endpoint. |
committed | No | The payout was committed and is in the process of being executed. |
pending | No | Funds have been placed in an escrow and are awaiting the recipient to sign up to Airtm in order to receive them. |
completed | Yes | The payout has been completed successfully, funds have been credited to the customer's account. |
canceled | Yes | Payout has been canceled and funds have been returned to your account. (Only applies if the payout was previously pending) |
failed | Yes | An unlikely occurrence that something went wrong when we attempted to process the Payout. Please contact support@airtm.com. |
Endpoints
POST
POST
POST
GET
POST
Operations
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.
Endpoints
GET
GET
Partner
The partner endpoint is a simple one, which contains information on the partner using the API.
Bulk Payments
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
Status | Is it final? | Meaning |
pending | No | The bulk payment was received but it has yet to be started |
running | No | Our system is currently processing all the individual payments contained in this bulk payment. |
done | Yes | This doesn't mean all payments were completed successfully, it may have guest or failed Payment Items. Tasks with status = |
failed | Yes | An unlikely occurrence that something went wrong when processing one or more individual payments. Please check the errors endpoint to know what happened and contact support@airtm.com if necessary. |
For individual payments within the bulk payments
Keep in mind individual payment items inside a bulk payment can have different statuses.
Status | Is it final? | Meaning |
created | No | The payment has been received and queued and is awaiting its turn to be processed |
committed | No | The payment is in the process of being executed. |
pending | No | Funds have been placed in an escrow and are awaiting the recipient to sign up to Airtm in order to receive them. |
completed | Yes | The payment has been completed successfully, funds have been credited to the customer's account. |
canceled | Yes | Payment has been canceled and funds have been returned to your account. (Only applies if the payment was previously pending) |
failed | Yes | Something went wrong when we attempted to process the payment. Please check the errors endpoint to know what happened and contact support if necessary. |
What made this section unhelpful for you?
Endpoints
POST
GET
GET
GET
GET
POST
What made this section unhelpful for you?
New bulk payment
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.
Header Parameters
Body Parameters
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.
The amount of money you want to send down to two decimals.
A string representing the currency you want to send in (Currently we only support 'USD', any other currency will be rejected)
A string that will be added as a note to your transaction for the recipient to see.
An internal note for yourself, like a comment or a system number for your internal software.
Response
Response Attributes
Unique identifier automatically generated on bulk payment creation.
Status of the bulk payment, please check the Possible Statuses section in this endpoint's summary.
Show child attributes
Response Attributes
Description about how much more USD the partner needs to fulfill the payment.
Response Attributes
What made this section unhelpful for you?
Response
{
"id": "938ab3e6-a8f7-4995-bb23-a09703fc3289",
"status": "RUNNING",
"payments": {
"count": 2
}
}
What made this section unhelpful for you?
Get 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 processed yet. Once that has happened, the status will switch to DONE
.
Header Parameters
Path Parameters
Response
Response Attributes
ID
Status of the bulk payment, please check the Possible Statuses section in this endpoint's summary.
Show child attributes
Response Attributes
What made this section unhelpful for you?
Response
{
"id": "2fa2b192-e140-4b69-b842-db4a4ef63063",
"status": "DONE",
"payments": {
"count": 2,
"pending": 1
}
}
What made this section unhelpful for you?
Get failed bulk payments
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 support@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.
Header Parameters
Path Parameters
Response
Response Attributes
Response if some payments failed, divided in individual payments to users.
Show child attributes
Number of failed payments found.
Number of pages with all the individual payments.
Current page that the information is in.
Response Attributes
This is the response when no errors were found.
Number of failed payments found.
Number of pages.
Current page that the information is in.
Status of the payments displayed. Always FAILED.
Response Attributes
What made this section unhelpful for you?
Response
{
"payments": [
{
"receiver_email": "cristobal@airtm.io",
"amount": 10,
"currency": "USD",
"note": "salary",
"internal_note": "best",
"status": "FAILED",
"error": "error 052108 - please contact support"
},
{
"receiver_email": "master@airtm.io",
"amount": 10,
"currency": "USD",
"note": "salary",
"internal_note": "best",
"status": "FAILED",
"error": "The second party is not allowed to receive more money"
}
],
"count": 2,
"pages": 1,
"currentPage": 1
}
What made this section unhelpful for you?
Get bulk payments history
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.
Header Parameters
Query Parameters
Page number to get bulk payments information from.
Response
Response Attributes
Array of bulk payments that were created by the partner.
Show child attributes
Number of bulk payments found.
Number of pages with bulk payment information.
Current page that the partner is exploring.
What made this section unhelpful for you?
Response
{
"bulk_payments": [
{
"id": "7fc5b130-e65f-4a19-9073-f3e7bdde1c2a",
"status": "DONE",
"created_at": "2021-06-25T23:22:47.415Z",
"payments": {
"count": 4,
"completed": 4,
"failed": null,
"errored": 2
}
},
{
"id": "16872319-fdf8-42ff-bf1d-6f5d83d0ec63",
"status": "DONE",
"created_at": "2021-06-25T19:53:56.978Z",
"payments": {
"count": 713,
"completed": 713,
"failed": null
}
},
{
"id": "3d2f2c20-0590-4df5-beb7-acaf76339122",
"status": "DONE",
"created_at": "2021-06-25T19:53:44.428Z",
"payments": {
"count": 5,
"completed": 5,
"failed": null
}
},
{
"id": "79146ce5-a16f-47d3-99cb-d7b4d137d629",
"status": "DONE",
"created_at": "2021-06-25T14:43:12.801Z",
"payments": {
"count": 4,
"completed": 2,
"errored": 2
}
},
{
"id": "47b08782-20c1-4c8e-b7a5-1ca0b046af08",
"status": "DONE",
"created_at": "2021-06-25T14:31:24.549Z",
"payments": {
"count": 4,
"completed": 4,
"failed": null
}
}
],
"count": 5,
"pages": 1,
"currentPage": 1
}
What made this section unhelpful for you?
Get bulk payments by id
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.
Header Parameters
Query Parameters
Path Parameters
ID of the bulk payment to look into.
Response
Response Attributes
Show child attributes
Number of individual payments found.
Number of pages with all the individual payments.
Current page that the partner is exploring.
What made this section unhelpful for you?
Response
{
"payments": [
{
"receiver_email": "cristobal@airtm.io",
"airtm_user_id": "95df0c21-c7ae-40b1-a049-04b2a352c996",
"amount": 23,
"currency": "USD",
"note": "salary",
"internal_note": "system number 12345-235",
"status": "COMPLETED",
"hash": "93493N9CNIKWNF"
},
{
"receiver_email": "master@airtm.io",
"airtm_user_id": "e5b6d935-916d-49c6-8347-d9a98331e2c0",
"amount": 10,
"currency": "USD",
"note": "salary",
"internal_note": "system number 45113-231",
"status": "PENDING",
"hash": "6BD5RK4DC3VH835F"
}
],
"count": 2,
"pages": 1,
"currentPage": 1
}
What made this section unhelpful for you?
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
.
Header Parameters
Path Parameters
Body Parameters
Show child attributes
Response
Response Attributes
Show child attributes
Response Attributes
Description on standard bulk payment ID format.
Show child attributes
What made this section unhelpful for you?
Response
{
"successful": [
"CADBEW460EXAMPLE"
]
}
What made this section unhelpful for you?
Account Status
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
Parameter | Type | Description |
| string | Returns a 3-letter string with the ISO alpha-3 code of the country where the user's ID was issued. |
| boolean | Indicates whether the email provided in the header corresponds to the user's primary email. Possible values: |
| string | Returns the user's account status. Possible values: |
| boolean | Indicates whether the user has been verified. Returns |
| string | Returns the full name of the user as registered in Airtm. This allows API users to validate recipient name before processing payments. |