Safefy Pay API Reference

https://docs.safefypay.com.br/api-reference/
Admin
Safefy Pay API Reference provides documentation for integrating with Safefy Pay's payment platform,...
Tokens:67,548
Snippets:198
Trust Score:2.1
Update:8 months ago
Show doc for...
Tokens:
Raw
### Pix QR Code Generation

Source: https://docs.safefypay.com.br/api-reference/transactions/create

Instructions and code examples for generating a visual Pix QR code from the `pix.copyAndPaste` EMV (BR Code) string.

```APIDOC
## Pix QR Code Generation

### Description
This section explains how to generate a visual QR code for Pix payments using the `pix.copyAndPaste` field, which contains the EMV (BR Code).

### JavaScript Example (using qrcode.js)

```html
<script src="https://cdn.jsdelivr.net/npm/qrcode/build/qrcode.min.js"></script>

<canvas id="qrcode"></canvas>

<script>
  const pixCode = "00020126580014br.gov.bcb.pix0136a1b2c3d4..."; // Replace with actual pix.copyAndPaste value
  QRCode.toCanvas(document.getElementById('qrcode'), pixCode, function (error) {
    if (error) console.error(error)
  });
</script>
```

### React Example (using react-qr-code)

```jsx
import QRCode from 'react-qr-code';

function PaymentPage({ transaction }) {
  return (
    <div>
      <QRCode value={transaction.pix.copyAndPaste} size={256} />
      <p>Or copy the code:</p>
      <code>{transaction.pix.copyAndPaste}</code>
    </div>
  );
}
```

### Next.js Example (using next-qrcode)

```jsx
import { useQRCode } from 'next-qrcode';

function PaymentPage({ transaction }) {
  const { Canvas } = useQRCode();
  
  return (
    <Canvas
      text={transaction.pix.copyAndPaste}
      options={{
        width: 256,
        margin: 2
      }}
    />
  );
}
```

<Tip>
  The `copyAndPaste` code can also be copied by the user and pasted directly into their banking app to complete the payment.
</Tip>
```

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

### Create Customer API Request (OpenAPI)

Source: https://docs.safefypay.com.br/api-reference/customers/create

This snippet defines the OpenAPI schema for creating a new customer. It specifies the required fields such as name and email, along with optional fields like externalId, document, phone, and metadata. The example demonstrates a typical request payload.

```yaml
openapi: 3.1.1
info:
  title: Safefy - Pix Gateway
  description: |
    ## Introducao
    **Seu parceiro financeiro de confianca.**
    Nos somos a Safefy, uma plataforma especializada em solucoes de pagamento
    PIX. Com um servico personalizado e focado nas suas necessidades, estamos
    prontos para apoiar sua empresa em cada etapa do processo.
    - Conte com o **PIX** como metodo de pagamento rapido, seguro e alinhado com
    as melhores praticas de conformidade e prevencao a fraudes.
    - Gerencie suas financas de forma simples e acessivel por meio de uma
    interface completa e intuitiva.
    - Nosso time de suporte esta sempre disponivel para oferecer um atendimento
    exclusivo e eficiente.
    ## Precisa de Ajuda?
    A equipe da Safefy quer garantir que sua integracao seja um sucesso. Se
    tiver duvidas ou precisar de suporte, nao hesite em nos contatar:
    **suporte@safefypay.com.br**
    ---
    ## Valores Monetarios
    Todos os valores monetarios sao representados em **centavos** (menor unidade
    da moeda).
    | Valor Real | Valor na API |
    |------------|--------------|
    | R$ 1,00    | 100          |
    | R$ 10,50   | 1050         |
    | R$ 100,00  | 10000        |
  contact:
    name: Suporte Safefy
    email: suporte@safefypay.com.br
  version: v1
servers:
  - url: https://api-payment.safefypay.com.br
    description: API de Pagamentos Safefy
security:
  - bearerAuth: []
tags:
  - name: Autenticacao
    description: Endpoints de autenticacao OAuth2
  - name: Transacoes
    description: Gerenciamento de transacoes PIX
  - name: Clientes
    description: Gerenciamento de clientes
  - name: Saldo
    description: Consulta de saldo e volumes
  - name: Saques
    description: Solicitacao e gerenciamento de saques
paths:
  /v1/customers:
    post:
      tags:
        - Clientes
      summary: Criar cliente
      description: Cria um novo cliente associado a sua organizacao.
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            example:
              name: Joao Silva
              email: joao@email.com
              externalId: cliente_123
              document: '12345678900'
              documentType: CPF
              phone: '11999998888'
              metadata: '{"plano": "premium"}'
      responses:
        '201':
          description: Cliente criado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomerResponse'
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  externalId: cliente_123
                  name: Joao Silva
                  email: joao@email.com
                  document: 123.456.789-00
                  documentType: CPF
                  phone: '11999998888'
                  status: Active
                  metadata: '{"plano": "premium"}'
                  address: null
                  createdAt: '2025-01-15T15:00:00Z'
                message: Cliente criado com sucesso.
                error: null
        '400':
          description: Dados invalidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                data: null
                message: null
                error:
                  message: O campo email e obrigatorio.
                  code: validation_error
        '401':
          description: Nao autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                data: null
                message: null
                error:
                  message: Token invalido ou expirado.
                  code: unauthorized
        '409':
          description: Cliente ja existe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                data: null
                message: null
                error:
                  message: Ja existe um cliente com o externalId informado.
                  code: conflict
components:
  schemas:
    CreateCustomerRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          description: Nome completo do cliente
          example: Joao Silva
        email:
          type: string
          description: E-mail do cliente
          example: joao@email.com
        externalId:
          type: string
          nullable: true
          description: Seu identificador interno
          example: cliente_123

```

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

