### Transaction Object Structure and Example (JSON)

Source: https://docs.blupayip.io/get-pix-out-transaction-25565106e0

Defines the structure of a successful transaction object for 'pix_out' type payments. It includes fields for transaction ID, amount, status, company details, payment method, timestamps, customer information, PIX-specific details, fee information, and potential refusal reasons. An example demonstrates a typical paid transaction.

```json
{
  "id": "f4b25725-5c90-485f-962d-aad7210b4f6a",
  "amount": 10000,
  "type": "pix_out",
  "status": "paid",
  "refundedAmount": 0,
  "companyId": "4d1a3c25-2cfc-4f72-b814-23d9fd168c8e",
  "paymentMethod": "pix",
  "externalRef": "withdraw_123",
  "postbackUrl": "https://webhook.example.com/postback",
  "ip": "::1",
  "createdAt": "2025-12-12T00:41:31.170Z",
  "updatedAt": "2025-12-12T00:41:41.976Z",
  "paidAt": "2025-12-12T00:41:41.955Z",
  "cancelledAt": null,
  "refundedAt": null,
  "customer": null,
  "pix": {
    "endToEndId": "E04838403202512120041TS55EAFN3YS",
    "destination": {
      "pixKey": "maria.santos@example.com",
      "pixKeyType": "EMAIL",
      "name": "Maria Santos",
      "document": "98765432100"
    },
    "requiresManualApproval": false,
    "beneficiary": {
      "name": "MARIA SANTOS OLIVEIRA",
      "document": "98765432100",
      "documentType": "cpf",
      "branch": "0001",
      "account": "123456",
      "bankName": "ITAÚ",
      "bankIspb": "60701190"
    }
  },
  "refusedReason": null,
  "refusedCode": null,
  "refunds": [],
  "fee": {
    "total": 60,
    "net": 9940
  }
}
```

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

### GET /baseUrl/api/v1/balance

Source: https://docs.blupayip.io/get-wallet-balances-25565108e0

Retrieves the balances for PIX, PIX_BLOCKED, and RESERVE wallets for the authenticated company. This endpoint requires Basic Authentication using your secretKey and publicKey.

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

### Description
Returns balances for PIX, PIX_BLOCKED, and RESERVE wallets for the authenticated company. Requires Basic Auth (`secretKey:publicKey`).

### Method
GET

### Endpoint
/baseUrl/api/v1/balance

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the wallet balance information.
  - **pix** (object) - Balance details for the PIX wallet.
    - **balance** (string) - The available balance for the PIX wallet.
  - **pixBlocked** (object) - Balance details for the PIX_BLOCKED wallet.
    - **balance** (string) - The blocked balance for the PIX_BLOCKED wallet.
  - **reserve** (object) - Balance details for the RESERVE wallet.
    - **balance** (string) - The available balance for the RESERVE wallet.

#### Response Example
```json
{
  "success": true,
  "data": {
    "pix": {
      "balance": "36.36"
    },
    "pixBlocked": {
      "balance": "0.00"
    },
    "reserve": {
      "balance": "0.00"
    }
  }
}
```
```

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

### GET /baseUrl/api/v1/transactions/pix-in

Source: https://docs.blupayip.io/get-pix-in-transaction-25565105e0

Retrieve a PIX IN transaction by `id` or `externalRef`. Requires Basic Auth.

```APIDOC
## GET /baseUrl/api/v1/transactions/pix-in

### Description
Retrieve a PIX IN transaction by `id` or `externalRef`. Requires Basic Auth (`secretKey:publicKey`).

### Method
GET

### Endpoint
/baseUrl/api/v1/transactions/pix-in

### Parameters
#### Query Parameters
- **id** (string) - Required - Transaction id (UUID)
- **externalRef** (string) - Required - Optional external reference

### Request Example
```bash
curl -X GET \
  'https://your-api-domain.com/baseUrl/api/v1/transactions/pix-in?id={{transactionId}}' \
  -H 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS'
```

