SafePix

https://safepix.readme.io
Admin
SafePix is a Brazilian payment API that enables developers to create and manage payment transactions...
Tokens:8,347
Snippets:23
Trust Score:9.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### GET /v1/company

Source: https://safepix.readme.io/reference/dados-da-empresa

Retrieves the details of the company associated with the authenticated account.

```APIDOC
## GET /v1/company

### Description
Retrieves the profile information for the company currently authenticated via the provided Basic Auth credentials.

### Method
GET

### Endpoint
https://api.safepix.pro/v1/company

### Parameters
None

### Request Example
```
GET /v1/company HTTP/1.1
Host: api.safepix.pro
Authorization: Basic base64(public_key:secret_key)
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the company
- **fantasy_name** (string) - Company trading name
- **postal_code** (string) - Zip code of the company address
- **address** (string) - Street address
- **number** (string) - Building number
- **cnpj** (string) - Brazilian tax identification number
- **complement** (string) - Address complement
- **city** (string) - City name
- **state** (string) - State abbreviation
- **status** (string) - Current account status
- **created_at** (string) - Creation timestamp (ISO 8601)
- **updated_at** (string) - Last update timestamp (ISO 8601)

#### Response Example
{
  "id": "comp_12345",
  "fantasy_name": "Example Corp",
  "postal_code": "01001-000",
  "address": "Av. Paulista",
  "number": "1000",
  "cnpj": "00.000.000/0001-00",
  "city": "São Paulo",
  "state": "SP",
  "status": "active",
  "created_at": "2025-11-12T18:15:10.891Z",
  "updated_at": "2025-11-12T21:05:36.910Z"
}
```

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

### GET /v1/dashboard/balance

Source: https://safepix.readme.io/reference/consultar-saldo

Endpoint para consultar o saldo disponível na conta do usuário, retornado em centavos.

```APIDOC
## GET /v1/dashboard/balance

### Description
Retorna o saldo atual da conta. A autenticação é realizada via Basic Auth utilizando as credenciais fornecidas.

### Method
GET

### Endpoint
https://api.safepix.pro/v1/dashboard/balance

### Parameters
Nenhum parâmetro necessário.

### Request Example
```http
GET /v1/dashboard/balance HTTP/1.1
Host: api.safepix.pro
Authorization: Basic base64(public_key:secret_key)
```

### Response
#### Success Response (200)
- **data** (object) - Objeto contendo as informações de saldo.
- **data.amount** (object) - Saldo disponível em centavos.

#### Response Example
{
  "data": {
    "amount": 15000
  }
}
```

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

### GET /v1/payment-transaction/info/{id}

Source: https://safepix.readme.io/reference/post_idrefund-1

Retrieves detailed information about a specific payment transaction by its unique identifier.

```APIDOC
## GET /v1/payment-transaction/info/{id}

### Description
Retrieves the details of a specific payment transaction, including status, amount, and payment method, using the transaction ID.

### Method
GET

### Endpoint
https://api.safepix.pro/v1/payment-transaction/info/{id}

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

### Request Example
GET /v1/payment-transaction/info/tx_123456789
Authorization: Basic base64(public_key:secret_key)

### Response
#### Success Response (200)
- **id** (string) - Transaction ID
- **created_at** (date-time) - Creation timestamp
- **updated_at** (date-time) - Last update timestamp
- **company_id** (string) - ID of the company
- **acquirer_id** (string) - ID of the acquirer
- **external_id** (string) - External reference ID
- **paid_at** (date-time) - Payment timestamp
- **amount** (integer) - Transaction amount
- **refunded_amount** (integer) - Amount refunded
- **installments** (integer) - Number of installments
- **payment_method** (string) - Method used (e.g., PIX, Boleto, Card)
- **status** (string) - Status: PAID, PENDING, REFUNDED, FAILED, REFUSED
- **anticipation_status** (string) - Status of anticipation
- **postback_url** (string) - Webhook URL
- **metadata** (json) - Additional transaction data

