Pluggoucash

https://docs.pluggoucash.com
Admin
Pluggoucash is a payment intermediation platform API that enables developers to integrate PIX...
Tokens:28,937
Snippets:149
Trust Score:4.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Create Withdrawal Request Example

Source: https://docs.pluggoucash.com/api-reference/withdrawals/create

This example shows the structure of a request to create a withdrawal. Ensure the amount is in cents.

```yaml
openapi: 3.1.0
info:
  title: Pluggou API
  description: API de intermediação de pagamentos da Pluggou
  version: 1.0.0
servers:
  - url: https://api.pluggoutech.com/api
security:
  - publicKey: []
    secretKey: []
paths:
  /withdrawals:
    post:
      tags:
        - Transferências
      summary: Solicitar transferência
      description: >-
        Solicita uma transferência (saque) via PIX para a chave informada. O
        valor é debitado do saldo disponível na sua conta.
      operationId: createWithdrawal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWithdrawalRequest'
            example:
              amount: 50000
              key_type: cpf
              key_value: '12345678909'
      responses:
        '201':
          description: Saque solicitado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWithdrawalSuccess'
              example:
                success: true
                message: Saque solicitado e processado com sucesso!
                data:
                  id: e5f6a1b2-c3d4-7890-efgh-4567890abcde
                  amount: 50000
                  liquid_amount: 50000
                  pix_key_type: cpf
                  pix_key: '12345678909'
                  status: pending
                  created_at: '2026-01-29 14:58:00'
        '400':
          description: Erro de regra de negócio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                saldo_insuficiente:
                  summary: Saldo insuficiente
                  value:
                    success: false
                    message: Saldo insuficiente para saque.
                    data:
                      available_balance: 30000
                      requested_amount: 50000
                valor_minimo:
                  summary: Valor mínimo não atingido
                  value:
                    success: false
                    message: O valor mínimo para saque é R$ 10,00.
                    data: null
                limite_por_solicitacao:
                  summary: Limite por solicitação excedido
                  value:
                    success: false
                    message: >-
                      O valor solicitado ultrapassa o limite por solicitação de
                      saque.
                    data:
                      valid: false
                      limit: 500000
                      requested: 600000
                limite_diario:
                  summary: Limite diário excedido
                  value:
                    success: false
                    message: O valor solicitado ultrapassa o limite diário de saques.
                    data:
                      valid: false
                      daily_limit: 1000000
                      withdrawn_today: 800000
                      remaining: 200000
                      requested: 500000
                valor_liquido_zero:
                  summary: Valor líquido zero após taxas
                  value:
                    success: false
                    message: O valor do saque após as taxas deve ser maior que R$ 0,00.
                    data: null
                fora_horario:
                  summary: Fora do horário de funcionamento
                  value:
                    success: false
                    message: >-
                      Saques estão disponíveis apenas das 09:00 às 22:00. Tente
                      novamente dentro do horário.
                    data: null
        '401':
          description: Erro de autenticação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
              examples:
                credenciais_ausentes:
                  summary: Credenciais ausentes
                  value:
                    error: Credenciais inválidas
                    message: Chave pública e chave privada são obrigatórias
                credenciais_invalidas:
                  summary: Credenciais inválidas
                  value:
                    error: Credenciais inválidas
                    message: Chave não encontrada ou inativa
        '403':
          description: Erro de permissão
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                credencial_sem_permissao:
                  summary: Sem permissão de cashout
                  value:
                    success: false
                    message: >-
                      Esta credencial não tem permissão para realizar esta
                      operação.

```

--------------------------------

### Webhook Reception Example

Source: https://docs.pluggoucash.com/api-reference/webhooks

This example demonstrates how to receive a webhook, queue it for asynchronous processing, and immediately respond with a 200 OK status to avoid timeouts.

