Toku Payout Request Items API

openapi: 3.2.0
info:
  title: Recursos secundarios Payout Request Items API
  version: 1.0.0
  description: Seguimiento y cierre de los Payout Request Items, las filas individuales que quedaron registradas al ingestar un Payout Request.
servers:
- description: Production
  url: https://api.trytoku.com
security:
- ApiKeyAuth: []
tags:
- description: Seguimiento y cierre de los Payout Request Items, las filas individuales que quedaron registradas al ingestar un Payout Request.
  name: Payout Request Items
paths:
  /payouts-data-ingestion/payout-request-items/{id_payout_request}:
    get:
      description: 'Devuelve los conteos por estado y el detalle fila a fila de un Payout Request ingestado.


        Se usa para hacer seguimiento de una carga: `summary` entrega cuántos items quedaron en SUCCESS, FAILED y PREPARING, e `items` entrega una entrada por fila con su `external_id`, su estado y, cuando falló, el motivo en `failure_reason`.


        Cada entrada incluye además el detalle del payout que se guardó cuando el lote terminó de ejecutarse: `id_payout`, `amount`, `description`, `due_date`, `expire_at`, `voucher_url`, `is_fraud`, `source_reference`, `beneficiary` y `beneficiary_account`. Esos campos llegan en `null` mientras el lote no termina y en las filas que nunca llegaron a generar un payout.


        **Límite de tasa:** 1000 solicitudes por hora. Al superarlo, la API responde `429`. Ver Límites de tasa.'
      operationId: list_payout_request_items
      parameters:
      - description: Identificador del Payout Request cuyas filas ingestadas se quieren consultar
        in: path
        name: id_payout_request
        required: true
        schema:
          description: Identificador del Payout Request cuyas filas ingestadas se quieren consultar
          examples:
          - 6f1d0f5e-6b1a-4f2e-9a0c-2f3b4c5d6e7f
          format: uuid
          title: Id Payout Request
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPayoutRequestItemsResponse'
          description: Conteos y detalle por fila del Payout Request
        '400':
          description: El servicio de configuración respondió con un error de cliente. Su código de estado se propaga sin modificarlo, por lo que cualquier código 4xx de ese servicio puede aparecer aquí.
        '401':
          description: Falta la API key de la organización o no es válida
        '422':
          description: El identificador del Payout Request no tiene formato UUID
      summary: Listar Payout Request Items
      tags:
      - Payout Request Items