#### Response Example
{
  "id": "tx_123456789",
  "status": "PAID",
  "amount": 1000,
  "payment_method": "PIX"
}
```

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

### POST /v1/payment-transaction/create

Source: https://safepix.readme.io/reference/createpaymenttransaction-1

Creates a new payment transaction. Supports PIX, credit card, and boleto as payment methods. Authentication is handled via Basic Auth.

```APIDOC
## POST /v1/payment-transaction/create

### Description
Creates a new payment transaction with card, boleto, or PIX. The authentication is done via **Basic Auth**, using:
```
Authorization: Basic base64(public_key:secret_key)
```

### Method
POST

### Endpoint
https://api.safepix.pro/v1/payment-transaction/create

### Parameters
#### Request Body
- **amount** (integer) - Required - Total amount in cents
- **payment_method** (string) - Required - Enum: ["pix", "credit_card", "boleto"]
- **postback_url** (string) - Optional - URL to receive transaction updates
- **customer** (object) - Required - Customer details
  - **name** (string) - Required - Customer's full name
  - **email** (string) - Required - Customer's email address
  - **document** (object) - Required - Customer's identification document
    - **number** (string) - Required - Document number (CPF or CNPJ)
    - **type** (string) - Required - Enum: ["cpf", "cnpj"]
  - **phone** (string) - Required - Customer's phone number
- **items** (array) - Required - List of items in the transaction
  - **title** (string) - Required - Name of the item
  - **unit_price** (integer) - Required - Price per unit in cents
  - **quantity** (integer) - Required - Number of units
  - **tangible** (boolean) - Required - Defines if the product is physical or not
  - **external_ref** (string) - Optional - External reference for the item
- **shipping** (object) - Optional - Shipping details
  - **fee** (number) - Optional - Shipping fee
  - **address** (object) - Optional - Shipping address
    - **street** (string) - Optional - Street name
    - **street_number** (string) - Optional - Street number

### Request Example
```json
{
  "amount": 12050,
  "payment_method": "credit_card",
  "postback_url": "https://meusite.com/webhook",
  "customer": {
    "name": "João Silva",
    "email": "joao.silva@email.com",
    "document": {
      "number": "11111111111",
      "type": "cpf"
    },
    "phone": "+5511999999999"
  },
  "items": [
    {
      "title": "Produto Exemplo 1",
      "unit_price": 5000,
      "quantity": 2,
      "tangible": true,
      "external_ref": "PROD001"
    },
    {
      "title": "Serviço Exemplo 2",
      "unit_price": 2050,
      "quantity": 1,
      "tangible": false
    }
  ],
  "shipping": {
    "fee": 1000,
    "address": {
      "street": "Rua das Flores",
      "street_number": "123"
    }
  }
}
```

### Response
#### Success Response (200)
- **transaction_id** (string) - Unique identifier for the transaction
- **status** (string) - Current status of the transaction (e.g., "pending", "paid", "failed")
- **payment_url** (string) - URL for payment (if applicable, e.g., for boleto)

#### Response Example
```json
{
  "transaction_id": "txn_abc123xyz789",
  "status": "pending",
  "payment_url": "https://safepix.pro/pay/boleto/xyz789"
}
```
```

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

### Authentication

Source: https://safepix.readme.io/reference

Details on how to authenticate API requests using Basic Auth with your public and secret keys.

```APIDOC
## Authentication

### Description
Our API follows the REST standard, and all responses are sent in JSON format. To make authenticated requests, you must send your credentials using the Basic Auth method. You can find your credentials in the dashboard on the "API Credentials" page.

### Method
All authenticated requests require the `Authorization` header.

### Header Format
`Basic Base64(PUBLIC_KEY:SECRET_KEY)`

To authenticate, transform the string `PUBLIC_KEY:SECRET_KEY` into Base64 and include it in the `Authorization` header.

### Request Example (Node.js)
```javascript
const options = {
  method: "POST",
  url: "https://api.safepix.pro/v1/payment-transaction/create",
  headers: {
    authorization: "Basic " + Buffer.from("{PUBLIC_KEY}:{SECRET_KEY}").toString("base64"),
  },
};
```
```

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

### POST /v1/wallet-transaction/create/withdrawal

Source: https://safepix.readme.io/reference/criar-transfer%C3%AAncia

Creates a withdrawal transaction using PIX. Supports various PIX key types and requires amount and postback URL.

```APIDOC
## POST /v1/wallet-transaction/create/withdrawal