```APIDOC
## POST /webhook

### Description
Receives webhook notifications from Pluggou, validates authenticity, queues the event for asynchronous processing, and responds immediately to ensure timely delivery.

### Method
POST

### Endpoint
/webhook

### Parameters
#### Request Body
- **event** (object) - Required - The event data sent by Pluggou.

#### Headers
- **Content-Type** (string) - Required - Always `application/json`.
- **X-Webhook-Event-ID** (string) - Required - Unique UUID to ensure idempotency.
- **X-Webhook-Code** (string) - Required - Security code to validate the webhook's origin.
- **User-Agent** (string) - Required - Always `Pluggou-Webhook/1.0`.

### Request Example
```json
{
  "event": {
    "type": "payment.confirmed",
    "data": {
      "id": "evt_12345",
      "amount": 10000,
      "currency": "BRL"
    }
  }
}
```

### Response
#### Success Response (200)
- **received** (boolean) - Indicates that the webhook was successfully received and queued for processing.

#### Response Example
```json
{
  "received": true
}
```

#### Error Response (401)
- **error** (string) - "Código de webhook inválido" if the `X-Webhook-Code` header does not match the expected value.
```

--------------------------------

### Example Withdrawal Webhook Received

Source: https://docs.pluggoucash.com/api-reference/withdrawals/webhook

This example demonstrates how to simulate receiving a withdrawal webhook from Pluggou. It shows the structure of the POST request, including headers and the JSON payload.

```bash
curl -X POST https://seusite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event-ID: b2c3d4e5-f6a1-7890-bcde-234567890abc" \
  -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
  -H "User-Agent: Pluggou-Webhook/1.0" \
  -d '{
    "id": "d4e5f6a1-b2c3-7890-defg-34567890abcd",
    "event_type": "withdrawal",
    "data": {
        "id": "e5f6a1b2-c3d4-7890-efgh-4567890abcde",
        "e2e_id": "E12345678202301011234abcdefghijkl",
        "amount": 50000,
        "liquid_amount": 50000,
        "pix_type": "cpf",
        "pix_key": "12345678909",
        "status": "paid",
        "paid_at": "2026-01-29 15:00:00",
        "created_at": "2026-01-29 14:58:00"
    }
  }'
```

--------------------------------

### Withdrawal Webhook Example

Source: https://docs.pluggoucash.com/api-reference/withdrawals/webhook

This example demonstrates how to receive a withdrawal webhook from Pluggou. It shows the structure of the POST request, including headers and the JSON payload, and provides a sample payload with details of a withdrawal event.

```APIDOC
## POST /webhook

### Description
Receives webhook notifications for withdrawal status changes.

### Method
POST

### Endpoint
`https://seusite.com/webhook`

### Headers
- **Content-Type**: `application/json`
- **X-Webhook-Event-ID**: Unique ID for the webhook event.
- **X-Webhook-Code**: Authentication code for the webhook.
- **User-Agent**: `Pluggou-Webhook/1.0`

### Request Body

#### Fields
- **id** (string (UUID)) - Required - Unique identifier for this webhook event.
- **event_type** (string) - Required - Always `"withdrawal"` for withdrawal webhooks.
- **data** (object) - Required - Contains details about the withdrawal.
  - **id** (string (UUID)) - Required - Unique identifier of the withdrawal.
  - **e2e_id** (string | null) - Optional - End-to-end PIX identifier for outgoing PIX, generated by the bank. Available only after the transfer is processed.
  - **amount** (integer) - Required - Total withdrawal amount in cents.
  - **liquid_amount** (integer) - Required - Net amount transferred in cents (after withdrawal fees, if any).
  - **pix_type** (string) - Required - Type of the destination PIX key. Possible values: `cpf`, `cnpj`, `email`, `phone`, `random`.
  - **pix_key** (string) - Required - Value of the destination PIX key for the withdrawal.
  - **status** (string) - Required - Current status of the withdrawal (see possible statuses below).
  - **paid_at** (string | null) - Optional - Date/time when the withdrawal was effective in the format `"YYYY-MM-DD HH:mm:ss"`. `null` if not yet paid.
  - **created_at** (string) - Required - Date/time of withdrawal creation in the format `"YYYY-MM-DD HH:mm:ss"`.

