Airtm

Introduction

Authentication

Hosts, Servers, and Ports

Rate Limit

Headers

Purchases / Payins

Create purchase

Get purchase

Refund Purchase

Payments / Payouts

Create payout

Commit payout

One step payout

Get payout event

Cancel pending payouts

Operations

List operations

Get operation detail

Partner

My balance

Bulk Payments

New bulk payment

Get bulk payments details

Get failed bulk payments

Get bulk payments history

Get bulk payments by id

Cancel pending payments

Account Status

Get account status

requests

Payments API

Production

Sandbox

<p class="slate-p " >Airtm&apos;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.</p><p class="slate-p " >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.</p><p class="slate-p " ><a href="https://airtm-product.typeform.com/to/YhApfD?typeform-source=www.airtm.com" target="_self">Contact Airtm Partnerships Team</a></p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >Once you have an Airtm Enterprise Account, you can create your API keys in your Settings.</p><p class="slate-p " ><a href="https://app.airtm.com/settings/apps" target="_self"><span style="color:#6C9EEB">Airtm Account Settings</span></a></p></div></div><h3 class="slate-h3 " >Not a programmer?</h3><p class="slate-p " >Try out our <a href="https://docs.airtm.com/api-runner/airtm/payments-api" target="_self">API Explorer </a>to create, test and implement these endpoints without programming knowledge.</p><p class="slate-p " ></p><p class="slate-p " ></p>

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.

to create, test and implement these endpoints without programming knowledge.

Use Airtm's Payments API to programmatically pay and get paid using Airtm. Organizations of all sizes use Airtm to receive payments from their users and distribute payments to employees, contractors, freelancers, and donation recipients around the world.

Airtm Payments API

<h3 class="slate-h3">Basic Auth</h3><p class="slate-p" placeholder="Type / for widgets">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.</p><p class="slate-p" placeholder="Type / for widgets">To compose this header manually, base64 encode a string conforming to the following format:</p><p class="slate-p" placeholder="Type / for widgets"><code class="slate-code">&lt;API Key&gt;:&lt;secret Key&gt;</code> </p><div  data-type="info" style="background-color:#eef1ff;color:#4a59af"><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p" placeholder="Type / for widgets">To encode base64, you can use an online tool like <a href="https://www.base64encode.org/" target="_blank">https://www.base64encode.org</a></p></div></div><p class="slate-p" placeholder="Type / for widgets">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: <code class="slate-code">Authorization: Basic MTIzOmFiYw==</code></p><p class="slate-p" placeholder="Type / for widgets">Most API clients will take care of this encoding automatically if you select Basic Auth.</p><div  data-type="warning" style="background-color:#FFF8E1;color:#f0b800"><div ><svg width="18" height="16" viewBox="0 0 18 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.916637 15.5009C0.791637 15.5009 0.683998 15.4732 0.59372 15.4176C0.503443 15.362 0.430526 15.2857 0.37497 15.1884C0.319415 15.0912 0.288165 14.9905 0.28122 14.8864C0.274276 14.7822 0.305526 14.6745 0.37497 14.5634L8.4583 0.605103C8.52775 0.493991 8.60761 0.41413 8.69789 0.365519C8.78816 0.316908 8.88886 0.292603 8.99997 0.292603C9.11108 0.292603 9.21178 0.316908 9.30205 0.365519C9.39233 0.41413 9.47219 0.493991 9.54164 0.605103L17.625 14.5634C17.6944 14.6745 17.7257 14.7822 17.7187 14.8864C17.7118 14.9905 17.6805 15.0912 17.625 15.1884C17.5694 15.2857 17.4965 15.362 17.4062 15.4176C17.3159 15.4732 17.2083 15.5009 17.0833 15.5009H0.916637ZM1.99997 14.2509H16L8.99997 2.1676L1.99997 14.2509ZM9.0833 13.0634C9.26386 13.0634 9.41316 13.0044 9.53122 12.8864C9.64928 12.7683 9.7083 12.619 9.7083 12.4384C9.7083 12.2579 9.64928 12.1086 9.53122 11.9905C9.41316 11.8725 9.26386 11.8134 9.0833 11.8134C8.90275 11.8134 8.75344 11.8725 8.63539 11.9905C8.51733 12.1086 8.4583 12.2579 8.4583 12.4384C8.4583 12.619 8.51733 12.7683 8.63539 12.8864C8.75344 13.0044 8.90275 13.0634 9.0833 13.0634ZM9.0833 10.7509C9.26386 10.7509 9.41316 10.6919 9.53122 10.5739C9.64928 10.4558 9.7083 10.3065 9.7083 10.1259V6.70927C9.7083 6.52871 9.64928 6.37941 9.53122 6.26135C9.41316 6.1433 9.26386 6.08427 9.0833 6.08427C8.90275 6.08427 8.75344 6.1433 8.63539 6.26135C8.51733 6.37941 8.4583 6.52871 8.4583 6.70927V10.1259C8.4583 10.3065 8.51733 10.4558 8.63539 10.5739C8.75344 10.6919 8.90275 10.7509 9.0833 10.7509Z" fill="#F1C21B"></path></svg></div><div ><p class="slate-p" placeholder="Type / for widgets">You cannot use your Production API keys for the Sandbox environment. Please contact your Airtm representative or <a href="mailto:support@airtm.com" target="_blank">support@airtm.com</a> for Sandbox API keys so that you can safely get familiar with our API before sending real money.</p></div></div><h3 class="slate-h3">Security Considerations</h3><p class="slate-p" placeholder="Type / for widgets">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.</p><p class="slate-p" placeholder="Type / for widgets"></p>

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:

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: 

