### PHP Implementation Example

Source: https://app.lordspay.com.br/doc

A basic PHP code example demonstrating how to receive and process a `transaction.paid` webhook.

```APIDOC
## PHP Implementation Example

### Description

A basic PHP code example demonstrating how to receive and process a `transaction.paid` webhook.

### Code Example

```php
<?php
// webhook.php

// Get the raw POST data from the request
$input = file_get_contents('php://input');
$data = json_decode($input, true);

// Check if the event is 'transaction.paid'
if ($data && isset($data['event']) && $data['event'] === 'transaction.paid') {
    // Extract relevant data
    $transactionId = $data['data']['transaction_id'] ?? null;
    $amount = $data['data']['amount'] ?? null;

    if ($transactionId && $amount) {
        // Process the confirmed payment (e.g., update order status)
        // updateOrderStatus($transactionId, 'paid');
        
        // Respond with a success status to acknowledge receipt
        http_response_code(200);
        echo json_encode(['status' => 'received']);
        exit;
    }
}

// If the event is not recognized or data is missing, return an error or default response
http_response_code(400); // Bad Request
echo json_encode(['status' => 'error', 'message' => 'Invalid event or data']);

?>
```
```

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

### Withdrawal Status Change Webhook

Source: https://app.lordspay.com.br/doc/#introducao

This section details the structure and examples of webhooks triggered by changes in withdrawal status, such as rejected, completed, or canceled.