### Request Example
```json
{
  "id": "d4e5f6a1-b2c3-7890-defg-34567890abcd",
  "event_type": "withdrawal",
  "data": {
    "id": "e5f6a1b2-c3d4-7890-efgh-4567890abcde",
    "e2e_id": "E12345678202301011234abcdefghijkl",
    "amount": 50000,
    "liquid_amount": 50000,
    "pix_type": "cpf",
    "pix_key": "12345678909",
    "status": "paid",
    "paid_at": "2026-01-29 15:00:00",
    "created_at": "2026-01-29 14:58:00"
  }
}
```

### Response

#### Success Response (200)
- **status** (string) - Indicates success of webhook reception.

#### Response Example
```json
{
  "message": "Webhook received successfully"
}
```

### Possible Statuses
- **pending**: Withdrawal requested and awaiting processing or approval.
- **approved**: Withdrawal approved and being processed by the acquirer.
- **paid**: Withdrawal effective. The amount has been transferred to the destination PIX key.
- **failed**: Withdrawal failed during processing (acquirer error, invalid data, etc.).
- **canceled**: Withdrawal canceled before processing.
- **refunded**: Withdrawal amount reversed and returned to the user's wallet.
```

--------------------------------

### Transaction Webhook Example

Source: https://docs.pluggoucash.com/api-reference/transactions/webhooks

An example of a transaction webhook payload received by your endpoint. This demonstrates the structure and fields included when a transaction status changes.

```APIDOC
## Webhook de transação

Sempre que ocorre uma mudança de status em uma transação, a Pluggou envia um webhook para todos os endpoints ativos cadastrados na sua conta. Para entender o funcionamento geral dos webhooks (headers, segurança, tempo limite, retentativas e idempotência), consulte o [guia geral de Webhooks](/api-reference/webhooks).

### Request Example
```bash
curl -X POST https://seusite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
  -H "User-Agent: Pluggou-Webhook/1.0" \
  -d 
{
  "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
  "event_type": "transaction",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "payment_method": "pix",
    "e2e_id": "E12345678202301011234abcdefghijkl",
    "amount": 10000,
    "platform_tax": 149,
    "liquid_amount": 9851,
    "status": "paid",
    "paid_at": "2026-01-29 14:30:00",
    "created_at": "2026-01-29 14:25:00"
  }
}
```

### Payload Fields

| Campo                 | Tipo           | Descrição                                                                                             |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `id`                  | string (UUID)  | Identificador único deste evento de webhook.                                                          |
| `event_type`          | string         | Sempre `"transaction"` para webhooks de transação.                                                    |
| `data.id`             | string (UUID)  | Identificador único da transação.                                                                     |
| `data.payment_method` | string         | Método de pagamento utilizado (ex: `"pix"`).                                                          |
| `data.e2e_id`         | string \| null | Identificador end-to-end do PIX gerado pelo banco. Disponível apenas após a confirmação do pagamento. |
| `data.amount`         | integer        | Valor total da transação em centavos.                                                                 |
| `data.platform_tax`   | integer        | Taxa total cobrada pela plataforma em centavos.                                                       |
| `data.liquid_amount`  | integer        | Valor líquido que o usuário receberá em centavos (`amount - platform_tax`).                           |
| `data.status`         | string         | Status atual da transação (veja tabela abaixo).                                                       |
| `data.paid_at`        | string \| null | Data/hora do pagamento no formato `"YYYY-MM-DD HH:mm:ss"`. `null` se ainda não foi pago.              |
| `data.created_at`     | string         | Data/hora de criação da transação no formato `"YYYY-MM-DD HH:mm:ss"`.                                 |

### Possible Statuses

| Status       | Significado                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `pending`    | Transação criada e aguardando pagamento pelo comprador.                     |
| `paid`       | Pagamento confirmado. O valor líquido foi creditado na carteira do usuário. |
| `failed`     | Pagamento falhou ou foi recusado pela instituição financeira.               |
| `canceled`   | Transação cancelada (expiração ou cancelamento manual).                     |
| `refunded`   | Valor devolvido ao pagador após o pagamento ter sido confirmado.            |
| `chargeback` | Contestação ou disputa aberta pelo pagador (MED, infração, bloqueio).       |
```

--------------------------------

### Authenticated Request Example

Source: https://docs.pluggoucash.com/api-reference/authentication

This example demonstrates how to make an authenticated POST request to the transactions endpoint using cURL. It includes the necessary Content-Type, X-Public-Key, and X-Secret-Key headers.

```APIDOC
## POST /api/transactions

