### GET /customers

Source: https://docs.wysepay.com.br/openapi.json

Lista os clientes da conta, do mais novo para o mais antigo. Permite filtrar por documento. Requer a permissão `customers:read`.

```APIDOC
## GET /customers

### Description
Lista os clientes da conta, do mais novo para o mais antigo. Permite filtrar por `document` para achar um CPF ou CNPJ.

### Method
GET

### Endpoint
/customers

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Quantos itens por página (1 a 100). Padrão: 20.
- **document** (string) - Optional - Filtro por CPF ou CNPJ.

### Response
#### Success Response (200)
- **Customer[]** - Lista de clientes.

#### Response Example
[
  {
    "id": "string",
    "name": "string",
    "document": "string",
    "email": "string",
    "phone": "string",
    "address": {}
  }
]

#### Error Responses
- **400** - Dados inválidos. A mensagem diz o campo.
- **401** - Chave de API ausente, inválida ou revogada.
- **403** - A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.
- **429** - Muitas requisições. Espere o tempo do header `Retry-After`.
```

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

### Requisição cURL para listar clientes

Source: https://docs.wysepay.com.br/api/referencia/listar-clientes

Exemplo de requisição GET para o endpoint /api/v1/customers usando cURL, com o cabeçalho x-api-key para autenticação.

```bash
curl -X GET "https://api.wysepay.com.br/api/v1/customers" \
  -H "x-api-key: "
```

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

### Exemplo de requisição cURL

Source: https://docs.wysepay.com.br/api/referencia/consultar-saque

Exemplo de requisição GET para consultar um saque, usando cURL com o header de autenticação x-api-key.

```bash
curl -X GET "https://api.wysepay.com.br/api/v1/withdrawals/string" \
  -H "x-api-key: "
```

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

### Exemplo de requisição cURL para listar transações

Source: https://docs.wysepay.com.br/api/referencia/listar-transacoes

Exemplo de requisição GET para o endpoint /api/v1/transactions usando cURL, com o cabeçalho x-api-key para autenticação.

```bash
curl -X GET "https://api.wysepay.com.br/api/v1/transactions" \
  -H "x-api-key: "
```

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

### GET /api/v1/customers

Source: https://docs.wysepay.com.br/openapi.json

Endpoint para listar clientes com paginação e filtros.

```APIDOC
## GET /api/v1/customers

### Description
Lista os clientes da conta com paginação e filtros opcionais.

### Method
GET

### Endpoint
/api/v1/customers

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Máximo de itens por página (1 a 100).
- **startingAfter** (string) - Optional - O `id` do último item da página anterior. A página seguinte começa depois dele.
- **document** (string) - Optional - Só o cliente deste CPF ou CNPJ (com ou sem pontuação).

### Response
#### Success Response (200)
- Uma página de clientes.

#### Error Responses
- **400** - Dados inválidos. A mensagem diz o campo.
- **401** - Chave de API ausente, inválida ou revogada.
- **403** - A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.
- **429** - Muitas requisições. Espere o tempo do header `Retry-After`.
```

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

### Achar cliente por documento com GET /api/v1/customers

Source: https://docs.wysepay.com.br/api/clientes

Busca um cliente pelo CPF ou CNPJ. A resposta é uma lista com no máximo um cliente.

```bash
curl "https://api.wysepay.com.br/api/v1/customers?document=12345678909" \
  -H "x-api-key: wyp_test_sua_chave"
```

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

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

Source: https://docs.wysepay.com.br/api/referencia/consultar-cliente

Retrieves a customer by their ID. Requires the `customers:read` permission.

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

### Description
Retrieves the data and address of a specific customer by their ID.

### Method
GET

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The customer ID (cus_…).

### Authentication
- **x-api-key** (header) - Required - Your API key, created in the dashboard under Developers → API Keys. Permission required: `customers:read`.

### Response
#### Success Response (200)
Returns the customer object.

#### Response Example
```json
{
  "id": "cus_01k6g8m2v4x7z9b3c5d7f9h0j2",
  "name": "Ana Souza",
  "email": "ana@exemplo.com.br",
  "phone": "11912345678",
  "documentType": "CPF",
  "document": "12345678909",
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "string",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  },
  "livemode": true,
  "createdAt": "2026-10-04T15:30:00.000Z",
  "updatedAt": "2026-10-04T15:30:00.000Z"
}
```

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **429** - Too Many Requests
```

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

### Cadastrar cliente com POST /api/v1/customers

Source: https://docs.wysepay.com.br/api/clientes

Cria um cliente na API WysePay. Se já existir um cliente com o mesmo CPF ou CNPJ, ele é atualizado em vez de duplicado; campos não enviados permanecem como estavam. Um documento inválido responde com erro 400.

```bash
curl -X POST https://api.wysepay.com.br/api/v1/customers \
  -H "x-api-key: wyp_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "document": "123.456.789-09",
    "email": "ana@exemplo.com.br",
    "phone": "11912345678",
    "address": { "zipCode": "01310-100", "number": "1000" }
  }'