### GET /v1/customers

Source: https://docs.safefypay.com.br/api-reference/customers

Retrieves a list of all customers. Supports filtering and pagination.

```APIDOC
## GET /v1/customers

### Description
Retrieves a list of all customers. Supports filtering and pagination.

### Method
GET

### Endpoint
/v1/customers

### Parameters
#### Query Parameters
- **limit** (integer, optional) - Maximum number of customers to return. Defaults to 20.
- **offset** (integer, optional) - Number of customers to skip before starting to collect the result set. Defaults to 0.
- **status** (string, optional) - Filter customers by status. Possible values: `Active`, `Inactive`.
- **email** (string, optional) - Filter customers by email address.
- **document** (string, optional) - Filter customers by document number (CPF or CNPJ).

### Response
#### Success Response (200)
- **data** (array) - An array of customer objects.
  - Each customer object contains the same fields as described in the Customer Object structure.
- **total** (integer) - The total number of customers matching the query.
- **limit** (integer) - The limit used for pagination.
- **offset** (integer) - The offset used for pagination.

#### Response Example
```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "externalId": null,
      "name": "Joao Pereira",
      "email": "joao.pereira@exemplo.com",
      "document": "98765432101",
      "documentType": "CPF",
      "phone": "+5521987654321",
      "status": "Active",
      "metadata": null,
      "address": {
        "street": "Avenida Principal",
        "number": "456",
        "complement": null,
        "neighborhood": null,
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postalCode": "20000000",
        "country": "BR"
      },
      "createdAt": "2024-03-10T14:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```
```

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

### List Customers API Endpoint (OpenAPI)

Source: https://docs.safefypay.com.br/api-reference/customers/list

Defines the GET /v1/customers endpoint for listing customers. Supports pagination, filtering by status, document type, and searching by name, email, or document. Returns a paginated list of customer objects or an unauthorized error.

```yaml
openapi: 3.1.1
info:
  title: Safefy - Pix Gateway
  description: >
    ## Introducao
    **Seu parceiro financeiro de confianca.**
    Nos somos a Safefy, uma plataforma especializada em solucoes de pagamento
    PIX. Com um servico personalizado e focado nas suas necessidades, estamos
    prontos para apoiar sua empresa em cada etapa do processo.
    - Conte com o **PIX** como metodo de pagamento rapido, seguro e alinhado com
    as melhores praticas de conformidade e prevencao a fraudes.
    - Gerencie suas financas de forma simples e acessivel por meio de uma
    interface completa e intuitiva.
    - Nosso time de suporte esta sempre disponivel para oferecer um atendimento
    exclusivo e eficiente.
    ## Precisa de Ajuda?