### Response
#### Success Response (200)
- **id** (string) - Transaction ID
- **amount** (integer) - Transaction amount
- **type** (string) - Transaction type
- **status** (string) - Transaction status
- **refundedAmount** (integer) - Amount refunded
- **companyId** (string) - Company ID
- **paymentMethod** (string) - Payment method used
- **externalRef** (string) - Client reference
- **postbackUrl** (string) - URL for postback notifications
- **ip** (string) - IP address of the client
- **createdAt** (string) - Timestamp of creation
- **updatedAt** (string) - Timestamp of last update
- **paidAt** (string) - Timestamp of payment
- **cancelledAt** (null) - Timestamp of cancellation (if applicable)
- **refundedAt** (null) - Timestamp of refund (if applicable)
- **customer** (object) - Customer details
  - **id** (string) - Customer ID
  - **name** (string) - Customer name
  - **email** (string) - Customer email
  - **phone** (string) - Customer phone number
  - **document** (object) - Customer document details
    - **type** (string) - Document type (e.g., CPF, CNPJ)
    - **number** (string) - Document number
- **pix** (object) - PIX transaction details
  - **qrcode** (string) - PIX QR code
  - **expiresAt** (string) - Expiration timestamp for the QR code
  - **endToEndId** (string) - End-to-end ID for the PIX transaction
  - **payer** (object) - Payer details
    - **name** (string) - Payer name
    - **document** (string) - Payer document number
    - **documentType** (string) - Payer document type
    - **branch** (string) - Payer bank branch
    - **account** (string) - Payer bank account number
    - **bankName** (string) - Payer bank name
    - **bankIspb** (string) - Payer bank ISPB code

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "amount": 10000,
  "type": "PIX_IN",
  "status": "PAID",
  "refundedAmount": 0,
  "companyId": "comp-12345",
  "paymentMethod": "PIX",
  "externalRef": "REF123456789",
  "postbackUrl": "https://example.com/postback",
  "ip": "192.168.1.1",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:05:00Z",
  "paidAt": "2023-10-27T10:02:00Z",
  "cancelledAt": null,
  "refundedAt": null,
  "customer": {
    "id": "cust-abcde",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "12345678900"
    }
  },
  "pix": {
    "qrcode": "00020126...",
    "expiresAt": "2023-10-27T11:00:00Z",
    "endToEndId": "E12345678901234567890",
    "payer": {
      "name": "Jane Smith",
      "document": "98765432100",
      "documentType": "CPF",
      "branch": "0001",
      "account": "12345-6",
      "bankName": "Banco Exemplo",
      "bankIspb": "12345678"
    }
  }
}
```
```

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

### Wallets - Get Balances

Source: https://docs.blupayip.io/index

Retrieves the current balances of your Pix wallet.

```APIDOC
## GET /wallets/balances

### Description
Retrieves the current balances of your Pix wallet, including available, blocked, and reserve amounts.

### Method
GET

### Endpoint
/wallets/balances

### Response
#### Success Response (200)
- **available** (integer) - The available balance in cents.
- **blocked** (integer) - The blocked balance in cents.
- **reserve** (integer) - The reserve balance in cents.

#### Response Example
```json
{
  "available": 150000,
  "blocked": 5000,
  "reserve": 10000
}
```
```

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

### GET /websites/blupayip_io

Source: https://docs.blupayip.io/get-pix-out-transaction-25565106e0

Retrieves details of a specific transaction. This endpoint allows you to fetch comprehensive information about a transaction, including its status, amount, payment method, and associated fees.

