{"openapi":"3.1.0","info":{"title":"Airtm Enterprise API V1","version":"1.0.0","description":"## Introduction\n\nWelcome to Airtm's Enterprise Payments API - a comprehensive solution for programmatic payment processing that enables organizations worldwide to send and receive payments efficiently and securely.\n\n### What is Airtm Enterprise API?\n\nAirtm's Payments API empowers organizations of all sizes to:\n\n- **Receive payments** from users globally\n- **Distribute payments** in bulk or individually\n- **Pay employees, contractors, and freelancers** worldwide\n- **Process donations** and other payment types\n- **Manage cross-border transactions** with ease\n\n### Getting Started\n\nIf you have a business or non-profit and would like to partner with Airtm, please contact our Airtm Partnerships team to set up your Airtm Enterprise Partner account.\n\n**[Contact Airtm Partnerships Team →](https://airtm-product.typeform.com/to/ggXbsJpl?typeform-source=api-docs)**\n\n> [!TIP]\n> Once you have an Airtm Enterprise Account, you can create your API keys in your Account Settings.\n\n**[Airtm Account Settings →](https://app.airtm.com/settings/apps)**\n\n\n---\n\n## Authentication\n\n### Basic Authentication\n\nEvery request to the Airtm Payments API requires proper authentication to identify the partner making the request.\n\n**Authentication Method:** HTTP Basic Authorization\n\n- **Username:** Your Partner ID (API Key)\n- **Password:** Your Partner Secret (Secret Key)\n\n> ⚠️ **Important**: The secret is only shown when the API key is created, and it cannot be retrieved afterwards. Store it securely, or create a new API key if you lose it.\n\n#### Manual Header Composition\n\nTo compose the authorization header manually:\n\n1. Combine your credentials: `<API_Key>:<Secret_Key>`\n2. Base64 encode the string\n3. Add the header: `Authorization: Basic <encoded_string>`\n\n**Example:**\n\n```\nPartner ID: 123\nSecret: abc\nCombined: 123:abc\nBase64 Encoded: MTIzOmFiYw==\nHeader: Authorization: Basic MTIzOmFiYw==\n```\n\n> [!NOTE]\n> Most API clients handle Basic Auth encoding automatically when you select \"Basic Auth\" authentication.\n\n#### Environment-Specific Keys\n\n- **Production API keys** cannot be used in the Sandbox environment\n- **Sandbox API keys** are required for testing and development\n- Contact your Airtm representative or [enterprise@airtm.com](mailto:enterprise@airtm.com) for Sandbox API keys\n\n### Security Best Practices\n\n- ✅ Store credentials securely on private servers only\n- ✅ Use HTTPS for all API communications\n- ✅ Never share access credentials\n- ✅ Implement proper credential rotation policies\n- ❌ Never connect to Airtm directly from client-side applications\n- ❌ Never expose credentials in public repositories or logs\n\n\n---\n\n## API Environments\n\nAirtm provides two environments for development and production use:\n\n| Environment    | Base URL                                      | Purpose                 |\n| -------------- | --------------------------------------------- | ----------------------- |\n| **Sandbox**    | `https://payments.static-stg.tests.airtm.org` | Testing and development |\n| **Production** | `https://api.enterprise.airtm.com`            | Live transactions       |\n\n### Callback IP Addresses\n\nWhen implementing webhooks, whitelist these IP addresses to receive callbacks:\n\n#### Sandbox Environment\n\n- `3.229.5.186`\n- `3.229.158.255`\n- `52.72.100.238`\n- `18.207.25.189`\n- `100.25.93.6`\n- `44.206.130.250`\n\n#### Production Environment\n\n- `34.223.198.111`\n- `34.223.166.175`\n- `34.223.169.181`\n- `35.155.119.51`\n\n\n---\n\n## Request Format\n\n### Required Headers\n\nAll API requests must include these headers:\n\n```http\nContent-Type: application/json\nAuthorization: Basic <your_base64_encoded_credentials>\n```\n\n### Request Example\n\n```http\nPOST /api/v1/payouts\nContent-Type: application/json\nAuthorization: Basic MTIzOmFiYw==\n\n{\n  \"amount\": 100.00,\n  \"currency\": \"USD\",\n  \"recipient\": \"user@example.com\",\n  \"description\": \"Payment for services\"\n}\n```\n\n\n---\n\n## Rate Limits\n\n### Current Limits\n\n- **Rate Limit:** 10 requests per second per partner\n- **Response Code:** `429 Too Many Requests` when limit exceeded\n- **Retry Strategy:** Implement exponential backoff\n\n### Requesting Higher Limits\n\nIf your use case requires higher rate limits, please contact [enterprise@airtm.com](mailto:enterprise@airtm.com) with:\n\n- Current usage patterns\n- Expected request volume\n- Business justification\n\n\n---\n\n## Error Handling\n\n### Standard HTTP Status Codes\n\n| Code  | Status                | Description                   |\n| ----- | --------------------- | ----------------------------- |\n| `200` | OK                    | Request successful            |\n| `201` | Created               | Resource created successfully |\n| `400` | Bad Request           | Invalid request format        |\n| `401` | Unauthorized          | Authentication required       |\n| `403` | Forbidden             | Access denied                 |\n| `404` | Not Found             | Resource not found            |\n| `429` | Too Many Requests     | Rate limit exceeded           |\n| `500` | Internal Server Error | Server error                  |\n\n### Error Response Format\n\n```json\n{\n  \"error\": {\n    \"code\": \"415001\",\n    \"message\": \"Detailed error description\",\n    \"details\": {\n      \"field\": \"specific_field_error\"\n    }\n  }\n}\n```\n\n\n---\n\n## Reason Codes Reference\n\n| Code     | Description                                                                   |\n| -------- | ----------------------------------------------------------------------------- |\n| `415003` | Error reaching external service                                               |\n| `415005` | Payout not found                                                              |\n| `415006` | No API keys configured                                                        |\n| `415008` | Recipient address not active                                                  |\n| `415009` | Recipient address inactive                                                    |\n| `415010` | User deleted or banned                                                        |\n| `415011` | Invalid file upload                                                           |\n| `415012` | Duplicate payouts detected                                                    |\n| `415013` | Bulk payout not in pending status                                             |\n| `415014` | Insufficient balance                                                          |\n| `415015` | Daily limit exceeded ($250,000)                                               |\n| `415016` | Insufficient balance for payout                                               |\n| `415017` | Cannot reject bulk payout                                                     |\n| `415019` | Bulk payout not finished                                                      |\n| `415022` | Must empty balance before account deletion                                    |\n| `415024` | Maximum API keys reached                                                      |\n| `415025` | API key not found                                                             |\n| `415027` | Payout already processed                                                      |\n| `415028` | Enterprise account required                                                   |\n| `415029` | Payin code already exists                                                     |\n| `415030` | Cannot confirm or cancel payin                                                |\n| `415031` | Payin not found                                                               |\n| `415032` | Payin already completed                                                       |\n| `415034` | User insufficient balance                                                     |\n| `415035` | Payout amount too small                                                       |\n| `415036` | No active payment provider                                                    |\n| `415039` | Operation not found                                                           |\n| `415041` | Bulk payout not found                                                         |\n| `415042` | Statement not found                                                           |\n| `415043` | Statement not pending                                                         |\n| `415044` | Statement not completed                                                       |\n| `415045` | Deposit account type exists                                                   |\n| `415046` | Country not supported                                                         |\n| `415047` | Insufficient balance for withdrawal                                           |\n| `415048` | Invalid payment rail                                                          |\n| `415049` | Bridge account not found                                                      |\n| `415050` | Invalid crypto payment rail                                                   |\n| `415051` | Crypto wallet not found                                                       |\n| `415053` | US users cannot make payins                                                   |\n| `415054` | Invalid sort field                                                            |\n| `415055` | Cannot cancel non-pending payout                                              |\n| `415056` | Payout code already exists                                                    |\n| `415057` | Payout exceeds maximum limit                                                  |\n| `415058` | Payout below minimum limit                                                    |\n| `415059` | Recipient not found                                                           |\n| `415060` | Recipient cannot receive payouts                                              |\n| `415061` | Recipient from restricted territory                                           |\n| `415062` | Invalid recipient payment method                                              |\n| `415064` | Invalid recipient payment method                                              |\n| `415065` | User has violated the AML policy                                              |\n| `415073` | The payment provider could not deliver the funds to the user's payment method |\n| `415103` | User is missing required information                                          |\n| `415134` | Recipient missing required endorsement with payment provider                  |\n| `415143` | Crypto address is within its hold period (24 hours by default)                |\n| `415144` | Crypto withdrawals are not enabled at the moment                              |\n| `415912` | Waiting for recipient to create an Airtm account                              |\n| `415901` | Invalid request format                                                        |\n| `415902` | Item not found                                                                |\n| `415903` | Request cannot be processed                                                   |\n| `415904` | Unauthorized request                                                          |\n| `415905` | Insufficient permissions                                                      |\n| `415906` | Invalid request                                                               |\n| `415998` | Unexpected error                                                              |\n| `415999` | Unknown error                                                                 |\n\n\n---\n\n## Next Steps\n\n1. **Set up your account** - Contact partnerships team\n2. **Get API credentials** - Generate keys in your settings\n3. **Test in Sandbox** - Use sandbox environment for development\n4. **Implement authentication** - Set up Basic Auth\n5. **Start with simple operations** - Begin with basic payouts or payins\n6. **Add error handling** - Implement proper error handling\n7. **Go live** - Switch to production environment\n\n## Support\n\nFor technical support, integration questions, or account issues:\n\n- **Email:** [enterprise@airtm.com](mailto:enterprise@airtm.com)\n- **Documentation:** This API documentation\n- **Status Page:** [Monitor API status and uptime](https://status.airtm.com/)\n\n\n---\n\n## Frequently Asked Questions\n\n### API Credentials\n\n#### Generating API Credentials (API Key & Secret)\n\n1. Log in to your Airtm Enterprise account\n2. Go to: **Settings → Payments API**\n3. Generate your credentials\n\n> ⚠️ **Important**: Credentials are displayed only once—store them securely.\n\n#### Key Considerations\n\n- **One credential per account**: Only one API credential can be generated per Enterprise account\n- **Role requirements**: Only users with Owner or Admin roles can access this feature\n\n---\n\n### Getting Started with the API\n\n#### Scope of the Airtm API\n\n✅ **The Airtm API enables:**\n\n- Initiating payments from an Enterprise account to Airtm users\n- Retrieving account balances and transaction history\n- Verifying the status of user accounts\n- Accessing detailed transaction information\n\n❌ **Not supported:**\n\n- P2P functionality\n- Card operations\n- Third-party bulk account creation\n\n#### Supported Regions\n\n🌍 Airtm operates globally, but certain jurisdictions are restricted.\n→ [Check the list of unsupported regions](https://help.airtm.com/en/support/solutions/articles/47001177565-where-are-airtm-s-products-and-services-available-)\n\n#### iFrames & Embedded Pages\n\n🚫 Embedding Airtm pages via iframes is not supported due to security policies.\n\n#### IP Addresses & Whitelisting\n\n🔒 → [Current server IPs are listed here](#description/api-environments)\n\n- Whitelisting Airtm IPs for callbacks is recommended but not mandatory\n\n#### Currency & Payment Methods\n\n- **Currency**: All API operations are denominated in USD (USDC)\n- **Currency conversion**: If needed, it must be handled on the Enterprise side\n- **Supported transactions**: The Airtm API supports transactions only between Airtm accounts\n- **Not supported**: Card, e-wallet, and crypto payments\n- **Exact matching**: The amount and currency must match the API request exactly\n\n---\n\n### Sandbox & Production Environments\n\n#### Sandbox (Testing) Environment\n\n| **Parameter**        | **Value**                                                                 |\n| -------------------- | ------------------------------------------------------------------------- |\n| **Host**             | `https://payments.static-stg.tests.airtm.org`                             |\n| **Enterprise Login** | [Sandbox Portal](https://stg.enterprise.airtm.com)                        |\n| **Documentation**    | [Sandbox Documentation](https://api.stg.enterprise.airtm.com/docs?api=v1) |\n\n##### Available Endpoints:\n\n- **Deposits (Pay-ins)**: `/purchases`\n- **Withdrawals (Payouts)**: `/payouts`\n- **Bulk Payments**: `/bulk-payments`\n\n##### Test Accounts:\n\n- Test accounts can be created manually (at least two are needed — one for initiating and one for receiving transactions)\n- Temporary sandbox accounts can also be requested through the Airtm Onboarding or Account Manager\n- Test funds may be requested from the assigned Airtm manager for use in the sandbox environment\n\n#### Production Environment\n\n| **Parameter**        | **Value**                                                                |\n| -------------------- | ------------------------------------------------------------------------ |\n| **Host**             | `https://payments.air-pay.io`                                            |\n| **Enterprise Login** | [Live Portal](https://enterprise.airtm.com)                              |\n| **Documentation**    | [Production Documentation](https://api.enterprise.airtm.com/docs?api=v1) |\n\n> ⚠️ **Important**: Make sure to switch to `payments.air-pay.io` when going live.\n\n---\n\n### Callbacks & Notifications\n\nAirtm no longer calls URLs that you provide when a transaction changes status. Use **webhooks** to receive status notifications; they are signed, so you can verify that they come from Airtm.\n\n> ⚠️ **Breaking change**: The payout fields `confirmation_uri`, `failure_uri`, `cancel_uri` and `callback_credentials`, and the purchase field `callback_uri`, are not supported anymore. Requests that include them are rejected with a `400` error. Remove them from your requests and subscribe to webhooks instead.\n\nThe `confirmation_uri` and `cancel_uri` fields of a purchase are not callbacks: they are the pages where the user is redirected after confirming or canceling the purchase, and they are still supported.\n\nIf you cannot use webhooks for a particular case, check the status of a transaction with `GET /operations/:id`.\n\n---\n\n### Transaction Statuses and Refunds\n\n#### Transaction Statuses\n\n##### Purchases\n\n| **Status**  | **Final?** | **Description**                                          |\n| ----------- | ---------- | -------------------------------------------------------- |\n| `created`   | No         | Purchase was created and is awaiting user action         |\n| `confirmed` | Yes        | Purchase completed and funds have been transferred       |\n| `canceled`  | Yes        | User canceled the purchase. No funds were transferred    |\n| `failed`    | Yes        | Purchase processing failed. Contact enterprise@airtm.com |\n\n##### Payouts\n\n| **Status**  | **Final?** | **Description**                                                                                                                                                                   |\n| ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `created`   | No         | Payout instruction created. Awaiting call to the commit endpoint                                                                                                                  |\n| `committed` | No         | Payout was committed and is being processed                                                                                                                                       |\n| `pending`   | No         | Funds in escrow, awaiting recipient action:<br/>• New user: create Airtm account<br/>• Over $1,000: ID verification<br/>• US user: ID verification + payment method configuration |\n| `completed` | Yes        | Payout completed. Funds credited to the recipient's account                                                                                                                       |\n| `canceled`  | Yes        | Payout canceled. Funds returned. Applies to pending payouts or when recipient is ineligible to receive funds                                                                      |\n| `failed`    | Yes        | Processing failed. Contact enterprise@airtm.com                                                                                                                                   |\n\n> 💡 **Tip**: Use case-insensitive comparisons when evaluating status strings.\n\n#### Endpoints\n\n- **Purchases & Payouts**: `GET /operations/{operationId}`\n- **Bulk Payments**: `GET /bulk-payments`\n\n#### Refunds via API\n\n❌ Automatic refunds are not supported.\n\n✅ **To issue a refund**:\n\n1. Initiate a payout from your account to the user\n2. More info available in the [Payouts section](https://docs.airtm.com/reference/payouts)\n\n---\n\n### Transaction Fees, Limits & Expirations\n\n#### Fees & Limits\n\n| **Parameter**                  | **Value**                              |\n| ------------------------------ | -------------------------------------- |\n| **Minimum (US & Puerto Rico)** | $1 USDC                                |\n| **Minimum (Other regions)**    | $0.01 USDC                             |\n| **Maximum per transaction**    | No upper limit                         |\n| **Fees**                       | Contact the sales team for exact rates |\n\n#### Processing Times\n\n- **Payouts to existing users**: Up to 2 minutes\n- **Purchases (pay-ins)**: Depends on client interaction. Usually immediate after confirmation\n\n#### Expiration Rules\n\n- **Pay-ins**: Expire after **15 days**\n- **Pay-outs (to unregistered users)**: Pending for up to **90 days**, unless otherwise configured in your Enterprise dashboard: **Settings → Cancel Timer**\n\n---\n\n### Attributes & Validation\n\n#### General Requirements\n\n- Payout requests do not accept `confirmation_uri`, `failure_uri`, `cancel_uri` or `callback_credentials` anymore, use webhooks to receive status notifications\n\n#### For Purchases:\n\n- The `items` array is **mandatory**\n- The `amount` must match the sum of all items. Any discrepancy will result in the request being rejected\n- Customers **cannot retry** deposit attempts. Only a single attempt is permitted per transaction\n- Purchase confirmation **must be done via a web browser**. Airtm apps does not support this flow\n\n---\n\n### Authentication & Security\n\n#### Authorization Header Format\n\nTo generate the Authorization header use the format:\n\n```\nAuthorization: Basic base64(API_KEY:SECRET_KEY)\n```\n\n#### Example\n\nFor API Key `123` and Secret `abc`:\n\n1. **Concatenate**: `123:abc`\n2. **Base64 encode**: `MTIzOmFiYw==`\n3. **Resulting header**: `Authorization: Basic MTIzOmFiYw==`\n\n#### Implementation Example\n\n```bash\n# Using curl\ncurl -H \"Authorization: Basic $(echo -n 'API_KEY:SECRET_KEY' | base64)\" \\\n     https://payments.air-pay.io/api/endpoint\n```\n\n---\n\n> 📞 **Need Help?** Contact [enterprise@airtm.com](mailto:enterprise@airtm.com) for support with API integration or technical issues.\n"},"tags":[{"name":"Purchases / Payins","description":"## Overview\n\nThe Payins endpoint (also known as Purchases) enables your organization to accept payments from users for products, services, or any other transactions. This endpoint is essential for e-commerce platforms, service providers, and any business that needs to collect payments from customers through the Airtm platform.\n\n## What are Payins?\n\nPayins represent incoming payments to your enterprise account. When a user makes a purchase or payment to your organization, it creates a payin operation that can be tracked and managed through this endpoint.\n\n### Key Features\n\n- **Flexible Payment Processing** - Accept payments for various products and services\n- **Multi-Currency Support** - Process payments in different currencies\n- **Real-Time Status Updates** - Track payment progress in real-time\n- **Secure Checkout Process** - Redirect users to secure Airtm payment pages\n- **Webhook Integration** - Receive instant notifications on payment status changes\n- **Reference Code Tracking** - Link payments to your internal order systems\n\n## Payment Flow\n\n1. **Create Purchase** - Your system creates a purchase request with payment details\n2. **User Checkout** - User is redirected to Airtm's secure checkout page\n3. **Authentication** - User logs into their Airtm account to complete payment\n4. **Processing** - Payment is processed and status updates are provided\n5. **Completion** - Payment is completed and funds are transferred to your account\n\n## Status Management\n\n### Purchase Status Values\n\n| Status      | Final? | Description                                       |\n| ----------- | ------ | ------------------------------------------------- |\n| `created`   | No     | Purchase created, awaiting user payment           |\n| `confirmed` | Yes    | Payment completed successfully, funds transferred |\n| `canceled`  | Yes    | User canceled the purchase, no funds transferred  |\n| `failed`    | Yes    | Payment processing failed                         |\n\n> [!TIP]\n> Implement case-insensitive status comparisons in your code to handle potential variations.\n"},{"name":"Payments / Payouts","description":"## Overview\n\nThe Payouts endpoint enables your organization to send payments to recipients worldwide through the Airtm platform. This powerful endpoint supports both individual and bulk payment processing, making it ideal for paying employees, contractors, freelancers, vendors, or any other recipients who have Airtm accounts.\n\n## What are Payouts?\n\nPayouts represent outgoing payments from your enterprise account to recipient users. The payout process is designed to be flexible, secure, and reliable, with multiple options for creating and managing payments based on your specific needs.\n\n### Key Features\n\n- **Two-Step or One-Step Processing** - Choose your preferred workflow\n- **Real-Time Status Tracking** - Monitor payment progress instantly\n- **Comprehensive Recipient Management** - Support for new and existing users\n- **Webhook Integration** - Receive instant status notifications\n\n## Payment Processing Options\n\n### 1. Two-Step Process (Create + Commit)\n\n**Best for:** Careful review and approval workflows\n\n1. **Create Payout** - Generate payout instruction\n2. **Review Details** - Verify recipient and amount information\n3. **Commit Payout** - Execute the payment\n\n### 2. One-Step Process (Direct)\n\n**Best for:** Automated systems and immediate processing\n\n- **Create and Execute** - Single API call processes payment immediately\n- **Streamlined Workflow** - Reduces API calls and complexity\n- **Instant Processing** - Payment begins processing immediately\n\n## Status Management\n\n### Payout Status Values\n\n| Status      | Final? | Description                                                      | Next Actions                |\n| ----------- | ------ | ---------------------------------------------------------------- | --------------------------- |\n| `created`   | No     | Payout instruction created, awaiting commit                      | Call commit endpoint        |\n| `committed` | No     | Payout committed and queued for processing                       | Monitor status updates      |\n| `pending`   | No     | Awaiting recipient action (account creation, verification, etc.) | Wait for recipient action   |\n| `completed` | Yes    | Payment successfully delivered to recipient                      | None - payment complete     |\n| `canceled`  | Yes    | Payout canceled, funds returned to sender                        | None - transaction reversed |\n| `failed`    | Yes    | Payment failed due to processing error                           | Contact support if needed   |\n\n### Detailed Status Descriptions\n\n#### Created Status\n\n- Payout instruction has been successfully created\n- Funds are not yet committed from your account\n- You can still modify or cancel the payout\n- Must call commit endpoint to proceed\n\n#### Committed Status\n\n- Payout has been committed for processing\n- Funds are placed in escrow\n- Processing has begun but not yet completed\n- Cannot be canceled once committed\n\n#### Pending Status\n\nThe payout is waiting for recipient action:\n\n- **New User:** Recipient needs to create an Airtm account\n- **Verification Required:** Recipient exceeds $1,000 threshold and needs ID verification\n- **US Recipients:** Must complete ID verification and configure payment method\n- **Account Issues:** Recipient account may have restrictions\n\nA pending payout can still be canceled before it is processed.\n\n#### Completed Status\n\n- Payment has been successfully processed\n- Funds have been credited to recipient's account\n- Final status - no further action needed\n- Success webhook sent (if configured)\n\n#### Canceled Status\n\n- Payout was canceled before or during processing\n- Funds have been returned to your account\n- Can occur due to:\n  - Manual cancellation\n  - Recipient unable to receive funds\n  - Account restrictions\n  - Compliance issues\n\n#### Failed Status\n\n- Rare occurrence of processing failure\n- Contact [enterprise@airtm.com](mailto:enterprise@airtm.com) for assistance\n- May require manual intervention to resolve\n\n## Recipient Management\n\n### New Recipients\n\nWhen sending to users who don't have Airtm accounts:\n\n1. **Payout Created** - Payment is created with recipient email\n2. **Email Notification** - Recipient receives invitation to join Airtm\n3. **Account Creation** - Recipient creates Airtm account\n4. **Payment Completion** - Funds are automatically credited\n\n### Existing Recipients\n\nFor users with existing Airtm accounts:\n\n- Payments are typically processed faster\n- Fewer verification requirements\n- Direct credit to their account balance\n\n### Recipient Verification Requirements\n\n#### $1,000+ Threshold\n\nRecipients receiving amounts that bring their total inflow over $1,000 must:\n\n- Complete ID verification\n- Provide government-issued identification\n- Verify personal information\n\n#### US Recipients\n\nAll US-based recipients must:\n\n- Complete ID verification regardless of amount\n- Configure a valid payment method\n- Meet additional compliance requirements\n"},{"name":"Operations","description":"## Overview\n\nThe Operations endpoint serves as the central hub for tracking all transaction-related activities within the Airtm Enterprise ecosystem. This comprehensive endpoint consolidates information about **Purchases**, **Pay-ins**, **Payouts**, and **Payments**, providing a unified view of all financial movements between Airtm accounts.\n\n## What are Operations?\n\nOperations represent any transaction that involves the movement of funds within the Airtm platform. Every financial activity generates an operation record that can be tracked and monitored through this endpoint.\n\n### Operation Types\n\n| Type                   | Description                                    | Use Case                                    |\n| ---------------------- | ---------------------------------------------- | ------------------------------------------- |\n| **Purchases / Payins** | Payments made by users for products/services   | E-commerce transactions, service payments   |\n| **Payments / Payouts** | Outgoing payments from your enterprise account | Employee payments, contractor fees, refunds |\n"},{"name":"Partner","description":"## Overview\n\nThe Partner endpoint provides essential information about your Airtm Enterprise account, including account details, configuration settings, balance information, and operational status. This endpoint serves as the central hub for managing your partner account and accessing critical business information.\n\n## What is a Partner Account?\n\nA Partner account is your organization's primary interface with the Airtm Enterprise ecosystem. It represents your business entity within the platform and contains all the necessary information for API operations, financial transactions, and account management.\n"},{"name":"Bulk Payments","description":"## Overview\n\nBulk Payments enable your organization to process multiple payouts simultaneously through a single API operation. This powerful feature is designed for businesses that need to send payments to large numbers of recipients efficiently, such as payroll processing, affiliate commissions, contractor payments, or distribution of rewards and bonuses.\n\n## What are Bulk Payments?\n\nBulk Payments allow you to upload a batch of payout instructions and process them all at once, rather than making individual API calls for each payment. This approach offers significant advantages in terms of efficiency, cost-effectiveness, and operational simplicity.\n\n### Key Features\n\n- **High-Volume Processing** - Handle thousands of payments in a single operation\n- **Asynchronous Processing** - Non-blocking operations that scale with your needs\n- **Real-Time Progress Tracking** - Monitor batch processing status in real-time\n- **Detailed Reporting** - Comprehensive success and failure reporting\n- **Cost Efficiency** - Reduced API calls and processing overhead\n\n### Use Cases\n\n- **Payroll Processing** - Monthly/weekly employee salary payments\n- **Contractor Payments** - Freelancer and contractor compensation\n- **Affiliate Commissions** - Partner and affiliate reward distribution\n- **Prize Distribution** - Contest and promotion prize payments\n- **Supplier Payments** - Vendor and supplier payment processing\n- **Refund Processing** - Bulk customer refund operations\n\n## Bulk Payment Workflow\n\n### 1. Preparation Phase\n\n- Validate recipient information\n- Calculate total amounts and fees\n- Ensure sufficient account balance\n\n### 2. Upload Phase\n\n- Submit bulk payment request\n- Receive batch ID for tracking\n- System validates all entries\n- Initial status: `pending`\n\n### 3. Processing Phase\n\n- Individual payments are processed asynchronously\n- Real-time status updates available\n- Status changes to `running`\n- Progress tracking via API\n\n### 4. Completion Phase\n\n- All payments processed (success or failure)\n- Final status: `done`\n- Detailed reports available\n- Success and failure breakdowns provided\n\n## Status Management\n\n### Bulk Payment Status Values\n\n| Status    | Description                                                | Actions Available                         |\n| --------- | ---------------------------------------------------------- | ----------------------------------------- |\n| `pending` | The bulk payment was received but it has yet to be started | Cancel entire batch                       |\n| `running` | Individual payments being processed                        | Monitor progress, cancel pending payments |\n| `done`    | All payments processed (success or failure)                | View reports, download results            |\n| `failed`  | An error occurred during processing                        | check the errors endpoint                 |\n"},{"name":"Account Status","description":"## Overview\n\nThe Account Status endpoint enables your organization to verify recipient account information before initiating payments. This powerful verification tool helps prevent payment failures, reduces transaction costs, and ensures smooth payment processing by validating recipient details and account capabilities in advance.\n\n## What is Account Status Verification?\n\nAccount Status Verification allows you to check the current status and capabilities of any Airtm user account by providing their email address. This pre-payment verification process helps identify potential issues before processing transactions, improving success rates and reducing operational overhead.\n"}],"servers":[{"url":"https://payments.air-pay.io"},{"url":"https://payments.static-stg.tests.airtm.org"}],"paths":{"purchases":{"post":{"security":[{"basicAuth":[]}],"tags":["Purchases / Payins"],"summary":"Create purchase","description":"This endpoint will allow you to create a Purchase (Pay-in). In order to\ncomplete a Purchase, it must first be created, then the user must be\ndirected to the Airtm website to confirm/checkout the Purchase, at which\ntime they will be redirected to a URL of your choosing. See “Usage”\nbelow.\n\nWe will redirect the user to either `confirmation_uri` or `cancel_uri`\nwith code as query parameter so you can process the Purchase as being\neither confirmed or cancelled.\n\n## Usage\n\n1.  Create a Purchase via an HTTP POST.\n\n2.  Extract the id from the response, and redirect user to:\nhttps://`<API Host>/checkout/:id` User will be redirected for\nauthentication as necessary.\n\n3.  User will confirm or cancel purchase from Airtm’s website.\n\n4.  If confirmed, money will be transferred from user’s Airtm wallet, to\npartner's Airtm wallet, and redirected to the provided\n`confirmation_uri`. If canceled, no money will be transferred, and the\nuser will be redirected to the provided cancel\\_uri.\n\nUpon confirmation, or cancellation the purchase will be considered\ncompleted, and the URL residing at /checkout/:id will no longer\nfunction. Therefore, if you wish to complete an identical Purchase, you\nwill need to create a new Purchase, and be provisioned a new id for that\nPurchase.\n\nThe `confirmation_uri` attribute should not be used for transaction\ncompleteness verification, if the URI was requested, it doesn't mean the\ntransaction was completed successfully. Use webhooks to be notified when\nthe purchase is completed, either if it was confirmed, canceled or\nfailed, or check the transaction status using `GET /operations/:id`\nbefore any external movement.\n\n> [!tip]\n> The way to emit a purchase refund is to create a payout from your Airtm\n> Partner account and then commit it, this will move money from your Airtm\n> account to your user's Airtm account.\n","operationId":"Purchases _ Payins_purchases-payins/create-purchase","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique id of the transaction","example":"5201de5f-03e6-43e1-ba36-bebaf3f429f6","format":"uuid"},"status":{"type":"string","description":"Status of the request, can be 'created', 'processing',\n'canceled' or 'confirmed'.\n","example":"created"},"amount":{"type":"Number","description":"The total amount in USD of the purchase. This value must\ncorrectly correspond to the sum of the amounts associated\nwith each purchase item.\n","example":"15.00","format":"float"},"description":{"type":"string","description":"A text string describing the purchase. This text is\ndisplayed to the user when they are confirming the\ntransaction.\n","example":"Purchase test"},"confirmation_uri":{"type":"string","description":"A URL to redirect the user to when they confirm the\ntransaction.\n","example":"https://your.site/confirm","format":"uri"},"cancel_uri":{"type":"string","description":"A URL to redirect the user to when they cancel the\ntransaction.\n","example":"https://your.site/cancel","format":"uri"},"code":{"type":"string","description":"An arbitrary string of the partner’s choosing. Used to\nidentify and correlate Airtm purchases with partner\nrecords. Must be unique.\n","example":"ExternalIdentifier01"},"airtm_operation_id":{"type":"string","description":"Airtm's internal unique id number for the operation."},"created_at":{"type":"string","description":"Datetime when the transaction was created.","example":"2022-05-25T00:34:30.641Z","format":"date-time"},"updated_at":{"type":"string","description":"Datetime of the latest change in status of the\ntransaction.\n","example":"2022-05-25T00:34:30.641Z","format":"date-time"},"airtm_user_id":{"type":"string","description":"User id of the user that completed one purchase. ","format":"uuid"},"airtm_user_email":{"type":"string","description":"Email of the user that completed one purchase.","format":"email"},"operation_type":{"type":"string","description":"Operation type, always 'purchase'.","example":"purchase"},"failure_uri":{"type":"string","description":"Not used. Airtm does not call this URL, use webhooks to be notified when a purchase fails.\n"},"failure_reason":{"type":"string","description":"This populates with the reason the operation failed."},"callback_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new purchase requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/callback"},"airtm_operation_hash":{"type":"string","description":"Unique hash for the Purchase operation within the Airtm\nsystem.\n"}}}}}},"403":{"description":"Duplicated Code","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"","example":"352014"},"message":{"type":"string","description":"","example":"A purchase with this code already exists"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","description":"","example":500},"message":{"type":"string","description":"","example":"Internal server error"}}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"An arbitrary string of the partner’s choosing. Used to\nidentify and correlate Airtm purchases with partner records.\nMust be unique.\n","example":"ExternalIdentifier01"},"description":{"type":"string","description":"A text string describing the purchase. This text is\ndisplayed to the user when they are confirming the\ntransaction.\n","example":"Test purchase"},"cancel_uri":{"type":"string","description":"A URL to redirect the user to when they cancel the\ntransaction.\n","example":"https://your.site/cancel","format":"uri"},"confirmation_uri":{"type":"string","description":"A URL to redirect the user to when they confirm the\ntransaction.\n","example":"https://your.site/confirm","format":"uri"},"failure_uri":{"type":"string","description":"Not used. Airtm does not call this URL, use webhooks to be notified when a purchase fails.\n","example":"https://your.site/failure","format":"uri"},"amount":{"type":"number","description":"The total amount in USD of the purchase. This value must\ncorrectly correspond to the sum of the amounts associated\nwith each purchase item.\n","example":15},"items":{"type":"array","description":"An array of the items being purchased/bought.","items":{"type":"object","properties":{"description":{"type":"string","description":"","example":"test item 2"},"amount":{"type":"number","description":"","example":3},"quantity":{"type":"number","description":"","example":1}},"required":["quantity"]}}},"required":["code","description","amount","items"]}}}}},"get":{"security":[{"basicAuth":[]}],"tags":["Purchases / Payins"],"summary":"Get purchase","description":"You can either use this endpoint or the /operations with the ‘type’\nparameter as ‘purchase’ in the endpoint to get the list of all\npurchases.\n","operationId":"Purchases _ Payins_purchases-payins/get-purchase","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currentPage":{"type":"number","description":"Page currently displayed.","example":1},"lastPage":{"type":"number","description":"Number of pages available.","example":1},"perPage":{"type":"number","description":"Number of items per page displayed in the response.","example":10},"total":{"type":"number","description":"Total operations retrieved.","example":1},"from":{"type":"number","description":"Number of first operation retrieved.","example":1},"to":{"type":"number","description":"Number of last operation retrieved.","example":1},"data":{"type":"array","description":"An array of items retrieved, contains all operations\navailable requested, limited by the 'perPage' parameter.\n","items":{"type":"object","properties":{"id":{"type":"string","description":"Payment unique identifier.","example":"f782702e-e4fe-46b7-8ef1-de8b70a50587"},"partner_id":{"type":"string","description":"ID of the partner that created the purchase.","example":"2c3e7d5e-0cfb-411f-9e34-78ba4d3b8ce7"},"status":{"type":"string","description":"The status of the operation. Please refer to the\nPurchases and Payments endpoints to see possible\nstatuses.\n","example":"created"},"amount":{"type":"string","description":"Amount in USD that was transacted in the operation.","example":"15.00"},"description":{"type":"string","description":"A text string describing the purchase. This text is\ndisplayed to the user when they are confirming the\ntransaction.\n","example":"Test purchase"},"confirmation_uri":{"type":"string","description":"A URL on partner's servers to redirect the user to when they confirm a purchase. For payouts it is deprecated, Airtm no longer calls it.\n","example":"https://your.site/confirm"},"cancel_uri":{"type":"string","description":"An available URL on partner's servers to redirect\nthe user to when they cancel a purchase.\n","example":"https://your.site/cancel"},"code":{"type":"string","description":"An arbitrary string of the partner’s choosing. Used\nto identify and correlate Airtm purchases with\npartner records. Must be a unique.\n","example":"ExternalIdentifier01"},"airtm_operation_id":{"type":"null","description":"The ID of the operation on Airtm platform.","example":""},"created_at":{"type":"string","description":"The datetime the operation was created.","example":"2023-06-08T15:30:58.887Z"},"updated_at":{"type":"string","description":"The datetime the operation was last modified.","example":"2023-06-08T15:30:58.887Z"},"airtm_user_id":{"type":"null","description":"The ID of the user involved in the payout/purchase","example":""},"airtm_user_email":{"type":"null","description":"The email of the user involved in the\npayout/purchase in Airtm.\n","example":""},"operation_type":{"type":"string","description":"Type of operation, will always be 'purchase'.","example":"purchase"},"failure_uri":{"type":"null","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":""},"failure_reason":{"type":"null","description":"This populates with the reason the operation failed.","example":""},"callback_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new purchase requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/callback"},"airtm_operation_hash":{"type":"null","description":"Unique hash for the payout operation within the\nAirTM system.\n","example":""}},"required":[]}}}}}}},"403":{"description":"Forbidden","content":{"application/html":{"schema":{"type":"object","properties":{"raw":{"type":"String","description":"","example":"<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\">\r\n<HTML><HEAD><META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html; charset=iso-8859-1\">\r\n<TITLE>ERROR: The request could not be satisfied</TITLE>\r\n</HEAD><BODY>\r\n<H1>403 ERROR</H1>\r\n<H2>The request could not be satisfied.</H2>\r\n<HR noshade size=\"1px\">\r\nRequest blocked.\r\nWe can't connect to the server for this app or website at this time. There might be too much traffic or a configuration error. Try again later, or contact the app or website owner.\r\n<BR clear=\"all\">\r\nIf you provide content to customers through CloudFront, you can find steps to troubleshoot and help prevent this error by reviewing the CloudFront documentation.\r\n<BR clear=\"all\">\r\n<HR noshade size=\"1px\">\r\n<PRE>\r\nGenerated by cloudfront (CloudFront)\r\nRequest ID: dXlTEB0QOsMHTVtAcDttXa8VxSYBx9HsPSfzJxHh3lwqgYKy6AQmiw==\r\n</PRE>\r\n<ADDRESS>\r\n</ADDRESS>\r\n</BODY></HTML>"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","description":"","example":500},"message":{"type":"string","description":"","example":"Internal server error"}}}}}}}}},"payouts":{"post":{"security":[{"basicAuth":[]}],"tags":["Payments / Payouts"],"summary":"Create payout","description":"This endpoint allows you to create a payout instruction. In the request\nbody, information about the payout such as the recipient's email,\ndescription, amount, and any URLs needed for confirmation or failure\nredirects should be provided. Upon successful creation, the API returns\na response containing the details of the newly created payout, including\na unique ID.\n\nAfter making a call to this endpoint, no money is moved yet. To finish\nmoving the money to a user you must call the payouts/:id/commit endpoint\nwith the id from this response.\n","operationId":"Payments _ Payouts_payments-payouts/create-payout","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"This is the unique identifier for the payout.","example":"57f384ac-c5f7-492a-aaf7-daa928de9b40","format":"uuid"},"partner_id":{"type":"string","description":"This is the unique identifier of the partner associated\nwith the payout.\n","example":"2abf29df-4c6d-4de4-ae55-d26556ac5475","format":"uuid"},"status":{"type":"string","description":"This field indicates the current status of the payout. For\nexample, \"created\" means the payout has been successfully\ncreated.\n","example":"created"},"amount":{"type":"Number","description":"Amount in USD to be paid out.","example":1},"description":{"type":"string","description":"An arbitrary string describing the payment. This\ninformation is displayed to the recipient. It's\nrecommended that the string summarizes the purpose of the\npayment.\n","example":"Payout test"},"confirmation_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/success"},"cancel_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"http://your.site/payout/cancel"},"failure_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/failure"},"failure_reason":{"type":"string","description":"This field will be populated if the payout fails,\nproviding a reason for the failure.\n"},"callback_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n"},"airtm_operation_id":{"type":"string","description":"Unique identifier for the payout operation within the\nAirtm system.\n"},"created_at":{"type":"string","description":"Timestamp of when the payout was created.","example":"2019-03-05T18:48:07.000Z"},"updated_at":{"type":"string","description":"Timestamp of the last update made to the payout.","example":"2019-03-05T18:48:07.000Z"},"airtm_user_email":{"type":"string","description":"This is the email of the Airtm user who is associated with\nthis payout.\n","example":"john.doe@gmail.com"},"airtm_user_id":{"type":"string","description":"This is the unique identifier for the AirTM user who is\nassociated with this payout.\n","example":"d2f17c25-4aa2-46c2-aecb-498ffdd23aa2"},"operation_type":{"type":"string","description":"This field indicates the type of operation. In this case,\nit's a \"payout\".\n","example":"payout"},"airtm_operation_hash":{"type":"string","description":"Unique hash for the payout operation within the Airtm\nsystem.\n"},"reason_code":{"type":"string","description":"This field will be populated if the payout failed or\ncanceled, providing a code to referenced in the codes\ncatalog.\n","example":""}}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The recipient's email address that is associated with their\nAirtm account\n","example":"john.doe@gmail.com","format":"email"},"description":{"type":"string","description":"An arbitrary string describing the payment. This information\nis displayed to the recipient. It's recommended that the\nstring summarizes the purpose of the payment.\n","example":"Payout test"},"amount":{"type":"number","description":"The payment amount in USD.","example":1},"code":{"type":"string","description":"A unique idempotency key used to prevent duplicate payouts\nfrom being created.\n","example":"1234abcd"}},"required":["email","description","amount"]}}}}}},"payouts/{payoutId}/commit":{"post":{"security":[{"basicAuth":[]}],"tags":["Payments / Payouts"],"summary":"Commit payout","description":"After calling this endpoint, Airtm will execute/process the previously\nreceived payout instruction. The RESPONSE confirms the reception and\nincorporation of the payout instruction for processing. Funds will be\ndeducted from your balance while the payout execution process is being\ncarried out.\n\nPlease note that a 200 response doesn't necessarily mean the money\nmoved, it simply means the system is now trying to send the amount. Use\nwebhooks OR call `/operations/:id` to get an update.\n\nThe status of the payout will either be `committed`, `pending` or\n`failed`, A `committed` status means that the recipient's email has been\nidentified as an active Airtm user and the payout process has\nsuccessfully started. A `pending` status means that the recipient's\nemail does not have an Airtm account. The payout process will be\ncompleted when the user signs up at Airtm. A `committed` payout will\neventually move on to `completed` once the payout execution process\nfinishes. Extra information of the recently `completed` payout can be\nqueried by calling /operations/:id\n","operationId":"Payments _ Payouts_payments-payouts/commit-payout","parameters":[{"name":"payoutId","in":"path","required":false,"schema":{"type":"String","example":"ed7ce4ce-53c2-43f8-aaa8-4afb6cf90cfc","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier automatically generated on payout\ncreation.\n","example":"57f384ac-c5f7-492a-aaf7-daa928de9b40"},"partner_id":{"type":"string","description":"ID of the partner who created and committed the payout.","example":"2abf29df-4c6d-4de4-ae55-d26556ac5475"},"status":{"type":"string","description":"Payout is commited and is the process of being executed","example":"COMMITTED"},"amount":{"type":"string","description":"Amount in USD that was committed.","example":"1.00"},"description":{"type":"string","description":"Description of the payout, inputted in the creation.","example":"Payout test"},"confirmation_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/success"},"cancel_uri":{"type":"String","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":""},"failure_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/failure"},"failure_reason":{"type":"String","description":"This field will be populated if the payout fails,\nproviding a reason for the failure.\n","example":""},"callback_uri":{"type":"String","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":""},"airtm_operation_id":{"type":"string","description":"Unique identifier for the payout operation within the\nAirtm system.\n","example":"a8bc79c2-cde3-4906-b3f5-5af028b3a57e"},"created_at":{"type":"string","description":"Timestamp of when the payout was created.","example":"2019-03-05T18:48:07.000Z"},"updated_at":{"type":"string","description":"Timestamp of the last update made to the payout\ninformation.\n","example":"2019-03-05T18:48:21.000Z"},"airtm_user_email":{"type":"string","description":"This is the email of the Airtm user who is associated with\nthis payout.\n","example":"john.doe@gmail.com"},"airtm_user_id":{"type":"string","description":"This is the unique identifier for the Airtm user who is\nassociated with this payout.\n","example":"d2f17c25-4aa2-46c2-aecb-498ffdd23aa2"},"operation_type":{"type":"string","description":"This field indicates the type of operation. In this case,\nit's a \"payout\".\n","example":"payout"},"code_reason":{"type":"string","description":"This field will be populated if the payout failed or\ncanceled, providing a code to referenced in the codes\ncatalog.\n","example":""}}}}}},"404":{"description":"Payout not found","content":{"application/graphql":{"schema":{"type":"object","properties":{"raw":{"type":"String","description":"","example":"Not Found"}}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}},"payouts/one-step":{"post":{"security":[{"basicAuth":[]}],"tags":["Payments / Payouts"],"summary":"One step payout","description":"This endpoint is a combination of the Create Payout and the Commit\nPayout endpoints. If you want to do a payout in just one API call\ninstead of a two-step process outlined in Create / Commit Payout, you\ncan now use this one-step endpoint.\n\nThe usage is exactly the same as the **Create payout** endpoint at POST\n/payouts with the only difference being that the second step (commit\npayout) will immediately be executed and there is no need to make a call\nto the commit endpoint. The RESPONSE of this endpoint will indicate\nwhether the payout instruction was received and incorporated\nsuccessfully (`committed` / `pending`) or if the creation instruction\nfailed (`failed`). Identically as in the payouts/{payoutId}/commit\nendpoint, the effective result of the executed payout is reported on the\ncallbacks URI\n","operationId":"Payments _ Payouts_payments-payouts/one-step-payout","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier automatically generated on payout\ncreation.\n","example":"57f384ac-c5f7-492a-aaf7-daa928de9b40"},"partner_id":{"type":"string","description":"ID of the partner who created and committed the payout.","example":"2abf29df-4c6d-4de4-ae55-d26556ac5475"},"status":{"type":"string","description":"Payout is commited and is the process of being executed","example":"COMMITTED"},"amount":{"type":"string","description":"Amount in USD that was committed.","example":"1.00"},"description":{"type":"string","description":"Description of the payout, inputted in the creation.","example":"Payout test"},"confirmation_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/success"},"cancel_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"http://your.site/payout/cancel"},"failure_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"https://your.site/failure"},"failure_reason":{"type":"string","description":"This field will be populated if the payout fails,\nproviding a reason for the failure.\n"},"callback_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n"},"airtm_operation_id":{"type":"string","description":"Unique identifier for the payout operation within the\nAirtm system.\n","example":"a8bc79c2-cde3-4906-b3f5-5af028b3a57e"},"created_at":{"type":"string","description":"Timestamp of when the payout was created.","example":"2019-03-05T18:48:07.000Z"},"updated_at":{"type":"string","description":"Timestamp of the last update made to the payout.","example":"2019-03-05T18:48:21.000Z"},"airtm_user_email":{"type":"string","description":"This is the email of the Airtm user who is associated with\nthis payout.\n","example":"john.doe@gmail.com"},"airtm_user_id":{"type":"string","description":"This is the unique identifier for the Airtm user who is\nassociated with this payout.\n","example":"d2f17c25-4aa2-46c2-aecb-498ffdd23aa2"},"operation_type":{"type":"string","description":"This field indicates the type of operation. In this case,\nit's a \"payout\".\n","example":"payout"},"airtm_operation_hash":{"type":"string","description":"Unique hash for the payout operation within the Airtm\nsystem.\n","example":"4AA2FV46C2CDAECB"},"reason_code":{"type":"string","description":"This field will be populated if the payout failed or\ncanceled, providing a code to referenced in the codes\ncatalog.\n","example":""}}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The recipient's email address that is associated with their\nAirtm account.\n","example":"john.doe@gmail.com"},"description":{"type":"string","description":"An arbitrary string describing the payment. This information\nis displayed to the recipient. It's recommended that the\nstring summarizes the purpose of the payment.\n","example":"Payout test"},"amount":{"type":"number","description":"The payment amount in USD.","example":1},"code":{"type":"string","description":"A unique idempotency key used to prevent duplicate payouts\nfrom being created.\n","example":"1234abcd"}},"required":["email","description","amount"]}}}}}},"payouts/events/:payoutId":{"get":{"security":[{"basicAuth":[]}],"tags":["Payments / Payouts"],"summary":"Get payout event","description":"This endpoint populates whenever either a Success URI or Failure URI are\ncalled; this information helps track the status and whatever is\nhappening with the committed Payout.\n","operationId":"Payments _ Payouts_payments-payouts/get-payout-event","parameters":[],"responses":{"200":{"description":"OK - If payout hasn't been committed or ID not found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"","example":{},"properties":{},"required":[]},"code":{"type":"string","description":"","example":"352018"},"message":{"type":"string","description":"","example":"No payout event found for supplied id"},"displayToUser":{"type":"boolean","description":"","example":true}}}}}}}}},"payouts/{payoutId}/cancel":{"post":{"security":[{"basicAuth":[]}],"tags":["Payments / Payouts"],"summary":"Cancel pending payouts","description":"This endpoint allows users to cancel specific `PENDING` individual\npayouts—those that have been created and committed but where the\nrecipient has not yet signed up on Airtm.com.\n\nTo manually cancel a pending payout, users must provide the transaction\n`id`, which can be retrieved when creating the payout through either the\n**Create & Commit** or **One-Step** payout flows. Pending payouts will\nautomatically cancel after 90 days (by default, other time periods are\navilable in dashboard settings) from the creation date.\n\nOnce canceled:\n\n*   Funds are automatically returned to the user's Airtm balance.\n\n*   The individual payout status is updated to `CANCELED`.\n\n*   The response will include all relevant details of the canceled\npayout.\n\nAdditional information about canceled payouts can be accessed through\nthe **Enterprise Portal** (enterprise.airtm.com) or by querying\n[**Operations**](642228876c87a11a975b0c47) .\n\n**Note:** _This feature is only available for partners who have migrated\nto the new infrastructure solution based on Bridge Ventures._\n","operationId":"Payments _ Payouts_payments-payouts/cancel-pending-payments-copy-1","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"String","example":"","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"","example":"5d8950c9-63f6-481f-a2b1-719ebe62ac74"},"amount":{"type":"string","description":"","example":"0.02"},"confirmation_uri":{"type":"string","description":"","example":"http://your.site/payout/success"},"failure_uri":{"type":"string","description":"","example":"http://your.site/payout/failure"},"failure_reason":{"type":"string","description":"","example":""},"airtm_user_id":{"type":"string","description":"","example":"d2f17c25-4aa2-46c2-aecb-498ffdd23aa2"},"airtm_user_email":{"type":"string","description":"","example":"john.doe@gmail.com"},"created_at":{"type":"string","description":"","example":"2024-05-16T15:53:12.016Z"},"updated_at":{"type":"string","description":"","example":"2025-02-17T17:34:39.051Z"},"status":{"type":"string","description":"","example":"CANCELED"},"description":{"type":"string","description":"","example":"Testing"},"airtm_operation_id":{"type":"string","description":"","example":"5d8950c9-63f6-481f-a2b1-719ebe62ac74"},"operation_type":{"type":"string","description":"","example":"payout"},"airtm_operation_hash":{"type":"string","description":"","example":"63F6ZU481FQEA2B1"},"partner_id":{"type":"string","description":"","example":"a78a2be5-cdec-4480-b40c-eb3c33a4f8f2"}}}}}},"400":{"description":"Payout is not in pending status.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"","example":"415055"},"data":{"type":"object","description":"","properties":{"payoutId":{"type":"string","description":"","example":"f1bb7777-814f-497c-b95b-f9177f680f88"}},"required":[]},"displayToUser":{"type":"boolean","description":"","example":false},"message":{"type":"string","description":"","example":"Payout cannot be canceled as it is not in a pending\nstatus.\n"}}}}}},"500":{"description":"Not valid {payoutId} ","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"","example":"invalid input syntax for type uuid: {payoutId}"}}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}},"operations":{"get":{"security":[{"basicAuth":[]}],"tags":["Operations"],"summary":"List operations","description":"An operation is an abstraction of the more specific entities: purchase\nand payout. Operations are used when referring to all of the\ntransactions within an account. This schema also applies to the other\nresponses under `/operations`.\n","operationId":"Operations_operations/list-operations","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currentPage":{"type":"number","description":"Page currently displayed.","example":1},"lastPage":{"type":"number","description":"Number of pages available.","example":5},"perPage":{"type":"number","description":"Number of items per page displayed in the response.","example":10},"total":{"type":"number","description":"Total operations retrieved.","example":25},"from":{"type":"number","description":"Number of first operation retrieved.","example":1},"to":{"type":"number","description":"Number of last operation retrieved.","example":10},"data":{"type":"array","description":"An array of items retrieved, contains all operations\navailable requested, limited by the 'perPage' parameter.\n","items":{"type":"object","properties":{"id":{"type":"string","description":"","example":"57f384ac-c5f7-492a-aaf7-daa928de9b40"},"status":{"type":"string","description":"","example":"created"},"amount":{"type":"string","description":"","example":"1.00"},"description":{"type":"string","description":"","example":"Payout test"},"confirmation_uri":{"type":"string","description":"","example":"https://your.site/success"},"cancel_uri":{"type":"null","description":""},"code":{"type":"null","description":""},"airtm_operation_id":{"type":"null","description":""},"created_at":{"type":"string","description":"","example":"2019-03-05T18:48:07.000Z"},"updated_at":{"type":"string","description":"","example":"2019-03-05T18:48:07.000Z"},"airtm_user_id":{"type":"string","description":"","example":"d2f17c25-4aa2-46c2-aecb-498ffdd23aa2"},"airtm_user_email":{"type":"string","description":"","example":"john.doe@gmail.com"},"operation_type":{"type":"string","description":"","example":"payout"},"failure_uri":{"type":"string","description":"","example":"https://your.site/failure"},"failure_reason":{"type":"null","description":""},"callback_uri":{"type":"null","description":""},"airtm_operation_hash":{"type":"null","description":""},"partner_id":{"type":"string","description":"ID of the partner that created the operation.","example":"2abf29df-4c6d-4de4-ae55-d26556ac5475"}},"required":[]}}}}}}},"403":{"description":"Forbidden","content":{"application/html":{"schema":{"type":"object","properties":{"raw":{"type":"String","description":"","example":"<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\">\r\n<HTML><HEAD><META HTTP-EQUIV=\"Content-Type\" CONTENT=\"text/html; charset=iso-8859-1\">\r\n<TITLE>ERROR: The request could not be satisfied</TITLE>\r\n</HEAD><BODY>\r\n<H1>403 ERROR</H1>\r\n<H2>The request could not be satisfied.</H2>\r\n<HR noshade size=\"1px\">\r\nRequest blocked.\r\nWe can't connect to the server for this app or website at this time. There might be too much traffic or a configuration error. Try again later, or contact the app or website owner.\r\n<BR clear=\"all\">\r\nIf you provide content to customers through CloudFront, you can find steps to troubleshoot and help prevent this error by reviewing the CloudFront documentation.\r\n<BR clear=\"all\">\r\n<HR noshade size=\"1px\">\r\n<PRE>\r\nGenerated by cloudfront (CloudFront)\r\nRequest ID: dXlTEB0QOsMHTVtAcDttXa8VxSYBx9HsPSfzJxHh3lwqgYKy6AQmiw==\r\n</PRE>\r\n<ADDRESS>\r\n</ADDRESS>\r\n</BODY></HTML>"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","description":"","example":500},"message":{"type":"string","description":"","example":"Internal server error"}}}}}}}}},"operations/{operationId}":{"get":{"security":[{"basicAuth":[]}],"tags":["Operations"],"summary":"Get operation detail","description":"This endpoint will return an operation corresponding to the specified\nID. Fields may differ depending on `operation_type` field, which can be\n`purchase` or `payout`. For payout operations, the status included in\nthe response can be either `committed` or `completed` depending on\nwether the payout execution has finished or still being carried out.\nCommitted status will eventually move to completed. Completed payouts\nwill populate the `airtm_operation_hash` related to the completed\ntransaction\n","operationId":"Operations_operations/get-operation-detail","parameters":[{"name":"operationId","in":"path","required":false,"schema":{"type":"String","example":"","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier automatically generated on operation\ncreation.\n","example":"5c55efac-2e10-4511-918b-8a27271c074e"},"partner_id":{"type":"string","description":"ID of the partner who created and committed the operation.","example":"2c3e7d5e-0cfb-411f-9e34-78ba4d3b8ce7"},"status":{"type":"string","description":"The status of the operation. Please refer to the Purchases\nand Payments endpoints to see possible statuses.\n","example":"COMPLETED"},"amount":{"type":"string","description":"Amount in USD that was transacted in the operation.","example":"1.00"},"description":{"type":"string","description":"Description of the operation, inputted in the creation.","example":"Payout test"},"confirmation_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"http://your.site/payout/success"},"cancel_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":""},"code":{"type":"string","description":"An arbitrary string of the partner’s choosing. Used to\nidentify and correlate Airtm purchases with partner\nrecords. Must be unique.\n","example":""},"airtm_operation_id":{"type":"string","description":"Unique identifier for the payout operation within the\nAirtm system.\n","example":"1e1042ac-acae-4e7f-91ae-6d4589f8ac9c"},"created_at":{"type":"string","description":"Datetime of operation creation.","example":"2023-06-13T23:37:53.471Z"},"updated_at":{"type":"string","description":"Datetime of latest change in the operation.","example":"2023-06-13T23:40:09.569Z"},"airtm_user_id":{"type":"string","description":"The ID of the user involved in the payout/purchase.","example":"3c4ca4b7-36d4-4d05-bb86-12512644c901"},"airtm_user_email":{"type":"string","description":"The email of the user involved in the payout/purchase in\nAirtm.\n","example":"john.doe@gmail.com"},"operation_type":{"type":"string","description":"Type of operation, can be 'purchase' or 'payout'.","example":"payout"},"failure_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"http://your.site/payout/failure"},"failure_reason":{"type":"string","description":"This populates with the reason the operation failed.","example":""},"callback_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new purchase requests that include it are rejected. Use webhooks instead.\n","example":""},"airtm_operation_hash":{"type":"string","description":"Unique hash for the payout operation within the Airtm\nsystem.\n","example":"ACAEBV4E7FNE91AE"},"reason_code":{"type":"string","description":"This field will be populated if the payout failed or\ncanceled, providing a code to referenced in the codes\ncatalog.\n","example":""}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"","properties":{},"required":[]},"code":{"type":"string","description":"","example":"352015"},"message":{"type":"string","description":"","example":"Operation not found"},"displayToUser":{"type":"boolean","description":"","example":false}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"","example":"Unprocessable entity"},"messages":{"type":"object","description":"","properties":{"id":{"type":"array","description":"","items":{"type":"string","description":"","example":"id must match the following:\n\"/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/\"\n"}}},"required":[]}}}}}}}}},"code/{code}":{"get":{"security":[{"basicAuth":[]}],"tags":["Operations"],"summary":"Get operation by code","description":"This endpoint will return an operation corresponding to the specified\n`code` used to create a payout.\n","operationId":"Operations_operations/get-operation-by-code","parameters":[{"name":"code","in":"path","required":false,"schema":{"type":"String","example":"","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier automatically generated on operation\ncreation.\n","example":"5c55efac-2e10-4511-918b-8a27271c074e"},"partner_id":{"type":"string","description":"ID of the partner who created and committed the operation.","example":"2c3e7d5e-0cfb-411f-9e34-78ba4d3b8ce7"},"status":{"type":"string","description":"The status of the operation. Please refer to the Purchases\nand Payments endpoints to see possible statuses.\n","example":"COMPLETED"},"amount":{"type":"string","description":"Amount in USD that was transacted in the operation.","example":"1.00"},"description":{"type":"string","description":"Description of the operation, inputted in the creation.","example":"Payout test"},"confirmation_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"http://your.site/payout/success"},"cancel_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":""},"code":{"type":"string","description":"An arbitrary string of the partner’s choosing. Used to\nidentify and correlate Airtm purchases with partner\nrecords. Must be unique.\n","example":""},"airtm_operation_id":{"type":"string","description":"Unique identifier for the payout operation within the\nAirtm system.\n","example":"1e1042ac-acae-4e7f-91ae-6d4589f8ac9c"},"created_at":{"type":"string","description":"Datetime of operation creation.","example":"2023-06-13T23:37:53.471Z"},"updated_at":{"type":"string","description":"Datetime of latest change in the operation.","example":"2023-06-13T23:40:09.569Z"},"airtm_user_id":{"type":"string","description":"The ID of the user involved in the payout/purchase.","example":"3c4ca4b7-36d4-4d05-bb86-12512644c901"},"airtm_user_email":{"type":"string","description":"The email of the user involved in the payout/purchase in\nAirtm.\n","example":"john.doe@gmail.com"},"operation_type":{"type":"string","description":"Type of operation, can be 'purchase' or 'payout'.","example":"payout"},"failure_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new payout requests that include it are rejected. Use webhooks instead.\n","example":"http://your.site/payout/failure"},"failure_reason":{"type":"string","description":"This populates with the reason the operation failed.","example":""},"callback_uri":{"type":"string","description":"Deprecated. Airtm no longer calls this URL, and new purchase requests that include it are rejected. Use webhooks instead.\n","example":""},"airtm_operation_hash":{"type":"string","description":"Unique hash for the payout operation within the Airtm\nsystem.\n","example":"ACAEBV4E7FNE91AE"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"","properties":{},"required":[]},"code":{"type":"string","description":"","example":"352015"},"message":{"type":"string","description":"","example":"Operation not found"},"displayToUser":{"type":"boolean","description":"","example":false}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"","example":"Unprocessable entity"},"messages":{"type":"object","description":"","properties":{"id":{"type":"array","description":"","items":{"type":"string","description":"","example":"id must match the following:\n\"/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/\"\n"}}},"required":[]}}}}}}}}},"partners/me":{"get":{"security":[{"basicAuth":[]}],"tags":["Partner"],"summary":"My balance","description":"## Get partner information\n\nThis endpoint returns information related to your Partner account,\nincluding current balance.\n","operationId":"Partner_partner/my-balance","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email with which the partner signed up for Airtm.","example":"john@acme.com"},"id":{"type":"string","description":"ID of the partner.","example":"53f2349-23r2-523w-ba421-1f23422d42"},"name":{"type":"string","description":"Name of either the Organization of the Partner or the user\nthat created the partner account.\n","example":"John Doe"},"currency":{"type":"string","description":"Currency that the partner has as default for their balance\ndisplay.\n","example":"USD"},"balance":{"type":"number","description":"Amount in currency set as default of funds available in\nthe partner's account.\n","example":1023.45}}}}}}}}},"bulk-payments":{"post":{"security":[{"basicAuth":[]}],"tags":["Bulk Payments"],"summary":"New bulk payment","description":"Create a new bulk payment. You will receive a response with the id of\nyour bulk payment and the processing will start asynchronously after you\nreceive your response. You can check in with the progress of your\nongoing bulk payment with any of the endpoints described further down\nthis section.\n","operationId":"Bulk Payments_bulk-payments/new-bulk-payment","parameters":[{"name":"Content-Type","in":"header","required":false,"schema":{"type":"String","example":"application/json","description":"","default":""},"description":""},{"name":"Authorization","in":"header","required":false,"schema":{"type":"String","example":"Basic {your_token}","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier automatically generated on bulk payment\ncreation.\n","example":"938ab3e6-a8f7-4995-bb23-a09703fc3289","format":"uuid"},"status":{"type":"string","description":"Status of the bulk payment, please check the Possible\nStatuses section in this endpoint's summary.\n","example":"RUNNING"},"payments":{"type":"object","description":"","properties":{"count":{"type":"number","description":"Number of individual payments within the bulk payment.","example":2}},"required":[]}}}}}},"500":{"description":"Invalid account status","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"","example":"sender does not have a valid account status (currently\nBANNED)\n"}}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"0":{"type":"array","description":"Single user information to receive the bulk payment.","items":{"type":"string","description":"User's Airtm email. If user does not have an Airtm account\nwith that email, if succeeded, the funds will move to a\nGUEST account with that email and will be released once\nthe user creates an Airtm account with that email.\n","example":"patrick@airtm.io","format":"email"}},"1":{"type":"object","description":"","properties":{"receiver_email":{"type":"string","description":"","example":"master@airtm.io"},"amount":{"type":"number","description":"","example":10},"currency":{"type":"string","description":"","example":"USD"},"note":{"type":"string","description":"","example":"salary"},"internal_note":{"type":"string","description":"","example":"system number 45113-231"}},"required":[]}}}}}}},"get":{"security":[{"basicAuth":[]}],"tags":["Bulk Payments"],"summary":"Get bulk payments history","description":"Endpoint to get all bulk payments associated with your account. This\nwill give you an overview of all the bulk payments you ever posted. This\nendpoint is paginated, so make sure to \"flip through the pages\" via the\nquery parameter \"page\" if you need to get all the information.\n","operationId":"Bulk Payments_bulk-payments/get-bulk-payments-history","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"String","example":"1","description":"Page number to get bulk payments information from.","default":""},"description":"Page number to get bulk payments information from."},{"name":"Accept","in":"header","required":false,"schema":{"type":"String","example":"application/json","description":"","default":""},"description":""},{"name":"Authorization","in":"header","required":false,"schema":{"type":"String","example":"Basic {your_token}","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"bulk_payments":{"type":"array","description":"Array of bulk payments that were created by the partner.","items":{"type":"object","properties":{"id":{"type":"string","description":"","example":"47b08782-20c1-4c8e-b7a5-1ca0b046af08"},"status":{"type":"string","description":"","example":"DONE"},"created_at":{"type":"string","description":"","example":"2021-06-25T14:31:24.549Z"},"payments":{"type":"object","description":"","properties":{"count":{"type":"number","description":"","example":4},"completed":{"type":"number","description":"","example":4},"failed":{"type":"string","description":"","example":""}},"required":[]}},"required":[]}},"count":{"type":"number","description":"Number of bulk payments found.","example":5},"pages":{"type":"number","description":"Number of pages with bulk payment information.","example":1},"currentPage":{"type":"number","description":"Current page that the partner is exploring.","example":1}}}}}}}}},"bulk-payments/{bulkPaymentId}":{"get":{"security":[{"basicAuth":[]}],"tags":["Bulk Payments"],"summary":"Get bulk payments details","description":"Endpoint to retrieve the details of an existing bulk payment. The status\n`RUNNING` is the default after you have posted your bulk payment. It\nmeans that the individual payments are being processed and not all of\nthem have processed yet. Once that has happened, the status will switch\nto `DONE`.\n","operationId":"Bulk Payments_bulk-payments/get-bulk-payments-details","parameters":[{"name":"bulkPaymentId","in":"path","required":false,"schema":{"type":"String","example":"","description":"","default":""},"description":""},{"name":"Content-Type","in":"header","required":false,"schema":{"type":"String","example":"application/json","description":"","default":""},"description":""},{"name":"Authorization","in":"header","required":false,"schema":{"type":"String","example":"Basic {your_token}","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID","example":"2fa2b192-e140-4b69-b842-db4a4ef63063"},"status":{"type":"string","description":"Status of the bulk payment, please check the Possible\nStatuses section in this endpoint's summary.\n","example":"DONE"},"payments":{"type":"object","description":"","example":{"count":2,"pending":1},"properties":{"count":{"type":"number","description":"Number of individual payments within the bulk payment.","example":2},"pending":{"type":"number","description":"Number of individual payments in the PENDING status.","example":1}},"required":[]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"","properties":{},"required":[]},"code":{"type":"string","description":"","example":"352017"},"message":{"type":"string","description":"","example":"Bulk payment not found"},"displayToUser":{"type":"boolean","description":"","example":false}}}}}}}}},"bulk-payments/{bulkPaymentId}/errors":{"get":{"security":[{"basicAuth":[]}],"tags":["Bulk Payments"],"summary":"Get failed bulk payments","description":"This endpoint allows you to see the parts of your bulk payment that\ncould not be processed. There is no way to restart them other than to\ncreate a new bulk payment. There may be unlikely occurrences where some\nerrors might not be clear or will only contain an error code. Please\nreach out to enterprise@airtm.com, we are eager to improve the API or\nexplain why a payment cannot be processed.\n\nThere is no way of restarting a failed payment. You must post a new bulk\npayment or contact support.\n\nThis endpoint is paginated, so make sure to \"flip through the pages\" via\nthe query parameter \"page\" if you need to get all the information.\n","operationId":"Bulk Payments_bulk-payments/get-failed-bulk-payments","parameters":[{"name":"bulkPaymentId","in":"path","required":false,"schema":{"type":"String","example":"","description":"","default":""},"description":""},{"name":"Accept","in":"header","required":false,"schema":{"type":"String","example":"application/json","description":"","default":""},"description":""},{"name":"Authorization","in":"header","required":false,"schema":{"type":"String","example":"Basic {your_token}","description":"","default":""},"description":""}],"responses":{"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"","properties":{},"required":[]},"code":{"type":"string","description":"","example":"352017"},"message":{"type":"string","description":"","example":"Bulk payment not found"},"displayToUser":{"type":"boolean","description":"","example":false}}}}}},"200 - Failed payments":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"payments":{"type":"array","description":"Response if some payments failed, divided in individual\npayments to users.\n","items":{"type":"object","properties":{"receiver_email":{"type":"string","description":"","example":"master@airtm.io"},"amount":{"type":"number","description":"","example":10},"currency":{"type":"string","description":"","example":"USD"},"note":{"type":"string","description":"","example":"salary"},"internal_note":{"type":"string","description":"","example":"best"},"status":{"type":"string","description":"","example":"FAILED"},"error":{"type":"string","description":"","example":"The second party is not allowed to receive more\nmoney\n"}},"required":[]}},"count":{"type":"number","description":"Number of failed payments found.","example":2},"pages":{"type":"number","description":"Number of pages with all the individual payments.","example":1},"currentPage":{"type":"number","description":"Current page that the information is in.","example":1}}}}}},"200 - No failed payments":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"payments":{"type":"array","description":"This is the response when no errors were found.","items":{}},"count":{"type":"number","description":"Number of failed payments found."},"pages":{"type":"number","description":"Number of pages."},"currentPage":{"type":"number","description":"Current page that the information is in.","example":1},"status":{"type":"string","description":"Status of the payments displayed. Always FAILED.","example":"FAILED"}}}}}}}}},"bulk-payments/{bulkPaymentId}/payments":{"get":{"security":[{"basicAuth":[]}],"tags":["Bulk Payments"],"summary":"Get bulk payments by id","description":"Get the status of all payments in an existing bulk payment of yours.\nThis will allow you to find out which payments succeeded, are still\npending or may have failed. This endpoint is paginated, so make sure to\n\"flip through the pages\" via the query parameter \"page\" if you need to\nget all the information.\n","operationId":"Bulk Payments_bulk-payments/get-bulk-payments-by-id","parameters":[{"name":"bulkPaymentId","in":"path","required":false,"schema":{"type":"String","example":"","description":"ID of the bulk payment to look into.","default":""},"description":"ID of the bulk payment to look into."},{"name":"page","in":"query","required":false,"schema":{"type":"String","example":"1","description":"","default":""},"description":""},{"name":"sort","in":"query","required":false,"schema":{"type":"String","example":"desc:amount,asc:internal_note","description":"","default":""},"description":""},{"name":"Accept","in":"header","required":false,"schema":{"type":"String","example":"application/json","description":"","default":""},"description":""},{"name":"Authorization","in":"header","required":false,"schema":{"type":"String","example":"Basic {your_token}","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"payments":{"type":"array","description":"","items":{"type":"object","properties":{"receiver_email":{"type":"string","description":"","example":"master@airtm.io"},"airtm_user_id":{"type":"string","description":"","example":"e5b6d935-916d-49c6-8347-d9a98331e2c0"},"amount":{"type":"number","description":"","example":10},"currency":{"type":"string","description":"","example":"USD"},"note":{"type":"string","description":"","example":"salary"},"internal_note":{"type":"string","description":"","example":"system number 45113-231"},"status":{"type":"string","description":"","example":"PENDING"},"hash":{"type":"string","description":"","example":"6BD5RK4DC3VH835F"}},"required":[]}},"count":{"type":"number","description":"Number of individual payments found.","example":2},"pages":{"type":"number","description":"Number of pages with all the individual payments.","example":1},"currentPage":{"type":"number","description":"Current page that the partner is exploring.","example":1}}}}}}}}},"bulk-payments/{bulkPaymentId}/payments/cancel":{"post":{"security":[{"basicAuth":[]}],"tags":["Bulk Payments"],"summary":"Cancel pending bulk payments","description":"This endpoint enables users to manually cancel specific or all `pending`\nindividual payouts within a bulk payment. Users can input transaction\n`hash` IDs for specific pending payouts they wish to cancel, retrievable\nfrom the GET bulk payments by id. If no hash is included in the request\nbody, the endpoint will cancel all pending payouts associated with the\nbulk payment. Pending payouts will automatically cancel after 90 days\n(by default, other time periods are avilable in dashboard settings) from\nthe creation date. Once canceled, funds are automatically restituted to\nuser's Airtm balance, and individual payout status are updated to\n`canceled`.\n","operationId":"Bulk Payments_bulk-payments/cancel-pending-payments-1","parameters":[{"name":"bulkPaymentId","in":"path","required":false,"schema":{"type":"String","example":"","description":"","default":""},"description":""},{"name":"Content-Type","in":"header","required":false,"schema":{"type":"String","example":"application/json","description":"","default":""},"description":""},{"name":"Authorization","in":"header","required":false,"schema":{"type":"String","example":"Basic {your_token}","description":"","default":""},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"successful":{"type":"array","description":"","items":{"type":"string","description":"","example":"CADBEW460EXAMPLE"}}}}}}},"422":{"description":"Bulk Payment ID not valid","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Description on standard bulk payment ID format.","example":"Unprocessable entity"},"messages":{"type":"object","description":"","properties":{"id":{"type":"array","description":"","items":{"type":"string","description":"","example":"id must match the following:\n\"/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/\"\n"}}},"required":[]}}}}}}},"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentItems":{"type":"array","description":"","items":{"type":"object","properties":{"airtm_operation_hash":{"type":"string","description":"","example":"CADBEW460EXAMPLE"}},"required":[]}}}}}}}}},"account-status":{"get":{"security":[{"basicAuth":[]}],"tags":["Account Status"],"summary":"Get account status","description":"Retrieve the current status of any user's account by providing their\nemail in the request headers. The response will return the user's client\nID, account status, whether the email corresponds to the primary account\n(Airtm allows up to two secondary emails per account), the country where\nthe account is registered, the verification status, and the full name\nregistered on the account.\n\n**The email parameter should be URL Encoded. You can learn more about\nencoding urls here:**\n[**https://www.w3schools.com/tags/ref\\_urlencode.ASP**](https://www.w3schools.com/tags/ref_urlencode.ASP)\n","operationId":"Account Status_account-status/get-account-status","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"String","example":"test-email@gmail.com","description":"Email associated with the account to check.","default":""},"description":"Email associated with the account to check."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","description":"Unique Airtm identifier of the user associated with the\nemail.\n","example":"4dc6bf66-fc9d-4873-a1f2-9d2c8c9c5b9d"},"status":{"type":"string","description":"The user's account status (active or inactive).","example":"active"},"isPrimary":{"type":"boolean","description":"Indicates if the queried email corresponds to the user's\nprimary email\n","example":false},"country_ID":{"type":"string","description":"The ISO alpha-3 code for the country where the user's ID\nwas issued\n","example":"ARG"},"is_verified":{"type":"boolean","description":"Indicates whether the user is verified (true or false)","example":false},"fullName":{"type":"string","description":"The user's full name as registered in Airtm","example":"Luciano PM"}}}}}}}}}},"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}}}}