A equipe da Safefy quer garantir que sua integracao seja um sucesso. Se
    tiver duvidas ou precisar de suporte, nao hesite em nos contatar:
    **suporte@safefypay.com.br**
    ---    ## Valores Monetarios
Todos os valores monetarios sao representados em **centavos** (menor unidade
da moeda).
| Valor Real | Valor na API |
|------------|--------------|
| R$ 1,00    | 100          |
| R$ 10,50   | 1050         |
| R$ 100,00  | 10000        |
  contact:
    name: Suporte Safefy
    email: suporte@safefypay.com.br
  version: v1
servers:
  - url: https://api-payment.safefypay.com.br
    description: API de Pagamentos Safefy
security:
  - bearerAuth: []
tags:
  - name: Autenticacao
    description: Endpoints de autenticacao OAuth2
  - name: Transacoes
    description: Gerenciamento de transacoes PIX
  - name: Clientes
    description: Gerenciamento de clientes
  - name: Saldo
    description: Consulta de saldo e volumes
  - name: Saques
    description: Solicitacao e gerenciamento de saques
paths:
  /v1/customers:
    get:
      tags:
        - Clientes
      summary: Listar clientes
      description: Retorna uma lista paginada de clientes com suporte a filtros.
      operationId: listCustomers
      parameters:
        - name: page
          in: query
          description: Numero da pagina
          schema:
            type: integer
            default: 1
            example: 1
        - name: pageSize
          in: query
          description: 'Itens por pagina (max: 100)'
          schema:
            type: integer
            default: 20
            example: 20
        - name: status
          in: query
          description: Filtrar por status
          schema:
            type: string
            enum:
              - Active
              - Inactive
            example: Active
        - name: documentType
          in: query
          description: Filtrar por tipo de documento
          schema:
            type: string
            enum:
              - CPF
              - CNPJ
            example: CPF
        - name: search
          in: query
          description: Buscar por nome, email ou documento
          schema:
            type: string
            example: joao
        - name: externalId
          in: query
          description: Filtrar por ID externo
          schema:
            type: string
            example: cliente_123
      responses:
        '200':
          description: Lista de clientes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomersResponse'
              example:
                data:
                  items:
                    - id: 550e8400-e29b-41d4-a716-446655440000
                      externalId: cliente_123
                      name: Joao Silva
                      email: joao@email.com
                      document: 123.456.789-00
                      documentType: CPF
                      phone: '11999998888'
                      status: Active
                      metadata: null
                      address: null
                      createdAt: '2025-01-15T15:00:00Z'
                  page: 1
                  pageSize: 20
                  totalItems: 1
                  totalPages: 1
                  hasNextPage: false
                  hasPreviousPage: false
                message: null
                error: null
        '401':
          description: Nao autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                data: null
                message: null
                error:
                  message: Token invalido ou expirado.
                  code: unauthorized
components:
  schemas:
    ListCustomersResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PaginatedCustomers'
        message:
          type: string
          nullable: true
        error:
          $ref: '#/components/schemas/ApiErrorResponse'
    BaseResponse:
      type: object
      properties:

