### GET /v1/webhook-config

Source: https://devs.pagniv.com/docs/webhooks

Retrieves a list of all webhook configurations associated with the organization.

```APIDOC
## GET /v1/webhook-config

### Description
Returns a list of all registered webhooks for the authenticated organization. Note: The secret is not returned in this response.

### Method
GET

### Endpoint
/v1/webhook-config

### Response
#### Success Response (200)
- **data** (array) - List of webhook objects

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": "550e8400-...",
      "url": "https://seusite.com/webhooks/pagniv",
      "events": ["charge.paid"],
      "isActive": true
    }
  ]
}
```

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

### POST /v1/charges

Source: https://devs.pagniv.com/docs/api-keys

Example of how to use the API key to authenticate a request to create a new charge.

```APIDOC
## POST /v1/charges

### Description
Creates a new charge in the Pagniv system. This endpoint requires an API key passed in the request header.

### Method
POST

### Endpoint
https://api.pagniv.com/v1/charges

### Parameters
#### Request Body
- **amount** (integer) - Required - The charge amount in cents.
- **description** (string) - Optional - A description for the charge.

### Request Example
{
  "amount": 15000,
  "description": "Pedido #1234"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created charge.
- **status** (string) - The status of the transaction.

#### Response Example
{
  "id": "ch_123456789",
  "status": "pending"
}
```

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

### GET /balance

Source: https://devs.pagniv.com/docs/introducao

Retrieves the current account balance for the authenticated user.

```APIDOC
## GET /balance

### Description
Returns the current balance information for the account associated with the provided API Key.

### Method
GET

### Endpoint
https://api.pagniv.com/v1/balance

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your secret API key (sk_live_ or sk_sandbox_)

### Request Example
curl https://api.pagniv.com/v1/balance \
  -H "X-API-Key: sk_live_sua_chave"

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains balance details

#### Response Example
{
  "success": true,
  "data": {
    "available": 1500.50,
    "currency": "BRL"
  }
}
```

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

### Example Webhook Payload

Source: https://devs.pagniv.com/docs/webhooks

This is an example of the JSON payload that Pagniv sends to your configured webhook URL when a 'charge.paid' event occurs. It includes event details, transaction information, and timestamps. This payload is signed with HMAC-SHA256.

```json
{
  "event": "charge.paid",
  "data": {
    "id": "550e8400-...",
```

```json
    "txid": "pagniv_abc123def456",
    "amount": 15000,
    "netAmount": 14901,
    "status": "PAID",
    "paidAt": "2026-01-15T11:05:00Z",
    "externalId": "pedido-1234"
  },
  "timestamp": "2026-01-15T11:05:01Z"
}
```

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

### GET /v1/balance

Source: https://devs.pagniv.com/docs/carteira

Retrieves the current balance of the wallet, including a breakdown by payment method.

```APIDOC
## GET /v1/balance

### Description
Retrieves the current balance of the wallet, including a breakdown by payment method.

### Method
GET

### Endpoint
/v1/balance

### Authentication
- **X-API-Key** (string) - Required - Your API key in the header `X-API-Key: sk_live_...`.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains balance information.
  - **availableBalance** (integer) - Amount available for withdrawal.
  - **pendingBalance** (integer) - Amount awaiting settlement (D+N).
  - **reservedBalance** (integer) - Amount reserved for open disputes.
  - **blockedBalance** (integer) - Amount blocked due to administrative action.
  - **totalEarned** (integer) - Total gross amount received.
  - **totalWithdrawn** (integer) - Total amount withdrawn.
  - **totalFeesPaid** (integer) - Total amount paid in fees.
  - **breakdown** (object) - Breakdown of balances by payment method.
    - **PIX** (object) - Balance breakdown for PIX.
      - **availableBalance** (integer) - Available balance for PIX.
      - **pendingBalance** (integer) - Pending balance for PIX.
    - **CARD** (object) - Balance breakdown for CARD.
      - **availableBalance** (integer) - Available balance for CARD.
      - **pendingBalance** (integer) - Pending balance for CARD.
    - **BOLETO** (object) - Balance breakdown for BOLETO.
      - **availableBalance** (integer) - Available balance for BOLETO.
      - **pendingBalance** (integer) - Pending balance for BOLETO.

### Response Example
```json
{
  "success": true,
  "data": {
    "availableBalance": 125050,
    "pendingBalance": 30000,
    "reservedBalance": 15000,
    "blockedBalance": 0,
    "totalEarned": 1580000,
    "totalWithdrawn": 1420000,
    "totalFeesPaid": 34950,
    "breakdown": {
      "PIX": { "availableBalance": 110050, "pendingBalance": 20000 },
      "CARD": { "availableBalance": 10000, "pendingBalance": 8000 },
      "BOLETO": { "availableBalance": 5000, "pendingBalance": 2000 }
    }
  }
}
```
```

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

