> ## Documentation Index
> Fetch the complete documentation index at: https://docs.3xpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CashOut

> Cria uma nova transação de saída (cash-out). O usuário deve incluir uma assinatura RSA no cabeçalho `signature` para autenticar a requisição.

# Cash-out (exposes)

## Autenticação

* `ApiKeyGuard` + `SignatureGuard`
* Envie `api_key`, `api_secret` e `signature` nos headers

## Body (CashOutDto)

```json theme={null}
{
  "transaction": {
    "amount": 123.45,
    "key": "chave-pix-ou-qr",
    "pixType": "CPF|CNPJ|EMAIL|PHONE|RANDOM|QRCODE",
    "external_id": "id-externo-do-cliente",
    "callback_url": "https://seu-callback.com/opcional"
  }
}
```

### Regras

* Para `pixType diferente de QRCODE`: `amount` é obrigatório e > 0.
* Para `pixType igual a QRCODE`:
  * `amount` vem do QRCODE, ou seja não precisa ser enviado na requisição.
  * Se o QR estiver expirado, retorna 400 com `"qrcode já expirado"`.

## Exemplo – Chave Pix comum (CPF)

```http theme={null}
POST /transaction/cash-out
api_key: SEU_API_KEY
api_secret: SEU_API_SECRET
signature: <assinatura>
Content-Type: application/json

{
  "transaction": {
    "amount": 150.00,
    "key": "12345678901",
    "pixType": "CPF",
    "external_id": "order-123",
    "callback_url": "https://meu-callback.com/cashout"
  }
}
```

### Resposta (sucesso)

```json theme={null}
{
  "status": "success",
  "payment": {
    "status": "pending",
    "transaction_id": "generated-uuid",
    "payment_code": null,
    "link": null,
    "total": 150
  }
}
```

## Exemplo – Pix via QR Code (EMV completo, sem amount)

```http theme={null}
POST /transaction/cash-out
api_key: SEU_API_KEY
api_secret: SEU_API_SECRET
signature: <assinatura>
Content-Type: application/json

{
  "transaction": {
    "key": "00020126780014br.gov.bcb.pix0136f4c6089a-bfde-4c00-a2d9-9eaa584b02190216CobrancaEstatica5204000053039865406546.285802BR5903Pix6008BRASILIA6229...6304ABCD",
    "pixType": "QRCODE",
    "external_id": "order-456",
    "callback_url": "https://meu-callback.com/cashout"
  }
}
```

### Resposta (sucesso)

```json theme={null}
{
  "status": "success",
  "payment": {
    "status": "pending",
    "transaction_id": "generated-uuid",
    "payment_code": null,
    "link": null,
    "total": 546.28
  }
}
```


## OpenAPI

````yaml POST /transaction/cash-out
openapi: 3.0.1
info:
  title: 3X Pay Gateway
  description: >-
    Para autenticar as rotas dessa API são necessario ter em mãos a
    **api_secret** e **api_key** da sua conta. Este podem ser encontrados dentro
    do painel https://app.3xpay.co acessando a página de Configurações e
    clicando na opção de Credencias de API.
  version: 1.0.0
servers:
  - url: https://gateway.3xpay.co
security:
  - apiKeyAuth: []
    apiSecretAuth: []
tags:
  - name: Transações
    description: Operações relacionadas a transações financeiras
  - name: Webhooks
    description: Notificações de eventos da API
  - name: Balance
    description: Operações relacionadas ao saldo da conta
  - name: Sub-accounts
    description: Operações relacionadas a subcontas BaaS
  - name: MED Contest
    description: >-
      Endpoints server-to-server para responder a solicitações de MED (Mecanismo
      Especial de Devolução do Pix)
paths:
  /transaction/cash-out:
    post:
      tags:
        - Transações
      summary: CashOut
      description: >-
        Cria uma nova transação de saída (cash-out). O usuário deve incluir uma
        assinatura RSA no cabeçalho `signature` para autenticar a requisição.
      operationId: createCashOut
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashOutRequest'
      responses:
        '201':
          description: Transação criada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashOutResponse'
        '400':
          description: Erro de validação ou QR Code expirado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                qrcodeExpired:
                  summary: QR Code expirado
                  value:
                    error: 400
                    message: qrcode já expirado
components:
  schemas:
    CashOutRequest:
      type: object
      properties:
        transaction:
          type: object
          required:
            - key
            - callback_url
            - external_id
            - pixType
          properties:
            key:
              type: string
              description: >-
                Chave PIX do destinatário ou EMV completo do QR Code para
                pixType=QRCODE
            amount:
              type: number
              description: >-
                Valor a ser transacionado. Obrigatório exceto quando
                pixType=QRCODE (valor inferido do QR).
            callback_url:
              type: string
              description: A URL para a qual o callback da transação será enviado
            external_id:
              type: string
              description: >-
                O identificador externo para a transação (pode ser sobrescrito
                com o txid quando pixType=QRCODE)
            pixType:
              type: string
              description: Tipo da chave PIX
              enum:
                - CPF
                - CNPJ
                - PHONE
                - EMAIL
                - RANDOM
                - QRCODE
    CashOutResponse:
      type: object
      properties:
        status:
          type: string
          description: Status da transação
          example: success
        payment:
          type: object
          properties:
            status:
              type: string
              description: Status do pagamento
              example: pending
            transaction_id:
              type: string
              description: ID da transação
              example: 3b7abeda-205a-4439-a078-957e3f37c330
            payment_code:
              type: string
              description: Código de pagamento
            link:
              type: string
              description: Link para pagamento
            total:
              type: number
              description: Valor total
              example: 2
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api_key
    apiSecretAuth:
      type: apiKey
      in: header
      name: api_secret

````