Skip to main content

Payout Object

A Payout represents a disbursement of funds from a customer's wallet to one or more recipients.

ENDPOINTS
POST/v1/payoutsGET/v1/payoutsGET/v1/payouts/{id}PATCH/v1/payouts/{payout_id}/cancel
THE PAYOUT OBJECT
{
  "id": "8dc85f2f-1cca-4f20-85fb-dcc16b233c94",
  "fee_type": "STANDARD",
  "fee_amount": "1000.42",
  "transfer_amount": "1200.50",
  "refunded_amount": null,
  "status": "PENDING",
  "status_code": "AWAIT_PROCESSING",
  "origin_source_id": "ee931602-016a-434d-9833-6910d241b8f4",
  "public_data": {
    "deposit_wallet_address": "0xe8D8480D0e1849C1895ba905dEABD391D0BD8D50",
    "transaction_hash": null,
    "creator_type": "USER",
    "creator_identifier": "f1cdbec9-4fd1-4fea-b20a-b70c524b9382",
    "user_file_key_name": "file.csv"
  },
  "activities": [
    {
      "type": "AWAIT_PROCESSING",
      "status": "PENDING",
      "last_update_at": "2024-08-15T18:35:29.613Z"
    }
  ],
  "finished_at": null,
  "created_at": "2024-08-15T18:35:29.613Z",
  "updated_at": "2024-08-15T18:35:29.613Z"
}

Attributes​

iduuid

This Payout's unique identifier.

fee_typestring

Deprecated — this field is accepted but ignored. All payouts use standard fee calculation. Will be removed after April 30, 2026.

fee_amountstring

Fee amount. Numeric string with up to 18 decimal digits.

transfer_amountstring

Total transfer amount. Numeric string with up to 18 decimal digits.

refunded_amountstringnullable

Total refunded amount to the customer.

statusstring

Payout status: PENDING, ABORTED, IN_PROGRESS, or FULFILLED.

status_codestringnullable

Status code providing detail on the current status. See Status Codes below.

origin_source_iduuid

ID of the origin wallet.

public_dataobjectnullable

Public data associated with the payout.

activitiesarray

Activities related to the payout. Each has type (Status Code), status (PENDING, SUCCEEDED, FAILED), and last_update_at.

finished_atstringnullable

Date when the payout finished. ISO 8601 format.

created_atstring

Creation date. ISO 8601 format.

updated_atstring

Last update date. ISO 8601 format.

Status Codes​

AWAIT_PROCESSING
Enqueued and waiting for the processing pipeline to start.
AWAIT_VALIDATIONS
Waiting for file/content and business-rule validations.
SETTLE_INCOMING_TRANSFER
Settling the incoming transfer before disbursement.
AWAIT_BURN_TOKENSNew
Waiting to burn tokens from the deposit wallet.
AWAIT_DISBURSEMENT
Ready and waiting to disburse to recipients.
AWAIT_RE_TOKENIZE_TOKENSNew
Waiting to re-tokenize tokens.
AWAIT_REFUNDNew
Waiting to execute a refund back to the customer.
CANCELED
Payout canceled; processing stopped.
INVALID_CSV
Provided CSV is invalid.
VALIDATION_FAILED
Business validations failed.
REFUNDEDNew
Payout amount refunded to the customer.
EXPIREDNew
Payout expired due to time window or inactivity.
CREATE_PAYOUTDeprecated
Superseded by AWAIT_PROCESSING.
AWAIT_RECIPIENTS_KYCDeprecated
Deprecated.
AWAIT_DISBURSEMENT_INITIATIONDeprecated
Deprecated.

Status Lifecycle​