### Store API Key in Environment Variable

Source: https://devs.pagniv.com/docs/autenticacao

This example shows how to securely store your Pagniv API key in an environment variable using a .env file. This is a best practice to avoid hardcoding sensitive credentials directly in your source code.

```bash
# Nunca commite este arquivo
PAGNIV_API_KEY=sk_live_7f3a1b9c4e2d8f6a...
```

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

### Authenticate API Requests using cURL

Source: https://devs.pagniv.com/docs/api-keys

Demonstrates how to perform a POST request to the Pagniv API by including the API key in the X-API-Key header. This example creates a charge and requires a valid key prefix for the chosen environment.

```bash
curl -X POST https://api.pagniv.com/v1/charges \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "description": "Pedido #1234"
  }'
```

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

### GET /v1/disputes

Source: https://devs.pagniv.com/docs/disputas

Retrieves a paginated list of disputes. You can filter disputes by their status.

```APIDOC
## GET /v1/disputes

### Description
Lista paginada de disputas. Filtre por status.

### Method
GET

### Endpoint
/v1/disputes

### Parameters
#### Path Parameters
None

#### Query Parameters
- **status** (string) - Optional - Filters disputes by status (e.g., OPEN, MERCHANT_RESPONDED, UNDER_REVIEW, RESOLVED_MERCHANT, RESOLVED_BUYER).
- **page** (integer) - Optional - Specifies the page number for pagination (default: 1).
- **limit** (integer) - Optional - Specifies the number of items per page (default: 20).

#### Request Body
None

### Request Example
```bash
curl "https://api.pagniv.com/v1/disputes?status=OPEN&page=1" \
  -H "X-API-Key: sk_live_sua_chave"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array) - An array of dispute objects.
  - **id** (string) - The unique identifier for the dispute.
  - **chargeId** (string) - The ID of the charge associated with the dispute.
  - **reason** (string) - The reason for the dispute.
  - **status** (string) - The current status of the dispute.
  - **createdAt** (string) - The timestamp when the dispute was created.
- **meta** (object) - Metadata for pagination.
  - **total** (integer) - Total number of disputes.
  - **page** (integer) - Current page number.
  - **limit** (integer) - Items per page.
  - **pages** (integer) - Total number of pages.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "660e8400-...",
      "chargeId": "550e8400-e29b-41d4-a716-446655440000",
      "reason": "PRODUCT_NOT_RECEIVED",
      "status": "OPEN",
      "createdAt": "2026-01-20T10:00:00Z"
    }
  ],
  "meta": { "total": 5, "page": 1, "limit": 20, "pages": 1 }
}
```
```

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

### GET /v1/webhook-deliveries

Source: https://devs.pagniv.com/docs/webhooks

Retrieves the history of webhook delivery attempts, including status and server responses.

```APIDOC
## GET /v1/webhook-deliveries

### Description
Fetches the delivery logs for webhooks, allowing you to audit successful and failed notification attempts.

### Method
GET

### Endpoint
/v1/webhook-deliveries

### Response
#### Success Response (200)
- **data** (array) - List of delivery history records
```

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

### GET /v1/charges

Source: https://devs.pagniv.com/docs/cobrancas

Retrieves a paginated list of charges with optional filtering by status, method, and date range.