```APIDOC
## POST /webhooks/withdrawal

### Description
Receives automatic notifications about changes in withdrawal transaction statuses. This webhook is sent when a withdrawal is approved, completed, canceled, or rejected.

### Method
POST

### Endpoint
`/webhooks/withdrawal` (This is a conceptual endpoint; the actual URL is configured via `postbackUrl`)

### Parameters
#### Request Body
- **event** (string) - Required - The type of withdrawal event (e.g., `withdrawal.status_changed`, `withdrawal.concluido`, `withdrawal.cancelado`).
- **timestamp** (string) - Required - The date and time when the event occurred, in ISO 8601 format.
- **data** (object) - Required - An object containing details about the withdrawal.
  - **id** (integer) - Required - The unique identifier for the withdrawal.
  - **codigo_externo** (string) - Required - The external code associated with the withdrawal (e.g., order ID).
  - **amount** (number) - Required - The total amount of the withdrawal.
  - **fee_amount** (number) - Required - The fee associated with the withdrawal.
  - **net_amount** (number) - Required - The net amount after fees.
  - **pix_key_type** (string) - Required - The type of PIX key used (e.g., `cpf`, `email`).
  - **pix_key** (string) - Required - The PIX key used for the withdrawal.
  - **status** (string) - Required - The current status of the withdrawal (e.g., `rejeitado`, `concluido`, `cancelado`, `aprovado`).
  - **created_at** (string) - Optional - The date and time when the withdrawal was created.
  - **updated_at** (string) - Optional - The date and time when the withdrawal was last updated.
  - **completed_at** (string) - Optional - The date and time when the withdrawal was completed.
  - **observacoes** (string) - Optional - Additional notes about the withdrawal.
  - **end_to_end_id** (string) - Optional - The end-to-end ID of the PIX transaction if completed.
  - **destinatario** (string) - Optional - The name of the PIX key holder if available.
  - **refunded_at** (string) - Optional - The date and time when the withdrawal was refunded.
  - **motivo** (string) - Optional - The reason for cancellation or rejection.

### Request Example
```json
{
  "event": "withdrawal.status_changed",
  "timestamp": "2026-01-13T19:01:32-03:00",
  "data": {
    "id": 394,
    "codigo_externo": "ORDER-555",
    "amount": 20,
    "fee_amount": 3,
    "net_amount": 17,
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00",
    "status": "rejeitado",
    "created_at": "2026-01-13 19:01:08",
    "updated_at": "2026-01-13 19:01:32",
    "completed_at": "2026-01-13 19:01:32",
    "observacoes": "Saque solicitado pelo cliente"
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the webhook was successfully processed.

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

### Security Recommendations
- Use HTTPS for your `postbackUrl`.
- Validate the received payload to ensure authenticity.
- Implement idempotency to handle duplicate webhook deliveries.
- Respond to webhooks promptly (within 5 seconds) to avoid timeouts.
```

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

### Consultar Saque por ID ou Código Externo - Exemplo cURL

Source: https://app.lordspay.com.br/doc/#introducao

Exemplos de como consultar o status de um saque específico utilizando cURL. Pode-se consultar pelo ID do saque ou pelo código externo fornecido na criação. Requer autenticação básica.

```bash
# Consultar por ID
curl -X GET "https://api.lordspayments.com/withdrawal?id=123" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI="

# Consultar por código externo
curl -X GET "https://api.lordspayments.com/withdrawal?codigo_externo=ORDER-555" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI="
```

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

### Autenticação Basic com API Key em JavaScript

Source: https://app.lordspay.com.br/doc/#introducao

Demonstra como gerar as credenciais de autenticação Basic usando API Keys em JavaScript. Combina a chave pública e privada, codifica em Base64 e formata para o header 'Authorization'.

```javascript
const credentials = "pk_sua_chave_publica:sk_sua_chave_privada";

const encodedCredentials = btoa(credentials);

const headers = {
    "Authorization": `Basic ${encodedCredentials}`,
    "Content-Type": "application/json"
};
```

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

### Create Withdrawal

Source: https://app.lordspay.com.br/doc

Initiates a new withdrawal request. Funds are reserved immediately upon request.

```APIDOC
## POST /withdrawal

### Description
Initiates a new withdrawal request. Funds are reserved immediately upon request.

### Method
POST

### Endpoint
/withdrawal

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - The withdrawal amount in BRL (e.g., 100.50).
- **pix_key_type** (string) - Required - The type of PIX key (cpf, cnpj, email, telefone, aleatoria).
- **pix_key** (string) - Required - The PIX key for receiving the funds.
- **observacoes** (string) - Optional - Notes about the withdrawal.
- **postbackUrl** (string) - Optional - URL to receive status change notifications.
- **codigo_externo** (string) - Optional - External reference code from the client (e.g., ORDER-12345).

### Request Example
```json
{
  "amount": 100.50,
  "pix_key_type": "cpf",
  "pix_key": "123.456.789-00",
  "observacoes": "Saque solicitado pelo cliente",
  "postbackUrl": "https://seu-site.com/webhook/saque-status",
  "codigo_externo": "ORDER-12345"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - Confirmation message.
- **data** (object) - Withdrawal details.
  - **id** (number) - Unique identifier for the withdrawal.
  - **amount** (number) - The withdrawal amount.
  - **fee_amount** (number) - The fee charged for the withdrawal.
  - **net_amount** (number) - The net amount after fees.
  - **pix_key_type** (string) - The type of PIX key used.
  - **pix_key** (string) - The PIX key used.
  - **status** (string) - The current status of the withdrawal (e.g., 'pendente').
  - **created_at** (string) - Timestamp of creation.
  - **observacoes** (string) - Notes about the withdrawal.
  - **postback_url** (string) - The provided postback URL.
  - **codigo_externo** (string) - The external reference code.

#### Response Example
```json
{
  "success": true,
  "message": "Withdrawal request created successfully",
  "data": {
    "id": 123,
    "amount": 100.50,
    "fee_amount": 2.50,
    "net_amount": 98.00,
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00",
    "status": "pendente",
    "created_at": "2025-01-13 17:00:00",
    "observacoes": "Saque solicitado pelo cliente",
    "postback_url": "https://seu-site.com/webhook/saque-status",
    "codigo_externo": "ORDER-12345"
  }
}
```
```

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

### Create Withdrawal

Source: https://app.lordspay.com.br/doc/#introducao

Initiates a withdrawal request. You can specify the amount, PIX key details, and an optional postback URL for status updates.

```APIDOC
## POST /withdrawal

### Description
Initiates a withdrawal request.

### Method
POST

### Endpoint
/withdrawal

### Parameters
#### Request Body
- **amount** (number) - Required - The withdrawal amount in BRL (e.g., 100.50).
- **pix_key_type** (string) - Required - The type of PIX key (cpf, cnpj, email, telefone, aleatoria).
- **pix_key** (string) - Required - The PIX key for receiving the amount.
- **observacoes** (string) - Optional - Notes about the withdrawal.
- **postbackUrl** (string) - Optional - URL to receive status change notifications.
- **codigo_externo** (string) - Optional - External reference code from the client (e.g., ORDER-12345).

### Request Example
```json
{
  "amount": 100.50,
  "pix_key_type": "cpf",
  "pix_key": "123.456.789-00",
  "observacoes": "Saque solicitado pelo cliente",
  "postbackUrl": "https://seu-site.com/webhook/saque-status",
  "codigo_externo": "ORDER-12345"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains details of the created withdrawal.
  - **id** (integer) - The unique identifier for the withdrawal.
  - **amount** (number) - The withdrawal amount.
  - **fee_amount** (number) - The fee charged for the withdrawal.
  - **net_amount** (number) - The net amount after fees.
  - **pix_key_type** (string) - The type of PIX key used.
  - **pix_key** (string) - The PIX key used.
  - **status** (string) - The current status of the withdrawal (e.g., 'pendente').
  - **created_at** (string) - The timestamp when the withdrawal was created.
  - **observacoes** (string) - Notes about the withdrawal.
  - **postback_url** (string) - The postback URL provided.
  - **codigo_externo** (string) - The external reference code.

#### Response Example
```json
{
  "success": true,
  "message": "Withdrawal request created successfully",
  "data": {
    "id": 123,
    "amount": 100.50,
    "fee_amount": 2.50,
    "net_amount": 98.00,
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00",
    "status": "pendente",
    "created_at": "2025-01-13 17:00:00",
    "observacoes": "Saque solicitado pelo cliente",
    "postback_url": "https://seu-site.com/webhook/saque-status",
    "codigo_externo": "ORDER-12345"
  }
}
```
```

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

### Consultar Saldo

Source: https://app.lordspay.com.br/doc/#introducao

Consulte o saldo disponível da sua conta para realizar saques.

```APIDOC
## GET /balance

### Description
Consulte o saldo disponível da sua conta para realizar saques.

### Method
GET

### Endpoint
`/balance`

### About Balance
O saldo retornado representa o valor disponível para saque na sua conta. Este valor é atualizado automaticamente conforme as transações são processadas e aprovadas.
  * **Saldo disponível:** Valor liberado para saque
  * Transações pendentes ou em processamento não são incluídas
  * Taxas de saque são descontadas no momento da solicitação

### Request Example
```curl
curl -X GET "https://api.lordspayments.com/balance" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI="
```

### Response
#### Success Response (200)
- **success** (boolean) - Indica se a requisição foi bem sucedida
- **data** (object)
  - **balance** (number) - Saldo disponível em reais (R$)

#### Response Example
```json
{
  "success": true,
  "data": {
    "balance": 99
  }
}
```

#### Tip
Consulte o saldo antes de solicitar um saque para garantir que há fundos suficientes disponíveis.
```

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

### Authentication

Source: https://app.lordspay.com.br/doc/#introducao

Explains how to authenticate with the LORDS PAYMENTS API using Basic Authentication with API Keys.

```APIDOC
## Authentication

The API uses **Basic Authentication** with your API keys encoded in Base64.

### Get Your Keys
Access the administrative panel to obtain your **public key** (pk_) and **private key** (sk_).

### Combine Keys
Combine the keys in the format: `public_key:private_key`

### Encode in Base64
Encode the combined string in Base64 and send it in the Authorization header.

### Authentication Format
```javascript
// 1. Combine your keys
const credentials = "pk_your_public_key:sk_your_private_key";

// 2. Encode in Base64
const encodedCredentials = btoa(credentials);

// 3. Use in the Authorization header
const headers = {
    "Authorization": `Basic ${encodedCredentials}`,
    "Content-Type": "application/json"
};
```

### Required Headers
```
Authorization: Basic cGtfc3VhX2NoYXZlX3B1YmxpY2E6c2tfc3VhX2NoYXZlX3ByaXZhZGE=
Content-Type: application/json
```

**Important:** Keep your keys secure! The private key (sk_) should never be exposed in the frontend or public repositories.

### Practical Example
If your keys are:
  * **Public Key:** `pk_test_123456`
  * **Private Key:** `sk_test_789012`

The string to encode would be: `pk_test_123456:sk_test_789012`
```

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

### Webhook Security Best Practices

Source: https://app.lordspay.com.br/doc

Recommendations for securing webhook endpoints to ensure data integrity and prevent unauthorized access.

```APIDOC
## Webhook Security Best Practices

### Description
Implementing robust security measures for your webhook endpoints is crucial to protect your system and data. Follow these best practices to ensure the integrity and security of your webhook integrations.

### Recommendations

1.  **Use HTTPS for Postback URLs**:
    Always configure your `postbackUrl` with HTTPS to encrypt the data transmitted between our servers and yours, preventing man-in-the-middle attacks.

2.  **Validate the Received Payload**:
    Before processing any data, validate the structure and content of the incoming webhook payload. Check for required fields and expected data types. Consider implementing a signature verification mechanism if provided by the API provider.

3.  **Implement Idempotency**:
    Design your webhook handler to be idempotent. This means that processing the same webhook payload multiple times should not result in unintended side effects (e.g., charging a customer twice). Use unique identifiers like `codigo_externo` or `data.id` to track and prevent duplicate processing.

4.  **Respond Quickly**:
    Acknowledge receipt of the webhook as quickly as possible, ideally within 5 seconds. This prevents timeouts on our end and ensures reliable delivery. If complex processing is required, acknowledge the webhook first and then perform the processing asynchronously.

5.  **Monitor and Log**:
    Implement comprehensive logging for all incoming webhooks and their processing status. Monitor these logs for any errors, suspicious activity, or delivery failures. Set up alerts for critical issues.

6.  **Use a Dedicated Endpoint**:
    Consider using a dedicated endpoint for receiving webhooks rather than mixing it with your regular API traffic. This can help with security, monitoring, and performance isolation.

7.  **Rate Limiting**:
    If necessary, implement rate limiting on your webhook endpoint to protect against denial-of-service attacks or excessive traffic from a single source.
```

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

### Implementação de Webhook para Processar Status de Saque (PHP)

Source: https://app.lordspay.com.br/doc/#introducao

Este script PHP demonstra como receber e processar um webhook de mudança de status de saque. Ele decodifica o payload JSON e atualiza o status de um pedido com base no status do saque.

```php
<?php
// webhook-saque-status.php

$input = file_get_contents('php://input');
$data = json_decode($input, true);

if ($data && $data['event'] === 'withdrawal.status_changed') {
    $saque_id = $data['data']['id'];
    $codigo_externo = $data['data']['codigo_externo'];
    $status = $data['data']['status'];
    
    // Processar mudança de status
    switch ($status) {
        case 'aprovado':
        case 'concluido':
            // Saque processado com sucesso
            atualizarPedido($codigo_externo, 'pago');
            break;
            
        case 'cancelado':
        case 'rejeitado':
            // Saque falhou
            atualizarPedido($codigo_externo, 'falhou');
            break;
    }
    
    // Responder ao webhook
    http_response_code(200);
    echo json_encode(['success' => true]);
}
?>
```

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

### Listar Pagamentos

Source: https://app.lordspay.com.br/doc/#introducao

Liste todas as transações da sua conta com filtros opcionais por status, data e paginação.

```APIDOC
## GET /transactions

### Description
Liste todas as transações da sua conta com filtros opcionais.

### Method
GET

### Endpoint
`/transactions`

#### Query Parameters
- **page** (integer) - Optional - Página (padrão: 1)
- **limit** (integer) - Optional - Itens por página (padrão: 20, máx: 100)
- **status** (string) - Optional - Filtrar por status (pago, pendente, cancelado)
- **start_date** (string) - Optional - Data inicial (YYYY-MM-DD)
- **end_date** (string) - Optional - Data final (YYYY-MM-DD)

### Request Example
```curl
curl -X GET "https://api.lordspayments.com/transactions?page=1&limit=10&status=pago" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indica se a requisição foi bem sucedida
- **data** (object)
  - **transactions** (array) - Lista de transações
    - **id** (string) - ID único da transação
    - **status** (string) - Status da transação
    - **amount** (number) - Valor da transação
    - **created_at** (string) - Data e hora de criação da transação
    - **customer** (object) - Informações do cliente
      - **name** (string)
      - **email** (string)
  - **pagination** (object) - Informações de paginação
    - **current_page** (integer)
    - **total_pages** (integer)
    - **total_items** (integer)
    - **items_per_page** (integer)

#### Response Example
```json
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "PXB_68E6C0A14DC3D_1759953057",
        "status": "pago",
        "amount": 5,
        "created_at": "2025-10-08 19:50:57",
        "customer": {
          "name": "João Silva",
          "email": "joao.silva@email.com"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20
    }
  }
}
```
```

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

### Solicitar Saque PIX

Source: https://app.lordspay.com.br/doc/#introducao

Solicite saques do seu saldo disponível via PIX de forma rápida e segura.

```APIDOC
## POST /withdrawal

### Description
Solicite saques do seu saldo disponível via PIX.

### How Withdrawals Work
Os saques permitem transferir o saldo disponível da sua conta para uma chave PIX de sua escolha. O processo é simples e seguro:
  * Solicite o saque informando valor e chave PIX
  * O valor é reservado do seu saldo disponível
  * Nossa equipe analisa e processa a solicitação
  * O valor é transferido para sua chave PIX

### Request Body
- **amount** (number) - Required - Valor a ser sacado
- **pix_key** (string) - Required - Chave PIX para onde o valor será transferido

### Request Example
```curl
curl -X POST "https://api.lordspayments.com/withdrawal" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "pix_key": "sua_chave_pix_aqui"
  }'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indica se a requisição foi bem sucedida