components:
  schemas:
    ListPayoutRequestItemsResponse:
      description: Conteos y detalle fila a fila de los Payout Request Items de un Payout Request.
      properties:
        id_payout_request:
          description: Payout Request consultado.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          title: Id Payout Request
          type: string
        items:
          description: Una entrada por fila ingestada, con su estado y el detalle del payout.
          items:
            $ref: '#/components/schemas/PayoutRequestItemSummaryRow'
          title: Items
          type: array
        summary:
          allOf:
          - $ref: '#/components/schemas/PayoutRequestItemsSummaryCounts'
          description: Conteo de items en SUCCESS, FAILED y PREPARING.
      required:
      - id_payout_request
      - summary
      title: ListPayoutRequestItemsResponse
      type: object
    PayoutRequestItemSummaryRow:
      description: 'Una fila ingestada con su estado y el detalle del payout que generó.


        ``status`` y ``failure_reason`` provienen de la fila registrada. El resto de los campos son el detalle que se guardó cuando el lote terminó de ejecutarse; llegan en ``null`` mientras el lote no termina y en las filas que nunca llegaron a generar un payout.'
      properties:
        amount:
          anyOf:
          - type: number
          - type: 'null'
          description: Monto del payout; si aún no existe, el monto de la fila ingestada.
          examples:
          - 99.5
          title: Amount
        beneficiary:
          anyOf:
          - $ref: '#/components/schemas/PayoutBeneficiary'
          - type: 'null'
          description: Datos del beneficiario que recibió el payout.
        beneficiary_account:
          anyOf:
          - $ref: '#/components/schemas/PayoutBeneficiaryAccount'
          - type: 'null'
          description: Cuenta del beneficiario en la que se depositó el payout.
        description:
          anyOf:
          - type: string
          - type: 'null'
          description: Descripción con la que quedó registrado el payout.
          examples:
          - Comisiones
          title: Description
        due_date:
          anyOf:
          - type: string
          - type: 'null'
          description: Fecha de vencimiento del payout cuando está definida.
          examples:
          - '2026-06-11T00:00:00Z'
          title: Due Date
        expire_at:
          anyOf:
          - type: string
          - type: 'null'
          description: Fecha de expiración del payout cuando está definida.
          examples:
          - '2026-12-31T23:59:59+00:00'
          title: Expire At
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          description: external_id de la fila registrada cuando viene en el payload.
          examples:
          - ext-001
          title: External Id
        failure_reason:
          anyOf:
          - type: string
          - type: 'null'
          description: Motivo legible de la falla cuando el estado es FAILED.
          examples:
          - Payout ended with status REJECTED
          title: Failure Reason
        id_payout:
          anyOf:
          - type: string
          - type: 'null'
          description: Identificador del payout generado por esta fila.
          examples:
          - payout-1
          title: Id Payout
        is_fraud:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Indica si el payout quedó marcado como fraude.
          examples:
          - false
          title: Is Fraud
        source_reference:
          anyOf:
          - type: string
          - type: 'null'
          description: Referencia de origen del Payout Request al que pertenece la fila.
          examples:
          - ref-1
          title: Source Reference
        status:
          description: PREPARING (en curso), FAILED (con error) o SUCCESS (payout completado).
          examples:
          - SUCCESS
          title: Status
          type: string
        voucher_url:
          anyOf:
          - type: string
          - type: 'null'
          description: Comprobante del payout ejecutado cuando está disponible.
          examples:
          - CEP-REF-1
          title: Voucher Url
      required:
      - status
      title: PayoutRequestItemSummaryRow
      type: object
    PayoutBeneficiaryAccount:
      description: Cuenta del beneficiario en la que se depositó el payout.
      properties:
        account_number:
          anyOf:
          - type: string
          - type: 'null'
          description: Número de cuenta enmascarado.
          examples:
          - '****1223'
          title: Account Number
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Identificador externo de la cuenta en la integración.
          examples:
          - ben-acct-ext-001
          title: External Id
      title: PayoutBeneficiaryAccount
      type: object
    PayoutBeneficiary:
      description: Datos del beneficiario que recibió el payout, tal como quedaron al ejecutarse el lote.
      properties:
        email:
          anyOf:
          - type: string
          - type: 'null'
          description: Correo del beneficiario.
          examples:
          - jane@acme.com
          title: Email
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Identificador externo del beneficiario en la integración.
          examples:
          - benef-ext-001
          title: External Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          description: Nombre del beneficiario.
          examples:
          - Jane Doe
          title: Name
        phone:
          anyOf:
          - type: string
          - type: 'null'
          description: Teléfono del beneficiario.
          examples:
          - '+525512345678'
          title: Phone
      title: PayoutBeneficiary
      type: object
    PayoutRequestItemsSummaryCounts:
      description: Conteo de Payout Request Items por estado dentro de un Payout Request.
      properties:
        failed_count:
          description: Items que quedaron con una falla registrada.
          examples:
          - 1
          minimum: 0
          title: Failed Count
          type: integer
        preparing_count:
          description: Items todavía en preparación.
          examples:
          - 0
          minimum: 0
          title: Preparing Count
          type: integer
        success_count:
          description: Items cuyo payout se completó.
          examples:
          - 2
          minimum: 0
          title: Success Count
          type: integer
      required:
      - success_count
      - failed_count
      - preparing_count
      title: PayoutRequestItemsSummaryCounts
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Toku public API key. Send it in the x-api-key header on every request.
      in: header
      name: x-api-key
      type: apiKey
x-toku-api-version: '2026-10-08'
x-toku-dto-versions:
  DTOAccountPaymentInstrument: DTOAccountPaymentInstrumentV1
  DTOAggregatedPaymentMethod: DTOAggregatedPaymentMethodV2
  DTOAggregatedTransaction: DTOAggregatedTransactionV2
  DTOBankAccountPaymentMethod: DTOBankAccountPaymentMethodV1
  DTOBoletoPaymentInstrument: DTOBoletoPaymentInstrumentV2
  DTOBrPaymentInstrument: DTOBrPaymentInstrumentV2
  DTOCardPaymentInstrument: DTOCardPaymentInstrumentV1
  DTOCardPaymentMethod: DTOCardPaymentMethodV1
  DTOCashClPaymentInstrument: DTOCashClPaymentInstrumentV1
  DTOCashMxPaymentInstrument: DTOCashMxPaymentInstrumentV1
  DTOClPaymentInstrument: DTOClPaymentInstrumentV2
  DTOCustomer: DTOCustomerV2
  DTOInvoice: DTOInvoiceV4
  DTOMxPaymentInstrument: DTOMxPaymentInstrumentV3
  DTOPacManagementPaymentInstrument: DTOPacManagementPaymentInstrumentV1
  DTOPatpassPaymentInstrument: DTOPatpassPaymentInstrumentV1
  DTOPaymentIntent: DTOPaymentIntentV5
  DTOPaymentMethod: DTOPaymentMethodV7
  DTOPixPaymentInstrument: DTOPixPaymentInstrumentV1
  DTOPixPaymentMethod: DTOPixPaymentMethodV1
  DTOReferencedPaymentMXInstrument: DTOReferencedPaymentMXInstrumentV1
  DTOTransaction: DTOTransactionV10
  DTOTransferClPaymentInstrument: DTOTransferClPaymentInstrumentV2
  DTOTransferMxPaymentInstrument: DTOTransferMxPaymentInstrumentV1
  DTOUpdatedFields: DTOUpdatedFieldsV1
  DTOWalletMovement: DTOWalletMovementV1
  DTOWalletPaymentInstrument: DTOWalletPaymentInstrumentV2