```APIDOC
## GET /v1/charges

### Description
Returns a paginated list of charges. Supports filters by status, method, and period.

### Method
GET

### Endpoint
/v1/charges

### Parameters
#### Query Parameters
- **status** (string) - Optional - PENDING, PAID, EXPIRED, CANCELLED, REFUNDED, DISPUTED
- **paymentMethod** (string) - Optional - PIX, CARD ou BOLETO
- **startDate** (ISO 8601) - Optional - Criadas a partir de
- **endDate** (ISO 8601) - Optional - Criadas até
- **page** (integer) - Optional - Página (padrão: 1)
- **limit** (integer) - Optional - Itens por página (padrão: 20)

### Response Example
{
  "success": true,
  "data": [
    {
      "id": "550e8400-...",
      "amount": 15000,
      "status": "PAID"
    }
  ],
  "meta": { "total": 45, "page": 1, "limit": 10 }
}
```

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

### Retrieve Webhook Deliveries via cURL

Source: https://devs.pagniv.com/docs/webhooks

Fetches a list of webhook deliveries using the GET method. Requires an API key in the header and supports optional query parameters for filtering by status and pagination.

```bash
curl "https://api.pagniv.com/v1/webhook-deliveries?status=DELIVERED&page=1" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### Standard API Response Formats

Source: https://devs.pagniv.com/docs/introducao

Examples of the JSON structure returned by the API for both successful operations and error states. All responses include a success boolean field.

```json
{
  "success": true,
  "data": { ... }
}
```

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo amount é obrigatório."
  }
}
```

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

### GET /v1/charges/{id}

Source: https://devs.pagniv.com/docs/cobrancas

Retrieves full details of a specific charge, including QR Code and payer information.

```APIDOC
## GET /v1/charges/{id}

### Description
Returns all fields of a specific charge, including QR Code and payer data.

### Method
GET

### Endpoint
/v1/charges/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique charge identifier

### Response Example
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PENDING",
    "amount": 15000
  }
}
```

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

### GET /v1/withdrawals

Source: https://devs.pagniv.com/docs/saques

Retrieves a paginated list of withdrawals, with optional filtering by status.

```APIDOC
## GET /v1/withdrawals

### Description
Returns a paginated list of withdrawals. You can filter by status.

### Method
GET

### Endpoint
/v1/withdrawals

### Parameters
#### Query Parameters
- **status** (string) - Optional - PENDING, APPROVED, PROCESSING, COMPLETED, FAILED, REJECTED
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Items per page (default: 20)

### Response
#### Success Response (200)
- **data** (array) - List of withdrawal objects
- **meta** (object) - Pagination metadata

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": "550e8400-...",
      "amount": 50000,
      "status": "COMPLETED"
    }
  ],
  "meta": { "total": 12, "page": 1, "limit": 20 }
}
```

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

### GET /v1/disputes/{id}

Source: https://devs.pagniv.com/docs/disputas

Retrieves detailed information about a specific dispute, including evidence and merchant responses.

```APIDOC
## GET /v1/disputes/{id}

### Description
Retorna detalhes incluindo evidências e resposta do merchant.

### Method
GET

### Endpoint
/v1/disputes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the dispute.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl "https://api.pagniv.com/v1/disputes/{id}" \
  -H "X-API-Key: sk_live_sua_chave"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the dispute details.
  - **id** (string) - The unique identifier for the dispute.
  - **chargeId** (string) - The ID of the charge associated with the dispute.
  - **reason** (string) - The reason for the dispute.
  - **status** (string) - The current status of the dispute.
  - **createdAt** (string) - The timestamp when the dispute was created.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "660e8400-...",
    "chargeId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "PRODUCT_NOT_RECEIVED",
    "status": "OPEN",
    "createdAt": "2026-01-20T10:00:00Z"
  }
}
```
```

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

### GET /v1/charges/{id}/checkout

Source: https://devs.pagniv.com/docs/cobrancas

Public endpoint to retrieve secure data for the payment checkout page.

```APIDOC
## GET /v1/charges/{id}/checkout

### Description
Public endpoint (no authentication) that returns secure data for the checkout page.

### Method
GET

### Endpoint
/v1/charges/{id}/checkout

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique charge identifier

