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

Once you have an Airtm Enterprise Account, you can create your API keys in your Settings.

Airtm Account Settings

Not a programmer?

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

Was this section helpful?

What made this section unhelpful for you?

Language Box

Was this section helpful?

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.

Was this section helpful?

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

Was this section helpful?

What made this section unhelpful for you?

Base URL

Production:

https://payments.air-pay.io

Sandbox:

https://payments.static-stg.tests.airtm.org

Was this section helpful?

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

Was this section helpful?

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}

Was this section helpful?

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.

Use https://payments.air-pay.io/checkout/{purchaseOperationId} to redirect your users to the Purchase. The user will need to login to Airtm to complete the Purchase.

For mobile apps we recommend configure the provided redirection link to open in the device's default browser instead of a web view. This ensures a smoother redirection flow for users accessing our platform from mobile applications.

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

We recommend that API implementers perform case-insensitive comparisons when checking statuses.

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.

We recommend that API implementers perform case-insensitive comparisons when checking statuses.

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 = DONE mean only that the processing, validations and creation of operations related to that task is completed.

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.

We recommend that API implementors perform case-insensitive comparisons when checking statuses.

Was this section helpful?

What made this section unhelpful for you?

Endpoints

POST
GET
GET
GET
GET
POST
Was this section helpful?

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

Content-Typestring
Authorizationstring

Body Parameters

receiver_emailstring (email)

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.

amountnumber (float)

The amount of money you want to send down to two decimals.

currencystring

A string representing the currency you want to send in (Currently we only support 'USD', any other currency will be rejected)

notestring Required

A string that will be added as a note to your transaction for the recipient to see.

internal_notestring Required

An internal note for yourself, like a comment or a system number for your internal software.

Response

200
Object
OK

Response Attributes

idstring (uuid)

Unique identifier automatically generated on bulk payment creation.

statusstring

Status of the bulk payment, please check the Possible Statuses section in this endpoint's summary.

paymentsobject

Show child attributes

500
Object
Not enough balance

Response Attributes

messagestring

Description about how much more USD the partner needs to fulfill the payment.

500
Object
Invalid account status

Response Attributes

messagestring
Was this section helpful?

What made this section unhelpful for you?

POST

/bulk-payments

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 curl --location 'https://payments.air-pay.io/bulk-payments' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic {your_token}' \ --data-raw '[ { "receiver_email": "patrick@airtm.io", "amount": 10, "currency": "USD", "note": "salary", "internal_note": "system number 12345-235" }, { "receiver_email": "master@airtm.io", "amount": 10, "currency": "USD", "note": "salary", "internal_note": "system number 45113-231" } ]'

Response

{
  "id": "938ab3e6-a8f7-4995-bb23-a09703fc3289",
  "status": "RUNNING",
  "payments": {
    "count": 2
  }
}
Was this section helpful?

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

Content-Typestring
Authorizationstring

Path Parameters

bulkPaymentIdstring

Response

200
Object
OK

Response Attributes

idstring

ID

statusstring

Status of the bulk payment, please check the Possible Statuses section in this endpoint's summary.

paymentsobject

Show child attributes

404
Object
Not Found

Response Attributes

dataobject
codestring
messagestring
displayToUserboolean
Was this section helpful?

What made this section unhelpful for you?

GET

/bulk-payments/{bulkPaymentId}

Select
1 2 3 curl --location --globoff 'https://payments.air-pay.io/bulk-payments/{bulkPaymentId}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic {your_token}'

Response

{
  "id": "2fa2b192-e140-4b69-b842-db4a4ef63063",
  "status": "DONE",
  "payments": {
    "count": 2,
    "pending": 1
  }
}
Was this section helpful?

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

Acceptstring
Authorizationstring

Path Parameters

bulkPaymentIdstring

Response

200 - Failed payments
Object
OK

Response Attributes

paymentsarray

Response if some payments failed, divided in individual payments to users.

Show child attributes

countnumber

Number of failed payments found.

pagesnumber

Number of pages with all the individual payments.

currentPagenumber

