--- title: "Create a payout" method: POST path: "/payouts" tags: ["Payouts"] --- # Create a payout `POST /payouts` ## Request - Base URL: `https://api.enterprise.airtm.com/v2` - URL: `https://api.enterprise.airtm.com/v2/payouts` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint allows you to create a payout instruction. In the request body, information about the payout such as the recipient's email, description, amount, and any URLs needed for confirmation or failure redirects should be provided. Upon successful creation, the API returns a response containing the details of the newly created payout, including a unique ID. > [!tip] > After making a call to this endpoint, no money is moved yet. To finish moving the money to a > user, you must call the `POST /v2/payouts/:id/commit` endpoint with the id from this response. > Alternatively, you may pass `commit: true` to do the payout in a single API call. ## Request body - CreatePayoutRequest - `airtmUserEmail` string, required - `amount` number, double, required: The payment amount in USD. - `commit` boolean: Immediately commit the payout. If `true`, the payout will be committed immediately after creation. Use this if you want to create a payout in just one API call instead of a two-step process outlined in the Create / Commit process. - `code` string: A unique code used to identify the payout. Populate this value with the identifier on your system. > [!important] > It must be unique across all existing payouts. - `enterpriseFee` number, double: The enterprise fee to apply to the payout - `notes` string, required: An arbitrary string describing the payment. This information is displayed to the recipient. It's recommended that the string summarizes the purpose of the payment. - `internalNote` string: The description of the payout; visible to internal users - `requireIdVerified` boolean: Set this to true to require that the recipient is ID-verified ## Response `200` Ok - PayoutResponse: Represents a Payout Object - `id` string, uuid, required - `bulkPayoutId` string, uuid - `hash` string: Unique hash for the payout operation within the Airtm system. - `code` string: A unique code used to identify the payout. - `airtmUserId` string, uuid, required - `airtmUserEmail` string, required - `requireIdVerified` boolean: Whether the recipient must be ID-verified to receive the funds - `notes` string: An arbitrary string describing the payment. This information is displayed to the recipient. - `internalNote` string: The description of the payout; visible to internal users - `status` 'BRIDGE_COMPLETED' | 'BRIDGE_CREATED' | 'BRIDGE_FAILED' | 'BRIDGE_MAX_RETRIES_REACHED' | 'BRIDGE_USER_SIGNUP_PENDING' | 'CANCELED' | 'CANCEL_REQUESTED' | 'COMMITTED' | 'COMPLETED' | 'COSMOEM_COMPLETED' | 'CREATED' | 'ERROR' | 'FAILED' | 'PENDING' | 'PENDING_SIGNATURE' | 'SIGNED' | 'PENDING_USER_ACTION' | 'PROCESSING', required: The current status of the payout. - `CREATED`: The payout instruction has been registered and is awaiting you to call the commit endpoint. - `COMMITTED`: The payout was committed and is in the process of being executed. - `PENDING`: Funds have been placed in escrow and waiting for the recipient to take the following action to complete the payout 1. If a new user, create an Airtm account. 2. If a user receiving an amount taking them over the $1,000 inflow threshold requiring KYC. 3. If a US user, complete KYC and configure payment method. - `COMPLETED`: The payout has been completed successfully, funds have been credited to the customer's account. - `CANCELED`: Payout has been canceled and funds have been returned to your account. - `FAILED`: The payout has failed and funds have been returned to your account. - `ERROR`: A temporary error state. Payouts in this state should be fixed and retried until they reach a final state (COMPLETED or CANCELED). - `grossAmount` number, double, required: amount originally intended for the payout - `amount` number, double, required: amount to be deducted from the enterprise account (grossAmount - enterpriseFee) - `netAmount` number, double, required: amount received by the user (grossAmount - enterpriseFee - airtmFee) - `airtmFee` number, double: The airtm fee applied to the payout - `enterpriseFee` number, double: The enterprise fee applied to the payout - `reasonCode` string: Machine-friendly code relating to the reason why the payout has the current status - `reasonDescription` string: Human-readable message describing the reason why the payout has the current status - `kycInformation` KycInformation: Represents the user's KYC information for a payout. > [!TIP] > Only available in `payout.completed` webhook and only if ID verification is enabled in your account. > If you want access to this information, please contact [enterprise@airtm.io](mailto:enterprise@airtm.io) Represents the user's KYC information for a payout. > [!TIP] > Only available in `payout.completed` webhook and only if ID verification is enabled in your account. > If you want access to this information, please contact [enterprise@airtm.io](mailto:enterprise@airtm.io) - `fullName` string, nullable, required - `birthDate` string, nullable, required - `identificationNumber` string, nullable, required - `countryCode` string, nullable, required - `state` string, nullable - `createdAt` string, date-time, required: Timestamp of when the payout was created. - `updatedAt` string, date-time, required: Timestamp of the last update made to the payout. ## Other responses - `default`: Error --- [API](https://skmtc.dev/airtm/apis/airtm-enterprise-api-v2.md) - [All operations](https://skmtc.dev/airtm/apis/airtm-enterprise-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/airtm/apis/airtm-enterprise-api-v2/revisions/c9ed13d4c5c0?raw)