### Description
Creates a withdrawal transaction using PIX. Supports various PIX key types and requires amount and postback URL.

### Method
POST

### Endpoint
https://api.safepix.pro/v1/wallet-transaction/create/withdrawal

### Parameters
#### Query Parameters
None

#### Request Body
- **pix_key** (string) - Required - The PIX key for the transaction.
- **pix_type** (string) - Required - The type of PIX key (cpf, cnpj, evp, phone, email).
- **amount** (number) - Required - The amount in BRL. Example: 10.00
- **postback_url** (string) - Required - The URL to receive postback notifications.

### Request Example
```json
{
  "pix_key": "e8a0224e-7c3e-4b1a-8c1e-0e1a2b3c4d5e",
  "pix_type": "evp",
  "amount": 10.00,
  "postback_url": "https://example.com/postback"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains transaction details.
  - **id** (string) - The unique identifier for the transaction.
  - **company_id** (string) - The ID of the company associated with the transaction.
  - **pix_key** (string) - The PIX key used in the transaction.
  - **created_at** (string) - The timestamp when the transaction was created (date-time format).
  - **updated_at** (string) - The timestamp when the transaction was last updated (date-time format).
  - **status** (string) - The current status of the transaction (PROCESSING, PAID, REFUSED).
  - **required_amount** (number) - The amount required for the transaction.
  - **total_amount** (string) - The total amount of the transaction.

#### Response Example
```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "company_id": "comp_12345",
    "pix_key": "e8a0224e-7c3e-4b1a-8c1e-0e1a2b3c4d5e",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:05:00Z",
    "status": "PROCESSING",
    "required_amount": 10.00,
    "total_amount": "10.00"
  }
}
```
```

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

### POST /transactions

Source: https://safepix.readme.io/reference/createpaymenttransaction-1

Creates a new payment transaction with specified details, including item information, shipping address, and payment method preferences.