```APIDOC
## GET /websites/blupayip_io

### Description
Retrieves details of a specific transaction. This endpoint allows you to fetch comprehensive information about a transaction, including its status, amount, payment method, and associated fees.

### Method
GET

### Endpoint
/websites/blupayip_io

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

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

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the transaction.
- **amount** (integer) - The transaction amount.
- **type** (string) - The type of transaction (e.g., 'pix_out').
- **status** (string) - The current status of the transaction (e.g., 'paid', 'pending', 'failed').
- **refundedAmount** (integer) - The amount that has been refunded.
- **companyId** (string) - The identifier of the company associated with the transaction.
- **paymentMethod** (string) - The payment method used for the transaction (e.g., 'pix').
- **externalRef** (string) - An external reference identifier for the transaction.
- **postbackUrl** (string) - The URL to which postback notifications should be sent.
- **ip** (string) - The IP address from which the transaction was initiated.
- **createdAt** (string) - The timestamp when the transaction was created.
- **updatedAt** (string) - The timestamp when the transaction was last updated.
- **paidAt** (string) - The timestamp when the transaction was paid.
- **cancelledAt** (string) - The timestamp when the transaction was cancelled (null if not cancelled).
- **refundedAt** (string) - The timestamp when the transaction was refunded (null if not refunded).
- **customer** (object) - Customer details (null if not applicable).
- **pix** (object) - Details specific to PIX transactions.
  - **endToEndId** (string) - The end-to-end identifier for the PIX transaction.
  - **destination** (object) - PIX destination details.
    - **pixKey** (string) - The PIX key of the destination.
    - **pixKeyType** (string) - The type of the PIX key (e.g., 'EMAIL', 'CPF').
    - **name** (string) - The name of the destination.
    - **document** (string) - The document number of the destination.
  - **requiresManualApproval** (boolean) - Indicates if manual approval is required for the PIX transaction.
  - **beneficiary** (object) - Beneficiary details for the PIX transaction.
    - **name** (string) - The name of the beneficiary.
    - **document** (string) - The document number of the beneficiary.
    - **documentType** (string) - The type of the beneficiary's document (e.g., 'cpf').
    - **branch** (string) - The branch code of the beneficiary's bank.
    - **account** (string) - The account number of the beneficiary.
    - **bankName** (string) - The name of the beneficiary's bank.
    - **bankIspb** (string) - The ISPB code of the beneficiary's bank.
- **refusedReason** (string) - The reason for refusal (null if not refused).
- **refusedCode** (string) - The code associated with the refusal (null if not refused).
- **refunds** (array) - A list of refund identifiers.
- **fee** (object) - Fee details for the transaction.
  - **total** (integer) - The total fee amount.
  - **net** (integer) - The net fee amount.

#### Response Example
```json
{
  "id": "f4b25725-5c90-485f-962d-aad7210b4f6a",
  "amount": 10000,
  "type": "pix_out",
  "status": "paid",
  "refundedAmount": 0,
  "companyId": "4d1a3c25-2cfc-4f72-b814-23d9fd168c8e",
  "paymentMethod": "pix",
  "externalRef": "withdraw_123",
  "postbackUrl": "https://webhook.example.com/postback",
  "ip": "::1",
  "createdAt": "2025-12-12T00:41:31.170Z",
  "updatedAt": "2025-12-12T00:41:41.976Z",
  "paidAt": "2025-12-12T00:41:41.955Z",
  "cancelledAt": null,
  "refundedAt": null,
  "customer": null,
  "pix": {
    "endToEndId": "E04838403202512120041TS55EAFN3YS",
    "destination": {
      "pixKey": "maria.santos@example.com",
      "pixKeyType": "EMAIL",
      "name": "Maria Santos",
      "document": "98765432100"
    },
    "requiresManualApproval": false,
    "beneficiary": {
      "name": "MARIA SANTOS OLIVEIRA",
      "document": "98765432100",
      "documentType": "cpf",
      "branch": "0001",
      "account": "123456",
      "bankName": "ITAÚ",
      "bankIspb": "60701190"
    }
  },
  "refusedReason": null,
  "refusedCode": null,
  "refunds": [],
  "fee": {
    "total": 60,
    "net": 9940
  }
}
```

#### Error Response (404)
- **error** (string) - A message describing the error.
- **code** (string) - An error code.

#### Error Response Example
```json
{
  "error": "Transaction not found",
  "code": "TRANSACTION_NOT_FOUND"
}
```
```

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

### Get Wallet Balances - OpenAPI Specification

Source: https://docs.blupayip.io/get-wallet-balances-25565108e0

This OpenAPI 3.0.1 specification defines the 'Get Wallet Balances' endpoint. It returns balances for PIX, PIX_BLOCKED, and RESERVE wallets for the authenticated company. Authentication is handled via Basic Auth using `secretKey:publicKey`.

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /baseUrl/api/v1/balance:
    get:
      summary: Get Wallet Balances
      deprecated: false
      description: >-
        Returns balances for PIX, PIX_BLOCKED, and RESERVE wallets for the
        authenticated company. Requires Basic Auth (`secretKey:publicKey`).
      tags:
        - Wallets
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      pix:
                        type: object
                        properties:
                          balance:
                            type: string
                        required:
                          - balance
                        x-apidog-orders:
                          - balance
                      pixBlocked:
                        type: object
                        properties:
                          balance:
                            type: string
                        required:
                          - balance
                        x-apidog-orders:
                          - balance
                      reserve:
                        type: object
                        properties:
                          balance:
                            type: string
                        required:
                          - balance
                        x-apidog-orders:
                          - balance
                    required:
                      - pix
                      - pixBlocked
                      - reserve
                    x-apidog-orders:
                      - pix
                      - pixBlocked
                      - reserve
                required:
                  - success
                  - data
                x-apidog-orders:
                  - success
                  - data
              example:
                success: true
                data:
                  pix:
                    balance: '36.36'
                  pixBlocked:
                    balance: '0.00'
                  reserve:
                    balance: '0.00'
          headers: {}
          x-apidog-name: ''
      security:
        - basic: []
      x-apidog-folder: Wallets
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1152278/apis/api-25565108-run
components:
  schemas: {}
  securitySchemes:
    basic:
      type: http
      scheme: basic
