# List Cash-Outs

Returns Cash-Out transactions created within a period, oldest first by default.
Pass order=desc for newest first.

## Cursor pagination

Send nextCursor from the previous response to fetch the next page. When the response
comes back without nextCursor, you have reached the end of the period.

To walk backwards, send previousCursor in the very same cursor parameter. It is
absent on the first page, so its absence is how you know you are at the start.

Keep from, to, limit and order identical across every page — only cursor changes.
Both directions return the page in the order you asked for.

> ℹ️ There is no total field. Counting the whole window would require a full scan,
> which is exactly what cursor pagination avoids.

Each item carries the same fields as GET /cash-out/{id}, with the same status, failure and
reason values.

Endpoint: GET /cash-out
Version: 2.2.0
Security: bearerAuth

## Header parameters:

  - `ApplicationToken` (string, required)
    Fixed GUID that uniquely identifies your integration. Provided during ConnectPSP onboarding.
    Example: "{{ApplicationToken}}"

## Query parameters:

  - `from` (string, required)
    Start of the period, inclusive. Accepts a plain date (YYYY-MM-DD) or a full ISO 8601
timestamp (YYYY-MM-DDTHH:mm:ss).

Times without an explicit offset are read as America/Sao_Paulo (UTC-3). A plain date
becomes 00:00:00.000 of that day in that timezone.

The period filters on when the transaction was created, not when it was paid.
    Example: "2026-08-01"

  - `to` (string, required)
    End of the period, inclusive. Same format rules as from. A plain date becomes
23:59:59.999 of that day in America/Sao_Paulo.
    Example: "2026-08-01"

  - `limit` (integer)
    Maximum number of items per page. Defaults to 50, maximum 1000.
    Example: 50

  - `cursor` (string)
    Opaque cursor pointing at another page. Copy nextCursor (to go forward) or
previousCursor (to go back) from the previous response verbatim. Do not build or
parse it yourself, its format may change — a cursor already knows which way it goes.

Keep from, to, limit and order identical across every page of the same walk.
    Example: "MTM4OTU0NzI4MDAwMDAwMDB8YXxufFBIUVlST0I"

  - `order` (string)
    Sort direction by date. asc (default) returns the oldest first, desc the newest first.

> ⚠️ order cannot change mid-walk. The direction is baked into the cursor. Sending a
> different order alongside a cursor returns 422 LIST_ORDER_MISMATCH, because the
> next page would otherwise walk backwards — repeating rows you already had and skipping
> rows you never got. To change direction, start a new walk without cursor.
    Enum: "asc", "desc"

## Response 200 fields (application/json):

  - `items` (array)

  - `items.transactionId` (string)
    Example: "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9"

  - `items.internalCode` (string)
    Example: "IVKPRMOCDY"

  - `items.externalReference` (string)
    Example: "withdraw_xyz789"

  - `items.endToEndId` (string)
    BACEN/SPI settlement proof.
- COMPLETED: starts with E
- REFUNDED: starts with D (the devolution); the payment E2E is in originalEndToEndId
- CANCELLED: absent when the transfer never reached the PIX network
    Example: "E00416968202603101827cemeFscF6AG"

  - `items.originalEndToEndId` (string)
    Original E2E ID when endToEndId represents an async refund.

  - `items.status` (string)
    - PROCESSING — being executed at the financial institution
- PENDING — held on the ConnectPSP side (approval, analysis or reconciliation)
- COMPLETED — paid to the payee
- CANCELLED — the money never left your account; see failure
- REFUNDED — the money left and came back to your account; see reason
    Enum: "PROCESSING", "PENDING", "COMPLETED", "CANCELLED", "REFUNDED"

  - `items.amount` (number)
    Example: 500

  - `items.failure` (object)
    Why the Cash-Out was cancelled. Present only when status is CANCELLED. The full table of codes,
messages and whether to retry is in GET /cash-out/{id}.

  - `items.failure.code` (string)
    Machine-readable failure code. Key your handling on this. New codes may be added — treat an unknown
code as PROCESSING_ERROR.
    Enum: "PROVIDER_UNAVAILABLE", "PIX_KEY_NOT_FOUND", "PIX_KEY_INVALID", "PAYEE_DOCUMENT_MISMATCH", "PAYEE_ACCOUNT_INVALID", "PAYEE_ACCOUNT_UNAVAILABLE", "PAYEE_BANK_UNAVAILABLE", "PAYEE_BANK_REJECTED", "FRAUD_SUSPECTED", "INSUFFICIENT_FUNDS", "AMOUNT_ABOVE_MAXIMUM", "DAILY_LIMIT_EXCEEDED", "PERIOD_LIMIT_EXCEEDED", "PAYEE_LIMIT_EXCEEDED", "PAYEE_NOT_ALLOWED", "DUPLICATED_TRANSFER", "APPROVAL_REJECTED", "PROCESSING_ERROR"

  - `items.failure.message` (string)
    Fixed English text for the code, safe to show to your operators. Do not parse it.
    Example: "The provided PIX key did not resolve to a valid account."

  - `items.reason` (string)
    Why a completed Cash-Out came back. Present only when status is REFUNDED.

- PAYEE_REQUESTED — the payee asked their bank to return the transfer
- FRAUD — returned because of fraud, including a MED (Special Return Mechanism) claim
- OPERATIONAL_ERROR — returned because of an operational error at a bank
- REVERSED_BY_INSTITUTION — reversed by the financial institution
- OTHER — any other reason
    Enum: "PAYEE_REQUESTED", "FRAUD", "OPERATIONAL_ERROR", "REVERSED_BY_INSTITUTION", "OTHER"

  - `items.payee` (object)

  - `items.payee.name` (string, required)
    Full name of the payee.
    Example: "Maria Silva"

  - `items.payee.document` (string, required)
    CPF or CNPJ of the payee (numbers only).
    Example: "12345678909"

  - `items.payee.destination` (object, required)

  - `items.payee.destination.type` (string, required)
    - PIX — payment via PIX key. Provide pixKeyType and pixKey.