- **data** (object)
  - **withdrawal_id** (string) - ID único da solicitação de saque
  - **status** (string) - Status da solicitação de saque (ex: processando, concluido, falhou)

#### Response Example
```json
{
  "success": true,
  "data": {
    "withdrawal_id": "WD_12345abcde",
    "status": "processando"
  }
}
```
```

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

### Headers Obrigatórios para Autenticação

Source: https://app.lordspay.com.br/doc/#introducao

Exibe os headers HTTP necessários para autenticação na API LORDS PAYMENTS. Inclui o header 'Authorization' com credenciais codificadas em Base64 e o header 'Content-Type'.

```http
Authorization: Basic cGtfc3VhX2NoYXZlX3B1YmxpY2E6c2tfc3VhX2NoYXZlX3ByaXZhZGE=
Content-Type: application/json
```

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

### Webhook de Saque Aprovado - Exemplo JSON

Source: https://app.lordspay.com.br/doc/#introducao

Formato de notificação automática (webhook) recebida quando um saque é aprovado. Inclui detalhes da transação, como ID, valor, chave PIX e o identificador `end_to_end_id` da transferência bancária.

```json
{
  "event": "withdrawal.aprovado",
  "timestamp": "2026-01-22T20:30:00-03:00",
  "data": {
    "id": 410,
    "codigo_externo": "ORDER-12345",
    "amount": 100.00,
    "fee_amount": 2.50,
    "net_amount": 97.50,
    "pix_key": "123.456.789-00",
    "pix_key_type": "cpf",
    "status": "aprovado",
    "end_to_end_id": "E29477089202601220013331837cab5d",
    "destinatario": "JOÃO PEREIRA SILVA",
    "completed_at": "2026-01-22T20:30:00-03:00"
  }
}
```

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

### PHP Webhook Implementation for Transaction Paid

Source: https://app.lordspay.com.br/doc/#introducao

This PHP script demonstrates how to receive and process a 'transaction.paid' webhook. It reads the raw input, decodes the JSON payload, checks the event type, extracts relevant data, and responds with a 200 status code to confirm receipt. Ensure 'updateOrderStatus' function is defined elsewhere.

```php
<?php
// webhook.php
$input = file_get_contents('php://input');
$data = json_decode($input, true);