servers: []
security:
  - basic: []

```

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

### POST /websites/blupayip_io/transactions

Source: https://docs.blupayip.io/create-pix-out-transaction-25565107e0

Creates a new payment transaction. This endpoint allows initiating a payment with details such as amount, recipient information, and Pix key.

```APIDOC
## POST /websites/blupayip_io/transactions

### Description
Creates a new payment transaction. This endpoint allows initiating a payment with details such as amount, recipient information, and Pix key.

### Method
POST

### Endpoint
/websites/blupayip_io/transactions

### Parameters
#### Request Body
- **id** (string) - Required - Unique identifier for the transaction.
- **secureId** (string) - Required - Secure identifier for the transaction.
- **status** (string) - Required - Current status of the transaction (e.g., PROCESSING, COMPLETED, FAILED).
- **amount** (integer) - Required - The total amount of the transaction in cents.
- **fee** (integer) - Required - The transaction fee in cents.
- **netAmount** (integer) - Required - The net amount after deducting the fee, in cents.
- **pixKey** (string) - Required - The Pix key associated with the transaction.
- **pixKeyType** (string) - Required - The type of the Pix key (e.g., EMAIL, CPF, PHONE, RANDOM).
- **destinationName** (string) - Required - The name of the recipient.
- **destinationDocument** (string) - Required - The document number (CPF or CNPJ) of the recipient.
- **requiresManualApproval** (boolean) - Required - Indicates if manual approval is needed for the transaction.
- **acquirerTxId** (string or null) - Required - The acquirer's transaction ID, can be null.
- **createdAt** (string) - Required - The timestamp when the transaction was created, in ISO 8601 format.

### Request Example
```json
{
  "id": "dd5c6b14-8fb2-4eaf-b092-7e65a6f3182b",
  "secureId": "e9fa7447-40b9-46e6-b4e5-29bce3043edc",
  "status": "PROCESSING",
  "amount": 10000,
  "fee": 60,
  "netAmount": 10000,
  "pixKey": "maria.santos@example.com",
  "pixKeyType": "EMAIL",
  "destinationName": "Maria Santos",
  "destinationDocument": "98765432100",
  "requiresManualApproval": false,
  "acquirerTxId": null,
  "createdAt": "2025-12-12T02:11:40.090Z"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the created transaction.
  - **id** (string) - Unique identifier for the transaction.
  - **secureId** (string) - Secure identifier for the transaction.
  - **status** (string) - Current status of the transaction.
  - **amount** (integer) - The total amount of the transaction in cents.
  - **fee** (integer) - The transaction fee in cents.
  - **netAmount** (integer) - The net amount after deducting the fee, in cents.
  - **pixKey** (string) - The Pix key associated with the transaction.
  - **pixKeyType** (string) - The type of the Pix key.
  - **destinationName** (string) - The name of the recipient.
  - **destinationDocument** (string) - The document number of the recipient.
  - **requiresManualApproval** (boolean) - Indicates if manual approval is needed.
  - **acquirerTxId** (string or null) - The acquirer's transaction ID.
  - **createdAt** (string) - The timestamp when the transaction was created.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "dd5c6b14-8fb2-4eaf-b092-7e65a6f3182b",
    "secureId": "e9fa7447-40b9-46e6-b4e5-29bce3043edc",
    "status": "PROCESSING",
    "amount": 10000,
    "fee": 60,
    "netAmount": 10000,
    "pixKey": "maria.santos@example.com",
    "pixKeyType": "EMAIL",
    "destinationName": "Maria Santos",
    "destinationDocument": "98765432100",
    "requiresManualApproval": false,
    "acquirerTxId": null,
    "createdAt": "2025-12-12T02:11:40.090Z"
  }
}
```