### Response Example
{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "amount": 15000,
    "status": "PENDING",
    "qrCode": "00020126580014br.gov.bcb.pix..."
  }
}
```

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

### GET /v1/withdrawals/{id}

Source: https://devs.pagniv.com/docs/saques

Retrieves the full details of a specific withdrawal by its ID.

```APIDOC
## GET /v1/withdrawals/{id}

### Description
Returns the complete details of a specific withdrawal request.

### Method
GET

### Endpoint
/v1/withdrawals/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the withdrawal

### Response
#### Success Response (200)
- **data** (object) - Withdrawal details

#### Response Example
{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "amount": 50000,
    "status": "PENDING"
  }
}
```

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

### GET /v1/transactions

Source: https://devs.pagniv.com/docs/carteira

Retrieves a paginated list of transactions. Filters can be applied by type, payment method, and date range.

```APIDOC
## GET /v1/transactions

### Description
Retrieves a paginated list of transactions. Filters can be applied by type, payment method, and date range.

### Method
GET

### Endpoint
/v1/transactions

### Authentication
- **X-API-Key** (string) - Required - Your API key in the header `X-API-Key: sk_live_...`.

### Parameters
#### Query Parameters
- **type** (string) - Optional - Transaction type (see Types & Enums).
- **paymentMethod** (string) - Optional - PIX, CARD, or BOLETO.
- **startDate** (date) - Optional - Start date (YYYY-MM-DD).
- **endDate** (date) - Optional - End date (YYYY-MM-DD).
- **page** (integer) - Optional - Page number (default: 1).
- **limit** (integer) - Optional - Items per page (default: 20).

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of transaction objects.
  - **id** (string) - Unique identifier for the transaction.
  - **type** (string) - Type of transaction (e.g., CREDIT).
  - **amount** (integer) - Transaction amount.
  - **description** (string) - Description of the transaction.
  - **createdAt** (string) - Timestamp when the transaction was created (ISO 8601 format).
- **meta** (object) - Metadata for pagination.
  - **total** (integer) - Total number of transactions.
  - **page** (integer) - Current page number.
  - **limit** (integer) - Number of items per page.
  - **pages** (integer) - Total number of pages.

### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "CREDIT",
      "amount": 14901,
      "description": "Pagamento recebido - abc123",
      "createdAt": "2026-01-15T11:05:00Z"
    }
  ],
  "meta": { "total": 230, "page": 1, "limit": 20, "pages": 12 }
}
```
```

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

### GET /v1/webhook-deliveries

Source: https://devs.pagniv.com/docs/webhooks

Retrieves a list of webhook deliveries. You can filter the results by charge ID, status, and control pagination with page and limit parameters.

```APIDOC
## GET /v1/webhook-deliveries

### Description
Retrieves a list of webhook deliveries. You can filter the results by charge ID, status, and control pagination with page and limit parameters.

### Method
GET

### Endpoint
/v1/webhook-deliveries

### Parameters
#### Query Parameters
- **chargeId** (UUID) - Optional - Filter by charge ID.
- **status** (string) - Optional - Filter by status. Possible values: PENDING, DELIVERED, or FAILED.
- **page** (integer) - Optional - Page number. Defaults to 1.
- **limit** (integer) - Optional - Items per page. Defaults to 20, maximum 100.

### Request Example
```json
{
  "example": "curl \"https://api.pagniv.com/v1/webhook-deliveries?status=DELIVERED&page=1\" \
  -H \"X-API-Key: sk_live_sua_chave\""
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - An array of webhook delivery objects.
  - **id** (string) - The unique identifier for the delivery.
  - **chargeId** (string) - The ID of the charge associated with the webhook.
  - **url** (string) - The URL where the webhook was sent.
  - **status** (string) - The delivery status (PENDING, DELIVERED, FAILED).
  - **attempts** (integer) - The number of delivery attempts made.
  - **responseStatus** (integer) - The HTTP status code received from the webhook endpoint.
  - **createdAt** (string) - The timestamp when the delivery was created.
- **meta** (object) - Metadata about the pagination.
  - **total** (integer) - Total number of records.
  - **page** (integer) - Current page number.
  - **limit** (integer) - Items per page.
  - **pages** (integer) - Total number of pages.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "...",
      "chargeId": "...",
      "url": "https://seusite.com/webhooks/pagniv",
      "status": "DELIVERED",
      "attempts": 1,
      "responseStatus": 200,
      "createdAt": "2026-01-15T11:05:02Z"
    }
  ],
  "meta": { "total": 45, "page": 1, "limit": 20, "pages": 3 }
}
```
```

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

