### curl - Consultar saldo da conta

Source: https://docs.kavropay.online/saldo-conta

Faz uma requisição GET para /v1/balance com autenticação Bearer. Substitua sk_live_SUA_CHAVE_AQUI pela sua chave de API.

```bash
curl https://api.kavropay.online/v1/balance \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

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

### Consultar Cliente - GET /v1/customers/{id}

Source: https://docs.kavropay.online/gestao-clientes

Busca os dados de um cliente específico pelo ID retornado na criação. Requer escopo 'payments:read'. Retorna HTTP 200 OK com os dados do cliente.

```bash
curl https://api.kavropay.online/v1/customers/cus_abc123def456 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

```json
{
  "id": "cus_abc123def456",
  "name": "Renata Alcantara",
  "document": "98765432100",
  "email": "renata@email.com",
  "phone": "21999998888",
  "created_at": "2026-08-26T12:00:00.000Z"
}
```

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

### Listar Cobranças Paginado (GET /v1/charges)

Source: https://docs.kavropay.online/cobrancas-pix

Lista cobranças com parâmetros de consulta como status, limit e offset. A resposta é otimizada para menos de 15ms. Exemplo de requisição usando curl.

```bash
curl "https://api.kavropay.online/v1/charges?status=paid&limit=50&offset=0" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

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

### Listar Clientes - GET /v1/customers

Source: https://docs.kavropay.online/gestao-clientes

Lista clientes com suporte a busca por texto e paginação via parâmetros 'search' e 'limit'. Retorna HTTP 200 OK com um objeto contendo 'data', 'total', 'limit' e 'offset'.

```bash
curl "https://api.kavropay.online/v1/customers?search=Renata&limit=10" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

```json
{
  "data": [
    {
      "id": "cus_abc123def456",
      "name": "Renata Alcantara",
      "document": "98765432100",
      "email": "renata@email.com",
      "phone": "21999998888",
      "created_at": "2026-08-26T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```

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

### Listar Saques Paginados via GET /v1/withdrawals

Source: https://docs.kavropay.online/saques-pix

Exemplo de requisição cURL para listar saques com filtros de status, limite e offset.

```bash
curl "https://api.kavropay.online/v1/withdrawals?status=completed&limit=50&offset=0" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

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

### Consultar Saque via GET /v1/withdrawals/{id}

Source: https://docs.kavropay.online/saques-pix

Exemplo de requisição cURL para buscar os detalhes de um saque específico pelo seu ID.

```bash
curl https://api.kavropay.online/v1/withdrawals/WIT7A28F1B3E4C9D01 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

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

### GET /v1/customers

Source: https://docs.kavropay.online/gestao-clientes

Lists customers with optional search and pagination parameters. Requires authentication via Bearer token.

```APIDOC
## GET /v1/customers

### Description
Lists customers with optional search and pagination parameters. Requires authentication via Bearer token.

### Method
GET

### Endpoint
/v1/customers

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term to filter customers by name or other fields.
- **limit** (integer) - Optional - Maximum number of customers to return.
- **offset** (integer) - Optional - Number of customers to skip for pagination.

### Request Example
curl "https://api.kavropay.online/v1/customers?search=Renata&limit=10" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"

### Response
#### Success Response (200 OK)
- **data** (array) - List of customer objects.
- **total** (integer) - Total number of customers matching the query.
- **limit** (integer) - Maximum number of customers returned.
- **offset** (integer) - Number of customers skipped.

#### Response Example
{
  "data": [
    {
      "id": "cus_abc123def456",
      "name": "Renata Alcantara",
      "document": "98765432100",
      "email": "renata@email.com",
      "phone": "21999998888",
      "created_at": "2026-08-26T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```

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

### GET /v1/charges

Source: https://docs.kavropay.online/cobrancas-pix

Lista cobranças PIX de forma paginada, com filtros por status e limites de paginação. Requer o escopo payments:read.