#### Error Responses
- **400 Bad Request**:
  - **error** (string) - Error type (e.g., VALIDATION_ERROR).
  - **message** (string) - Description of the error (e.g., pixKey is required).
  - **code** (string) - Specific error code (e.g., INVALID_PIX_KEY).
  - Example:
    ```json
    {
      "error": "VALIDATION_ERROR",
      "message": "pixKey is required",
      "code": "INVALID_PIX_KEY"
    }
    ```
- **401 Unauthorized**:
  - **error** (string) - Error type (e.g., AUTHENTICATION_ERROR).
  - **message** (string) - Description of the error (e.g., Invalid or missing authentication credentials).
  - Example:
    ```json
    {
      "error": "AUTHENTICATION_ERROR",
      "message": "Invalid or missing authentication credentials"
    }
    ```
- **402 Payment Required**:
  - **error** (string) - Error type (e.g., BUSINESS_ERROR).
  - **message** (string) - Description of the error (e.g., Insufficient wallet balance).
  - **code** (string) - Specific error code (e.g., INSUFFICIENT_FUNDS).
  - Example:
    ```json
    {
      "error": "BUSINESS_ERROR",
      "message": "Insufficient wallet balance",
      "code": "INSUFFICIENT_FUNDS"
    }
    ```
- **422 Unprocessable Entity**:
  - **error** (string) - Error type.
  - Example:
    ```json
    {
      "error": "UNPROCESSABLE_ENTITY"
    }
    ```
```

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

### Pix Out API

Source: https://docs.blupayip.io/intro-1860985m0

Initiate Pix transfers and query their status.

```APIDOC
## Pix Out API

### Description
Initiate Pix transfers (withdrawals) and query their status using various identifiers.

### Method
POST, GET