```

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

### Consultar cliente com cURL

Source: https://docs.wysepay.com.br/api/referencia/consultar-cliente

Consulta um cliente pelo ID usando a API Wyse Pay. Requer a chave de API no header x-api-key e a permissão customers:read.

```bash
curl -X GET "https://api.wysepay.com.br/api/v1/customers/string" \
  -H "x-api-key: "
```

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

### GET /api/v1/payment-links/:id

Source: https://docs.wysepay.com.br/wysepay.postman_collection.json

Endpoint para consultar um link de pagamento específico.

```APIDOC
## [GET] /api/v1/payment-links/:id

### Description
Consulta um link de pagamento específico e verifica se ele ainda aceita pagamentos (`active`).

### Method
GET

### Endpoint
{{baseUrl}}/api/v1/payment-links/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Identificador do link de pagamento.

#### Headers
- **x-api-key** (string) - Required - Chave de API para autenticação.

### Response
#### Success Response (200)
- **link** (object) - Dados do link de pagamento.
- **active** (boolean) - Indica se o link ainda aceita pagamentos.

### Permissão
`payment_links:read`
```

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

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

Source: https://docs.wysepay.com.br/openapi.json

Endpoint para consultar um cliente específico pelo seu ID.

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

### Description
Consulta os dados e o endereço de um cliente específico.

### Method
GET

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

### Parameters
#### Path Parameters
- **id** (string) - Required - O `id` do cliente (cus_…).

### Response
#### Success Response (200)
- O cliente.

#### Error Responses
- **400** - Dados inválidos. A mensagem diz o campo.
- **401** - Chave de API ausente, inválida ou revogada.
- **403** - A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.
- **404** - Cliente não encontrado nesta conta e neste modo.
- **429** - Muitas requisições. Espere o tempo do header `Retry-After`.
```

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

### Consultar saldo com cURL

Source: https://docs.wysepay.com.br/api/referencia/consultar-saldo

Consulta o saldo da conta usando a API WysePay. Requer a chave de API no header x-api-key e a permissão balance:read.

```bash
curl -X GET "https://api.wysepay.com.br/api/v1/balance" \
  -H "x-api-key: "
```

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

### Gerar Pix com POST /api/v1/charges/pix (curl, Node.js, Python, PHP, Go)

Source: https://docs.wysepay.com.br/llms-full.txt

Cria uma cobrança Pix em modo teste chamando o endpoint POST /api/v1/charges/pix. Requer uma chave de API de teste (começa com wyp_test_) e um cabeçalho idempotency-key. A resposta contém o campo pix.copyPaste com o código Pix copia-e-cola.

```bash
curl -X POST https://api.wysepay.com.br/api/v1/charges/pix \
  -H "x-api-key: wyp_test_sua_chave" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: pedido-1042" \
  -d '{
    "amountCents": 8990,
    "description": "Pedido #1042",
    "customer": {
      "name": "Ana Souza",
      "email": "ana@exemplo.com.br",
      "phone": "11912345678",
      "documentType": "CPF",
      "document": "12345678909"
    },
    "metadata": { "orderId": "1042" }
  }'
```

```js
const response = await fetch("https://api.wysepay.com.br/api/v1/charges/pix", {
  method: "POST",
  headers: {
    "x-api-key": process.env.WYSEPAY_API_KEY,
    "Content-Type": "application/json",
    "idempotency-key": "pedido-1042",
  },
  body: JSON.stringify({
    amountCents: 8990,
    description: "Pedido #1042",
    customer: {
      name: "Ana Souza",
      email: "ana@exemplo.com.br",
      phone: "11912345678",
      documentType: "CPF",
      document: "12345678909",
    },
    metadata: { orderId: "1042" },
  }),
});

const charge = await response.json();
console.log(charge.pix.copyPaste);
```

```python
import os
import requests

response = requests.post(
    "https://api.wysepay.com.br/api/v1/charges/pix",
    headers={
        "x-api-key": os.environ["WYSEPAY_API_KEY"],
        "idempotency-key": "pedido-1042",
    },
    json={
        "amountCents": 8990,
        "description": "Pedido #1042",
        "customer": {
            "name": "Ana Souza",
            "email": "ana@exemplo.com.br",
            "phone": "11912345678",
            "documentType": "CPF",
            "document": "12345678909",
        },
        "metadata": {"orderId": "1042"},
    },
)

charge = response.json()
print(charge["pix"]["copyPaste"])
```