```APIDOC
## GET /v1/charges

### Description
Lista cobranças PIX de forma paginada, com filtros por status e limites de paginação. Requer o escopo payments:read.

### Method
GET

### Endpoint
/v1/charges

### Parameters
#### Query Parameters
- **status** (string) - Opcional - Filtra por status da cobrança: paid, waiting_payment ou expired.
- **limit** (integer) - Opcional - Número máximo de resultados (1 a 100).
- **offset** (integer) - Opcional - Deslocamento para paginação (0, 20, ...).

### Request Example
```bash
curl "https://api.kavropay.online/v1/charges?status=paid&limit=50&offset=0" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

### Response
#### Success Response (200)
- **id** (string) - Identificador da cobrança.
- **status** (string) - Status da cobrança (paid, waiting_payment, expired, cancelled).
- **cancelled_at** (string) - Data de cancelamento, se aplicável.

#### Response Example
```json
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "status": "cancelled",
  "cancelled_at": "2026-08-26T12:15:00.000Z"
}
```
```

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

### GET /v1/withdrawals

Source: https://docs.kavropay.online/saques-pix

Lista saques de forma paginada. Requer o escopo `withdrawals:read`.

```APIDOC
## GET /v1/withdrawals

### Description
Lista saques de forma paginada. Requer o escopo `withdrawals:read`.

### Method
GET

### Endpoint
/v1/withdrawals

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filtro por status: `pending`, `processing`, `completed`, `failed`.
- **limit** (number) - Optional - Limite de resultados (1 a 100).
- **offset** (number) - Optional - Deslocamento para paginação (ex: 0, 20...).

### Request Example
```bash
curl "https://api.kavropay.online/v1/withdrawals?status=completed&limit=50&offset=0" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```
```

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

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

Source: https://docs.kavropay.online/cobrancas-pix

Busca os dados detalhados de uma cobrança existente. O parâmetro {id} pode ser o ID da KavroPay (PAY...) ou o externalId. Requer o escopo payments:read.

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

### Description
Busca os dados detalhados de uma cobrança existente. O parâmetro {id} pode ser o ID da KavroPay (PAY...) ou o externalId. Requer o escopo payments:read.

### Method
GET

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

### Parameters
#### Path Parameters
- **id** (string) - Required - ID da cobrança na KavroPay (formato PAY...) ou o externalId definido na criação.

### Request Example
curl https://api.kavropay.online/v1/charges/PAY9B1DEB4D3B7D4BAD9BDD2B \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"

### Response
#### Success Response (200)
- **id** (string) - ID da cobrança.
- **amount** (number) - Valor da cobrança.
- **fee** (number) - Taxa da cobrança.
- **net** (number) - Valor líquido.
- **status** (string) - Status da cobrança.
- **paid_at** (string) - Data de pagamento.
- **end_to_end_id** (string) - Identificador end-to-end do PIX.
- **externalId** (string) - Identificador externo.
- **customer** (object) - Dados do cliente.
  - **name** (string) - Nome do cliente.
  - **document** (string) - Documento do cliente.
  - **email** (string) - Email do cliente.

#### Response Example
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "amount": 49.00,
  "fee": 0.99,
  "net": 48.01,
  "status": "paid",
  "paid_at": "2026-08-26T12:05:12.000Z",
  "end_to_end_id": "E9274656202608261205abcdef",
  "externalId": "ped_998811",
  "customer": {
    "name": "Carlos Eduardo Silva",
    "document": "12345678909",
    "email": "carlos@email.com.br"
  }
}
```

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

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

Source: https://docs.kavropay.online/saques-pix

Busca os dados detalhados de um saque específico. Requer o escopo `withdrawals:read`.

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

### Description
Busca os dados detalhados de um saque específico. O parâmetro `{id}` é o ID retornado na criação (`WIT...`). Requer o escopo `withdrawals:read`.

### Method
GET

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

### Parameters
#### Path Parameters
- **id** (string) - Required - ID do saque (ex: `WIT7A28F1B3E4C9D01`).