```

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

### List Cashouts API Endpoint (OpenAPI)

Source: https://docs.safefypay.com.br/api-reference/cashouts/list

Defines the GET /v1/cashouts endpoint for listing cashouts. Supports pagination, filtering by status, and date ranges. Returns a paginated list of cashout objects or an error response.

```yaml
openapi: 3.1.1
info:
  title: Safefy - Pix Gateway
  description: |
    ## Introducao

    **Seu parceiro financeiro de confianca.**

    Nos somos a Safefy, uma plataforma especializada em solucoes de pagamento
    PIX. Com um servico personalizado e focado nas suas necessidades, estamos
    prontos para apoiar sua empresa em cada etapa do processo.

    - Conte com o **PIX** como metodo de pagamento rapido, seguro e alinhado com
    as melhores praticas de conformidade e prevencao a fraudes.

    - Gerencie suas financas de forma simples e acessivel por meio de uma
    interface completa e intuitiva.

    - Nosso time de suporte esta sempre disponivel para oferecer um atendimento
    exclusivo e eficiente.

    ## Precisa de Ajuda?

    A equipe da Safefy quer garantir que sua integracao seja um sucesso. Se
    tiver duvidas ou precisar de suporte, nao hesite em nos contatar:

    **suporte@safefypay.com.br**

    ---

    ## Valores Monetarios

    Todos os valores monetarios sao representados em **centavos** (menor unidade
    da moeda).

    | Valor Real | Valor na API |
    |------------|--------------|
    | R$ 1,00    | 100          |
    | R$ 10,50   | 1050         |
    | R$ 100,00  | 10000        |
  contact:
    name: Suporte Safefy
    email: suporte@safefypay.com.br
  version: v1
servers:
  - url: https://api-payment.safefypay.com.br
    description: API de Pagamentos Safefy
security:
  - bearerAuth: []
tags:
  - name: Autenticacao
    description: Endpoints de autenticacao OAuth2
  - name: Transacoes
    description: Gerenciamento de transacoes PIX
  - name: Clientes
    description: Gerenciamento de clientes
  - name: Saldo
    description: Consulta de saldo e volumes
  - name: Saques
    description: Solicitacao e gerenciamento de saques
paths:
  /v1/cashouts:
    get:
      tags:
        - Saques
      summary: Listar saques
      description: Retorna uma lista paginada de saques com suporte a filtros.
      operationId: listCashouts
      parameters:
        - name: page
          in: query
          description: Numero da pagina
          schema:
            type: integer
            default: 1
            example: 1
        - name: pageSize
          in: query
          description: 'Itens por pagina (max: 100)'
          schema:
            type: integer
            default: 20
            example: 20
        - name: status
          in: query
          description: Filtrar por status
          schema:
            type: string
            enum:
              - Pending
              - Processing
              - Completed
              - Failed
              - Rejected
              - Cancelled
            example: Completed
        - name: startDate
          in: query
          description: Data inicial (ISO 8601)
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: endDate
          in: query
          description: Data final (ISO 8601)
          schema:
            type: string
            format: date-time
            example: '2025-01-31T23:59:59Z'
      responses:
        '200':
          description: Lista de saques
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCashoutsResponse'
              example:
                data:
                  items:
                    - id: b2c3d4e5-f6a7-8901-bcde-f23456789012
                      amount: 50000
                      fee: 200
                      netAmount: 49800
                      status: Completed
                      pixKeyType: CPF
                      pixKey: '***456789**'
                      endToEndId: E12345678202501151600xyz789abc012
                      failureReason: null
                      requestedAt: '2025-01-15T16:00:00Z'
                      completedAt: '2025-01-15T16:05:00Z'
                      createdAt: '2025-01-15T16:00:00Z'
                  page: 1
                  pageSize: 20
                  totalItems: 1
                  totalPages: 1
                  hasNextPage: false
                  hasPreviousPage: false
                message: null
                error: null
        '401':
          description: Nao autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCashoutsResponse'
              example:
                data: null
                message: null
                error:
                  message: Token invalido ou expirado.
                  code: unauthorized
components:
  schemas:
    ListCashoutsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PaginatedCashouts'
        message:
          type: string
          nullable: true
        error:
          $ref: '#/components/schemas/ApiErrorResponse'
    PaginatedCashouts:

```

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

### GET /v1/transactions/{id}

Source: https://docs.safefypay.com.br/api-reference/transactions

Retrieves a specific transaction by its ID. Use this to get details of a single transaction.

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

### Description
Retrieves a specific transaction by its ID.

### Method
GET

### Endpoint
/v1/transactions/{id}

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

### Request Example
*No example provided in the input text.*

### Response
#### Success Response (200)
*The success response schema is not provided in the input text.*

#### Response Example
*No example provided in the input text.*
```

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

### POST /websites/safefypay_br_api-reference/withdrawals/simulate

Source: https://docs.safefypay.com.br/api-reference/cashouts/simulate