Most API clients will take care of this encoding automatically if you select Basic Auth.

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.

Learn how to authenticate the Payments API so that you can use it with your organization.

Airtm Payments API - Authentication

<p class="slate-p" placeholder="Type / for widgets">Airtm supports two different environments for developers, a Sandbox environment and the Production environment.</p><table class="slate-table"><colgroup><col style="width:6.090026478375993%"/><col/><col/></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Sandbox</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Production</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Host</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">https://payments.static-stg.tests.airtm.org</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">https://payments.air-pay.io</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Port</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">443</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">443</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><h3 class="slate-h3">Callback IPs</h3><p class="slate-p" placeholder="Type / for widgets">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:</p><table class="slate-table"><colgroup></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Sandbox</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"><strong class="slate-bold">Production</strong></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">3.229.5.186</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">34.223.198.111</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">3.229.158.255</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">34.223.166.175</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">52.72.100.238</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">34.223.169.181</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">18.207.25.189</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">35.155.119.51</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">100.25.93.6</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr><tr class="slate-tr"><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets">44.206.130.250</p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td><td class="slate-td"><div class="slate-TableCellElement-content"><p class="slate-p" placeholder="Type / for widgets"></p></div><div class="slate-TableCellElement-resizableWrapper" contenteditable="false"><div style="position:relative;user-select:auto;width:100%;height:100%;box-sizing:border-box;flex-shrink:0" ><div><div  style="position:absolute;user-select:none;width:10px;height:calc(100% + 12px);top:-12px;cursor:col-resize;right:-5px;z-index:20"></div></div></div><div class="slate-TableCellElement-handle"></div></div><div class="slate-TableCellElement-selectedCell" contenteditable="false"></div></td></tr></tbody></table><p class="slate-p" placeholder="Type / for widgets">

</p>

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

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:

Use our Sandbox and Production environments in your development.

Airtm Payments API - Hosts, Servers, and Ports

<p class="slate-p" placeholder="Type / for widgets">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 <code class="slate-code">429</code> error is returned.</p><div  data-type="info" style="background-color:#eef1ff;color:#4a59af"><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p" placeholder="Type / for widgets">If your use case requires a higher limit, please contact <a href="mailto:partners@airtm.com" target="_blank">partners@airtm.com</a></p></div></div><p class="slate-p" placeholder="Type / for widgets"></p>

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 

