# Create Cash-Out

Submits a PIX payment to an external bank account or PIX key.

The request is validated against available balance and fraud rules, then queued for settlement. The response is 202 Accepted — the payment is not yet settled at this point.

Two destination types are supported:
- PIX — by PIX key (CPF, CNPJ, email, phone, or EVP random key)
- BANK_ACCOUNT — by bank account details (ISPB + branch + account)

This endpoint requires DigitalSignature and X-Idempotency-Key headers.

Once the payment is settled (or fails), ConnectPSP will POST either a CASHOUT_COMPLETED or CASHOUT_FAILED event to your webhookUrl.

Endpoint: POST /cash-out
Version: 2.0.0
Security: bearerAuth

## Header parameters:

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

  - `DigitalSignature` (string, required)
    HMAC-SHA256 hash of the JWT token + your CryptoToken. Required for sensitive operations.
See the Authentication Guide for the exact computation steps.
    Example: "{{DigitalSignature}}"

  - `X-Idempotency-Key` (string)
    A client-generated UUID v4 to guarantee idempotency. If the same key is sent twice, the second request returns the original response without creating a duplicate transaction.
Strongly recommended for all POST operations.
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Request fields (application/json):

  - `amount` (number, required)
    Amount in BRL (Reais). Decimal format.
    Example: 500

  - `externalReference` (string, required)
    Your unique transaction reference. Duplicate references return 409 Conflict.
    Example: "withdraw_xyz789"

  - `description` (string)
    Optional description that may appear on the payee's bank statement.
    Example: "Player withdrawal"

  - `webhookUrl` (string)
    URL to receive settlement events (CASHOUT_COMPLETED, CASHOUT_FAILED, CASHOUT_REFUNDED).
    Example: "https://api.yourdomain.com/webhooks/connectpsp"

  - `payee` (object, required)

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

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

  - `payee.destination` (object, required)

  - `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"

  - `payee.destination.pixKeyType` (string)
    Type of PIX key. Required when type is PIX.
    Enum: "CPF", "CNPJ", "EMAIL", "PHONE", "EVP"

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

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

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

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

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

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

## Response 202 fields (application/json):

  - `transactionId` (string)
    Internal UUID for this transaction.
    Example: "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9"

  - `internalCode` (string)
    ConnectPSP alphanumeric code. Use for polling.
    Example: "IVKPRMOCDY"

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

  - `status` (string)
    Enum: "PROCESSING"

  - `requestedAt` (string)
    Example: "2026-03-10T14:00:00-03:00"

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

  - `type` (string)
    URI identifying the error type.
    Example: "https://connect-psp.redocly.app/errors/insufficient-funds"

  - `title` (string)
    Short, human-readable summary.
    Example: "Insufficient Funds"

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

  - `code` (string)
    Machine-readable error code for programmatic handling.
    Example: "INSUFFICIENT_FUNDS"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."

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

  - `type` (string)
    URI identifying the error type.
    Example: "https://connect-psp.redocly.app/errors/insufficient-funds"

  - `title` (string)
    Short, human-readable summary.
    Example: "Insufficient Funds"

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

  - `code` (string)
    Machine-readable error code for programmatic handling.
    Example: "INSUFFICIENT_FUNDS"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."

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

  - `type` (string)
    URI identifying the error type.
    Example: "https://connect-psp.redocly.app/errors/insufficient-funds"

  - `title` (string)
    Short, human-readable summary.
    Example: "Insufficient Funds"

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

  - `code` (string)
    Machine-readable error code for programmatic handling.
    Example: "INSUFFICIENT_FUNDS"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."

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

  - `type` (string)
    URI identifying the error type.
    Example: "https://connect-psp.redocly.app/errors/insufficient-funds"

  - `title` (string)
    Short, human-readable summary.
    Example: "Insufficient Funds"

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

  - `code` (string)
    Machine-readable error code for programmatic handling.
    Example: "INSUFFICIENT_FUNDS"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."