x-toku-schema-names:
  ApiPaymentMethod_AssociatePaymentMethodResponse: AssociatePaymentMethodResponse
  ApiPaymentMethod_DTOPaymentMethodV7: PaymentMethod
  ApiPaymentTransaction_DTOTransactionV10: Transaction
  ApiPaymentTransaction_TransactionStatus: TransactionStatus
  ApiRenditionFile_BusinessDaysBeforeFilter: BusinessDaysBeforeFilter
  ApiRenditionFile_DaysBeforeFilter: DaysBeforeFilter
  ApiRenditionFile_DueDatesDaysFutureFilter: DueDatesDaysFutureFilter
  ApiRenditionFile_EntityRestrictions: EntityRestrictions
  ApiRenditionFile_NewestNInvoicesFilter: NewestNInvoicesFilter
  ApiRenditionFile_OldestNInvoicesFilter: OldestNInvoicesFilter
  CheckoutApi_AccountDetailsResponse: AccountDetailsResponse
  CheckoutApi_CheckoutSessionResponse: CheckoutSession
  ClientPaymentPortalBackend_CheckoutSessionResponse: CheckoutSessionResponse
  CollectionStrategist_InstitutionId: InstitutionId
  CollectionStrategist_SubTreeConfiguration: SubTreeConfiguration
  DTOAccountPaymentInstrumentV1: AccountPaymentInstrument
  DTOAggregatedTransactionV2: AggregatedTransaction
  DTOAppliedAdjustmentDocumentV1: AppliedAdjustmentDocument
  DTOBoletoPaymentInstrumentV2: BoletoPaymentInstrument
  DTOBrPaymentInstrumentV2: BrPaymentInstrument
  DTOCardPaymentInstrumentV1: CardPaymentInstrument
  DTOCardPaymentMethodV1: CardPaymentMethod
  DTOCashClPaymentInstrumentV1: CashClPaymentInstrument
  DTOCashMxPaymentInstrumentV1: CashMxPaymentInstrument
  DTOClPaymentInstrumentV2: ClPaymentInstrument
  DTOInvoiceV4: Invoice
  DTOMxPaymentInstrumentV3: MxPaymentInstrument
  DTOPacManagementPaymentInstrumentV1: PacManagementPaymentInstrument
  DTOPatpassPaymentInstrumentV1: PatpassPaymentInstrument
  DTOPaymentIntentV5: PaymentIntent
  DTOPixPaymentInstrumentV1: PixPaymentInstrument
  DTOPixPaymentMethodV1: PixPaymentMethod
  DTOReferencedPaymentMXInstrumentV1: ReferencedPaymentMXInstrument
  DTOTransferClPaymentInstrumentV2: TransferClPaymentInstrument
  DTOTransferMxPaymentInstrumentV1: TransferMxPaymentInstrument
  DTOUpdatedFieldsV1: UpdatedFields
  DTOWalletMovementV1: WalletMovement
  DTOWalletPaymentInstrumentV2: WalletPaymentInstrument
  GetCustomerResponse: Customer
  GetSubscriptionResponse: Subscription
  PayoutsBeneficiaryService_ApprovalFlowsStatus: ApprovalFlowsStatus
  PayoutsBeneficiaryService_Beneficiary: Beneficiary
  PayoutsBeneficiaryService_BeneficiaryAccount: BeneficiaryAccount
  PayoutsBeneficiaryService_BeneficiaryAccountVerification: BeneficiaryAccountVerification
  PayoutsBeneficiaryService_IdentityDocument: IdentityDocument
  PayoutsBeneficiaryService_VerificationStatus: VerificationStatus
  PayoutsDataIngestionService_DisbursementType: DisbursementType
  WebhookEndpointResponse: WebhookEndpoint
