AIairtm
Payouts

Create a payout

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.

post/payouts

Request

Request body

airtmUserEmailstring required
amountnumber double required

The payment amount in USD.

commitboolean

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.

codestring

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.

enterpriseFeenumber double

The enterprise fee to apply to the payout

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

internalNotestring

The description of the payout; visible to internal users

requireIdVerifiedboolean

Set this to true to require that the recipient is ID-verified

Response

Ok

idstring uuid required
bulkPayoutIdstring uuid
hashstring

Unique hash for the payout operation within the Airtm system.

codestring

A unique code used to identify the payout.

airtmUserIdstring uuid required
airtmUserEmailstring required
requireIdVerifiedboolean

Whether the recipient must be ID-verified to receive the funds

notesstring

An arbitrary string describing the payment. This information is displayed to the recipient.

internalNotestring

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).
grossAmountnumber double required

amount originally intended for the payout

amountnumber double required

amount to be deducted from the enterprise account (grossAmount - enterpriseFee)

netAmountnumber double required

amount received by the user (grossAmount - enterpriseFee - airtmFee)

airtmFeenumber double

The airtm fee applied to the payout

enterpriseFeenumber double

The enterprise fee applied to the payout

reasonCodestring

Machine-friendly code relating to the reason why the payout has the current status

reasonDescriptionstring

Human-readable message describing the reason why the payout has the current status

createdAtstring date-time required

Timestamp of when the payout was created.

updatedAtstring date-time required

Timestamp of the last update made to the payout.

Example response

{
  "grossAmount": 10,
  "amount": 9.5,
  "netAmount": 9,
  "airtmFee": 0.5,
  "enterpriseFee": 0.5
}

Changes

No recorded changes to this operation across all 1 revision of this API.