if ($data['event'] === 'transaction.paid') {
    $transactionId = $data['data']['transaction_id'];
    $amount = $data['data']['amount'];
    
    // Processar pagamento confirmado
    updateOrderStatus($transactionId, 'paid');
    
    // Responder com sucesso
    http_response_code(200);
    echo json_encode(['status' => 'received']);
}
?>
```

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

### Consultar Pagamento

Source: https://app.lordspay.com.br/doc/#introducao

Consulte o status de uma transação específica usando seu ID único.

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

### Description
Consulte o status de uma transação específica.

### Method
GET

### Endpoint
`/transactions/{id}`

#### Path Parameters
- **id** (string) - Required - ID único da transação (formato: PXB_xxxxx)

### Request Example
```curl
curl -X GET "https://api.lordspayments.com/transactions/PXB_68E6C0A14DC3D_1759953057" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indica se a requisição foi bem sucedida
- **data** (object) - Contém os detalhes da transação
  - **id** (string) - ID único da transação
  - **status** (string) - Status atual da transação (pago, pendente, cancelado)
  - **amount** (number) - Valor da transação
  - **payment_method** (string) - Método de pagamento utilizado
  - **created_at** (string) - Data e hora de criação da transação
  - **paid_at** (string) - Data e hora de pagamento da transação
  - **endtoend** (string) - Identificador único da transação PIX no sistema bancário (pode ser vazio)
  - **nome_pagador** (string) - Nome do titular da conta que realizou o pagamento (pode ser vazio)
  - **customer** (object) - Informações do cliente
    - **name** (string)
    - **email** (string)
    - **document** (string)
    - **phone** (string)
  - **metadata** (object) - Metadados adicionais da transação
    - **order_id** (string)
    - **product_id** (string)

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "PXB_68E6C0A14DC3D_1759953057",
    "status": "pago",
    "amount": 5,
    "payment_method": "pix",
    "created_at": "2025-10-08 19:50:57",
    "paid_at": "2025-10-08 19:51:18",
    "endtoend": "E18236120202601132313s13d35ab7b2",
    "nome_pagador": "Fernando Pereira Silva",
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    }
  }
}
```

### Statuses
- **pendente**: Aguardando pagamento
- **pago**: Pagamento confirmado
- **cancelado**: Transação cancelada
```

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