### Description
This endpoint is used to initiate a new transaction. Authentication is required.

### Method
POST

### Endpoint
https://api.pluggoutech.com/api/transactions

### Headers
- **Content-Type** (string) - Required - Specifies the format of the request body, typically `application/json`.
- **X-Public-Key** (string) - Required - Your public API access key.
- **X-Secret-Key** (string) - Required - Your secret API access key.

### Request Example
```bash
curl -X POST https://api.pluggoutech.com/api/transactions \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: pk_live_abc123def456..." \
  -H "X-Secret-Key: sk_live_xyz789ghi012..."
```

### Response
#### Success Response (200)
This section is not detailed in the source text.

#### Response Example
This section is not detailed in the source text.
```

--------------------------------

### Recommended Webhook Reception

Source: https://docs.pluggoucash.com/api-reference/webhooks

This example shows how to receive a webhook, queue it for asynchronous processing, and respond immediately with a 200 status code. It includes validation of the webhook code.

```javascript
app.post('/webhook', (req, res) => {
  const event = req.body;
  const webhookCode = req.headers['x-webhook-code'];

  // Valide a autenticidade
  if (webhookCode !== process.env.PLUGGOU_WEBHOOK_CODE) {
    return res.status(401).json({ error: 'Código de webhook inválido' });
  }

  // Salve na fila para processamento assíncrono
  queue.add('process-event', event);

  // Responda 200 imediatamente
  return res.status(200).json({ received: true });
});
```

--------------------------------

### Create Withdrawal Success Response

Source: https://docs.pluggoucash.com/api-reference/withdrawals/create

Example of a successful withdrawal request response. Includes transaction details and status.

```json
{
  "success": true,
  "message": "Saque solicitado e processado com sucesso!",
  "data": {
    "id": "e5f6a1b2-c3d4-7890-efgh-4567890abcde",
    "amount": 50000,
    "liquid_amount": 50000,
    "pix_key_type": "cpf",
    "pix_key": "12345678909",
    "status": "pending",
    "created_at": "2026-01-29 14:58:00"
  }
}
```

--------------------------------

### Webhook Idempotency Handling

Source: https://docs.pluggoucash.com/api-reference/webhooks

This example demonstrates how to implement idempotency for incoming webhooks by checking for a unique event ID in the request header and payload.

```APIDOC
## POST /webhook

### Description
This endpoint receives webhook events from Pluggou. It includes logic to ensure that each event is processed only once, even if received multiple times.

### Method
POST

### Endpoint
/webhook

### Parameters
#### Request Body
- **`id`** (string) - Required - The unique identifier for the webhook event within the payload.

### Request Headers
- **`X-Webhook-Event-ID`** - Required - The unique identifier for the webhook event in the header.

### Request Example
```javascript
// Example of idempotency verification
app.post('/webhook', async (req, res) => {
  const eventId = req.headers['x-webhook-event-id'];

  // Check if this event has already been processed
  const alreadyProcessed = await db.webhookEvents.findOne({ eventId });
  if (alreadyProcessed) {
    return res.status(200).json({ received: true, duplicate: true });
  }

  // Register the event as processed
  await db.webhookEvents.create({ eventId, processedAt: new Date() });

  // Process the event
  queue.add('process-event', req.body);

  return res.status(200).json({ received: true });
});
```

### Response
#### Success Response (200)
- **`received`** (boolean) - Indicates if the webhook was successfully received.
- **`duplicate`** (boolean, optional) - Indicates if the received event was a duplicate.

#### Response Example
```json
{
  "received": true
}
```

#### Duplicate Response Example
```json
{
  "received": true,
  "duplicate": true
}
```

<Tip>
  Even if you return `200` for a duplicate event, it is good practice to log that the event has already been processed and not execute the business logic again.