- BANK_ACCOUNT — payment via bank account data. Provide bankAccount.
    Enum: "PIX", "BANK_ACCOUNT"

  - `items.payee.destination.pixKeyType` (string)
    Type of PIX key. Required when type is PIX. Responses and webhooks always return one of these
same five values: CPF, CNPJ, EMAIL, PHONE or EVP (random key).
    Enum: "CPF", "CNPJ", "EMAIL", "PHONE", "EVP"

  - `items.payee.destination.pixKey` (string)
    The PIX key value. Required when type is PIX.
    Example: "12345678909"

  - `items.payee.destination.bankAccount` (object)
    Bank account details. Required when destination.type is BANK_ACCOUNT.

  - `items.payee.destination.bankAccount.ispb` (string, required)
    Bank ISPB code (8 digits).
    Example: "18236120"

  - `items.payee.destination.bankAccount.branch` (string, required)
    Branch number (without check digit).
    Example: "0001"

  - `items.payee.destination.bankAccount.account` (string, required)
    Account number with check digit.
    Example: "947710840"

  - `items.payee.destination.bankAccount.accountType` (string)
    Account type. Defaults to CACC (checking).
    Enum: "CACC", "SVGS", "PAYMENT"

  - `items.payee.bankData` (object)
    Banking details returned after settlement. May be null before settlement.

  - `items.payee.bankData.bank` (string)
    Bank name.
    Example: "Banco do Brasil S.A."

  - `items.payee.bankData.branch` (string)
    Branch number.
    Example: "0001"

  - `items.payee.bankData.account` (string)
    Account number.
    Example: "123456"

  - `items.settlement` (object)
    - COMPLETED / REFUNDED — the ConnectPSP account that settled the Cash-Out.
- CANCELLED — the ConnectPSP account the Cash-Out would have been paid from. Present
  only when a bank had already been assigned; no money left your account.
- PROCESSING / PENDING — absent.

  - `items.settlement.ispb` (string)
    ISPB of the settling institution. Key on this, not on bank.
    Example: "12345678"

  - `items.settlement.bank` (string)
    Example: "SETTLEMENT PARTNER A"

  - `items.settlement.branch` (string)
    Example: "0001"

  - `items.settlement.account` (string)
    Example: "123456"

  - `items.requestedAt` (string)
    When the Cash-Out was requested. Always present.
    Example: "2026-03-10T14:00:00-03:00"

  - `items.completedAt` (string)
    When the payment was completed. Present on COMPLETED, and kept on REFUNDED.
    Example: "2026-03-10T14:02:30-03:00"

  - `items.cancelledAt` (string)
    When the Cash-Out was cancelled. Present only on CANCELLED.

  - `items.refundedAt` (string)
    When the money came back. Present only on REFUNDED.

  - `nextCursor` (string)
    Opaque cursor for the next page. Absent when there are no more pages.
    Example: "MTM4OTU1MTIwMDAwMDAwMDB8YXxufElWS1BSTU9DRFk"

  - `previousCursor` (string)
    Opaque cursor for the page before this one. Send it in the same cursor parameter.
Absent on the first page — that is how you know you are at the start.
    Example: "MTM4OTU1MTIwMDAwMDAwMDB8YXxwfElWS1BSTU9DRFk"

## Response 401 fields (application/problem+json):

  - `type` (string)
    URI identifying the error type. It can contain non-ASCII characters.
    Example: "https://doc.connectpsp.com/errors/duplicated-external-reference"

  - `title` (string)
    Short, human-readable summary.
    Example: "Referência Externa Duplicada"

  - `status` (integer)
    HTTP status code.
    Example: 409

  - `code` (string)
    Machine-readable error code for programmatic handling. Absent on the 401 for a missing or
invalid ApplicationToken.
    Example: "DUPLICATED_EXTERNAL_REFERENCE"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "Já existe uma operação com o externalReference informado: withdraw_xyz789."

  - `errors` (object)
    Only on VALIDATION_ERROR. Field name → list of validation messages for that field.

  - `instance` (string)
    Request path where the error occurred. Present on some errors, such as INTERNAL_ERROR.

  - `traceId` (string)
    Only on INTERNAL_ERROR. Send it to support to locate the occurrence.

## Response 422 fields (application/problem+json):

  - `type` (string)
    URI identifying the error type. It can contain non-ASCII characters.
    Example: "https://doc.connectpsp.com/errors/duplicated-external-reference"

  - `title` (string)
    Short, human-readable summary.
    Example: "Referência Externa Duplicada"

  - `status` (integer)
    HTTP status code.
    Example: 409

  - `code` (string)
    Machine-readable error code for programmatic handling. Absent on the 401 for a missing or
invalid ApplicationToken.
    Example: "DUPLICATED_EXTERNAL_REFERENCE"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "Já existe uma operação com o externalReference informado: withdraw_xyz789."

  - `errors` (object)
    Only on VALIDATION_ERROR. Field name → list of validation messages for that field.

  - `instance` (string)
    Request path where the error occurred. Present on some errors, such as INTERNAL_ERROR.

  - `traceId` (string)
    Only on INTERNAL_ERROR. Send it to support to locate the occurrence.