### POST /payments

Source: https://app.lordspay.com.br/doc/#introducao

Endpoint to create a new PIX transaction.

```APIDOC
## Create Payment
Endpoint to create a new PIX transaction.
POST `https://api.lordspayments.com`

### Request Parameters
| Field | Type | Description |
|---|---|---|
| `amount` | number | Amount in reais (e.g., 5.00) |
| `payment_method` | string | Payment method ("pix") |
| `description` | string | Payment description |
| `items` | array | List of transaction items (optional) |
| `customer` | object | Customer data (name, email, document, phone) |
| `metadata` | object | Custom data (order_id, product_id, etc.) |
| `postbackUrl` | string | URL to receive webhook notifications |

### Items Field Structure
The `items` field is optional and allows specifying details of products/services for the transaction. If not provided, an item will be automatically created based on the description.
| Field | Type | Description |
|---|---|---|
| `title` | string | Item/product name |
| `unitPrice` | integer | Unit price in cents (500 = R$ 5.00) |
| `quantity` | integer | Item quantity |
| `tangible` | boolean | Whether it is a physical (true) or digital (false) product |

#### Example of Items
```json
"items": [
  {
    "title": "Pro Plan",
    "unitPrice": 2590,
    "quantity": 1,
    "tangible": false
  },
  {
    "title": "Setup Fee",
    "unitPrice": 500,
    "quantity": 1,
    "tangible": false
  }
]
```