</Tip>
```

--------------------------------

### Get Withdrawal Balance

Source: https://docs.pluggoucash.com/api-reference/withdrawals/balance

Retrieves the available balance for withdrawal, configured limits, and the remaining daily limit calculated in real-time.

```APIDOC
## GET /withdrawals/balance

### Description
Returns the available balance for withdrawal, configured limits, and the remaining daily limit calculated in real-time.

### Method
GET

### Endpoint
/withdrawals/balance

### Parameters
#### Headers
- **X-Public-Key** (string) - Required - Your public API access key.
- **X-Secret-Key** (string) - Required - Your secret API access key.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - Descriptive message of the result.
- **data** (object) - Contains withdrawal balance details.
  - **available_balance** (integer) - Available balance for withdrawal in cents.
  - **daily_limit_remaining** (integer) - Remaining daily limit in cents. `null` if no daily limit is configured. Calculated in real-time based on `paid` and `pending` withdrawals of the day.
  - **minimum_withdrawal** (integer) - Minimum withdrawal amount in cents.
  - **limits** (object) - Withdrawal limits configured for the account.
    - **per_request** (integer) - Maximum limit per withdrawal request in cents. `null` if no limit is configured.
    - **per_day_total** (integer) - Total daily withdrawal limit in cents. `null` if no limit is configured.

#### Error Response (401)
- **error** (string) - Type of authentication error.
- **message** (string) - Descriptive message of the error.

#### Error Response (403)
- **success** (boolean) - Always `false` in case of error.
- **message** (string) - Descriptive message of the error.
- **data** (object) - Always `null` for simple errors.

#### Error Response (500)
- **success** (boolean) - Always `false` in case of error.
- **message** (string) - Descriptive message of the error.
- **data** (object) - Always `null` for simple errors.

### Request Example
```http
GET /withdrawals/balance
Host: api.pluggoutech.com
X-Public-Key: pk_live_abc123def456...
X-Secret-Key: sk_live_abc123def456...
```

### Response Example (200 OK)
```json
{
  "success": true,
  "message": "Saldo consultado com sucesso!",
  "data": {
    "available_balance": 1250000,
    "daily_limit_remaining": 500000,
    "minimum_withdrawal": 500,
    "limits": {
      "per_request": 500000,
      "per_day_total": 1000000
    }
  }
}
```

### Response Example (401 Unauthorized - Missing Credentials)
```json
{
  "error": "Credenciais inválidas",
  "message": "Chave pública e chave privada são obrigatórias"
}
```

### Response Example (401 Unauthorized - Invalid Credentials)
```json
{
  "error": "Credenciais inválidas",
  "message": "Chave não encontrada ou inativa"
}
```

### Response Example (403 Forbidden)
```json
{
  "success": false,
  "message": "Esta credencial não tem permissão para realizar esta operação.",
  "data": null
}
```

### Response Example (500 Internal Server Error)
```json
{
  "success": false,
  "message": "Ocorreu um erro ao consultar o saldo.",
  "data": null
}
```
```

--------------------------------

### API Error Response Example

Source: https://docs.pluggoucash.com/api-reference/introduction

This JSON structure represents a typical error response from the API, indicating a validation failure with specific field errors.

```json
{
    "success": false,
    "message": "Erro de validação",
    "data": {
        "errors": {
            "campo": ["mensagem de erro"]
        }
    }
}
```

--------------------------------

### Exemplo de Webhook de Transação Recebido

Source: https://docs.pluggoucash.com/api-reference/transactions/webhooks

Este exemplo demonstra o formato de um payload de webhook de transação recebido via cURL. Ele inclui headers essenciais para identificação e o corpo JSON com os detalhes da transação.

```bash
curl -X POST https://seusite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
  -H "User-Agent: Pluggou-Webhook/1.0" \
  -d '{
    "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "event_type": "transaction",
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "payment_method": "pix",
        "e2e_id": "E12345678202301011234abcdefghijkl",
        "amount": 10000,
        "platform_tax": 149,
        "liquid_amount": 9851,
        "status": "paid",
        "paid_at": "2026-01-29 14:30:00",
        "created_at": "2026-01-29 14:25:00"
    }
  }'