### Endpoint
`/pix/out/transfers`, `/pix/out/transfers/{id}`, `/pix/out/transfers/by-external-ref/{externalRef}`, `/pix/out/transfers/by-idempotency-key/{idempotencyKey}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the transfer.
- **externalRef** (string) - Required - The external reference of the transfer.
- **idempotencyKey** (string) - Required - The idempotency key of the transfer.

#### Query Parameters
None

#### Request Body
For POST /pix/out/transfers:
- **amount** (integer) - Required - The amount to transfer in cents.
- **recipientBank** (string) - Required - The recipient's bank code.
- **recipientAccount** (string) - Required - The recipient's account number.
- **recipientName** (string) - Required - The recipient's full name.
- **recipientDocument** (string) - Required - The recipient's CPF or CNPJ.
- **description** (string) - Optional - A description for the transfer.
- **externalRef** (string) - Optional - An external reference for reconciliation.
- **idempotencyKey** (string) - Required - A UUID to ensure the transfer is processed only once.

### Request Example
POST /pix/out/transfers
```json
{
  "amount": 5000,
  "recipientBank": "001",
  "recipientAccount": "12345-6",
  "recipientName": "Jane Doe",
  "recipientDocument": "111.222.333-44",
  "description": "Payment for services",
  "externalRef": "service-payment-001",
  "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the transfer.
- **status** (string) - The current status of the transfer (e.g., `pending`, `completed`, `failed`).
- **externalRef** (string) - The external reference provided.
- **idempotencyKey** (string) - The idempotency key used.
- **createdAt** (string) - The timestamp when the transfer was initiated.

#### Response Example
```json
{
  "id": "txn_xyz789",
  "status": "completed",
  "externalRef": "service-payment-001",
  "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "createdAt": "2023-10-27T11:00:00Z"
}
```
```

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

### Webhooks - Pix In Events

Source: https://docs.blupayip.io/index

Handles incoming webhooks for Pix In transaction events.

```APIDOC
## POST /webhooks/pixin

### Description
Receives webhook notifications for Pix In transaction events. Supported events include `transaction.paid`, `transaction.refunded`, and `transaction.infraction`.

### Method
POST

### Endpoint
/webhooks/pixin

### Parameters
#### Header Parameters
- **X-Webhook-Signature** (string) - Optional - HMAC-SHA256 signature of the request body if `webhookSecret` is configured.

#### Request Body
- **event** (string) - The type of event (e.g., `transaction.paid`).
- **data** (object) - The payload containing transaction details.
  - **transactionId** (string) - The ID of the transaction.
  - **externalRef** (string) - The external reference for the transaction.
  - **amount** (integer) - The transaction amount in cents.
  - **status** (string) - The status of the transaction.
  - ... (other relevant transaction details)

### Request Example
```json
{
  "event": "transaction.paid",
  "data": {
    "transactionId": "txn_12345abcde",
    "externalRef": "ORDER987",
    "amount": 1000,
    "status": "paid",
    "paidAt": "2023-10-27T10:30:00Z"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the webhook was received.

#### Response Example
```json
{
  "message": "Webhook received successfully."
}
```
```

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

### Pix Out - Get Transaction

Source: https://docs.blupayip.io/index

Retrieves the details of a specific Pix Out transaction.

```APIDOC
## GET /pix/out/{transferId}

### Description
Retrieves the details of a specific Pix Out transaction.

### Method
GET

### Endpoint
/pix/out/{transferId}

### Parameters
#### Path Parameters
- **transferId** (string) - Required - The unique identifier of the transfer.

#### Query Parameters
- **externalRef** (string) - Optional - An external reference for reconciliation.
- **idempotencyKey** (string) - Optional - The idempotency key used when creating the transfer.

### Response
#### Success Response (200)
- **transferId** (string) - The unique identifier for the transfer.
- **amount** (integer) - The transfer amount in cents.
- **status** (string) - The current status of the transfer.
- **recipientBank** (string) - The recipient's bank code.
- **recipientBranch** (string) - The recipient's bank branch.
- **recipientAccount** (string) - The recipient's bank account number.
- **recipientName** (string) - The recipient's full name.
- **recipientDocument** (string) - The recipient's CPF or CNPJ.
- **description** (string) - A description for the transfer.
- **externalRef** (string) - The external reference provided.
- **createdAt** (string) - The timestamp when the transfer was created.

#### Response Example
```json
{
  "transferId": "trf_abcdef12345",
  "amount": 5000,
  "status": "completed",
  "recipientBank": "001",
  "recipientBranch": "0001",
  "recipientAccount": "12345-6",
  "recipientName": "Jane Doe",
  "recipientDocument": "111.222.333-44",
  "description": "Payment for invoice #INV987",
  "externalRef": "INV987",
  "createdAt": "2023-10-27T11:00:00Z"
}
```
```

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

### POST /baseUrl/api/v1/transactions/pix-out

Source: https://docs.blupayip.io/create-pix-out-transaction-25565107e0

Initiates a Pix Out transaction, debiting the company wallet and creating a Pix transfer to the specified destination key. Supports idempotency and webhooks for status updates.

```APIDOC
## POST /baseUrl/api/v1/transactions/pix-out

### Description
Initiates a Pix Out transaction, debiting the company wallet and creating a Pix transfer to the destination key. All amounts are in cents. The `Idempotency-Key` header is required to prevent duplicate transfers. Webhook notifications can be sent to a provided `postbackUrl`.

### Method
POST

### Endpoint
/baseUrl/api/v1/transactions/pix-out

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Header Parameters
- **Content-Type** (string) - Required - `application/json`
- **Idempotency-Key** (string) - Required - Unique UUID to prevent duplicate transfers. Use a new UUID for each new transfer request.
- **Authorization** (string) - Required - Basic Auth token.

#### Request Body
- **amount** (integer) - Required - Amount in cents (min: 100)
- **pixKey** (string) - Required - Destination Pix key
- **pixKeyType** (string) - Required - Type of Pix key (`CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `RANDOM`)
- **destinationName** (string) - Required - Recipient name
- **destinationDocument** (string) - Required - Recipient CPF/CNPJ (digits only)
- **externalRef** (string) - Optional - Client reference/external ID
- **postbackUrl** (string) - Optional - URL for webhook notifications
- **webhookSecret** (string) - Optional - Secret key for HMAC signature
- **metadata** (object) - Optional - Custom metadata for tracking
  - **channel** (string) - Required - The channel of the transaction.