Simula o processamento de um saque no ambiente Sandbox. Permite testar diferentes cenários de saque, como conclusão com sucesso, falha ou rejeição.

```APIDOC
## POST /websites/safefypay_br_api-reference/withdrawals/simulate

### Description
Simula o processamento de um saque no ambiente Sandbox. Use para testar fluxos de saque sem dinheiro real.

<Warning>
  Disponível apenas no ambiente **Sandbox**.
</Warning>

### Method
POST

### Endpoint
/websites/safefypay_br_api-reference/withdrawals/simulate

### Parameters
#### Path Parameters
- **id** (string) - Required - ID do saque (UUID).

#### Query Parameters
Nenhum

#### Request Body
- **action** (integer) - Required - Ação a simular:
  * `1` - Simula conclusão com sucesso (Completed)
  * `2` - Simula falha (Failed)
  * `3` - Simula rejeição (Rejected)

### Request Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "action": 1
}
```

### Response
#### Success Response (200)
* **message** (string) - Mensagem de confirmação da simulação.

#### Response Example
```json
{
  "message": "Simulação de saque concluída com sucesso."
}
```
```

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

### GET /v1/cashouts/{id}

Source: https://docs.safefypay.com.br/api-reference/cashouts/get

Retrieves the complete data for a specific cashout request.

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

### Description
Retrieves the complete data for a specific cashout request.

### Method
GET

### Endpoint
/v1/cashouts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - ID of the cashout

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **data** (object) - Details of the cashout.
- **message** (string) - Nullable.
- **error** (object) - Nullable.

#### Response Example
```json
{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "externalId": "saque_001",
    "amount": 50000,
    "fee": 200,
    "netAmount": 49800,
    "currency": "BRL",
    "status": "Completed",
    "environment": "Sandbox",
    "pix": {
      "pixKeyType": "CPF",
      "pixKey": "***456789**",
      "endToEndId": "E12345678202501151600xyz789abc012"
    },
    "requestedAt": "2025-01-15T16:00:00Z",
    "processedAt": "2025-01-15T16:02:00Z",
    "completedAt": "2025-01-15T16:05:00Z",
    "failureReason": null,
    "createdAt": "2025-01-15T16:00:00Z"
  },
  "message": null,
  "error": null
}
```

#### Error Response (401)
- **data** (null)
- **message** (null)
- **error** (object) - Contains error details.

#### Error Response Example (401)
```json
{
  "data": null,
  "message": null,
  "error": {
    "message": "Token invalido ou expirado.",
    "code": "unauthorized"
  }
}
```

#### Error Response (404)
- **data** (null)
- **message** (null)
- **error** (object) - Contains error details.

#### Error Response Example (404)
```json
{
  "data": null,
  "message": null,
  "error": {
    "message": "Saque nao encontrado.",
    "code": "not_found"
  }
}
```
```

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

### POST /simulate/transaction/{transactionId}

Source: https://docs.safefypay.com.br/api-reference/transactions/simulate

Simula ações em uma transação no ambiente Sandbox, como pagamento, expiração, falha ou estorno.

```APIDOC
## POST /simulate/transaction/{transactionId}

### Description
Simula ações em uma transação no ambiente Sandbox. Use para testar fluxos de pagamento sem dinheiro real.

<Warning>
  Disponível apenas no ambiente **Sandbox**.
</Warning>

### Method
POST

### Endpoint
/simulate/transaction/{transactionId}

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - ID da transação (UUID).

#### Query Parameters
Nenhum

#### Request Body
- **action** (string) - Required - Ação a simular:
  * `pay` - Simula o pagamento (muda status para Completed)
  * `expire` - Simula expiração (muda status para Expired)
  * `fail` - Simula falha (muda status para Failed)
  * `refund` - Simula estorno (muda status para Refunded)

### Request Example
```json
{
  "action": "pay"
}
```

### Response
#### Success Response (200)
- **status** (string) - O novo status da transação.
- **message** (string) - Mensagem de confirmação da simulação.

#### Response Example
```json
{
  "status": "Completed",
  "message": "Ação 'pay' simulada com sucesso."
}
```

<Note>
  A simulação dispara webhooks normalmente, permitindo testar seu endpoint de callback.
</Note>
```

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