### Request Example
```bash
curl https://api.kavropay.online/v1/withdrawals/WIT7A28F1B3E4C9D01 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

### Response
#### Success Response (200 OK)
- **id** (string) - Identificador do saque.
- **amount** (number) - Valor do saque.
- **fee** (number) - Taxa cobrada.
- **net** (number) - Valor líquido.
- **status** (string) - Status do saque (ex: "completed").
- **pix_key** (string) - Chave PIX mascarada.
- **pix_key_type** (string) - Tipo da chave PIX.
- **description** (string) - Descrição do saque.
- **created_at** (string) - Data de criação.
- **completed_at** (string) - Data de conclusão.

#### Response Example
```json
{
  "id": "WIT7A28F1B3E4C9D01",
  "amount": 100.00,
  "fee": 2.50,
  "net": 97.50,
  "status": "completed",
  "pix_key": "***.456.789-**",
  "pix_key_type": "CPF",
  "description": "Retirada de comissão de vendas",
  "created_at": "2026-08-26T12:10:00.000Z",
  "completed_at": "2026-08-26T12:10:45.000Z"
}
```
```

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

### Consultar cobrança - Requisição curl com Bearer token

Source: https://docs.kavropay.online/cobrancas-pix

Exemplo de requisição para consultar uma cobrança, usando o endpoint GET /v1/charges/{id} com escopo payments:read. O ID pode ser o ID da KavroPay (PAY...) ou o externalId.

```bash
curl https://api.kavropay.online/v1/charges/PAY9B1DEB4D3B7D4BAD9BDD2B \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

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

### GET /v1/balance

Source: https://docs.kavropay.online/saldo-conta

Retrieves the current account balance, showing available and locked amounts. Requires the payments:read scope.

```APIDOC
## GET /v1/balance

### Description
Verifica em tempo real o saldo disponível para saques e valores retidos.

### Method
GET

### Endpoint
/v1/balance

### Parameters
#### Query Parameters
- **scope** (string) - Required - O escopo `payments:read` é necessário para acessar este endpoint.

### Request Example
```bash
curl https://api.kavropay.online/v1/balance \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

### Response
#### Success Response (200)
- **available** (number) - Saldo disponível para saques.
- **locked** (number) - Valor retido.
- **currency** (string) - Moeda do saldo.

#### Response Example
```json
{
  "available": 3450.00,
  "locked": 0.00,
  "currency": "BRL"
}
```
```

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

### GET /v1/status

Source: https://docs.kavropay.online/status-unificado

Consulta o status atual de uma transação (cobrança ou saque PIX) usando o ID da transação. O endpoint identifica automaticamente o tipo de transação e retorna o status atual.

```APIDOC
## GET /v1/status

### Description
Consulta o status atual de uma transação (cobrança ou saque PIX) usando o ID da transação. O endpoint identifica automaticamente o tipo de transação e retorna o status atual.

### Method
GET

### Endpoint
/v1/status

### Parameters
#### Query Parameters
- **idtransaction** (string) - Required - ID da transação (ex: PAY..., WIT..., ID externo do pedido ou txId da adquirente).

### Request Example
```bash
curl "https://api.kavropay.online/v1/status?idtransaction=PAY9B1DEB4D3B7D4BAD9BDD2B" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

### Response
#### Success Response (200)
- **id** (string) - ID da transação.
- **status** (string) - Status atual da transação (ex: 'paid', 'waiting_payment', 'paid_out').

#### Response Example
```json
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "status": "paid"
}
```
```

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

### GET /v1/customers/{id}

Source: https://docs.kavropay.online/gestao-clientes

Retrieves a specific customer by its ID. Requires the `payments:read` scope and authentication via Bearer token.

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

### Description
Retrieves a specific customer by its ID. Requires the `payments:read` scope and authentication via Bearer token.

### Method
GET

### Endpoint
/v1/customers/{id}

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

### Request Example
curl https://api.kavropay.online/v1/customers/cus_abc123def456 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"

### Response
#### Success Response (200 OK)
- **id** (string) - Unique customer identifier.
- **name** (string) - Customer's full name.
- **document** (string) - Customer's document number.
- **email** (string) - Customer's email address.
- **phone** (string) - Customer's phone number.
- **created_at** (string) - Timestamp of customer creation.

#### Response Example
{
  "id": "cus_abc123def456",
  "name": "Renata Alcantara",
  "document": "98765432100",
  "email": "renata@email.com",
  "phone": "21999998888",
  "created_at": "2026-08-26T12:00:00.000Z"
}
```

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