### Request Example
```json
{
  "amount": 10000,
  "pixKey": "user@example.com",
  "pixKeyType": "EMAIL",
  "destinationName": "Maria Santos",
  "destinationDocument": "98765432100",
  "externalRef": "withdraw_123",
  "postbackUrl": "https://webhook.example.com/postback",
  "webhookSecret": "your-secret-key-for-hmac",
  "metadata": {
    "channel": "api"
  }
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains transaction details.
  - **id** (string) - Unique identifier for the transaction.
  - **secureId** (string) - Secure identifier for the transaction.
  - **status** (string) - Current status of the transaction.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "txn_12345abcde",
    "secureId": "sec_abcdef12345",
    "status": "PENDING"
  }
}
```
```

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

### Pix In - Get Transaction

Source: https://docs.blupayip.io/index

Retrieves the details of a specific Pix In transaction.

```APIDOC
## GET /pix/in/{transactionId}

### Description
Retrieves the details of a specific Pix In transaction.

### Method
GET

### Endpoint
/pix/in/{transactionId}

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

#### Query Parameters
- **externalRef** (string) - Optional - An external reference for reconciliation.

### Response
#### Success Response (200)
- **transactionId** (string) - The unique identifier for the transaction.
- **amount** (integer) - The transaction amount in cents.
- **description** (string) - A description for the transaction.
- **status** (string) - The current status of the transaction.
- **paymentUrl** (string) - The URL to generate the Pix payment QR code.
- **createdAt** (string) - The timestamp when the transaction was created.

#### Response Example
```json
{
  "transactionId": "txn_12345abcde",
  "amount": 1000,
  "description": "Payment for order #123",
  "status": "paid",
  "paymentUrl": "https://api.blupayip.io/pix/qr/txn_12345abcde",
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

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

### Get Pix In Transaction - OpenAPI Specification

Source: https://docs.blupayip.io/get-pix-in-transaction-25565105e0

This OpenAPI specification defines the 'Get Pix In Transaction' endpoint. It allows retrieval of PIX IN transactions using either an `id` or `externalRef`. Authentication is handled via Basic Auth with a `secretKey` and `publicKey`. The endpoint accepts query parameters for filtering and returns a detailed JSON object representing the transaction.

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /baseUrl/api/v1/transactions/pix-in:
    get:
      summary: Get Pix In Transaction
      deprecated: false
      description: |-
        Retrieve a PIX IN transaction by `id` or `externalRef`.

        Query params (at least one):
        - `id`: transaction `id` (UUID)
        - `externalRef`: client reference

        Requires Basic Auth (`secretKey:publicKey`).
      tags:
        - Pix In
      parameters:
        - name: id
          in: query
          description: Transaction id
          required: true
          example: '{{transactionId}}'
          schema:
            type: string
        - name: externalRef
          in: query
          description: Optional external reference
          required: true
          example: ''
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  amount:
                    type: integer
                  type:
                    type: string
                  status:
                    type: string
                  refundedAmount:
                    type: integer
                  companyId:
                    type: string
                  paymentMethod:
                    type: string
                  externalRef:
                    type: string
                  postbackUrl:
                    type: string
                  ip:
                    type: string
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                  paidAt:
                    type: string
                  cancelledAt:
                    type: 'null'
                  refundedAt:
                    type: 'null'
                  customer:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      email:
                        type: string
                      phone:
                        type: string
                      document:
                        type: object
                        properties:
                          type:
                            type: string
                          number:
                            type: string
                        required:
                          - type
                          - number
                        x-apidog-orders:
                          - type
                          - number
                    required:
                      - id
                      - name
                      - email
                      - phone
                      - document
                    x-apidog-orders:
                      - id
                      - name
                      - email
                      - phone
                      - document
                  pix:
                    type: object
                    properties:
                      qrcode:
                        type: string
                      expiresAt:
                        type: string
                      endToEndId:
                        type: string
                      payer:
                        type: object
                        properties:
                          name:
                            type: string
                          document:
                            type: string
                          documentType:
                            type: string
                          branch:
                            type: string
                          account:
                            type: string
                          bankName:
                            type: string
                          bankIspb:
                            type: string
                        required:
                          - name
                          - document
                          - documentType
                          - branch
                          - account
                          - bankName
                          - bankIspb
                        x-apidog-orders:
                          - name
                          - document
                          - documentType
                          - branch
                          - account
                          - bankName
                          - bankIspb
                    required:
                      - qrcode
                      - expiresAt
                      - endToEndId
                      - payer
                    x-apidog-orders:
                      - qrcode
                      - expiresAt

```

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

### OpenAPI Specification for Pix In Refunded Webhook

Source: https://docs.blupayip.io/pix-in-refunded-transaction-refunded-25565110e0