<p class="slate-p" placeholder="Type / for widgets">The headers for your POSTs and GETs will always be:</p><ul class="slate-ul"><li class="slate-li"><div style="position:relative"><code class="slate-code">Content-Type: application/json</code></div></li><li class="slate-li"><div style="position:relative"><code class="slate-code">Authorization: Basic {your_token}</code></div></li></ul><div  data-type="info" style="background-color:#eef1ff;color:#4a59af"><div ><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p" placeholder="Type / for widgets">Authorization mentioned above here: <a href="https://app.theneo.io/airtm/payments-api/authentication" target="_blank">https://app.theneo.io/airtm/Payments API/authentication/</a></p></div></div><p class="slate-p" placeholder="Type / for widgets"></p>

The headers for your POSTs and GETs will always be:

<p class="slate-p " >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.</p><p class="slate-p " >Here&apos;s an explanation of typical operations that might be associated with a Purchases endpoint:</p><h3 class="slate-h3 " >Create Purchase</h3><p class="slate-p " >This is a POST request used to initiate a new purchase. In the request body, you would usually provide information such as the user&apos;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.</p><h3 class="slate-h3 " >Get Purchase Detail</h3><p class="slate-p " >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&apos;s information.</p><h3 class="slate-h3 " >Checkout Operation</h3><p class="slate-p " >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. </p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >Use <a href="https://payments.air-pay.io/checkout/{operationId}" target="_self">https://payments.air-pay.io/checkout/{purchaseOperationId}</a> 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&apos;s default browser instead of a web view. This ensures a smoother redirection flow for users accessing our platform from mobile applications.</p></div></div><h3 class="slate-h3 " >Possible statuses</h3><div class="table-container" style="width:100%;min-width:100%"><table class="slate-table" ><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:179px;">Title</div><div style="width:179px;">Description</div><div style="width:0px;">Title</div></div><colgroup ><col style="width:179px"><col style="width:179px"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Status</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Is it final?</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Meaning</strong></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >created</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The purchase was created and is awaiting action from the user.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >confirmed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Purchase has been completed and funds have been transferred.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >canceled</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The user canceled the purchase. No funds were transferred.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >failed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >An unlikely occurrence that something went wrong when we attempted to process the Purchase. Please contact <a href="mailto:support@airtm.com" target="_self">support@airtm.com</a></p></td></div></tr></tbody></table></div><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >We recommend that API implementers perform case-insensitive comparisons when checking statuses.</p></div></div><p class="slate-p " ></p><p class="slate-p " ></p>

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:

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.

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.

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. 

Title

Description

Airtm Payments API - Purchases / Payins

<p class="slate-p " >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&apos;s Airtm accounts. Our payouts creation process follows an asynchronous process. 

Here&apos;s a breakdown of typical operations associated with a Payouts endpoint:</p><h3 class="slate-h3 " >Create payout</h3><p class="slate-p " >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&apos;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.</p><h3 class="slate-h3 " >Commit payout</h3><p class="slate-p " >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).</p><h3 class="slate-h3 " >One-step payout</h3><p class="slate-p " >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. </p><p class="slate-p " >The usage is exactly the same as the <strong class="slate-bold">Create payout</strong> 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.</p><h3 class="slate-h3 " >Get Payout Event</h3><p class="slate-p " >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.</p><h3 class="slate-h3 " >Possible Statuses</h3><div class="table-container" style="width:100%;min-width:100%"><table class="slate-table" style="min-width:100%"><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:179px;">Title</div><div style="width:161px;">Description</div><div style="width:0px;">Title</div></div><colgroup ><col style="width:179px"><col style="width:161px"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Status</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Is it final?</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Meaning</strong></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >created</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The payout instruction have been succesfully created and is awaiting you to call the commit endpoint.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >committed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The payout was committed and is in the process of being executed. </p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >pending</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Funds have been placed in an escrow and are awaiting the recipient to sign up to Airtm in order to receive them.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >completed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The payout has been completed successfully, funds have been credited to the customer&apos;s account.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >canceled</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Payout has been canceled and funds have been returned to your account. (Only applies if the payout was previously pending) </p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >failed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >An unlikely occurrence that something went wrong when we attempted to process the Payout. Please contact <a href="mailto:support@airtm.com" target="_blank"><u class="slate-underline">support@airtm.com</u></a>.</p></td></div></tr></tbody></table></div><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >We recommend that API implementers perform case-insensitive comparisons when checking statuses.</p></div></div><p class="slate-p " ></p><p class="slate-p " ></p>

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:

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.

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).

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. 

 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.

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.

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.