**Important:** If the `items` field is not provided, an item will be automatically created based on the `description` field and the total transaction amount.

### Request Example (cURL)
```bash
curl -X POST "https://api.lordspayments.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.90,
    "payment_method": "pix",
    "description": "Purchase of product XYZ",
    "items": [
      {
        "title": "Pro Plan",
        "unitPrice": 2590,
        "quantity": 1,
        "tangible": false
      }
    ],
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    },
    "postbackUrl": "https://your-site.com/webhook/payments"
  }'
```

### Response Example
```json
{
  "success": true,
  "data": {
    "id": "PXB_68E6C0A14DC3D_1759953057",
    "status": "pending",
    "amount": 5,
    "payment_method": "pix",
    "pix_code": "00020126860014br.gov.bcb.pix2564pix.bancoe2.com.br/qr/v3/at/afa55845-f3f2-4275-8b31-e4abd...",
    "pix_qr_code": "iVBORw0KGgoAAAANSUhEUgAAAOwAAADsCAAAAABSuBXIAAAEn0lEQVR42u2dQXLjSAwE+f9Pcy9zmIkVUVltXw...",
    "external_ref": "12345",
    "created_at": "2025-10-08 19:50:57",
    "expires_at": "2025-10-09 19:50:57",
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    }
  }
}
```
```

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

### Exemplo de Requisição cURL para Criar Pagamento PIX

Source: https://app.lordspay.com.br/doc/#introducao

Um exemplo prático de como criar uma transação PIX utilizando cURL. Inclui o endpoint, headers de autenticação e o corpo da requisição com detalhes do pagamento, cliente e metadados.

```curl
curl -X POST "https://api.lordspayments.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.90,
    "payment_method": "pix",
    "description": "Compra de produto XYZ",
    "items": [
      {
        "title": "Plano Pro",
        "unitPrice": 2590,
        "quantity": 1,
        "tangible": false
      }
    ],
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    },
    "postbackUrl": "https://seu-site.com/webhook/pagamentos"
  }'