### Criar cobrança PIX com Node.js (fetch)

Source: https://docs.kavropay.online/cobrancas-pix

Exemplo de criação de cobrança PIX usando fetch no Node.js. Envia amount como string com duas casas decimais e imprime o campo pix_copy_paste da resposta.

```javascript
const res = await fetch('https://api.kavropay.online/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: (49).toFixed(2), // '49.00' — sempre envie como string
    description: 'Assinatura #998811',
    externalId: 'ped_998811',
    customer: { name: 'Carlos Eduardo', document: '12345678909', email: 'carlos@email.com' }
  })
});
const charge = await res.json();
console.log('PIX Copia e Cola:', charge.pix_copy_paste);
```

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

### Criar Cliente - POST /v1/customers

Source: https://docs.kavropay.online/gestao-clientes

Cria um novo cliente pagador. Requer autenticação via Bearer token. Retorna HTTP 201 Created com os dados do cliente, incluindo o ID gerado.

```bash
curl -X POST https://api.kavropay.online/v1/customers \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renata Alcantara",
    "document": "98765432100",
    "email": "renata@email.com",
    "phone": "21999998888"
  }'
```

```json
{
  "id": "cus_abc123def456",
  "name": "Renata Alcantara",
  "document": "98765432100",
  "email": "renata@email.com",
  "phone": "21999998888",
  "created_at": "2026-08-26T12:00:00.000Z"
}
```

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

### Consultar status unificado com Node.js

Source: https://docs.kavropay.online/status-unificado

Exemplo em Node.js que envia requisição fetch para o endpoint /v1/status e exibe o campo 'status' (valores como 'paid', 'waiting_payment', 'paid_out'). Requer autenticação via header Authorization.

```javascript
const id = 'PAY9B1DEB4D3B7D4BAD9BDD2B';
const res = await fetch(`https://api.kavropay.online/v1/status?idtransaction=${id}`, {
  headers: { 'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI' }
});
const data = await res.json();
console.log('Status Atual:', data.status); // 'paid', 'waiting_payment', 'paid_out', etc.
```

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

### POST /v1/customers

Source: https://docs.kavropay.online/gestao-clientes

Creates a new customer in the system. Requires authentication via Bearer token and a JSON body with customer details.

```APIDOC
## POST /v1/customers

### Description
Creates a new customer in the system. Requires authentication via Bearer token and a JSON body with customer details.

### Method
POST

### Endpoint
/v1/customers

### Parameters
#### Request Body
- **name** (string) - Required - Customer's full name.
- **document** (string) - Required - Customer's document number (CPF/CNPJ).
- **email** (string) - Required - Customer's email address.
- **phone** (string) - Required - Customer's phone number.

### Request Example
{
  "name": "Renata Alcantara",
  "document": "98765432100",
  "email": "renata@email.com",
  "phone": "21999998888"
}

### Response
#### Success Response (201 Created)
- **id** (string) - Unique customer identifier.
- **name** (string) - Customer's full name.
- **document** (string) - Customer's document number.
- **email** (string) - Customer's email address.
- **phone** (string) - Customer's phone number.
- **created_at** (string) - Timestamp of customer creation.