```

--------------------------------

### Get Transaction by ID (OpenAPI Specification)

Source: https://docs.pluggoucash.com/api-reference/transactions/get

This OpenAPI 3.1.0 specification defines the GET /transactions/{id} endpoint for retrieving transaction details. It includes parameters, success responses with transaction data, and error responses for authentication, authorization, and not found scenarios.

```yaml
openapi: 3.1.0
info:
  title: Pluggou API
  description: API de intermediação de pagamentos da Pluggou
  version: 1.0.0
servers:
  - url: https://api.pluggoutech.com/api
security:
  - publicKey: []
    secretKey: []
paths:
  /transactions/{id}:
    get:
      tags:
        - Transações
      summary: Consultar transação
      description: >-
        Consulta os dados de uma transação específica pelo seu identificador
        único (UUID).
      operationId: getTransaction
      parameters:
        - name: id
          in: path
          required: true
          description: Identificador único da transação (UUID).
          schema:
            type: string
            format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Transação encontrada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTransactionSuccess'
              example:
                success: true
                message: Transação encontrada com sucesso.
                data:
                  id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  payment_method: pix
                  e2e_id: E12345678202301011234abcdefghijkl
                  amount: 10000
                  platform_tax: 149
                  liquid_amount: 9851
                  status: paid
                  paid_at: '2026-01-29 11:30:00'
                  created_at: '2026-01-29 11:25:00'
        '401':
          description: Erro de autenticação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
              examples:
                credenciais_ausentes:
                  summary: Credenciais ausentes
                  value:
                    error: Credenciais inválidas
                    message: Chave pública e chave privada são obrigatórias
                credenciais_invalidas:
                  summary: Credenciais inválidas
                  value:
                    error: Credenciais inválidas
                    message: Chave não encontrada ou inativa
        '403':
          description: Erro de permissão
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conta_nao_aprovada:
                  summary: Conta não aprovada
                  value:
                    success: false
                    message: >-
                      Sua conta precisa estar aprovada para usar esta
                      funcionalidade.
                    data: null
                conta_bloqueada:
                  summary: Conta bloqueada
                  value:
                    success: false
                    message: Sua conta está bloqueada.
                    data: null
        '404':
          description: Transação não encontrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                message: Transação não encontrada.
                data: null
components:
  schemas:
    GetTransactionSuccess:
      type: object
      properties:
        success:
          type: boolean
          description: Indica se a operação foi bem-sucedida.
        message:
          type: string
          description: Mensagem descritiva do resultado.
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Identificador único da transação (UUID).
            payment_method:
              type: string
              description: 'Método de pagamento utilizado (ex: `pix`).'
            e2e_id:
              type: string
              nullable: true
              description: >-
                Identificador end-to-end do PIX gerado pelo banco. `null` se o
                pagamento ainda não foi confirmado.
            amount:
              type: integer
              description: Valor total da transação em centavos.
            platform_tax:
              type: integer
              description: Valor da taxa da plataforma em centavos.
            liquid_amount:
              type: integer
              description: >-
                Valor líquido creditado na sua conta em centavos (amount -
                platform_tax).
            status:
              type: string
              enum:
                - pending
                - paid
                - failed
                - canceled
                - refunded
                - chargeback
              description: Status atual da transação.
            paid_at:
              type: string
              nullable: true
              description: >-

```

--------------------------------

### Authentication Error: Missing Credentials

Source: https://docs.pluggoucash.com/api-reference/withdrawals/create

Response indicating that both public and private keys are required for authentication.

```json
{
  "error": "Credenciais inválidas",
  "message": "Chave pública e chave privada são obrigatórias"
}
```

--------------------------------

### Get Transaction by ID

Source: https://docs.pluggoucash.com/api-reference/transactions/get

Fetches the details of a specific transaction using its unique identifier (UUID).

```APIDOC
## GET /transactions/{id}

### Description
Consultar os dados de uma transação específica pelo seu identificador único (UUID).

### Method
GET