```

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

### Criar Saque com PIX - Exemplo cURL

Source: https://app.lordspay.com.br/doc/#introducao

Exemplo de como criar uma requisição de saque utilizando cURL. Define o valor, tipo e chave PIX, além de informações opcionais como observações, URL de postback e código externo. Requer autenticação básica.

```bash
curl -X POST "https://api.lordspayments.com/withdrawal" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00",
    "observacoes": "Saque solicitado pelo cliente",
    "postbackUrl": "https://seu-site.com/webhook/saque-status",
    "codigo_externo": "ORDER-12345"
  }'
```

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

### Exemplo de Resposta da Criação de Pagamento PIX

Source: https://app.lordspay.com.br/doc/#introducao

Estrutura de resposta esperada ao criar uma transação PIX. Contém informações sobre o sucesso da operação, detalhes do pagamento, código PIX, QR Code e dados do cliente.

```json
{
  "success": true,
  "data": {
    "id": "PXB_68E6C0A14DC3D_1759953057",
    "status": "pendente",
    "amount": 5,
    "payment_method": "pix",
    "pix_code": "00020126860014br.gov.bcb.pix2564pix.bancoe2.com.br/qr/v3/at/afa55845-f3f2-4275-8b31-e4abd...",
    "pix_qr_code": "iVBORw0KGgoAAAANSUhEUgAAAOwAAADsCAAAAABSuBXIAAAEn0lEQVR42u2dQXLjSAwE+f9Pcy9zmIkVUVltXw...",
    "external_ref": "12345",
    "created_at": "2025-10-08 19:50:57",
    "expires_at": "2025-10-09 19:50:57",
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    }
  }
}
```

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

### Exemplo de Resposta da Consulta de Saque - JSON

Source: https://app.lordspay.com.br/doc/#introducao

Formato da resposta ao consultar um saque específico que foi aprovado e processado. Inclui detalhes como `id`, `amount`, `status`, e o `endtoend` ID quando a transferência PIX é concluída.

```json
{
  "success": true,
  "data": {
    "id": 395,
    "amount": 20,
    "fee_amount": 3,
    "net_amount": 17,
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00",
    "status": "aprovado",
    "created_at": "2026-01-13 19:02:15",
    "observacoes": "Saque solicitado pelo cliente",
    "postback_url": "https://webhook.site/exemplo",
    "codigo_externo": "ORDER-555",
    "endtoend": "E3412312321321321321",
    "completed_at": "2026-01-13 19:02:30"
  }
}
```

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

### Query Withdrawals

Source: https://app.lordspay.com.br/doc/#introducao

Allows querying withdrawal details by ID or external code, or listing all withdrawals with pagination and filtering options.

```APIDOC
## GET /withdrawal

### Description
Queries withdrawal details by ID or external code, or lists withdrawals.