### GET /withdrawals/{id}

Source: https://docs.safefypay.com.br/api-reference/cashouts/get

Retrieve complete data for a specific withdrawal by its ID.

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

### Description
Consult a withdrawal by ID. Returns the complete data of a specific withdrawal.

### Method
GET

### Endpoint
/withdrawals/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - ID of the withdrawal (UUID).

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the withdrawal.
- **amount** (number) - The withdrawal amount.
- **currency** (string) - The currency of the withdrawal.
- **status** (string) - The current status of the withdrawal (e.g., PENDING, COMPLETED, FAILED).
- **createdAt** (string) - The timestamp when the withdrawal was created.
- **updatedAt** (string) - The timestamp when the withdrawal was last updated.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "amount": 100.50,
  "currency": "BRL",
  "status": "COMPLETED",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z"
}
```
```

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

### Buscar Cliente por ID

Source: https://docs.safefypay.com.br/api-reference/customers/get

Consulte um cliente por ID. Retorna os dados completos de um cliente específico.

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

### Description
Consulte um cliente por ID. Retorna os dados completos de um cliente específico.

### Method
GET

### Endpoint
/clientes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - ID do cliente (UUID).

### Response
#### Success Response (200)
- **[fields]** (object) - Dados completos do cliente.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "nome": "Nome do Cliente",
  "email": "cliente@example.com"
}
```
```

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

### GET /v1/transactions

Source: https://docs.safefypay.com.br/api-reference/transactions/list

Retrieves a paginated list of transactions with support for various filtering options.

```APIDOC
## GET /v1/transactions

### Description
Returns a paginated list of transactions with support for filters.

### Method
GET

### Endpoint
/v1/transactions

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Number of the page. Default: 1. Example: 1
- **pageSize** (integer) - Optional - Items per page (max: 100). Default: 20. Example: 20
- **status** (string) - Optional - Filter by status. Allowed values: Pending, Completed, Expired, Failed, Refunded. Example: Completed
- **method** (string) - Optional - Filter by payment method. Allowed values: Pix, CreditCard, Boleto. Example: Pix
- **externalId** (string) - Optional - Search by external ID. Example: pedido_12345
- **customerId** (string) - Optional - Filter by customer ID. Format: uuid. Example: 550e8400-e29b-41d4-a716-446655440000
- **startDate** (string) - Optional - Start date (ISO 8601). Example: '2025-01-01T00:00:00Z'
- **endDate** (string) - Optional - End date (ISO 8601). Example: '2025-01-31T23:59:59Z'

### Response
#### Success Response (200)
- **data** (object) - Contains the list of transactions.
  - **items** (array) - Array of transaction objects.
    - **id** (string) - Unique identifier for the transaction.
    - **externalId** (string) - External identifier for the transaction.
    - **method** (string) - Payment method used.
    - **amount** (integer) - Total amount in cents.
    - **fee** (integer) - Transaction fee in cents.
    - **netAmount** (integer) - Net amount after fee in cents.
    - **currency** (string) - Currency of the transaction (e.g., BRL).
    - **status** (string) - Current status of the transaction.
    - **description** (string) - Description of the transaction.
    - **environment** (string) - Environment where the transaction occurred (e.g., Sandbox).
    - **expiresAt** (string) - Expiration date and time in ISO 8601 format.
    - **completedAt** (string) - Completion date and time in ISO 8601 format.
    - **createdAt** (string) - Creation date and time in ISO 8601 format.
    - **customerId** (string) - ID of the customer associated with the transaction.
    - **customer** (object) - Customer details.
      - **id** (string) - Unique identifier for the customer.
      - **name** (string) - Name of the customer.
      - **email** (string) - Email address of the customer.

#### Response Example
```json
{
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "externalId": "pedido_12345",
        "method": "Pix",
        "amount": 10000,
        "fee": 150,
        "netAmount": 9850,
        "currency": "BRL",
        "status": "Completed",
        "description": "Pagamento do pedido #12345",
        "environment": "Sandbox",
        "expiresAt": "2025-01-15T15:30:00Z",
        "completedAt": "2025-01-15T15:10:00Z",
        "createdAt": "2025-01-15T15:00:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "customer": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Joao Silva",
          "email": "joao@email.com"
        }
      }
    ]
  }
}
```
```

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