```php
<?php

$ch = curl_init('https://api.wysepay.com.br/api/v1/charges/pix');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('WYSEPAY_API_KEY'),
    'Content-Type: application/json',
    'idempotency-key: pedido-1042',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amountCents' => 8990,
    'description' => 'Pedido #1042',
    'customer' => [
      'name' => 'Ana Souza',
      'email' => 'ana@exemplo.com.br',
      'phone' => '11912345678',
      'documentType' => 'CPF',
      'document' => '12345678909',
    ],
    'metadata' => ['orderId' => '1042'],
  ]),
]);

$charge = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $charge['pix']['copyPaste'];
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"amountCents": 8990,
		"description": "Pedido #1042",
		"customer": map[string]any{
			"name":         "Ana Souza",
			"email":        "ana@exemplo.com.br",
			"phone":        "11912345678",
			"documentType": "CPF",
			"document":     "12345678909",
		},
		"metadata": map[string]any{"orderId": "1042"},
	})
```

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

### GET /api/v1/payment-links

Source: https://docs.wysepay.com.br/api/links-de-pagamento

Lista os links de pagamento da conta, com filtro opcional por status ativo.

```APIDOC
## GET /api/v1/payment-links

### Description
Lista os links de pagamento da conta, com filtro opcional por status ativo.

### Method
GET

### Endpoint
https://api.wysepay.com.br/api/v1/payment-links

### Query Parameters
- **active** (boolean) - Optional - Filtra os links por ativo/inativo.

### Response
#### Success Response (200)
- **links** (array) - Lista de links de pagamento.

#### Response Example
```json
{
  "links": [
    {
      "id": "pay_...",
      "active": true,
      "amountCents": 15900,
      "description": "Caneca WysePay"
    }
  ]
}
```
```

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

### Cadastrar cliente com cURL (POST /api/v1/customers)

Source: https://docs.wysepay.com.br/api/referencia/cadastrar-cliente

Cria ou atualiza um cliente na API Wyse Pay. Envie o CPF ou CNPJ no campo `document`; campos não enviados permanecem como estavam. Requer a chave de API no header `x-api-key` e a permissão `customers:write`.

```bash
curl -X POST "https://api.wysepay.com.br/api/v1/customers" \
  -H "x-api-key: " \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "document": "12345678909",
    "email": "ana@exemplo.com.br",
    "phone": "11912345678"
  }'
```

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

### GET /api/v1/payment-links/{id}

Source: https://docs.wysepay.com.br/api/referencia/consultar-link

Consulta um link de pagamento e verifica se ele ainda aceita pagamentos (`active`).

```APIDOC
## GET /api/v1/payment-links/{id}

### Description
Consulta um link de pagamento e verifica se ele ainda aceita pagamentos (`active`).

### Method
GET

### Endpoint
/api/v1/payment-links/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - O `id` do link (plk_…).

### Authentication
- **apiKey** (header) - `x-api-key` - Sua chave de API, criada no painel em Desenvolvedores → Chaves de API.

### Response
#### Success Response (200)
O link.

#### Response Example
```json
{
  "id": "plk_01k6g8m2v4x7z9b3c5d7f9h0j2",
  "url": "https://app.wysepay.com.br/checkout/pay_2sngtnj5fkcnnm1m6v39xfe5b3",
  "amountCents": 8990,
  "description": "Camiseta básica · Tamanho M",
  "active": true,
  "maxPayments": 0,
  "askAddress": true,
  "returnUrl": "string",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "livemode": true,
  "expiresAt": "2026-10-04T15:30:00.000Z",
  "createdAt": "2026-10-04T15:30:00.000Z"
}
```

### Error Handling
- **400** - Bad Request
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **429** - Too Many Requests
```

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

### POST /customers

Source: https://docs.wysepay.com.br/openapi.json

Cria um novo cliente na conta. Requer a permissão `customers:write` (implícita).

