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.

Was this section helpful?

What made this section unhelpful for you?

Endpoints

GET
GET
Was this section helpful?

What made this section unhelpful for you?

List operations

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.

Header Parameters

Content-Typestring Required
Authorizationstring Required

Body Parameters

pagenumber

The page number requested.

Default value
1
perPagenumber

The number of operations to return in each request. Default: 10.

Default value
10
typestring

Filter just for a specific payment type. May be payout or purchase.

Response

200
Object
OK

Response Attributes

currentPagenumber

Page currently displayed.

lastPagenumber

Number of pages available.

perPagenumber

Number of items per page displayed in the response.

totalnumber

Total operations retrieved.

fromnumber

Number of first operation retrieved.

tonumber

Number of last operation retrieved.

dataarray

An array of items retrieved, contains all operations available requested, limited by the 'perPage' parameter.

Show child attributes

403
Object
Forbidden
500
Object
Internal Server Error

Response Attributes

statusnumber
messagestring
Was this section helpful?

What made this section unhelpful for you?

GET

/operations

Select
1 2 3 4 5 6 7 8 curl --location --request GET 'https://payments.air-pay.io/operations' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic {your_token}' \ --data '{ "page": null, "perPage": null, "type": "" }'

Response

{
  "currentPage": 1,
  "lastPage": 5,
  "perPage": 10,
  "total": 25,
  "from": 1,
  "to": 10,
  "data": [
    {
      "id": "5c55efac-2e10-4511-918b-8a27271c074e",
      "status": "PENDING",
      "amount": "1.00",
      "description": "Payout test",
      "confirmation_uri": "https://your.site/confirm",
      "cancel_uri": "https://your.site/cancel",
      "code": "ExternalIdentifier01",
      "airtm_operation_id": "1e1042ac-acae-4e7f-91ae-6d4589f8ac9c",
      "created_at": "2022-05-25T00:34:30.641Z",
      "updated_at": "2022-05-25T00:34:30.641Z",
      "airtm_user_id": "3c4ca4b7-36d4-4d05-bb86-12512644c901",
      "airtm_user_email": "john.doe@gmail.com",
      "operation_type": "payout",
      "failure_uri": "http://your.site/payout/failure",
      "failure_reason": "",
      "callback_uri": "https://your.site/callback",
      "airtm_operation_hash": "ACAEBV4E7FNE91AE"
    },
    {
      "id": "57f384ac-c5f7-492a-aaf7-daa928de9b40",
      "partner_id": "2abf29df-4c6d-4de4-ae55-d26556ac5475",
      "status": "created",
      "amount": "1.00",
      "description": "Payout test",
      "confirmation_uri": "https://your.site/success",
      "cancel_uri": "",
      "failure_uri": "https://your.site/failure",
      "failure_reason": "",
      "callback_uri": "",
      "code": "",
      "airtm_operation_id": "",
      "created_at": "2019-03-05T18:48:07.000Z",
      "updated_at": "2019-03-05T18:48:07.000Z",
      "airtm_user_email": "john.doe@gmail.com",
      "airtm_user_id": "d2f17c25-4aa2-46c2-aecb-498ffdd23aa2",
      "operation_type": "payout",
      "airtm_operation_hash": ""
    }
  ]
}
Was this section helpful?

What made this section unhelpful for you?

Get operation detail

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

Header Parameters

Content-Typestring Required
Authorizationstring Required

Path Parameters

operationIdstring

Response

200
Object
OK

Response Attributes

idstring

Unique identifier automatically generated on operation creation.

partner_idstring

ID of the partner who created and committed the operation.

statusstring

The status of the operation. Please refer to the Purchases and Payments endpoints to see possible statuses.

amountstring

Amount in USD that was transacted in the operation.

descriptionstring

Description of the operation, inputted in the creation.

confirmation_uristring

An endpoint / webhook on your server which we will POST the payout JSON to when the payout is successfully completed.

cancel_uristring

An endpoint / webhook on your servers which we will POST the payout JSON to when the payout has been canceled.

codestring

An arbitrary string of the partner’s choosing. Used to identify and correlate Airtm purchases with partner records. Must be unique.

airtm_operation_idstring

Unique identifier for the payout operation within the Airtm system.

created_atstring

Datetime of operation creation.

updated_atstring

Datetime of latest change in the operation.

airtm_user_idstring

The ID of the user involved in the payout/purchase.

airtm_user_emailstring

The email of the user involved in the payout/purchase in Airtm.

operation_typestring

Type of operation, can be 'purchase' or 'payout'.

failure_uristring

An available URL on partner's servers to POST when payout fails.

failure_reasonstring

This populates with the reason the operation failed.

callback_uristring

An endpoint / webhook on your server which we will POST the purchase JSON to when the purchase is completed.

airtm_operation_hashstring

Unique hash for the payout operation within the Airtm system.

404
Object
Not Found

Response Attributes

dataobject
codestring
messagestring
displayToUserboolean
422
Object
Unprocessable Entity

Response Attributes

messagestring
messagesobject

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

GET

/operations/{operationId}

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

Response

{
  "id": "5c55efac-2e10-4511-918b-8a27271c074e",
  "partner_id": "2c3e7d5e-0cfb-411f-9e34-78ba4d3b8ce7",
  "status": "COMPLETED",
  "amount": "1.00",
  "description": "Payout test",
  "confirmation_uri": "http://your.site/payout/success",
  "cancel_uri": null,
  "code": null,
  "airtm_operation_id": "1e1042ac-acae-4e7f-91ae-6d4589f8ac9c",
  "created_at": "2023-06-13T23:37:53.471Z",
  "updated_at": "2023-06-13T23:40:09.569Z",
  "airtm_user_id": "3c4ca4b7-36d4-4d05-bb86-12512644c901",
  "airtm_user_email": "john.doe@gmail.com",
  "operation_type": "payout",
  "failure_uri": "http://your.site/payout/failure",
  "failure_reason": null,
  "callback_uri": null,
  "airtm_operation_hash": "ACAEBV4E7FNE91AE"
}
Was this section helpful?

What made this section unhelpful for you?

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.

Endpoints

POST
GET
GET
GET
GET
POST

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