```APIDOC
## POST /transactions

### Description
Creates a new payment transaction with specified details, including item information, shipping address, and payment method preferences.

### Method
POST

### Endpoint
/transactions

### Parameters
#### Request Body
- **customer** (object) - Required - Customer details.
  - **name** (string) - Required - Customer's full name.
  - **email** (string) - Required - Customer's email address.
  - **phone** (object) - Required - Customer's phone number.
    - **ddd** (string) - Required - Area code.
    - **number** (string) - Required - Phone number.
  - **document** (object) - Required - Customer's identification document.
    - **type** (string) - Required - Document type (e.g., CPF, CNPJ).
    - **number** (string) - Required - Document number.
- **shipping** (object) - Required - Shipping details.
  - **fee** (number) - Required - Shipping fee.
  - **address** (object) - Required - Shipping address.
    - **street** (string) - Required - Street name.
    - **street_number** (string) - Required - Street number.
    - **complement** (string) - Optional - Apartment or suite number.
    - **zip_code** (string) - Required - Postal code.
    - **neighborhood** (string) - Required - Neighborhood.
    - **city** (string) - Required - City name.
    - **state** (string) - Required - State abbreviation.
    - **country** (string) - Required - Country abbreviation.
- **items** (array) - Required - List of items in the transaction.
  - **title** (string) - Required - Item name.
  - **unit_price** (number) - Required - Price per unit.
  - **quantity** (integer) - Required - Number of units.
  - **tangible** (boolean) - Required - Indicates if the item is tangible.
  - **external_ref** (string) - Required - External reference ID for the item.
- **postback_url** (string) - Required - URL to receive transaction status updates.
- **traceable** (boolean) - Required - Indicates if the transaction is traceable.
- **ip** (string) - Required - Customer's IP address.

### Request Example
```json
{
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": {
      "ddd": "11",
      "number": "987654321"
    },
    "document": {
      "type": "CPF",
      "number": "12345678900"
    }
  },
  "shipping": {
    "fee": 10.50,
    "address": {
      "street": "Av. Paulista",
      "street_number": "1000",
      "complement": "Sala 5",
      "zip_code": "01310-000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    }
  },
  "items": [
    {
      "title": "Assinatura Premium",
      "unit_price": 120.5,
      "quantity": 1,
      "tangible": false,
      "external_ref": "plan_premium"
    }
  ],
  "postback_url": "https://webhook.freepaybrasil.com",
  "traceable": true,
  "ip": "127.0.0.1"
}
```

### Response
#### Success Response (200)
- **data** (array) - Array of transaction objects.
  - **id** (string) - Unique identifier for the transaction.
  - **amount** (integer) - Total transaction amount.
  - **installments** (integer) - Number of installments.
  - **payment_method** (string) - Method used for payment.
  - **status** (string) - Current status of the transaction (e.g., PENDING, PAID, REFUNDED).
  - **postback_url** (string) - URL for transaction status updates.
  - **card** (object) - Card details if payment method is card.
    - **hash** (string) - Card hash.
    - **number** (string) - Last four digits of the card number.
    - **holder_name** (string) - Name of the cardholder.
    - **expiration_month** (integer) - Card expiration month.
    - **expiration_year** (integer) - Card expiration year.
    - **cvv** (string) - CVV of the card.
  - **boleto** (object) - Boleto details if payment method is boleto.
    - **expires_in_days** (integer) - Number of days until the boleto expires.
  - **pix** (object) - Pix details if payment method is pix.
    - **expiration_date** (string) - Date and time when the Pix expires.
    - **qr_code** (string) - QR code for Pix payment.
    - **url** (string) - URL for Pix payment.
    - **e2_e** (string) - E2E identifier for Pix transaction.

#### Response Example
```json
{
  "data": [
    {
      "id": "txn_12345abcde",
      "amount": 12050,
      "installments": 1,
      "payment_method": "credit_card",
      "status": "PENDING",
      "postback_url": "https://webhook.freepaybrasil.com",
      "card": {
        "hash": "card_hash_123",
        "number": "**** **** **** 1234",
        "holder_name": "John Doe",
        "expiration_month": 12,
        "expiration_year": 2025,
        "cvv": "***"
      },
      "boleto": null,
      "pix": null
    }
  ]
}
```
```

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

### OpenAPI Definition for Safepix API

Source: https://safepix.readme.io/reference/dados-da-empresa