#### Response Example
{
  "id": "cus_abc123def456",
  "name": "Renata Alcantara",
  "document": "98765432100",
  "email": "renata@email.com",
  "phone": "21999998888",
  "created_at": "2026-08-26T12:00:00.000Z"
}
```

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

### Exemplo de resposta rápida (HTTP 200 OK)

Source: https://docs.kavropay.online/status-unificado

Resposta JSON de exemplo, com status HTTP 200, retornando o ID da transação e o status atual ('paid').

```json
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "status": "paid"
}
```

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

### Criar cobrança PIX com Python (requests)

Source: https://docs.kavropay.online/cobrancas-pix

Exemplo de criação de cobrança PIX usando a biblioteca requests. Envia amount como string formatada com duas casas decimais e imprime o campo pix_copy_paste da resposta.

```python
import requests
res = requests.post('https://api.kavropay.online/v1/charges',
    headers={'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI', 'Content-Type': 'application/json'},
    json={'amount': f'{49:.2f}', 'description': 'Assinatura #998811', 'externalId': 'ped_998811'}
)
print(res.json()['pix_copy_paste'])
```

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

### Consultar status unificado com Python

Source: https://docs.kavropay.online/status-unificado

Exemplo em Python que usa requests para consultar o endpoint /v1/status e imprime o campo 'status'. A autenticação é feita via header Authorization.

```python
import requests
id_tx = 'PAY9B1DEB4D3B7D4BAD9BDD2B'
res = requests.get(f'https://api.kavropay.online/v1/status?idtransaction={id_tx}',
    headers={'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI'}
)
print('Status:', res.json()['status'])
```

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

### POST /v1/charges

Source: https://docs.kavropay.online/cobrancas-pix

Creates a new PIX charge. Returns a Copy and Paste code and QR Code for payment.

```APIDOC
## POST /v1/charges

### Description
Creates a new PIX charge. Returns a Copy and Paste code and QR Code for payment.

### Method
POST

### Endpoint
/v1/charges

### Parameters
#### Request Body
- **amount** (string) - Required - Value in Reais as a decimal string with two decimal places (e.g., "49.00"). JSON numbers are rejected.
- **description** (string) - Optional - Text displayed to the payer in the banking app.
- **externalId** (string) - Optional - Your order ID for automatic reconciliation.
- **expiresInMinutes** (integer) - Optional - Validity time in minutes (default: 30).
- **customer** (object) - Optional - Object with name, document (CPF/CNPJ), email, phone.
- **metadata** (object) - Optional - Custom metadata returned in queries and webhooks.
- **notification_url** (string) - Optional - HTTPS URL to receive the Webhook when paid.

### Request Example
```bash
curl -X POST https://api.kavropay.online/v1/charges \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ped_998811_attempt1" \
  -d '{
    "amount": "49.00",
    "description": "Assinatura #998811",
    "externalId": "ped_998811",
    "customer": {
      "name": "Carlos Eduardo",
      "document": "12345678909",
      "email": "carlos@email.com"
    }
  }'
```

### Response
#### Success Response (201 Created)
- **pix_copy_paste** (string) - The PIX Copy and Paste code.

#### Response Example
```json
{
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4e5f6..."
}
```
```

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

### Solicitar Saque via POST /v1/withdrawals

Source: https://docs.kavropay.online/saques-pix

Exemplo de requisição cURL para criar um novo saque PIX. Requer o escopo withdrawals:write e a chave de idempotência.

```bash
curl -X POST https://api.kavropay.online/v1/withdrawals \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wit_req_88192" \
  -d '{
    "amount": "100.00",
    "pix_key": "12345678909",
    "pix_key_type": "CPF",
    "description": "Retirada de comissão de vendas"
  }'
```

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

### POST /v1/charges

Source: https://docs.kavropay.online/cobrancas-pix

Cria uma nova cobrança PIX. O corpo da requisição deve conter os dados do cliente e o valor da cobrança. A resposta inclui o ID da cobrança, o código PIX copia e cola e o QR code em base64.

```APIDOC
## [POST] /v1/charges

### Description
Cria uma nova cobrança PIX. O corpo da requisição deve conter os dados do cliente e o valor da cobrança. A resposta inclui o ID da cobrança, o código PIX copia e cola e o QR code em base64.

### Method
POST

### Endpoint
/v1/charges

### Parameters
#### Request Body
- **customer** (object) - Required - Dados do cliente.
  - **name** (string) - Required - Nome do cliente.
  - **document** (string) - Required - CPF ou CNPJ do cliente.
  - **email** (string) - Required - Email do cliente.
- **amount** (number) - Required - Valor da cobrança em reais.
- **externalId** (string) - Optional - Identificador externo da cobrança.

### Request Example
{
  "customer": {
    "name": "Carlos Eduardo Silva",
    "document": "12345678909",
    "email": "carlos@email.com.br"
  },
  "amount": 49.00,
  "externalId": "ped_998811"
}