### Get Transaction Details

Source: https://docs.safefypay.com.br/api-reference/transactions/get

Retrieves the details of a specific transaction using its unique identifier.

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

### Description
Retrieves the details of a specific transaction using its unique identifier.

### Method
GET

### Endpoint
/transactions/{transactionId}

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

### Response
#### Success Response (200)
- **data** (object) - Contains the transaction details.
  - **id** (string) - The transaction's unique ID.
  - **externalId** (string) - The external identifier for the transaction.
  - **method** (string) - The payment method used (e.g., Pix, Card, Boleto).
  - **amount** (integer) - The total transaction amount in cents.
  - **fee** (integer) - The transaction fee in cents.
  - **netAmount** (integer) - The net amount after fees in cents.
  - **currency** (string) - The currency of the transaction (e.g., BRL).
  - **status** (string) - The current status of the transaction (e.g., Completed, Pending, Failed).
  - **description** (string) - A description for the transaction.
  - **failureReason** (string) - The reason for transaction failure, if applicable.
  - **environment** (string) - The environment the transaction was processed in (e.g., Sandbox, Production).
  - **metadata** (string) - Additional metadata associated with the transaction.
  - **callbackUrl** (string) - The URL to send transaction status updates to.
  - **customerId** (string) - The ID of the customer associated with the transaction.
  - **expiresAt** (string) - The expiration date and time of the transaction.
  - **completedAt** (string) - The date and time the transaction was completed.
  - **refundedAt** (string) - The date and time the transaction was refunded.
  - **createdAt** (string) - The date and time the transaction was created.
  - **updatedAt** (string) - The date and time the transaction was last updated.
  - **pix** (object) - Details specific to Pix transactions.
  - **card** (object) - Details specific to Card transactions.
  - **boleto** (object) - Details specific to Boleto transactions.
  - **customer** (object) - Details about the customer.
- **message** (string) - A success message, if any.

#### Error Response (404)
- **error** (object)
  - **message** (string) - Error message (e.g., "Transacao nao encontrada.").
  - **code** (string) - Error code (e.g., "not_found").

### Response Example
```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "pedido_12345",
    "method": "Pix",
    "amount": 10000,
    "fee": 150,
    "netAmount": 9850,
    "currency": "BRL",
    "status": "Completed",
    "description": "Pagamento do pedido #12345",
    "failureReason": null,
    "environment": "Sandbox",
    "metadata": "{\"orderId\": 12345}",
    "callbackUrl": "https://seusite.com.br/webhook",
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2025-01-15T15:30:00Z",
    "completedAt": "2025-01-15T15:10:00Z",
    "refundedAt": null,
    "createdAt": "2025-01-15T15:00:00Z",
    "updatedAt": "2025-01-15T15:10:00Z",
    "pix": {
      "txId": "SAFEFY2025011512345678901234",
      "endToEndId": "E12345678202501151510abc123def456",
      "copyAndPaste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890...",
      "payerName": "Joao Silva",
      "payerDocument": "***456789**",
      "payerBank": "Banco do Brasil",
      "expiresAt": "2025-01-15T15:30:00Z"
    },
    "card": null,
    "boleto": null,
    "customer": {
      "name": "Cliente Exemplo",
      "document": "123.456.789-00",
      "email": "cliente@exemplo.com"
    }
  },
  "message": null
}
```
```

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

### Listar Clientes

Source: https://docs.safefypay.com.br/api-reference/customers/list

Retorna uma lista paginada de clientes com opções de filtragem.

```APIDOC
## GET /clientes

### Description
Liste e filtre seus clientes. Retorna uma lista paginada de clientes com opções de filtragem.

### Method
GET

