Airtm Payments / Payouts API

## OverviewThe 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.## What are Payouts?Payouts 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.### Key Features- **Two-Step or One-Step Processing** - Choose your preferred workflow- **Real-Time Status Tracking** - Monitor payment progress instantly- **Comprehensive Recipient Management** - Support for new and existing users- **Webhook Integration** - Receive instant status notifications## Payment Processing Options### 1. Two-Step Process (Create + Commit)**Best for:** Careful review and approval workflows1. **Create Payout** - Generate payout instruction2. **Review Details** - Verify recipient and amount information3. **Commit Payout** - Execute the payment### 2. One-Step Process (Direct)**Best for:** Automated systems and immediate processing- **Create and Execute** - Single API call processes payment immediately- **Streamlined Workflow** - Reduces API calls and complexity- **Instant Processing** - Payment begins processing immediately## Status Management### Payout Status Values| Status | Final? | Description | Next Actions || ----------- | ------ | ---------------------------------------------------------------- | --------------------------- || `created` | No | Payout instruction created, awaiting commit | Call commit endpoint || `committed` | No | Payout committed and queued for processing | Monitor status updates || `pending` | No | Awaiting recipient action (account creation, verification, etc.) | Wait for recipient action || `completed` | Yes | Payment successfully delivered to recipient | None - payment complete || `canceled` | Yes | Payout canceled, funds returned to sender | None - transaction reversed || `failed` | Yes | Payment failed due to processing error | Contact support if needed |### Detailed Status Descriptions#### Created Status- Payout instruction has been successfully created- Funds are not yet committed from your account- You can still modify or cancel the payout- Must call commit endpoint to proceed#### Committed Status- Payout has been committed for processing- Funds are placed in escrow- Processing has begun but not yet completed- Cannot be canceled once committed#### Pending StatusThe payout is waiting for recipient action:- **New User:** Recipient needs to create an Airtm account- **Verification Required:** Recipient exceeds $1,000 threshold and needs ID verification- **US Recipients:** Must complete ID verification and configure payment method- **Account Issues:** Recipient account may have restrictionsA pending payout can still be canceled before it is processed.#### Completed Status- Payment has been successfully processed- Funds have been credited to recipient's account- Final status - no further action needed- Success webhook sent (if configured)#### Canceled Status- Payout was canceled before or during processing- Funds have been returned to your account- Can occur due to: - Manual cancellation - Recipient unable to receive funds - Account restrictions - Compliance issues#### Failed Status- Rare occurrence of processing failure- Contact [enterprise@airtm.com](mailto:enterprise@airtm.com) for assistance- May require manual intervention to resolve## Recipient Management### New RecipientsWhen sending to users who don't have Airtm accounts:1. **Payout Created** - Payment is created with recipient email2. **Email Notification** - Recipient receives invitation to join Airtm3. **Account Creation** - Recipient creates Airtm account4. **Payment Completion** - Funds are automatically credited### Existing RecipientsFor users with existing Airtm accounts:- Payments are typically processed faster- Fewer verification requirements- Direct credit to their account balance### Recipient Verification Requirements#### $1,000+ ThresholdRecipients receiving amounts that bring their total inflow over $1,000 must:- Complete ID verification- Provide government-issued identification- Verify personal information#### US RecipientsAll US-based recipients must:- Complete ID verification regardless of amount- Configure a valid payment method- Meet additional compliance requirements