### Response
#### Success Response (200)
- **id** (string) - ID da cobrança na KavroPay.
- **amount** (number) - Valor da cobrança.
- **fee** (number) - Taxa da cobrança.
- **net** (number) - Valor líquido recebido.
- **status** (string) - Status da cobrança.
- **pix_copy_paste** (string) - Código PIX copia e cola.
- **qr_code_base64** (string) - QR code em base64.
- **source** (string) - Origem da cobrança.
- **externalId** (string) - Identificador externo.
- **external_reference** (string) - Referência externa.
- **expires_at** (string) - Data de expiração.
- **created_at** (string) - Data de criação.

#### Response Example
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "amount": 49.00,
  "fee": 0.99,
  "net": 48.01,
  "status": "waiting_payment",
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY9B1DEB4D3B7D4BAD9BDD2B520400005303986540549.005802BR5913KavroPay6009SAO PAULO62070503***6304D1A9",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAR...",
  "source": "api",
  "externalId": "ped_998811",
  "external_reference": "ped_998811",
  "expires_at": "2026-08-26T12:30:00.000Z",
  "created_at": "2026-08-26T12:00:00.000Z"
}

### Error Handling
#### Error Response (400)
- **statusCode** (number) - Código de status HTTP.
- **message** (string) - Mensagem de erro.
- **error** (string) - Tipo de erro.
- **timestamp** (string) - Data e hora do erro.
- **path** (string) - Caminho da requisição.

#### Error Example
{
  "statusCode": 400,
  "message": "Documento CPF inválido. O CPF deve conter 11 dígitos numéricos válidos.",
  "error": "Request Error",
  "timestamp": "2026-08-26T12:00:00.000Z",
  "path": "/v1/charges"
}
```

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

### Consultar status unificado com PHP

Source: https://docs.kavropay.online/status-unificado

Exemplo em PHP que utiliza cURL para consultar o endpoint /v1/status. Inclui configuração dos headers e processamento da resposta JSON. Necessita da chave de API para autenticação.

```php
<?php
$id = 'PAY9B1DEB4D3B7D4BAD9BDD2B';
$ch = curl_init("https://api.kavropay.online/v1/status?idtransaction=" . urlencode($id));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer sk_live_SUA_CHAVE_AQUI']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Status: " . $res['status'];
```

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

### Resposta de Consulta de Saque (HTTP 200)

Source: https://docs.kavropay.online/saques-pix

Estrutura de resposta contendo os detalhes completos de um saque consultado.

```json
{
  "id": "WIT7A28F1B3E4C9D01",
  "amount": 100.00,
  "fee": 2.50,
  "net": 97.50,
  "status": "completed",
  "pix_key": "***.456.789-**",
  "pix_key_type": "CPF",
  "description": "Retirada de comissão de vendas",
  "created_at": "2026-08-26T12:10:00.000Z",
  "completed_at": "2026-08-26T12:10:45.000Z"
}
```

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

### Cancelar Cobrança (POST /v1/charges/{id}/cancel)

Source: https://docs.kavropay.online/cobrancas-pix

Cancela uma cobrança com status waiting_payment. Requer escopo payments:write. Retorna resposta 200 OK com o status 'cancelled' e a data de cancelamento.

```bash
curl -X POST https://api.kavropay.online/v1/charges/PAY9B1DEB4D3B7D4BAD9BDD2B/cancel \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

```json
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "status": "cancelled",
  "cancelled_at": "2026-08-26T12:15:00.000Z"
}
```

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

### Erro de Saldo Insuficiente (HTTP 402)

Source: https://docs.kavropay.online/saques-pix

Estrutura de resposta de erro retornada quando não há saldo disponível para a transferência.

```json
{
  "statusCode": 402,
  "message": "Saldo disponível insuficiente para realizar esta transferência.",
  "error": "Request Error",
  "timestamp": "2026-08-26T12:10:00.000Z",
  "path": "/v1/withdrawals"
}
```

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

### Criar cobrança PIX com cURL

Source: https://docs.kavropay.online/cobrancas-pix

Exemplo de requisição POST para criar uma cobrança PIX usando cURL. Inclui cabeçalhos de autenticação, idempotência e corpo JSON com amount, description, externalId e customer.