### Endpoint
/transactions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Identificador único da transação (UUID).

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indica se a operação foi bem-sucedida.
- **message** (string) - Mensagem descritiva do resultado.
- **data** (object) - Contém os detalhes da transação.
  - **id** (string) - Identificador único da transação (UUID).
  - **payment_method** (string) - Método de pagamento utilizado (ex: `pix`).
  - **e2e_id** (string) - Identificador end-to-end do PIX gerado pelo banco. `null` se o pagamento ainda não foi confirmado.
  - **amount** (integer) - Valor total da transação em centavos.
  - **platform_tax** (integer) - Valor da taxa da plataforma em centavos.
  - **liquid_amount** (integer) - Valor líquido creditado na sua conta em centavos (amount - platform_tax).
  - **status** (string) - Status atual da transação. Enum: `pending`, `paid`, `failed`, `canceled`, `refunded`, `chargeback`.
  - **paid_at** (string) - Data e hora em que a transação foi paga.
  - **created_at** (string) - Data e hora em que a transação foi criada.

#### Response Example
```json
{
  "success": true,
  "message": "Transação encontrada com sucesso.",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "payment_method": "pix",
    "e2e_id": "E12345678202301011234abcdefghijkl",
    "amount": 10000,
    "platform_tax": 149,
    "liquid_amount": 9851,
    "status": "paid",
    "paid_at": "2026-01-29 11:30:00",
    "created_at": "2026-01-29 11:25:00"
  }
}
```

#### Error Response (401)
- **error** (string) - Indica o tipo de erro de autenticação.
- **message** (string) - Mensagem detalhada sobre o erro de autenticação.

#### Error Response (403)
- **success** (boolean) - Indica se a operação foi bem-sucedida (sempre false neste caso).
- **message** (string) - Mensagem detalhada sobre o erro de permissão.
- **data** (null) - Campo nulo.

#### Error Response (404)
- **success** (boolean) - Indica se a operação foi bem-sucedida (sempre false neste caso).
- **message** (string) - Mensagem indicando que a transação não foi encontrada.
- **data** (null) - Campo nulo.
```

--------------------------------

### Exemplo de Requisição Autenticada com cURL

Source: https://docs.pluggoucash.com/api-reference/authentication

Demonstra como fazer uma requisição POST autenticada para a API usando cURL. Certifique-se de incluir seus headers `X-Public-Key` e `X-Secret-Key`.

```bash
curl -X POST https://api.pluggoutech.com/api/transactions \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: pk_live_abc123def456..." \
  -H "X-Secret-Key: sk_live_xyz789ghi012..."
```

--------------------------------

### Permission Error: No Cashout Permission

Source: https://docs.pluggoucash.com/api-reference/withdrawals/create

Response indicating that the authenticated credential does not have the necessary permissions to perform cashout operations.

```json
{
  "success": false,
  "message": "Esta credencial não tem permissão para realizar esta operação."
}
```

--------------------------------

### Permission Denied Error

Source: https://docs.pluggoucash.com/api-reference/transactions/guide

This response is returned when the API key used does not have the necessary 'cashin' or 'all' permission to create transactions. Check your credential's access rights.

```json
{
    "success": false,
    "message": "Esta credencial não tem permissão para realizar esta operação.",
    "data": null
}
```

--------------------------------

### Consultar saldo

Source: https://docs.pluggoucash.com/llms.txt

Returns the available balance for withdrawal, configured limits, and the remaining daily limit calculated in real-time.

```APIDOC
## GET /withdrawals/balance

### Description
Returns the available balance for withdrawal, configured limits, and the remaining daily limit calculated in real-time.

### Method
GET

### Endpoint
/withdrawals/balance

### Response
#### Success Response (200)
- **available_balance** (number) - The total available balance.
- **daily_limit** (number) - The configured daily withdrawal limit.
- **remaining_daily_limit** (number) - The remaining amount that can be withdrawn today.

#### Response Example
{
  "available_balance": 1500.75,
  "daily_limit": 5000.00,
  "remaining_daily_limit": 3250.25
}
```

--------------------------------

### List Withdrawals OpenAPI Specification

Source: https://docs.pluggoucash.com/api-reference/withdrawals/list

This OpenAPI 3.1.0 specification defines the GET /withdrawals endpoint. It includes details on query parameters for filtering by ID, amount, status, and dates, as well as the structure of successful and error responses.

```yaml
openapi: 3.1.0
info:
  title: Pluggou API
  description: API de intermediação de pagamentos da Pluggou
  version: 1.0.0