Airtm Payments API - Payments / Payouts

<p class="slate-p" placeholder="Type / for widgets">The Operations endpoint contains all the transactions related to movements between Airtm accounts. <strong class="slate-bold">Purchases, Pay-ins, Payouts, and Payments</strong> 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.</p><p class="slate-p" placeholder="Type / for widgets"></p>

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.

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.

Airtm Payments API - Operations

<p class="slate-p" placeholder="Type / for widgets">The partner endpoint is a simple one, which contains information on the partner using the API.</p>

The partner endpoint is a simple one, which contains information on the partner using the API.

<p class="slate-p " >This endpoint is used to issue bulk payments (payouts) to be processed in a single request.</p><h3 class="slate-h3 " >New Bulk Payment</h3><p class="slate-p " >The endpoint to create the bulk payment. You&apos;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.</p><h3 class="slate-h3 " >Bulk Payments Details</h3><p class="slate-p " >Endpoint to retrieve the details of an existing bulk payment. The status <code class="slate-code">RUNNING</code> 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 <code class="slate-code">DONE</code>.</p><h3 class="slate-h3 " >Failed Payments</h3><p class="slate-p " >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.</p><h3 class="slate-h3 " >Bulk Payments History</h3><p class="slate-p " >Endpoint to receive all bulk payments associated with your account. </p><h3 class="slate-h3 " >Bulk Payments by ID</h3><p class="slate-p " >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.</p><h3 class="slate-h3 " >Cancel pending Payments </h3><p class="slate-p slate-indent-0" style="0px">This endpoint enables users to cancel specific or all <code class="slate-code">pending</code> individual payouts within a bulk payment. Users can input transaction <code class="slate-code">hash</code> 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&apos;s Airtm balance, and individual payout status are updated to <code class="slate-code">canceled</code>.</p><p class="slate-p " ><strong class="slate-bold">For bulk payments</strong></p><div class="table-container" style="width:100%;min-width:100%"><table class="slate-table" style="min-width:100%"><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:214px;">Title</div><div style="width:197px;">Description</div><div style="width:0px;">Title</div></div><colgroup ><col style="width:214px"><col style="width:197px"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Status</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Is it final?</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Meaning</strong></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >pending</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The bulk payment was received but it has yet to be started</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >running</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Our system is currently processing all the individual payments contained in this bulk payment.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >done</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >This doesn&apos;t mean all payments were completed successfully, it may have guest or failed Payment Items. Tasks with status = <code class="slate-code">DONE</code> mean only that the processing, validations and creation of operations related to that task is completed.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >failed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >An unlikely occurrence that something went wrong when processing one or more individual payments. Please check <a href="https://airtm.bitbucket.io/#failed-payments-by-id" target="_blank">the errors endpoint</a> to know what happened and contact support@airtm.com if necessary.</p></td></div></tr></tbody></table></div><p class="slate-p " ><strong class="slate-bold">For individual payments within the bulk payments</strong></p><p class="slate-p " >Keep in mind individual payment items inside a bulk payment can have different statuses.</p><div class="table-container" style="width:100%;min-width:100%"><table class="slate-table" style="min-width:100%"><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:213px;">Title</div><div style="width:205px;">Description</div><div style="width:0px;">Title</div></div><colgroup ><col style="width:213px"><col style="width:205px"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Status</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Is it final?</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Meaning</strong></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >created</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The payment has been received and queued and is awaiting its turn to be processed</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >committed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The payment is in the process of being executed.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >pending</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >No</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Funds have been placed in an escrow and are awaiting the recipient to sign up to Airtm in order to receive them.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >completed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The payment has been completed successfully, funds have been credited to the customer&apos;s account.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >canceled</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Payment has been canceled and funds have been returned to your account. (Only applies if the payment was previously pending)</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >failed</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Yes</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Something went wrong when we attempted to process the payment. Please check <a href="https://airtm.bitbucket.io/#failed-payments-by-id" target="_blank">the errors endpoint</a> to know what happened and contact support if necessary.</p></td></div></tr></tbody></table></div><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >We recommend that API implementors perform case-insensitive comparisons when checking statuses.</p></div></div><p class="slate-p " ></p><p class="slate-p " ></p>

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

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.