This JSON document defines the OpenAPI 3.0.3 specification for the FreePay API, used by Safepix. It includes API information, server URLs, security schemes (Basic Auth), and available paths for operations like retrieving company data. It details request and response structures, including data types and formats.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "FreePay API",
    "version": "1.0.0",
    "description": "API para criação de transações de pagamento via cartão, boleto e PIX.  \nA autenticação é feita via **Basic Auth**, utilizando:\n```\nAuthorization: Basic base64(public_key:secret_key)\n```\n"
  },
  "servers": [
    {
      "url": "https://api.safepix.pro",
      "description": "Ambiente local de testes"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "paths": {
    "/v1/company": {
      "get": {
        "description": "",
        "operationId": "get_company{companyId]",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "fantasy_name": {
                      "type": "string"
                    },
                    "postal_code": {
                      "type": "string"
                    },
                    "address": {
                      "type": "string"
                    },
                    "number": {
                      "type": "string"
                    },
                    "cnpj": {
                      "type": "string"
                    },
                    "complement": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Ex: 2025-11-12T18:15:10.891Z"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Ex: 2025-11-12T21:05:36.910Z"
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "x-readme": {}
}

```

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

### POST /v1/payment-transaction/{id}/refund

Source: https://safepix.readme.io/reference/post_idrefund

Endpoint utilizado para solicitar o estorno de uma transação específica identificada pelo seu ID.

```APIDOC
## POST /v1/payment-transaction/{id}/refund

### Description
Realiza o estorno de uma transação de pagamento existente.

### Method
POST

### Endpoint
https://api.safepix.pro/v1/payment-transaction/{id}/refund

### Parameters
#### Path Parameters
- **id** (string) - Required - O identificador único da transação a ser estornada.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmação do sucesso da operação de estorno.

#### Response Example
```json
{
  "status": "success",
  "message": "Transaction refunded successfully"
}
```
```

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

### Authenticate API requests with Node.js

Source: https://safepix.readme.io/reference

Demonstrates how to perform an authenticated POST request to the SafePix API. It uses the Buffer class to encode the public and secret keys into a Base64 string for the Authorization header.

```javascript
const options = {
  method: "POST",
  url: "https://api.safepix.pro/v1/payment-transaction/create",
  headers: {
    authorization: "Basic " + Buffer.from("{PUBLIC_KEY}:{SECRET_KEY}").toString("base64"),
  },
};
```

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

### POST /transactions

Source: https://safepix.readme.io/reference/createpaymenttransaction-1

Endpoint to create a new payment transaction using supported payment methods.

```APIDOC
## POST /transactions

### Description
Creates a new payment transaction. Supports credit card, boleto, and PIX payment methods.

### Method
POST

### Endpoint
/transactions

### Parameters
#### Request Body
- **amount** (number) - Required - The total value of the transaction.
- **payment_method** (string) - Required - The method of payment: 'credit_card', 'boleto', or 'pix'.
- **customer_id** (string) - Required - The unique identifier of the customer.

### Request Example
{
  "amount": 150.00,
  "payment_method": "pix",
  "customer_id": "cust_12345"
}

### Response
#### Success Response (201)
- **transaction_id** (string) - The unique ID of the created transaction.
- **status** (string) - The current status of the transaction.

#### Response Example
{
  "transaction_id": "tx_98765",
  "status": "pending"
}
```

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

### Define Transaction Request and Response Schema

Source: https://safepix.readme.io/reference/createpaymenttransaction-1

This JSON schema defines the structure for transaction creation requests, including shipping and item details, and the corresponding 200 OK response structure. It includes enumeration for payment statuses and nested objects for payment methods like Pix, Boleto, and Credit Card.

```json
{
  "shipping": {
    "fee": 0,
    "address": {
      "street": "Av. Paulista",
      "street_number": "1000",
      "complement": "Sala 5",
      "zip_code": "01310-000",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    }
  },
  "items": [
    {
      "title": "Assinatura Premium",
      "unit_price": 120.5,
      "quantity": 1,
      "tangible": false,
      "external_ref": "plan_premium"
    }
  ],
  "postback_url": "https://webhook.freepaybrasil.com",
  "traceable": true,
  "ip": "127.0.0.1"
}
```

```json
{
  "status": {
    "type": "string",
    "enum": ["PENDING", "PAID", "REFUNDED", "REFUSED", "CHARGEBACK", "PRECHARGEBACK", "EXPIRED", "ERROR"]
  }
}
```

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

### Safepix Transaction Update Webhook Format (C#)

Source: https://safepix.readme.io/reference/formato-dos-webhooks

This C# JSON object represents the format of a webhook notification for transaction updates. It includes details such as transaction ID, creation and update timestamps, external ID, payment status, amount, and the postback URL. The 'Status' field indicates the current state of the transaction, with possible values like PENDING, PAID, REFUNDED, etc.

```json
{
  "Id": "a24207e615224923bf4a68265d519fc6",
  "CreatedAt": "05/11/2025 21:19:42",
  "UpdatedAt": "2025-11-05T21:19:42.3648396",
  "ExternalId": "27615041",
  "PaidAt": "0001-01-01T00:00:00",
  "Amount": 100, // Em reais
  "Installments": 0,
  "PaymentMethod": "pix",
  "Status": "PENDING",
  "PostbackUrl": "https://webhook.site/d69ba6ed-3b46-40eb-9e9f-15e66a57161d"
}
```

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

### Safepix Transfer Update Webhook Format (C#)

Source: https://safepix.readme.io/reference/formato-dos-webhooks

This C# JSON object defines the structure for webhook notifications concerning transfer updates. It contains information like transfer ID, company ID, Pix key, creation and update timestamps, transfer status, wallet transaction type, payment details, and the postback URL. The 'Status' field reflects the transfer's state, with values such as PAID, PROCESSING, and REFUSED.

```json
{
  "Id": "2471f1c668de4900b0634bff114f0820",
  "CompanyId": "e6fb6532522e4f13ac0ce8a11fbf0a24",
  "PixKey": "safepix@gmail.com",
  "CreatedAt": "2025-12-02T18:02:58.5909895",
  "UpdatedAt": "2025-12-02T18:03:05.0195791",
  "Status": "PAID",
  "WalletTransactionType": "WITHDRAWAL",
  "PaidAt": "02/12/2025 21:03:05",
  "RequiredAmount": 1.00,
  "Fee": 0.00,
  "TotalAmount": 1.00, // Em reais
  "Reason": "Chave informada não cadastrada.",
  "PostbackUrl": "https://webhook.site/69bea1e9-9a83-4abe-8fe8-cba1cb454f3a"
}
```

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

### Authentication Header Format

Source: https://safepix.readme.io/reference/introdu%C3%A7%C3%A3o

This section details the required format for the Authorization header when making authenticated requests to the Safepix API.

```APIDOC
## Authentication

### Description
To make authenticated requests, you must send your credentials using the Basic Auth method. Your credentials can be found in the 'API Credentials' section of your dashboard.

### Method
All authenticated requests require an `Authorization` header.

### Endpoint
N/A (This applies to all endpoints requiring authentication)

### Parameters
#### Request Headers
- **Authorization** (string) - Required - The authentication token in the format `Basic Base64(PUBLIC_KEY:SECRET_KEY)`.

### Request Example (Node.js)
```javascript
const options = {
  method: "POST",
  url: "https://api.safepix.pro/v1/payment-transaction/create",
  headers: {
    authorization: "Basic " + Buffer.from("{PUBLIC_KEY}:{SECRET_KEY}").toString("base64"),
  },
};
```

### Response
#### Success Response (200)
- **N/A** (Authentication is handled via headers)

#### Response Example
N/A
```

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

### Transaction Update Webhook

Source: https://safepix.readme.io/reference/formato-dos-webhooks

This section describes the JSON payload structure for transaction update webhooks. It includes details about transaction identifiers, timestamps, amounts, payment methods, status, and the postback URL.

```APIDOC
## Transaction Update Webhook

### Description
This endpoint provides details about transaction updates, including payment status and relevant transaction information.

### Method
POST

### Endpoint
`/webhooks/transactions`

### Parameters
#### Request Body
- **Id** (string) - Unique identifier for the transaction.
- **CreatedAt** (string) - The date and time the transaction was created.
- **UpdatedAt** (string) - The date and time the transaction was last updated.
- **ExternalId** (string) - An external identifier for the transaction.
- **PaidAt** (string) - The date and time the transaction was paid.
- **Amount** (number) - The transaction amount in BRL.
- **Installments** (number) - The number of installments for the transaction.
- **PaymentMethod** (string) - The method used for payment (e.g., 'pix').
- **Status** (string) - The current status of the transaction (e.g., 'PENDING', 'PAID', 'REFUNDED', 'REFUSED', 'CHARGEBACK', 'PRECHARGEBACK', 'EXPIRED', 'ERROR').
- **PostbackUrl** (string) - The URL to which the webhook notification will be sent.

### Request Example
```json
{
  "Id": "a24207e615224923bf4a68265d519fc6",
  "CreatedAt": "05/11/2025 21:19:42",
  "UpdatedAt": "2025-11-05T21:19:42.3648396",
  "ExternalId": "27615041",
  "PaidAt": "0001-01-01T00:00:00",
  "Amount": 100, 
  "Installments": 0,
  "PaymentMethod": "pix",
  "Status": "PENDING",
  "PostbackUrl": "https://webhook.site/d69ba6ed-3b46-40eb-9e9f-15e66a57161d"
}
```

### Response
#### Success Response (200)
- **Status** (string) - Indicates the status of the transaction update.

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

### Status Mapping
| Status Recebido | Evento relacionado   |
| :-------------- | :------------------- |
| PENDING         | Aguardando Pagamento |
| PAID            | Pagamento realizado  |
| REFUNDED        | Transação Estornada  |
| REFUSED         | Transação Recusada   |
| CHARGEBACK      | Chargeback           |
| PRECHARGEBACK   | Pré-Chargeback       |
| EXPIRED         | Expirado             |
| ERROR           | Erro na transação    |
```

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

### Retrieve Account Balance via FreePay API

Source: https://safepix.readme.io/reference/consultar-saldo

This endpoint allows users to fetch their current account balance in cents. It requires Basic Authentication using a base64 encoded string of the public and secret keys.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "FreePay API",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/dashboard/balance": {
      "get": {
        "operationId": "get_v1dashboardbalance",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "amount": {
                          "type": "object",
                          "description": "Saldo em centavos."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

```http
Authorization: Basic base64(public_key:secret_key)
```

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

### Transfer Update Webhook

Source: https://safepix.readme.io/reference/formato-dos-webhooks

This section outlines the JSON payload structure for transfer update webhooks. It covers transfer identifiers, timestamps, Pix key details, amounts, status, and the postback URL.

```APIDOC
## Transfer Update Webhook

### Description
This endpoint provides details about transfer updates, including the status of the transfer and associated financial information.

### Method
POST

### Endpoint
`/webhooks/transfers`

### Parameters
#### Request Body
- **Id** (string) - Unique identifier for the transfer.
- **CompanyId** (string) - Identifier for the company associated with the transfer.
- **PixKey** (string) - The Pix key used for the transfer.
- **CreatedAt** (string) - The date and time the transfer was created.
- **UpdatedAt** (string) - The date and time the transfer was last updated.
- **Status** (string) - The current status of the transfer (e.g., 'PAID', 'PROCESSING', 'REFUSED').
- **WalletTransactionType** (string) - The type of wallet transaction (e.g., 'WITHDRAWAL').
- **PaidAt** (string) - The date and time the transfer was paid.
- **RequiredAmount** (number) - The amount required for the transfer in BRL.
- **Fee** (number) - The fee associated with the transfer in BRL.
- **TotalAmount** (number) - The total amount of the transfer in BRL.
- **Reason** (string) - The reason for the transfer status, if applicable.
- **PostbackUrl** (string) - The URL to which the webhook notification will be sent.

### Request Example
```json
{
  "Id": "2471f1c668de4900b0634bff114f0820",
  "CompanyId": "e6fb6532522e4f13ac0ce8a11fbf0a24",
  "PixKey": "safepix@gmail.com",
  "CreatedAt": "2025-12-02T18:02:58.5909895",
  "UpdatedAt": "2025-12-02T18:03:05.0195791",
  "Status": "PAID",
  "WalletTransactionType": "WITHDRAWAL",
  "PaidAt": "02/12/2025 21:03:05",
  "RequiredAmount": 1.00,
  "Fee": 0.00,
  "TotalAmount": 1.00, 
  "Reason": "Chave informada não cadastrada.",
  "PostbackUrl": "https://webhook.site/69bea1e9-9a83-4abe-8fe8-cba1cb454f3a"
}
```

### Response
#### Success Response (200)
- **Status** (string) - Indicates the status of the transfer update.

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

### Status Mapping
| Status Recebido | Evento relacionado      |
| :-------------- | :---------------------- |
| PAID            | Transferência realizada |
| PROCESSING      | Processando Pagamento   |
| REFUSED         | Transferência Recusada  |
```

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

### Authentication Header Format

Source: https://safepix.readme.io/reference/post_idrefund-1

The API requires Basic Authentication. The Authorization header must be constructed using a base64 encoded string of the public key and secret key.

```http
Authorization: Basic base64(public_key:secret_key)
```

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

### Retrieve Transaction Details via OpenAPI

Source: https://safepix.readme.io/reference/post_idrefund-1

Defines the OpenAPI 3.0.3 specification for the /v1/payment-transaction/info/{id} endpoint. It outlines the required path parameters, authentication scheme, and the structure of the JSON response object.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "FreePay API",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/payment-transaction/info/{id}": {
      "get": {
        "operationId": "get_v1payment-transactioninfo{id}",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": { "schema": { "type": "object" } }
            }
          }
        }
      }
    }
  }
}
```
Tokens:
Raw