servers:
  - url: https://api.pluggoutech.com/api
security:
  - publicKey: []
    secretKey: []
paths:
  /withdrawals:
    get:
      tags:
        - Transferências
      summary: Listar saques
      description: >-
        Retorna uma lista paginada de saques da sua conta, com suporte a
        diversos filtros por status, valor, data e identificadores.
      operationId: listWithdrawals
      parameters:
        - name: id
          in: query
          description: Busca exata pelo UUID do saque.
          schema:
            type: string
            format: uuid
        - name: e2e_id
          in: query
          description: Busca exata pelo identificador end-to-end.
          schema:
            type: string
        - name: amount_min
          in: query
          description: Valor mínimo em centavos.
          schema:
            type: integer
        - name: amount_max
          in: query
          description: Valor máximo em centavos.
          schema:
            type: integer
        - name: status
          in: query
          description: Filtra por status do saque.
          schema:
            type: string
            enum:
              - pending
              - approved
              - paid
              - failed
              - canceled
              - refunded
          example: paid
        - name: paid_at_min
          in: query
          description: Data/hora mínima de pagamento no formato `Y-m-d H:i:s` (UTC-3).
          schema:
            type: string
        - name: paid_at_max
          in: query
          description: Data/hora máxima de pagamento no formato `Y-m-d H:i:s` (UTC-3).
          schema:
            type: string
        - name: created_at_min
          in: query
          description: Data/hora mínima de criação no formato `Y-m-d H:i:s` (UTC-3).
          schema:
            type: string
          example: '2026-01-01 00:00:00'
        - name: created_at_max
          in: query
          description: Data/hora máxima de criação no formato `Y-m-d H:i:s` (UTC-3).
          schema:
            type: string
          example: '2026-01-31 23:59:59'
        - name: page
          in: query
          description: 'Página da listagem (padrão: 1).'
          schema:
            type: integer
            default: 1
          example: 1
      responses:
        '200':
          description: Saques listados com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWithdrawalsSuccess'
              example:
                success: true
                message: Saques listados com sucesso.
                data:
                  withdrawals:
                    - id: e5f6a1b2-c3d4-7890-efgh-4567890abcde
                      e2e_id: E12345678202301011234abcdefghijkl
                      amount: 50000
                      liquid_amount: 50000
                      pix_type: cpf
                      pix_key: '12345678909'
                      status: paid
                      paid_at: '2026-01-29 12:00:00'
                      created_at: '2026-01-29 11:58:00'
                    - id: f6a1b2c3-d4e5-7890-fghi-567890abcdef
                      e2e_id: null
                      amount: 30000
                      liquid_amount: 30000
                      pix_type: email
                      pix_key: usuario@email.com
                      status: pending
                      paid_at: null
                      created_at: '2026-01-29 10:30:00'
                  pagination:
                    current_page: 1
                    last_page: 3
                    per_page: 10
                    total: 25
        '401':
          description: Erro de autenticação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
              examples:
                credenciais_ausentes:
                  summary: Credenciais ausentes
                  value:
                    error: Credenciais inválidas
                    message: Chave pública e chave privada são obrigatórias
                credenciais_invalidas:
                  summary: Credenciais inválidas
                  value:
                    error: Credenciais inválidas
                    message: Chave não encontrada ou inativa
        '403':
          description: Erro de permissão
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conta_nao_aprovada:
                  summary: Conta não aprovada
                  value:
                    success: false
                    message: >-
                      Sua conta precisa estar aprovada para usar esta

```

--------------------------------

### Formato de Resposta JSON Padrão

Source: https://docs.pluggoucash.com/api-reference/introduction

Todas as requisições e respostas da API são formatadas em JSON, incluindo mensagens de erro. Este é um exemplo de uma resposta de sucesso.

```json
{
    "success": true,
    "message": "Mensagem descritiva",
    "data": { ... }
}
```
Tokens:
Raw