This OpenAPI specification defines the structure for the '/postback' endpoint, specifically for the 'transaction.refunded' event. It details the request headers, including Content-Type and X-Webhook-Signature, and the JSON payload containing transaction details, customer information, and Pix-specific data.

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /postback:
    post:
      summary: Pix In - Refunded (transaction.refunded)
      deprecated: false
      description: >-
        Webhook sent when a Pix In payment is refunded.


        **Event:** `transaction.refunded`

        **Type:** `transaction`


        This webhook is sent to your configured `postbackUrl` when a Pix In
        payment is refunded.
      tags:
        - Webhooks (Reference)
      parameters:
        - name: Content-Type
          in: header
          description: ''
          required: true
          example: application/json
          schema:
            type: string
        - name: X-Webhook-Signature
          in: header
          description: HMAC-SHA256 signature (present if webhookSecret was provided)
          required: true
          example: a1b2c3d4e5f6...
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                type:
                  type: string
                event:
                  type: string
                objectId:
                  type: string
                data:
                  type: object
                  properties:
                    id:
                      type: string
                    status:
                      type: string
                    amount:
                      type: integer
                    refundedAmount:
                      type: integer
                    installments:
                      type: integer
                    paymentMethod:
                      type: string
                    companyId:
                      type: string
                    externalRef:
                      type: string
                    customer:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        email:
                          type: string
                        phone:
                          type: string
                        document:
                          type: string
                        createdAt:
                          type: string
                      required:
                        - id
                        - name
                        - email
                        - phone
                        - document
                        - createdAt
                      x-apidog-orders:
                        - id
                        - name
                        - email
                        - phone
                        - document
                        - createdAt
                    pix:
                      type: object
                      properties:
                        qrcode:
                          type: string
                        end2EndId:
                          type: string
                      required:
                        - qrcode
                        - end2EndId
                      x-apidog-orders:
                        - qrcode
                        - end2EndId
                    paidAt:
                      type: string
                    createdAt:
                      type: string
                    updatedAt:
                      type: string
                    postbackUrl:
                      type: string
                  required:
                    - id
                    - status
                    - amount
                    - refundedAmount
                    - installments
                    - paymentMethod
                    - companyId
                    - externalRef
                    - customer
                    - pix
                    - paidAt
                    - createdAt
                    - updatedAt
                    - postbackUrl
                  x-apidog-orders:
                    - id
                    - status
                    - amount
                    - refundedAmount
                    - installments
                    - paymentMethod
                    - companyId
                    - externalRef
                    - customer
                    - pix
                    - paidAt
                    - createdAt
                    - updatedAt
                    - postbackUrl
              required:
                - id
                - type
                - event
                - objectId
                - data
              x-apidog-orders:
                - id
                - type
                - event
                - objectId
                - data
            example:
              id: evt_1765502253006_utw9w05vo
              type: transaction
              event: transaction.refunded

```

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

### Webhooks - Pix Out Events

Source: https://docs.blupayip.io/index

Handles incoming webhooks for Pix Out transfer events.

```APIDOC
## POST /webhooks/pixout

### Description
Receives webhook notifications for Pix Out transfer events. Supported events include `transfer.paid` and `transfer.failed`.

### Method
POST

### Endpoint
/webhooks/pixout

### Parameters
#### Header Parameters
- **X-Webhook-Signature** (string) - Optional - HMAC-SHA256 signature of the request body if `webhookSecret` is configured.

#### Request Body
- **event** (string) - The type of event (e.g., `transfer.paid`).
- **data** (object) - The payload containing transfer details.
  - **transferId** (string) - The ID of the transfer.
  - **externalRef** (string) - The external reference for the transfer.
  - **status** (string) - The status of the transfer.
  - **destination** (object) - Details of the transfer destination.
  - **beneficiary** (object) - Details of the transfer beneficiary (if paid).
  - ... (other relevant transfer details)

### Request Example
```json
{
  "event": "transfer.paid",
  "data": {
    "transferId": "trf_abcdef12345",
    "externalRef": "INV987",
    "status": "completed",
    "amount": 5000,
    "paidAt": "2023-10-27T11:15:00Z",
    "destination": {
      "bank": "001",
      "branch": "0001",
      "account": "12345-6"
    },
    "beneficiary": {
      "name": "Jane Doe",
      "document": "111.222.333-44"
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the webhook was received.

#### Response Example
```json
{
  "message": "Webhook received successfully."
}
```
```