```bash
curl -X POST https://api.kavropay.online/v1/charges \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ped_998811_attempt1" \
  -d '{
    "amount": "49.00",
    "description": "Assinatura #998811",
    "externalId": "ped_998811",
    "customer": {
      "name": "Carlos Eduardo",
      "document": "12345678909",
      "email": "carlos@email.com"
    }
  }'
```

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

### Payload JSON de Exemplo com Metadata

Source: https://docs.kavropay.online/parametros

Exemplo de payload JSON completo mostrando o campo amount como string decimal ("250.00") e o campo metadata com dados customizados como order_id, cart_id, affiliate_id, parâmetros UTM e itens. O metadata é preservado e retornado intacto em consultas e Webhooks.

```json
{
  "amount": "250.00",
  "description": "Combo Gamer Headset + Teclado #998811",
  "externalId": "ped_998811",
  "expiresInMinutes": 30,
  "notification_url": "https://seusite.com.br/api/kavropay-webhook",
  "customer": {
    "name": "Carlos Eduardo Silva",
    "document": "12345678909",
    "email": "carlos@email.com.br",
    "phone": "11987654321"
  },
  "metadata": {
    "order_id": "PEDIDO-998811",
    "cart_id": "cart_88392",
    "affiliate_id": "afiliado_marcos",
    "utm_source": "google_ads",
    "utm_campaign": "black_friday_2026",
    "items": [
      { "sku": "TECLADO-RGB", "name": "Teclado Mecânico", "price": "180.00", "qty": 1 },
      { "sku": "MOUSE-16K", "name": "Mouse Gamer 16000 DPI", "price": "70.00", "qty": 1 }
    ]
  }
}
```

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

### Consultar status unificado com cURL

Source: https://docs.kavropay.online/status-unificado

Chamada cURL para o endpoint /v1/status, que retorna o status de uma transação. Exige o header de autenticação com o token Bearer (sk_live_...). Use o idtransaction da transação (PAY..., WIT..., ID do pedido ou txId).

```bash
curl "https://api.kavropay.online/v1/status?idtransaction=PAY9B1DEB4D3B7D4BAD9BDD2B" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

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

### Resposta HTTP 200 OK - Saldo da conta

Source: https://docs.kavropay.online/saldo-conta

Exemplo de resposta JSON com os campos available, locked e currency. available representa o saldo disponível para saques, locked os valores retidos.

```json
{
  "available": 3450.00,
  "locked": 0.00,
  "currency": "BRL"
}
```

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

### Consultar cobrança - Resposta (HTTP 200) após pagamento

Source: https://docs.kavropay.online/cobrancas-pix

Exemplo de resposta ao consultar uma cobrança, mostrando status 'paid', data de pagamento e dados do cliente. Inclui o end_to_end_id do pagamento.

```json
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "amount": 49.00,
  "fee": 0.99,
  "net": 48.01,
  "status": "paid",
  "paid_at": "2026-08-26T12:05:12.000Z",
  "end_to_end_id": "E9274656202608261205abcdef",
  "externalId": "ped_998811",
  "customer": {
    "name": "Carlos Eduardo Silva",
    "document": "12345678909",
    "email": "carlos@email.com.br"
  }
}
```

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

### Criar cobrança Pix - Resposta de sucesso (HTTP 200/201)

Source: https://docs.kavropay.online/cobrancas-pix

Exemplo de resposta ao criar uma cobrança Pix, contendo dados como código copia-e-cola, QR code, status inicial e datas. O status 'waiting_payment' indica que aguarda pagamento.

```json
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "amount": 49.00,
  "fee": 0.99,
  "net": 48.01,
  "status": "waiting_payment",
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY9B1DEB4D3B7D4BAD9BDD2B520400005303986540549.005802BR5913KavroPay6009SAO PAULO62070503***6304D1A9",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAR...",
  "source": "api",
  "externalId": "ped_998811",
  "external_reference": "ped_998811",
  "expires_at": "2026-08-26T12:30:00.000Z",
  "created_at": "2026-08-26T12:00:00.000Z"
}
```

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

### POST /v1/withdrawals

Source: https://docs.kavropay.online/saques-pix

Solicita um saque PIX, transferindo saldo para uma chave PIX externa. Requer o escopo `withdrawals:write`.

```APIDOC
## POST /v1/withdrawals