### Detail a Dispute (cURL)

Source: https://devs.pagniv.com/docs/disputas

Get detailed information about a specific dispute, including evidence and merchant response. Requires the dispute ID and API key authentication.

```cURL
curl "https://api.pagniv.com/v1/disputes/{id}" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### Get Checkout Link Data

Source: https://devs.pagniv.com/docs/cobrancas

Public endpoint to retrieve secure data required for a payment checkout page. Does not require API authentication.

```cURL
curl "https://api.pagniv.com/v1/charges/{id}/checkout"
```

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

### Get Specific Pix Withdrawal Details using cURL

Source: https://devs.pagniv.com/docs/saques

Fetches the detailed information for a specific Pix withdrawal using its unique ID. The withdrawal ID should be appended to the endpoint path. Authentication is mandatory via the 'X-API-Key' header.

```cURL
curl "https://api.pagniv.com/v1/withdrawals/{id}" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### Create Webhook Configuration (cURL)

Source: https://devs.pagniv.com/docs/webhooks

This snippet demonstrates how to create a new webhook configuration using cURL. It requires an API key and specifies the URL and events to subscribe to. The response includes the webhook's secret, which should be stored securely.

```shell
curl -X POST https://api.pagniv.com/v1/webhook-config \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/pagniv",
    "events": ["charge.paid"]
  }'
```

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

### Authentication Overview

Source: https://devs.pagniv.com/docs/autenticacao

Details on how to authenticate API requests using the X-API-Key header and environment management.

```APIDOC
## Authentication

### Description
All requests to the Pagniv API must be authenticated by providing a valid API Key in the request header.

### Header
- **X-API-Key** (string) - Required - Your unique API key generated via the Pagniv Dashboard.

### Environments
- **Production**: Keys prefixed with `sk_live_` process real Pix transactions.
- **Sandbox**: Keys prefixed with `sk_sandbox_` are for testing purposes only.

### Request Example
```bash
curl https://api.pagniv.com/v1/balance \
  -H "X-API-Key: sk_live_your_key_here"
```

### Error Handling
- **401 UNAUTHORIZED**: The API Key is missing or invalid.
- **403 FORBIDDEN**: The provided key lacks permission for the requested operation.
- **403 ORG_BLOCKED**: The organization account is blocked; contact support.
```

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

### List Webhook Configurations (cURL)

Source: https://devs.pagniv.com/docs/webhooks

This snippet shows how to retrieve a list of all configured webhooks for an organization using cURL. It requires an API key for authentication. The response contains details about each webhook, excluding the secret.

```shell
curl "https://api.pagniv.com/v1/webhook-config" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### POST /v1/webhook-config

Source: https://devs.pagniv.com/docs/webhooks

Creates a new webhook configuration to receive event notifications. Each organization can have up to 5 active webhooks.

```APIDOC
## POST /v1/webhook-config

### Description
Registers a new URL to receive real-time event notifications. If no secret is provided, one will be auto-generated.

### Method
POST

### Endpoint
/v1/webhook-config

### Parameters
#### Request Body
- **url** (string) - Required - HTTPS URL that will receive the webhooks
- **secret** (string) - Optional - HMAC secret (min 16 chars)
- **events** (array) - Optional - List of event types to filter (e.g., ["charge.paid"])

### Request Example
{
  "url": "https://seusite.com/webhooks/pagniv",
  "events": ["charge.paid", "charge.expired"]
}

### Response
#### Success Response (201)
- **id** (string) - Webhook unique identifier
- **url** (string) - Configured notification URL
- **secret** (string) - HMAC secret for signature verification
- **events** (array) - List of subscribed events