x-provenance:
  method: searched
  source: https://docs.trytoku.com/reference
  harvested: '2026-10-29'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.trytoku.com/reference/associate_subscription.md
  - https://docs.trytoku.com/reference/associate_subscription_bulk.md
  - https://docs.trytoku.com/reference/bulk_inscriptions_public.md
  - https://docs.trytoku.com/reference/cancel_billing_document.md
  - https://docs.trytoku.com/reference/cancel_preauth_endpoint.md
  - https://docs.trytoku.com/reference/capture_preauth_endpoint.md
  - https://docs.trytoku.com/reference/change_subscription_status.md
  - https://docs.trytoku.com/reference/create_adjustment_document.md
  - https://docs.trytoku.com/reference/create_beneficiaries.md
  - https://docs.trytoku.com/reference/create_bulk_automatic_debit_payment_methods.md
  - https://docs.trytoku.com/reference/create_credit_note.md
  - https://docs.trytoku.com/reference/create_customer.md
  - https://docs.trytoku.com/reference/create_customer_billing_data.md
  - https://docs.trytoku.com/reference/create_customer_billing_data_bulk.md
  - https://docs.trytoku.com/reference/create_document.md
  - https://docs.trytoku.com/reference/create_external_transaction.md
  - https://docs.trytoku.com/reference/create_external_transactions.md
  - https://docs.trytoku.com/reference/create_handler.md
  - https://docs.trytoku.com/reference/create_intent.md
  - https://docs.trytoku.com/reference/create_invoice_billing_data.md
  - https://docs.trytoku.com/reference/create_m2m_access_token.md
  - https://docs.trytoku.com/reference/create_or_update_invoice.md
  - https://docs.trytoku.com/reference/create_or_update_subscription.md
  - https://docs.trytoku.com/reference/create_pacs.md
  - https://docs.trytoku.com/reference/create_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/create_ppd_billing_document.md
  - https://docs.trytoku.com/reference/create_ppd_complement_billing_document.md
  - https://docs.trytoku.com/reference/create_ppd_complement_from_wallet_movement_billing_document.md
  - https://docs.trytoku.com/reference/create_public_validator_execution.md
  - https://docs.trytoku.com/reference/create_pue_billing_document.md
  - https://docs.trytoku.com/reference/create_receipt.md
  - https://docs.trytoku.com/reference/create_referenced_payment_mx_reference_endpoint.md
  - https://docs.trytoku.com/reference/create_terminal.md
  - https://docs.trytoku.com/reference/create_transfer_clabe_account.md
  - https://docs.trytoku.com/reference/create_webhook_endpoint.md
  - https://docs.trytoku.com/reference/delete_customer.md
  - https://docs.trytoku.com/reference/delete_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/delete_external_transaction.md
  - https://docs.trytoku.com/reference/delete_external_transactions.md
  - https://docs.trytoku.com/reference/delete_invoice.md
  - https://docs.trytoku.com/reference/delete_pacs.md
  - https://docs.trytoku.com/reference/delete_payment_method.md
  - https://docs.trytoku.com/reference/delete_subscription.md
  - https://docs.trytoku.com/reference/delete_terminal.md
  - https://docs.trytoku.com/reference/download_pdf_for_transaction.md
  - https://docs.trytoku.com/reference/edit_customer.md
  - https://docs.trytoku.com/reference/edit_invoice.md
  - https://docs.trytoku.com/reference/edit_invoice_billing_data.md
  - https://docs.trytoku.com/reference/edit_subscription.md
  - https://docs.trytoku.com/reference/edit_webhook_endpoint.md
  - https://docs.trytoku.com/reference/enroll_carteira_boleto.md
  - https://docs.trytoku.com/reference/expire_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/expire_handler.md
  - https://docs.trytoku.com/reference/expire_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/external_boleto_initialize.md
  - https://docs.trytoku.com/reference/external_onetime_initialize.md
  - https://docs.trytoku.com/reference/generate_report.md
  - https://docs.trytoku.com/reference/get_account_verifications_by_batch.md
  - https://docs.trytoku.com/reference/get_adjustment_document.md
  - https://docs.trytoku.com/reference/get_bank_account_verification_by_id.md
  - https://docs.trytoku.com/reference/get_bank_account_verifications.md
  - https://docs.trytoku.com/reference/get_beneficiary_accounts.md
  - https://docs.trytoku.com/reference/get_billing_document.md
  - https://docs.trytoku.com/reference/get_checkout_session_endpoint_v2.md
  - https://docs.trytoku.com/reference/get_customer.md
  - https://docs.trytoku.com/reference/get_customer_billing_data.md
  - https://docs.trytoku.com/reference/get_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/get_customers.md
  - https://docs.trytoku.com/reference/get_handler.md
  - https://docs.trytoku.com/reference/get_invoice.md
  - https://docs.trytoku.com/reference/get_invoice_billing_data.md
  - https://docs.trytoku.com/reference/get_paginated_chargeable_invoices.md
  - https://docs.trytoku.com/reference/get_payment_method.md
  - https://docs.trytoku.com/reference/get_payment_method_by_id.md
  - https://docs.trytoku.com/reference/get_payment_methods.md
  - https://docs.trytoku.com/reference/get_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/get_public_transactions.md
  - https://docs.trytoku.com/reference/get_receipt.md
  - https://docs.trytoku.com/reference/get_report_columns.md
  - https://docs.trytoku.com/reference/get_signed_document_url.md
  - https://docs.trytoku.com/reference/get_subscription.md
  - https://docs.trytoku.com/reference/get_subscriptions.md
  - https://docs.trytoku.com/reference/get_terminal.md
  - https://docs.trytoku.com/reference/get_transaction.md
  - https://docs.trytoku.com/reference/get_transaction_data_for_refund.md
  - https://docs.trytoku.com/reference/get_transaction_fees_public.md
  - https://docs.trytoku.com/reference/get_transfer_clabe_account.md
  - https://docs.trytoku.com/reference/get_webhook_endpoint.md
  - https://docs.trytoku.com/reference/get_webhook_endpoints.md
  - https://docs.trytoku.com/reference/get_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/ingest_payout_request_input.md
  - https://docs.trytoku.com/reference/initialize_enrollment_pix.md
  - https://docs.trytoku.com/reference/initialize_push_notification_enrollment.md
  - https://docs.trytoku.com/reference/list_adjustment_documents.md
  - https://docs.trytoku.com/reference/list_customer_invoices.md
  - https://docs.trytoku.com/reference/list_invoices.md
  - https://docs.trytoku.com/reference/list_invoices_by_customer.md
  - https://docs.trytoku.com/reference/list_payout_request_items.md
  - https://docs.trytoku.com/reference/list_payouts.md
  - https://docs.trytoku.com/reference/list_subject_consents.md
  - https://docs.trytoku.com/reference/list_terminals.md
  - https://docs.trytoku.com/reference/lookup_customer.md
  - https://docs.trytoku.com/reference/lookup_invoice.md
  - https://docs.trytoku.com/reference/lookup_subscription.md
  - https://docs.trytoku.com/reference/open_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/patch_beneficiary_account_data.md
  - https://docs.trytoku.com/reference/patch_beneficiary_account_external_id.md
  - https://docs.trytoku.com/reference/patch_beneficiary_metadata.md
  - https://docs.trytoku.com/reference/patch_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/pos_charge_endpoint.md
  - https://docs.trytoku.com/reference/post_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/post_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/public_available_institutions.md
  - https://docs.trytoku.com/reference/public_start_create_cash_mx_reference.md
  - https://docs.trytoku.com/reference/public_update_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/refund_invoice_public.md
  - https://docs.trytoku.com/reference/refund_transaction_public.md
  - https://docs.trytoku.com/reference/soft_delete_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/subscriptions_by_customer.md
  - https://docs.trytoku.com/reference/undo_debt_reconciliation_by_invoice_endpoint.md
  - https://docs.trytoku.com/reference/update_adjustment_document.md
  - https://docs.trytoku.com/reference/update_customer_billing_data.md
  - https://docs.trytoku.com/reference/update_external_transaction.md
  - https://docs.trytoku.com/reference/update_external_transactions.md
  - https://docs.trytoku.com/reference/update_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/update_terminal.md
  - https://docs.trytoku.com/reference/upload_external_pdf.md
  - https://docs.trytoku.com/reference/validate_handler.md
  - https://docs.trytoku.com/reference/verify_bank_account.md
  - https://docs.trytoku.com/reference/verify_public_bulk_bank_accounts.md
  - https://docs.trytoku.com/reference/void_invoice.md
  merge:
    pages: 131
    deduped: 757
    conflicts_kept_first: 0