### Method
GET

### Endpoint
/withdrawal

### Parameters
#### Query Parameters
- **id** (integer) - Optional - The ID of the withdrawal to retrieve.
- **codigo_externo** (string) - Optional - The external reference code of the withdrawal to retrieve.
- **list** (boolean) - Optional - If true, returns a list of withdrawals. Defaults to false.
- **limit** (integer) - Optional - Number of items per page (default: 50, max: 100). Used when `list` is true.
- **offset** (integer) - Optional - Offset for pagination (default: 0). Used when `list` is true.
- **status** (string) - Optional - Filter withdrawals by status (pendente, aprovado, concluido, cancelado). Used when `list` is true.

### Request Example
```bash
# Consultar por ID
curl -X GET "https://api.lordspayments.com/withdrawal?id=123" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI="

# Consultar por código externo
curl -X GET "https://api.lordspayments.com/withdrawal?codigo_externo=ORDER-555" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI="

# Listar saques com filtro de status
curl -X GET "https://api.lordspayments.com/withdrawal?list=true&status=aprovado" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI="
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object or array) - Contains the withdrawal details or a list of withdrawals.
  - If querying by ID or `codigo_externo`: Contains a single withdrawal object with fields like `id`, `amount`, `fee_amount`, `net_amount`, `pix_key_type`, `pix_key`, `status`, `created_at`, `observacoes`, `postback_url`, `codigo_externo`. If the withdrawal is approved and processed, it will also include `endtoend` (string) - The unique identifier of the transfer in the banking system.
  - If listing withdrawals (`list=true`): Contains an array of withdrawal objects.

#### Response Example (Withdrawal Approved)
```json
{
  "success": true,
  "data": {
    "id": 395,
    "amount": 20,
    "fee_amount": 3,
    "net_amount": 17,
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00",
    "status": "aprovado",
    "created_at": "2026-01-13 19:02:15",
    "observacoes": "Saque solicitado pelo cliente",
    "postback_url": "https://webhook.site/exemplo",
    "codigo_externo": "ORDER-555",
    "endtoend": "E3412312321321321321",
    "completed_at": "2026-01-13 19:02:30"
  }
}
```

#### Response Example (Account Summary)
```json
{
  "success": true,
  "data": {
    "total_saques": 15,
    "valor_pendente": 500.00,
    "valor_aprovado": 750.00,
    "valor_concluido": 2350.00,
    "valor_cancelado": 0.00
  }
}
```
```

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

### Exemplo de Payload: Saque Concluído com Destinatário (JSON)

Source: https://app.lordspay.com.br/doc/#introducao

Este payload JSON demonstra um evento de webhook para um saque concluído com sucesso. Inclui informações sobre o destinatário, que é o nome do titular da conta PIX que recebeu o valor.

```json
{
  "event": "withdrawal.concluido",
  "timestamp": "2026-01-21T21:18:00-03:00",
  "data": {
    "id": 410,
    "codigo_externo": "ORDER-12345",
    "amount": 4.00,
    "fee_amount": 0.00,
    "net_amount": 4.00,
    "pix_key": "123.456.789-00",
    "pix_key_type": "cpf",
    "status": "concluido",
    "end_to_end_id": "E29477089202601220013331837cab5d",
    "destinatario": "JOÃO PEREIRA SILVA",
    "completed_at": "2026-01-21T21:18:00-03:00"
  }
}
```

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

### Webhook Validation and Security

Source: https://app.lordspay.com.br/doc

Provides essential security tips and best practices for validating incoming webhooks to ensure the integrity and security of your integration.

```APIDOC
## Webhook Validation and Security

### Description

Provides essential security tips and best practices for validating incoming webhooks to ensure the integrity and security of your integration.

### Security Tips

- **Validate Request Origin**: Always verify the source of the incoming webhook request to prevent unauthorized access.
- **Use HTTPS**: Ensure your webhook URL is secured with HTTPS to encrypt data in transit.
- **Implement Retry Logic**: Implement retry mechanisms for temporary failures to ensure reliable delivery of webhooks.
- **Respond with 200 OK**: Acknowledge receipt of the webhook by responding with a `200 OK` status code promptly.
```