### Description
Solicita um saque PIX, transferindo saldo para uma chave PIX externa. Requer o escopo `withdrawals:write`.

### Method
POST

### Endpoint
/v1/withdrawals

### Parameters
#### Request Body
- **amount** (string) - Required - Valor do saque em Reais como string decimal com duas casas (ex: "100.00").
- **pix_key** (string) - Required - Chave PIX de destino (criptografada em AES-256 no banco).
- **pix_key_type** (string) - Required - Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `TELEFONE`, `EVP`.
- **description** (string) - Optional - Identificador ou motivo do saque.

### Request Example
```bash
curl -X POST https://api.kavropay.online/v1/withdrawals \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wit_req_88192" \
  -d '{
    "amount": "100.00",
    "pix_key": "12345678909",
    "pix_key_type": "CPF",
    "description": "Retirada de comissão de vendas"
  }'
```

### Response
#### Success Response (201 Created)
- **id** (string) - Identificador do saque.
- **amount** (number) - Valor do saque.
- **fee** (number) - Taxa cobrada.
- **net** (number) - Valor líquido.
- **status** (string) - Status do saque (ex: "processing").
- **pix_key** (string) - Chave PIX mascarada.
- **pix_key_type** (string) - Tipo da chave PIX.
- **created_at** (string) - Data de criação.

#### Response Example
```json
{
  "id": "WIT7A28F1B3E4C9D01",
  "amount": 100.00,
  "fee": 2.50,
  "net": 97.50,
  "status": "processing",
  "pix_key": "***.456.789-**",
  "pix_key_type": "CPF",
  "created_at": "2026-08-26T12:10:00.000Z"
}
```

#### Error Response (402 Payment Required)
- **statusCode** (number) - Código de status HTTP.
- **message** (string) - Mensagem de erro.
- **error** (string) - Tipo de erro.
- **timestamp** (string) - Data e hora do erro.
- **path** (string) - Caminho da requisição.

#### Error Response Example
```json
{
  "statusCode": 402,
  "message": "Saldo disponível insuficiente para realizar esta transferência.",
  "error": "Request Error",
  "timestamp": "2026-08-26T12:10:00.000Z",
  "path": "/v1/withdrawals"
}
```
```

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

### Resposta de Sucesso do Saque (HTTP 201)

Source: https://docs.kavropay.online/saques-pix

Estrutura de resposta retornada após uma solicitação de saque bem-sucedida.

```json
{
  "id": "WIT7A28F1B3E4C9D01",
  "amount": 100.00,
  "fee": 2.50,
  "net": 97.50,
  "status": "processing",
  "pix_key": "***.456.789-**",
  "pix_key_type": "CPF",
  "created_at": "2026-08-26T12:10:00.000Z"
}
```

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

### POST /v1/charges/{id}/cancel

Source: https://docs.kavropay.online/cobrancas-pix

Cancela uma cobrança que ainda está com status waiting_payment. Cobranças já pagas não podem ser canceladas. Requer o escopo payments:write.

```APIDOC
## POST /v1/charges/{id}/cancel

### Description
Cancela uma cobrança que ainda está com status waiting_payment. Cobranças já pagas não podem ser canceladas. Requer o escopo payments:write.

### Method
POST

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

### Parameters
#### Path Parameters
- **id** (string) - Obrigatório - Identificador da cobrança a ser cancelada.

### Request Example
```bash
curl -X POST https://api.kavropay.online/v1/charges/PAY9B1DEB4D3B7D4BAD9BDD2B/cancel \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

### Response
#### Success Response (200)
- **id** (string) - Identificador da cobrança cancelada.
- **status** (string) - Status atualizado da cobrança (cancelled).
- **cancelled_at** (string) - Data e hora do cancelamento.

#### Response Example
```json
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "status": "cancelled",
  "cancelled_at": "2026-08-26T12:15:00.000Z"
}
```
```