Endpoint to retrieve the details of an existing bulk payment. The status 

 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 

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.

Endpoint to receive all bulk payments associated with your account. 

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.

This endpoint enables users to cancel specific or all 

 individual payouts within a bulk payment. Users can input transaction 

 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 

For individual payments within the bulk payments

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

Issue bulk payments to be processed in a single request with this endpoint.

Airtm Payments API - Bulk Payments

<p class="slate-p" placeholder="Type / for widgets">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.</p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

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.

Single user information to receive the bulk payment.

Content-Type

Authorization

Unique identifier automatically generated on bulk payment creation.

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

status

payments

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

message

<p class="slate-p" placeholder="Type / for widgets">Endpoint to retrieve the details of an existing bulk payment. The status <code class="slate-code">RUNNING</code> 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 <code class="slate-code">DONE</code>.</p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

 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 

bulkPaymentId

data

code

displayToUser

<p class="slate-p" placeholder="Type / for widgets">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.</p><div  data-type="error" style="background-color:#FFF1F1;color:#ff3030"><div ><svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M9.08366 9.9801C9.25033 9.9801 9.39269 9.92107 9.51074 9.80302C9.6288 9.68496 9.68783 9.53566 9.68783 9.3551V5.31344C9.68783 5.14677 9.62533 5.00441 9.50033 4.88635C9.37533 4.7683 9.22949 4.70927 9.06283 4.70927C8.88227 4.70927 8.73296 4.7683 8.61491 4.88635C8.49685 5.00441 8.43783 5.15371 8.43783 5.33427V9.37594C8.43783 9.5426 8.50033 9.68496 8.62533 9.80302C8.75033 9.92107 8.9031 9.9801 9.08366 9.9801ZM9.00033 13.1676C9.19477 13.1676 9.35796 13.1016 9.48991 12.9697C9.62185 12.8377 9.68783 12.6745 9.68783 12.4801C9.68783 12.2857 9.62185 12.1225 9.48991 11.9905C9.35796 11.8586 9.19477 11.7926 9.00033 11.7926C8.80588 11.7926 8.64269 11.8586 8.51074 11.9905C8.3788 12.1225 8.31283 12.2857 8.31283 12.4801C8.31283 12.6745 8.3788 12.8377 8.51074 12.9697C8.64269 13.1016 8.80588 13.1676 9.00033 13.1676ZM9.00033 17.3343C7.81977 17.3343 6.72255 17.1225 5.70866 16.6989C4.69477 16.2752 3.81283 15.6884 3.06283 14.9384C2.31283 14.1884 1.72602 13.3065 1.30241 12.2926C0.878798 11.2787 0.666992 10.1815 0.666992 9.00094C0.666992 7.83427 0.878798 6.74399 1.30241 5.7301C1.72602 4.71621 2.31283 3.83427 3.06283 3.08427C3.81283 2.33427 4.69477 1.74399 5.70866 1.31344C6.72255 0.88288 7.81977 0.667603 9.00033 0.667603C10.167 0.667603 11.2573 0.88288 12.2712 1.31344C13.285 1.74399 14.167 2.33427 14.917 3.08427C15.667 3.83427 16.2573 4.71621 16.6878 5.7301C17.1184 6.74399 17.3337 7.83427 17.3337 9.00094C17.3337 10.1815 17.1184 11.2787 16.6878 12.2926C16.2573 13.3065 15.667 14.1884 14.917 14.9384C14.167 15.6884 13.285 16.2752 12.2712 16.6989C11.2573 17.1225 10.167 17.3343 9.00033 17.3343ZM9.00033 16.0843C10.9448 16.0843 12.6114 15.3898 14.0003 14.0009C15.3892 12.612 16.0837 10.9454 16.0837 9.00094C16.0837 7.05649 15.3892 5.38982 14.0003 4.00094C12.6114 2.61205 10.9448 1.9176 9.00033 1.9176C7.05588 1.9176 5.38921 2.61205 4.00033 4.00094C2.61144 5.38982 1.91699 7.05649 1.91699 9.00094C1.91699 10.9454 2.61144 12.612 4.00033 14.0009C5.38921 15.3898 7.05588 16.0843 9.00033 16.0843Z" fill="#E90005"></path></svg></div><div ><p class="slate-p" placeholder="Type / for widgets">There is no way of restarting a failed payment. You must post a new bulk payment or contact support.</p></div></div><p class="slate-p" placeholder="Type / for widgets">This endpoint is paginated, so make sure to &quot;flip through the pages&quot; via the query parameter &quot;page&quot; if you need to get all the information.</p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

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.

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.

