Saltar al contenido principal

Payout Item Object

A Payout Item represents an individual disbursement within a Payout, targeting a specific recipient.

Attributes​

iduuid

This Payout Item's unique identifier.

amountstring

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

effective_amountstring

The actual amount that will be transferred.

fee_amountstring

Fee amount for this item.

payout_iduuid

ID of the parent Payout.

statusstring

Item status: PENDING, SUCCEEDED, or REJECTED.

status_codestringnullable

Detail on the current status. See Status Codes below.

preferred_channelstringnullable

The channel originally requested for this item: SAVE, TURBO, or BREB. This is set from the channel field you send in the Create a Payout request. Immutable after creation.

channelstringnullable

The current channel for this item: SAVE, TURBO, or BREB. Starts as the same value as preferred_channel but may change during routing (e.g., TURBO may fall back to SAVE outside working hours). Compare with preferred_channel to detect fallbacks.

public_dataobjectnullable

Public data associated with this item.

activitiesarray

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

created_atstring

Creation date. ISO 8601 format.

updated_atstring

Last update date. ISO 8601 format.

Status Codes​

AWAIT_VALIDATIONSNew
Item is being validated.
AWAIT_THIRD_PARTY_KYCNew
Waiting for third-party KYC checks.
AWAIT_OWNERSHIP_VALIDATIONNew
Waiting for ownership validation.
AWAIT_BURN_TOKENSNew
Waiting to burn tokens for this item.
AWAIT_DISBURSEMENT
Ready and waiting to disburse to the recipient.
AWAIT_RE_TOKENIZE_TOKENSNew
Waiting to re-tokenize tokens.
AWAIT_REFUNDNew
Waiting to execute a refund for this item.
KYC_FAILED
Recipient failed KYC verification.
OWNERSHIP_VALIDATION_FAILEDNew
Identity does not match the bank account owner.
VALIDATIONS_FAILEDNew
Business validations failed (e.g. amount below 10,000 COP minimum).
PAYOUT_CANCELED
Parent payout was canceled.
PAYOUT_ABORTED
Parent payout was aborted.
FAILED_BANK_TRANSFER
The bank transfer failed.
DISBURSEMENT_INFRASTRUCTURE_ERRORNew
A banking infrastructure error occurred during disbursement. The funds were not transferred.
CLOSED_BANK_ACCOUNTNew
Destination bank account is closed.
UNOPENED_BANK_ACCOUNTNew
Destination bank account not yet opened.
INVALID_BANK_ACCOUNT_NUMBERNew
Destination account number is invalid.
EX_POST_REFUNDNew
Refund after the item was initially processed.
INVALID_IDENTITY_AND_BANK_ACCOUNTNew
Identity does not match bank account owner.
INVALID_BANK_ACCOUNT_TYPENew
Bank account type is invalid.
DISABLED_BANK_ACCOUNTNew
Bank account is disabled or blocked.
INCACTIVE_OR_BLOCKED_BANK_ACCOUNTNew
Bank account is inactive or blocked.
INCOMPATIBLE_RECIPIENT_AND_PREFERRED_CHANNELDeprecated
Deprecated.
FAILED_ROUTINGDeprecated
Deprecated.
INVALID_THIRD_PARTY_SOURCEDeprecated
Deprecated.
AWAIT_KYCDeprecated
Deprecated.
AWAIT_DISBURSEMENT_INITIATIONDeprecated
Deprecated.

JSON Example​

{
  "id": "aa25e1c3-bea4-4934-abd1-c8973ad3756f",
  "amount": "1000.23234",
  "effective_amount": "1000.12123",
  "fee_amount": "100.1231",
  "payout_id": "850feae6-ba74-4a03-893f-b7db0af03633",
  "status": "PENDING",
  "status_code": "AWAIT_DISBURSEMENT",
  "preferred_channel": "TURBO",
  "channel": "SAVE",
  "public_data": {
    "external_id": null,
    "full_name": "Juan Perez"
  },
  "activities": [
    {
      "type": "AWAIT_DISBURSEMENT",
      "status": "PENDING",
      "last_update_at": "2024-08-15T18:36:12.421Z"
    }
  ],
  "created_at": "2024-08-15T18:35:29.613Z",
  "updated_at": "2024-08-15T18:36:12.421Z"
}

In this example, the item was requested as TURBO (preferred_channel) but was routed to SAVE (channel) due to a fallback (e.g., bank not supported for TURBO or outside working hours). Note that preferred_channel and channel are read-only response fields — when creating a payout, you send the channel field per item in the request (see Create a Payout).