AIairtm
Payouts

Cancel a pending payout

This endpoint allows users to cancel specific CREATED or PENDING individual payouts—those that:

  • have been created and committed but where the recipient is not ready to receive the payout.
  • have been created but have not yet been committed.

Pending payouts will automatically cancel after 90 days (by default, other time periods are available in dashboard settings) from the creation date.

Once canceled:

  • Funds are automatically returned to the enterprise's balance.
  • The individual payout status is updated to CANCELED.
  • The response will include all relevant details of the canceled payout.

Additional information about canceled payouts can be accessed through the Enterprise Portal

delete/payouts/{id}

Request

Path parameters

idstring required

The payout id

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.