```APIDOC
## POST /customers

### Description
Cria um cliente na conta. O corpo da requisição deve conter os dados do cliente, como nome e documento.

### Method
POST

### Endpoint
/customers

### Parameters
#### Request Body
- **name** (string) - Required - Nome do cliente.
- **document** (string) - Required - CPF ou CNPJ do cliente.
- **email** (string) - Optional - Email do cliente.
- **phone** (string) - Optional - Telefone do cliente.
- **address** (object) - Optional - Endereço do cliente.
  - **zipcode** (string) - Optional - CEP.
  - **street** (string) - Optional - Rua (máx. 160 caracteres).
  - **number** (string) - Optional - Número (máx. 20 caracteres).
  - **complement** (string) - Optional - Complemento (máx. 80 caracteres).
  - **district** (string) - Optional - Bairro (máx. 80 caracteres).
  - **city** (string) - Optional - Cidade (máx. 80 caracteres).
  - **state** (string) - Optional - Estado.

### Request Example
{
  "name": "Ana Souza",
  "document": "12345678909",
  "email": "ana@exemplo.com.br",
  "phone": "11912345678"
}

### Response
#### Success Response (201)
- **Customer** - O cliente criado.

#### Response Example
{
  "id": "string",
  "name": "string",
  "document": "string",
  "email": "string",
  "phone": "string",
  "address": {}
}

#### Error Responses
- **400** - Dados inválidos. A mensagem diz o campo.
- **401** - Chave de API ausente, inválida ou revogada.
- **403** - A chave não pode fazer isso: falta a permissão (`API_KEY_PERMISSION`), o IP não está liberado (`API_KEY_IP`) ou a conta ainda não opera em produção.
- **429** - Muitas requisições. Espere o tempo do header `Retry-After`.
```

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

### GET /api/v1/balance

Source: https://docs.wysepay.com.br/openapi.json

Consult the account balance, including available, pending, and blocked amounts, and the current withdrawable amount. Requires the 'balance:read' permission.

```APIDOC
## GET /api/v1/balance

### Description
Consult the account balance, including available, pending, and blocked amounts, and the current withdrawable amount.

### Method
GET

### Endpoint
/api/v1/balance

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Balance** (object) - The account balance details.

#### Response Example
{
  "availableCents": 12345,
  "pendingCents": 0,
  "blockedCents": 0,
  "withdrawableCents": 12345
}

### Error Responses
- **400** - Invalid data. The message indicates the field.
- **401** - API key missing, invalid, or revoked.
- **403** - The key cannot do this: missing permission (`API_KEY_PERMISSION`), IP not allowed (`API_KEY_IP`), or account not yet operating in production.
- **429** - Too many requests. Wait for the `Retry-After` header.
```

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

### Atualizar cliente com cURL (PATCH /api/v1/customers/{id})

Source: https://docs.wysepay.com.br/api/referencia/atualizar-cliente

Atualiza os campos enviados de um cliente existente. O CPF ou CNPJ não muda. Requer a permissão `customers:write` e a chave de API no header `x-api-key`.

```bash
curl -X PATCH "https://api.wysepay.com.br/api/v1/customers/string" \
  -H "x-api-key: " \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "email": "ana@exemplo.com.br",
    "phone": "11912345678"
  }'
```

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

### GET /api/v1/balance

Source: https://docs.wysepay.com.br/api/referencia/consultar-saldo

Endpoint para consultar o saldo da conta, retornando valores disponíveis, pendentes, bloqueados e o valor sacável imediatamente.

```APIDOC
## GET /api/v1/balance

### Description
Consulta o saldo da conta, incluindo valores disponíveis, a liberar, bloqueados e o valor que pode ser sacado imediatamente.

### Method
GET

### Endpoint
/api/v1/balance

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Chave de API para autenticação.

### Response
#### Success Response (200)
- **availableCents** (integer) - O que já pode ser sacado.
- **pendingCents** (integer) - Vendas pagas ainda no prazo de liberação.
- **blockedCents** (integer) - Retido, por exemplo, por um MED em andamento.
- **withdrawableNowCents** (integer) - Quanto dá para sacar agora, num saque só (já considera a taxa e os mínimos).
- **withdrawFeeCents** (integer) - Taxa de cada saque.
- **livemode** (boolean) - Indica se está em modo de produção.

#### Response Example
```json
{
  "availableCents": 125000,
  "pendingCents": 8900,
  "blockedCents": 0,
  "withdrawableNowCents": 124900,
  "withdrawFeeCents": 100,
  "livemode": true
}
```
```

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

### GET /v1/payment-links

Source: https://docs.wysepay.com.br/openapi.json

Lista os links de pagamento da conta, do mais novo para o mais antigo. Requer a permissão `payment_links:read`.

```APIDOC
## GET /v1/payment-links

### Description
Lista os links de pagamento da conta, do mais novo para o mais antigo. Requer a permissão `payment_links:read`.

### Method
GET

### Endpoint
/v1/payment-links

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Limite de resultados.
```

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

### Create Pix charge with idempotency-key header

Source: https://docs.wysepay.com.br/api/limites-e-idempotencia

Use this curl command to create a Pix charge with an idempotency key. The key must be unique per charge (e.g., your order ID) and is valid for 24 hours; repeating the same key returns the same charge without duplicating it. The key is scoped per account and mode, so test and production keys are treated as different charges.

```bash
curl -X POST https://api.wysepay.com.br/api/v1/charges/pix \
  -H "x-api-key: wyp_test_sua_chave" \
  -H "idempotency-key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{ … }'
```