Accept

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

count

Number of pages with all the individual payments.

pages

currentPage

This is the response when no errors were found.

Status of the payments displayed. Always FAILED.

<p class="slate-p" placeholder="Type / for widgets">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 &quot;flip through the pages&quot; via the query parameter &quot;page&quot; if you need to get all the information.</p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

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.

Page number to get bulk payments information from.

page

Array of bulk payments that were created by the partner.

bulk_payments

Number of pages with bulk payment information.

Current page that the partner is exploring.

<p class="slate-p" placeholder="Type / for widgets">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 &quot;flip through the pages&quot; via the query parameter &quot;page&quot; if you need to get all the information.</p><p class="slate-p" placeholder="Type / for widgets"></p><p class="slate-p" placeholder="Type / for widgets"></p>

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.

sort

<p class="slate-p slate-indent-0" style="0px">This endpoint enables users to cancel specific or all <code class="slate-code">pending</code> individual payouts within a bulk payment. Users can input transaction <code class="slate-code">hash</code> 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&apos;s Airtm balance, and individual payout status are updated to <code class="slate-code">canceled</code>.</p><div class="slate-div"></div><div class="slate-div"></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

paymentItems

successful

Description on standard bulk payment ID format.

messages

<p class="slate-p slate-indent-0" style="0px">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</p><h3 class="slate-h3 " >Parameters</h3><div class="table-container" style="width:100%;min-width:100%"><table class="slate-table" ><colgroup ><col style="width:0%"><col style="width:4.885786802030457%"><col style="width:0%"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Parameter</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Type</p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Description</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-0" style="0px"><code class="slate-code">country_ID</code></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">string</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Returns a 3-letter string with the ISO alpha-3 code of the country where the user's ID was issued.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-0" style="0px"><code class="slate-code">isPrimary</code></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">boolean</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Indicates whether the email provided in the header corresponds to the user's primary email. Possible values: <code class="slate-code">true</code> or <code class="slate-code">false</code>.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-0" style="0px"><code class="slate-code">status</code></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">string</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Returns the user's account status. Possible values: <code class="slate-code">active</code> or <code class="slate-code">inactive</code>. - <strong class="slate-bold">Active</strong>: The account is active and ready to receive funds. - <strong class="slate-bold">Inactive</strong>: 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.</p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p slate-indent-0" style="0px"><code class="slate-code">is_verified</code></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">boolean</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Indicates whether the user has been verified. Returns <code class="slate-code">true</code> if the user is "Verified" or "Enhanced Verified", and <code class="slate-code">false</code> if the user is "Unverified". 
<em class="slate-italic">*For more information regarding existingverifaction status please contact support@airtm.com</em></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><code class="slate-code">fullName</code></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">string</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >Returns the full name of the user as registered in Airtm. This allows API users to validate recipient name before processing payments.</p></td></div></tr></tbody></table></div><p class="slate-p " ></p><p class="slate-p " ></p>

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

Sections