#### Response Example
{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "url": "https://seusite.com/webhooks/pagniv",
    "secret": "84bddbc2e93d...",
    "events": ["charge.paid", "charge.expired"],
    "isActive": true
  }
}
```

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

### POST /v1/charges

Source: https://devs.pagniv.com/docs/cobrancas

Creates a new Pix charge. Returns the QR Code and copy-paste code for the payment.

```APIDOC
## POST /v1/charges

### Description
Creates a new Pix charge. Returns the QR Code and copy-paste code.

### Method
POST

### Endpoint
/v1/charges

### Parameters
#### Request Body
- **amount** (number) - Required - Valor em centavos (mín. 100 = R$ 1,00)
- **description** (string) - Optional - Descrição da cobrança
- **externalId** (string) - Optional - ID externo para referência (idempotente)
- **payerName** (string) - Optional - Nome do pagador
- **payerEmail** (string) - Optional - Email do pagador
- **payerDocument** (string) - Optional - CPF/CNPJ do pagador
- **expiresIn** (integer) - Optional - Expiração em segundos (padrão: 3600)

### Request Example
{
  "amount": 15000,
  "description": "Pedido #1234",
  "externalId": "pedido-1234",
  "expiresIn": 1800
}

### Response
#### Success Response (201)
- **id** (string) - Charge ID
- **txid** (string) - Transaction ID
- **qrCode** (string) - Pix QR Code string

#### Response Example
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "txid": "pagniv_abc123def456",
    "amount": 15000,
    "status": "PENDING",
    "qrCode": "00020126580014br.gov.bcb.pix..."
  }
}
```

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

### Test API Connection with cURL

Source: https://devs.pagniv.com/docs/introducao

A basic cURL request to verify connectivity to the Pagniv balance endpoint. Requires an active API Key provided in the X-API-Key header.

```bash
curl https://api.pagniv.com/v1/balance \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### Consultar Saldo da Carteira (cURL)

Source: https://devs.pagniv.com/docs/carteira

Retrieves the current balance of the Pagniv wallet, including available, pending, reserved, and blocked amounts. Requires an API key for authentication.

```bash
curl "https://api.pagniv.com/v1/balance" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### POST /v1/disputes

Source: https://devs.pagniv.com/docs/disputas

Opens a dispute for a paid charge. You can specify the reason for the dispute and provide an optional detailed description.

```APIDOC
## POST /v1/disputes

### Description
Abre uma disputa para uma cobrança paga. Motivos aceitos: PRODUCT_NOT_RECEIVED, PRODUCT_NOT_AS_DESCRIBED, DUPLICATE_CHARGE, UNRECOGNIZED_CHARGE, OTHER.

### Method
POST

### Endpoint
/v1/disputes

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chargeId** (UUID) - Required - ID da cobrança
- **reason** (string) - Required - Motivo (ver Tipos & Enums)
- **description** (string) - Optional - Descrição detalhada

### Request Example
```json
{
  "chargeId": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "PRODUCT_NOT_RECEIVED",
  "description": "Produto não entregue após 30 dias"
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the dispute details.
  - **id** (string) - The unique identifier for the dispute.
  - **chargeId** (string) - The ID of the charge associated with the dispute.
  - **reason** (string) - The reason for the dispute.
  - **status** (string) - The current status of the dispute (e.g., OPEN).
  - **createdAt** (string) - The timestamp when the dispute was created.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "660e8400-...",
    "chargeId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "PRODUCT_NOT_RECEIVED",
    "status": "OPEN",
    "createdAt": "2026-01-20T10:00:00Z"
  }
}
```
```

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

### Pagination and Error Handling

Source: https://devs.pagniv.com/docs/introducao

Standard patterns for handling paginated list responses and API error states.

```APIDOC
## Pagination and Error Handling

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve (default: 1)
- **limit** (integer) - Optional - Number of items per page (default: 20)

### Meta Response
When listing resources, the response includes a meta object:
{
  "meta": { "total": 150, "page": 1, "limit": 20, "pages": 8 }
}