### Endpoint
/clientes

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Número da página. Padrão: 1.
- **pageSize** (integer) - Optional - Quantidade de itens por página. Padrão: 20. Máximo: 100.
- **status** (string) - Optional - Filtrar por status: `Active` ou `Inactive`.
- **documentType** (string) - Optional - Filtrar por tipo de documento: `CPF` ou `CNPJ`.
- **search** (string) - Optional - Buscar por nome, email ou documento.
- **externalId** (string) - Optional - Filtrar por ID externo.
- **startDate** (string) - Optional - Data inicial no formato ISO 8601.
- **endDate** (string) - Optional - Data final no formato ISO 8601.

### Response
#### Success Response (200)
- **clientes** (array) - Lista de clientes.
  - **id** (string) - ID do cliente.
  - **name** (string) - Nome do cliente.
  - **email** (string) - Email do cliente.
  - **document** (string) - Documento do cliente.
  - **status** (string) - Status do cliente (`Active` ou `Inactive`).
  - **documentType** (string) - Tipo de documento (`CPF` ou `CNPJ`).
  - **externalId** (string) - ID externo do cliente.
  - **createdAt** (string) - Data de criação do cliente (ISO 8601).
  - **updatedAt** (string) - Data de atualização do cliente (ISO 8601).

#### Response Example
```json
{
  "clientes": [
    {
      "id": "clt_123",
      "name": "João Silva",
      "email": "joao.silva@example.com",
      "document": "123.456.789-00",
      "status": "Active",
      "documentType": "CPF",
      "externalId": "ext_abc",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

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

### GET /v1/customers

Source: https://docs.safefypay.com.br/api-reference/customers/list

Retrieves a paginated list of customers, with support for various filtering options.

```APIDOC
## GET /v1/customers

### Description
Retrieves a paginated list of customers with support for filtering.

### Method
GET

### Endpoint
/v1/customers

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Number of the page. Default: 1. Example: 1
- **pageSize** (integer) - Optional - Items per page (max: 100). Default: 20. Example: 20
- **status** (string) - Optional - Filter by status. Enum: Active, Inactive. Example: Active
- **documentType** (string) - Optional - Filter by document type. Enum: CPF, CNPJ. Example: CPF
- **search** (string) - Optional - Search by name, email, or document. Example: joao
- **externalId** (string) - Optional - Filter by external ID. Example: cliente_123

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains paginated customer data.
  - **items** (array) - List of customer objects.
    - **id** (string) - Unique identifier for the customer.
    - **externalId** (string) - External identifier for the customer.
    - **name** (string) - Name of the customer.
    - **email** (string) - Email address of the customer.
    - **document** (string) - Document number (CPF or CNPJ).
    - **documentType** (string) - Type of the document (CPF or CNPJ).
    - **phone** (string) - Phone number of the customer.
    - **status** (string) - Status of the customer (Active or Inactive).
    - **metadata** (object) - Additional metadata for the customer.
    - **address** (object) - Address information for the customer.
    - **createdAt** (string) - Timestamp when the customer was created.
  - **page** (integer) - Current page number.
  - **pageSize** (integer) - Number of items per page.
  - **totalItems** (integer) - Total number of items available.
  - **totalPages** (integer) - Total number of pages.
  - **hasNextPage** (boolean) - Indicates if there is a next page.
  - **hasPreviousPage** (boolean) - Indicates if there is a previous page.
- **message** (string) - Nullable. Success message.
- **error** (object) - Nullable. Error details.

#### Error Response (401)
- **data** (object) - Null. Data field is null for errors.
- **message** (string) - Nullable. Error message.
- **error** (object) - Error details.
  - **message** (string) - Description of the error. Example: Token invalido ou expirado.
  - **code** (string) - Error code. Example: unauthorized

#### Response Example
```json
{
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "externalId": "cliente_123",
        "name": "Joao Silva",
        "email": "joao@email.com",
        "document": "123.456.789-00",
        "documentType": "CPF",
        "phone": "11999998888",
        "status": "Active",
        "metadata": null,
        "address": null,
        "createdAt": "2025-01-15T15:00:00Z"
      }
    ],
    "page": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "message": null,
  "error": null
}
```
```
Tokens:
Raw