Current page that the information is in.

200 - No failed payments
Object
OK

Response Attributes

paymentsarray

This is the response when no errors were found.

countnumber

Number of failed payments found.

pagesnumber

Number of pages.

currentPagenumber

Current page that the information is in.

statusstring

Status of the payments displayed. Always FAILED.

404
Object
Not found

Response Attributes

dataobject
codestring
messagestring
displayToUserboolean
Was this section helpful?

What made this section unhelpful for you?

GET

/bulk-payments/{bulkPaymentId}/errors

Select
1 2 3 curl --location --globoff 'https://payments.air-pay.io/bulk-payments/{bulkPaymentId}/errors' \ --header 'Accept: application/json' \ --header 'Authorization: Basic {your_token}' \

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
}
Was this section helpful?

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

Acceptstring
Authorizationstring

Query Parameters

pagestring

Page number to get bulk payments information from.

Response

200
Object
OK

Response Attributes

bulk_paymentsarray

Array of bulk payments that were created by the partner.

Show child attributes

countnumber

Number of bulk payments found.

pagesnumber

Number of pages with bulk payment information.

currentPagenumber

Current page that the partner is exploring.

Was this section helpful?

What made this section unhelpful for you?

GET

/bulk-payments?page=1

Select
1 2 3 curl --location 'https://payments.air-pay.io/bulk-payments?page=1' \ --header 'Accept: application/json' \ --header 'Authorization: Basic {your_token}' \

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
}
Was this section helpful?

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

Acceptstring
Authorizationstring

Query Parameters

pagestring
sortstring

Path Parameters

bulkPaymentIdstring

ID of the bulk payment to look into.

Response

200
Object
OK

Response Attributes

paymentsarray

Show child attributes

countnumber

Number of individual payments found.

pagesnumber

Number of pages with all the individual payments.

currentPagenumber

Current page that the partner is exploring.

Was this section helpful?

What made this section unhelpful for you?

GET

/bulk-payments/{bulkPaymentId}/payments?page=1&sort=desc:amount,asc:internal_note

Select
1 2 3 curl --location --globoff 'https://payments.air-pay.io/bulk-payments/{bulkPaymentId}/payments?page=1&sort=desc%3Aamount%2Casc%3Ainternal_note' \ --header 'Accept: application/json' \ --header 'Authorization: Basic {your_token}' \

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
}
Was this section helpful?

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

Content-Typestring
Authorizationstring

Path Parameters

bulkPaymentIdstring

Body Parameters

paymentItemsarray

Show child attributes

Response

200
Object
OK

Response Attributes

successfularray

Show child attributes

422
Object
Bulk Payment ID not valid

Response Attributes

messagestring

Description on standard bulk payment ID format.

messagesobject

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

POST

/bulk-payments/{bulkPaymentId}/payments/cancel

Select
1 2 3 4 5 6 7 8 9 10 curl --location --globoff 'https://payments.air-pay.io/bulk-payments/{bulkPaymentId}/payments/cancel' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic {your_token}' \ --data '{ "paymentItems": [ { "airtm_operation_hash": "CADBEW460EXAMPLE" } ] }'

Response

{
  "successful": [
    "CADBEW460EXAMPLE"
  ]
}
Was this section helpful?

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

country_ID

string

Returns a 3-letter string with the ISO alpha-3 code of the country where the user's ID was issued.

isPrimary

boolean

Indicates whether the email provided in the header corresponds to the user's primary email. Possible values: true or false.

status

string

Returns the user's account status. Possible values: active or inactive. - Active: The account is active and ready to receive funds. - Inactive: The email not yet associated with an Airtm account or is associated with an Airtm account that has not completed signup, or is associated with an Airtm account that is not currently able to receive funds.

is_verified

boolean

Indicates whether the user has been verified. Returns true if the user is "Verified" or "Enhanced Verified", and false if the user is "Unverified". *For more information regarding existingverifaction status please contact support@airtm.com

fullName

string

Returns the full name of the user as registered in Airtm. This allows API users to validate recipient name before processing payments.

Endpoints

GET