### Error Response Format
If a request fails, the API returns a 4xx or 5xx status code with the following structure:
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo amount é obrigatório."
  }
}
```

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

### Open a Dispute (cURL)

Source: https://devs.pagniv.com/docs/disputas

Open a dispute for a paid charge. Requires the charge ID and a reason. An optional detailed description can be provided. Authentication is done via API key.

```cURL
curl -X POST https://api.pagniv.com/v1/disputes \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "chargeId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "PRODUCT_NOT_RECEIVED",
    "description": "Produto não entregue após 30 dias"
  }'
```

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

### Create Pix Charge

Source: https://devs.pagniv.com/docs/cobrancas

Creates a new Pix payment request. Requires an amount in cents and optional metadata such as description, external ID, and payer information.

```cURL
curl -X POST https://api.pagniv.com/v1/charges \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "description": "Pedido #1234",
    "externalId": "pedido-1234",
    "expiresIn": 1800
  }'
```

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

### Accept a Dispute (cURL)

Source: https://devs.pagniv.com/docs/disputas

Accept a dispute on behalf of the merchant. This action will refund the buyer. If the reserved balance is insufficient, a DISPUTE_DEFICIT will be applied to future settlements. Requires API key authentication.

```cURL
curl -X POST "https://api.pagniv.com/v1/disputes/{id}/accept" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### Listar Transações (cURL)

Source: https://devs.pagniv.com/docs/carteira

Fetches a paginated list of transactions from the Pagniv account. Supports filtering by type, payment method, and date range. Requires an API key for authentication.

```bash
curl "https://api.pagniv.com/v1/transactions?type=CREDIT&page=1" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### POST /v1/withdrawals

Source: https://devs.pagniv.com/docs/saques

Creates a new Pix withdrawal request for the specified key.

```APIDOC
## POST /v1/withdrawals

### Description
Creates a new Pix withdrawal request for the provided Pix key.

### Method
POST

### Endpoint
/v1/withdrawals

### Parameters
#### Request Body
- **amount** (number) - Required - Value in cents (min 100)
- **pixKey** (string) - Required - Destination Pix key
- **pixKeyType** (string) - Required - CPF, CNPJ, EMAIL, PHONE or EVP

### Request Example
{
  "amount": 50000,
  "pixKey": "12345678901",
  "pixKeyType": "CPF"
}

### Response
#### Success Response (201)
- **id** (string) - Withdrawal ID
- **amount** (number) - Amount in cents
- **status** (string) - Current status

#### Response Example
{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "amount": 50000,
    "fee": 200,
    "netAmount": 49800,
    "status": "PENDING",
    "pixKey": "12345678901",
    "pixKeyType": "CPF",
    "createdAt": "2026-01-15T14:00:00Z"
  }
}
```

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

### Webhook Deliveries Response Schema

Source: https://devs.pagniv.com/docs/webhooks

Represents the JSON structure returned by the API upon a successful request. Includes a success flag, a list of delivery objects, and metadata for pagination.

```json
{
  "success": true,
  "data": [
    {
      "id": "...",
      "chargeId": "...",
      "url": "https://seusite.com/webhooks/pagniv",
      "status": "DELIVERED",
      "attempts": 1,
      "responseStatus": 200,
      "createdAt": "2026-01-15T11:05:02Z"
    }
  ],
  "meta": { "total": 45, "page": 1, "limit": 20, "pages": 3 }
}
```

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

### List Disputes (cURL)

Source: https://devs.pagniv.com/docs/disputas

Retrieve a paginated list of disputes. Disputes can be filtered by status. Requires API key authentication. Default pagination is 20 items per page.

```cURL
curl "https://api.pagniv.com/v1/disputes?status=OPEN&page=1" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### POST /v1/disputes/{id}/accept

Source: https://devs.pagniv.com/docs/disputas

Accepts a dispute. The reserved amount is refunded to the buyer. If the reservation is insufficient, the difference will be covered by future earnings.

```APIDOC
## POST /v1/disputes/{id}/accept

### Description
Aceita a disputa. Valor reservado é estornado ao comprador. Se reserva insuficiente, diferença fica como DISPUTE_DEFICIT e será coberta nos próximos recebimentos.

### Method
POST

### Endpoint
/v1/disputes/{id}/accept

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the dispute to accept.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X POST "https://api.pagniv.com/v1/disputes/{id}/accept" \
  -H "X-API-Key: sk_live_sua_chave"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the updated dispute status.
  - **id** (string) - The unique identifier for the dispute.
  - **status** (string) - The updated status of the dispute (e.g., RESOLVED_BUYER).

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "660e8400-...",
    "status": "RESOLVED_BUYER"
  }
}
```
```

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

### Pagination Metadata

Source: https://devs.pagniv.com/docs/introducao

The structure of the meta object returned in list endpoints to facilitate pagination. Includes total count, current page, limit per page, and total pages.

```json
"meta": { "total": 150, "page": 1, "limit": 20, "pages": 8 }
```

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

### Retrieve Charge Details

Source: https://devs.pagniv.com/docs/cobrancas

Fetches full details for a specific charge by its ID, including QR code data and current status.

```cURL
curl "https://api.pagniv.com/v1/charges/{id}" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### List Pix Charges

Source: https://devs.pagniv.com/docs/cobrancas

Retrieves a paginated list of charges. Supports filtering by status, payment method, and date ranges.

```cURL
curl "https://api.pagniv.com/v1/charges?status=PAID&page=1&limit=10" \
  -H "X-API-Key: sk_live_sua_chave"
```

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

### Request Pix Withdrawal using cURL

Source: https://devs.pagniv.com/docs/saques

Initiates a Pix withdrawal to a specified Pix key. Requires the amount, Pix key, and Pix key type. The API key must be included in the 'X-API-Key' header.

```cURL
curl -X POST https://api.pagniv.com/v1/withdrawals \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "pixKey": "empresa@email.com",
    "pixKeyType": "EMAIL"
  }'
```

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

### POST /v1/disputes/{id}/contest

Source: https://devs.pagniv.com/docs/disputas

Contests a dispute by providing a response and optional evidence. The dispute status changes to MERCHANT_RESPONDED.

```APIDOC
## POST /v1/disputes/{id}/contest

### Description
Contesta a disputa com resposta e evidências. Status muda para MERCHANT_RESPONDED.

### Method
POST

### Endpoint
/v1/disputes/{id}/contest

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the dispute to contest.

#### Query Parameters
None

#### Request Body
- **response** (string) - Required - A detailed response to the dispute.
- **evidences** (string[]) - Optional - An array of URLs pointing to evidence files.

### Request Example
```json
{
  "response": "Produto entregue em 10/01. Rastreio: AB123456BR",
  "evidences": ["https://storage.example.com/comprovante.pdf"]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the updated dispute status.
  - **id** (string) - The unique identifier for the dispute.
  - **status** (string) - The updated status of the dispute (e.g., MERCHANT_RESPONDED).

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "660e8400-...",
    "status": "MERCHANT_RESPONDED"
  }
}
```
```

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

### Contest a Dispute (cURL)

Source: https://devs.pagniv.com/docs/disputas

Contest a dispute by providing a response and optional evidence. This action updates the dispute status to MERCHANT_RESPONDED. Requires API key authentication.

```cURL
curl -X POST https://api.pagniv.com/v1/disputes/{id}/contest \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "response": "Produto entregue em 10/01. Rastreio: AB123BR",
    "evidences": ["https://storage.example.com/comprovante.pdf"]
  }'
```

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

### Verify Webhook Signature (Node.js)

Source: https://devs.pagniv.com/docs/webhooks

This Node.js function verifies the HMAC-SHA256 signature of an incoming webhook payload. It takes the raw request body, the signature header, and the webhook secret as input. It returns true if the signature is valid, and false otherwise. This is crucial for ensuring the authenticity of received webhook events.

```javascript
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const receivedSig = signatureHeader.replace('sha256=', '');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(receivedSig),
    Buffer.from(expected)
  );
}
```

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

### List Pix Withdrawals using cURL

Source: https://devs.pagniv.com/docs/saques

Retrieves a paginated list of Pix withdrawals. Supports filtering by status and pagination parameters like page number and limit. Authentication is required via the 'X-API-Key' header.

```cURL
curl "https://api.pagniv.com/v1/withdrawals?status=COMPLETED&page=1" \
  -H "X-API-Key: sk_live_sua_chave"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.