### GET /api/v1/pix/{id}/status

Source: https://beta.venopayments.com/docs/api

Retrieves the current status of a PIX payment using its unique ID.

```APIDOC
## Consultar Status

Returns the current status of a PIX payment.

### Method

`GET`

### Endpoint

`/api/v1/pix/{id}/status`

### Parameters

#### Path Parameters

- **id** (string) - Required - The unique ID of the PIX payment.

### Request Example

```curl
curl https://beta.venopayments.com/api/v1/pix/{id}/status \
  -H "Authorization: Bearer veno_live_xxxxx"
```

### Response Example (200 OK)

```json
{
  "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
  "txid": "pagloop-txid-abc123",
  "status": "paid",
  "amount": 10000,
  "paid_at": "2026-03-01T14:32:00Z",
  "end_to_end_id": "E12345678202603...",
  "external_id": "pedido-123",
  "payer_name": "Joao Silva",
  "payer_document": "12345678900"
}
```

### Response Fields

- **id** (string) - Required - Unique ID of the deposit.
- **txid** (string) - Required - Transaction ID at the acquirer.
- **status** (string) - Required - Current status of the PIX.
- **amount** (integer) - Required - Amount in cents.
- **paid_at** (string | null) - Optional - Payment date/time (ISO 8601).
- **end_to_end_id** (string | null) - Optional - BACEN end-to-end ID.
- **external_id** (string | null) - Optional - Your reference, if provided.
- **payer_name** (string | null) - Optional - Payer's name.
- **payer_document** (string | null) - Optional - Payer's CPF/CNPJ.
```

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

### POST /api/v1/pix

Source: https://beta.venopayments.com/docs/api

Creates a PIX payment and returns a QR Code for payment. It also supports idempotency using an `external_id`.

```APIDOC
## Create PIX

Creates a PIX charge and returns the QR Code for payment.

### Method

`POST`

### Endpoint

`/api/v1/pix`

### Parameters

#### Request Body

- **amount** (integer) - Required - Amount in cents. R$100.00 = 10000. Min: 100, Max: 100000000.
- **callback_url** (string) - Optional - URL to receive webhook notifications when the PIX is paid.
- **external_id** (string) - Optional - Your system's reference. Used for idempotency.
- **description** (string) - Optional - Payment description.
- **payer.name** (string) - Optional - Payer's name.
- **payer.email** (string) - Optional - Payer's email.
- **payer.document** (string) - Optional - Payer's CPF or CNPJ.

### Request Example

```curl
curl -X POST https://beta.venopayments.com/api/v1/pix \
  -H "Authorization: Bearer veno_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "callback_url": "https://seusite.com/webhook",
    "external_id": "pedido-123",
    "description": "Pedido #123",
    "payer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": "12345678900"
    }
  }'
```

### Response Example (201 Created)

```json
{
  "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
  "txid": "pagloop-txid-abc123",
  "status": "pending",
  "amount": 10000,
  "qr_code": "data:image/png;base64,...",
  "pix_copy_paste": "00020126...",
  "expires_at": "2026-03-01T15:00:00Z"
}
```

### Idempotency

If you send the same `external_id` twice, the second request will return the original PIX without creating a duplicate.
```

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

### Create PIX Payment Request (cURL)

Source: https://beta.venopayments.com/docs/api

This cURL command demonstrates how to create a PIX payment. It includes the amount, callback URL for notifications, an external ID for idempotency, an optional description, and payer details. The API returns a QR code and payment details upon success.

```cURL
curl -X POST https://beta.venopayments.com/api/v1/pix \
  -H "Authorization: Bearer veno_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "callback_url": "https://seusite.com/webhook",
    "external_id": "pedido-123",
    "description": "Pedido #123",
    "payer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": "12345678900"
    }
  }'
```

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

### Authentication

Source: https://beta.venopayments.com/docs/api

All PIX API requests require authentication using an API Key passed in the Authorization header.

```APIDOC
## Authentication

All PIX API requests use API Key authentication in the `Authorization` header.

### Header

```
Authorization: Bearer veno_live_a1b2c3d4e5f6...
```

### Obtaining Your API Key

Access Dashboard → API Keys and click "New Key". The key will be displayed only once, so save it securely.
```

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

### PIX Payment Creation Response (JSON)

Source: https://beta.venopayments.com/docs/api

A successful PIX payment creation request returns a JSON object containing the payment ID, transaction ID (txid), status, amount, QR code data, PIX copy-paste string, and expiration time.

```JSON
{
  "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
  "txid": "pagloop-txid-abc123",
  "status": "pending",
  "amount": 10000,
  "qr_code": "data:image/png;base64,...",
  "pix_copy_paste": "00020126...",
  "expires_at": "2026-03-01T15:00:00Z"
}
```

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

### Venopayments API Error Handling

Source: https://beta.venopayments.com/docs/api

This section describes the general structure of error responses from the Venopayments API and lists common HTTP status codes and their associated error codes.

```APIDOC
## Error Response Structure

All errors return a JSON object with the fields `code` and `message`.

### Request Example
```json
{
  "code": "BAD_REQUEST",
  "message": "amount must be greater than 0"
}
```

## HTTP Status Codes and Error Descriptions

| HTTP | Code | Description |
|---|---|---|
| 400 | `BAD_REQUEST` | Invalid request (body, parameters, amount out of range). |
| 401 | `UNAUTHORIZED` | Invalid, missing, or expired API Key. |
| 404 | `NOT_FOUND` | Resource not found or does not belong to your account. |
| 500 | `INTERNAL_ERROR` | Internal server error. |

### Response
#### Success Response (200)
This section is not applicable for error codes.

#### Response Example
(See Request Example above for error response structure)
```

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

### PIX Status Definitions

Source: https://beta.venopayments.com/docs/api

Defines the possible statuses for a PIX payment.

```APIDOC
## PIX Status

| Status    | Label   | Description                       |
|-----------|---------|-----------------------------------|
| `pending` | Pending | Waiting for payment               |
| `paid`    | Paid    | Payment confirmed                 |
| `expired` | Expired | Expired without payment (1 hour)  |
| `cancelled`| Cancelled| Canceled                          |
| `refunded`| Refunded| Amount returned to the payer      |
```

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

### Authenticate Veno API Requests

Source: https://beta.venopayments.com/docs/api

All Veno API requests require authentication using an API Key. The key should be included in the 'Authorization' header as a Bearer token. Obtain your API Key from the Dashboard.

```HTTP
Authorization: Bearer veno_live_a1b2c3d4e5f6...
```

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

### Webhook Notifications

Source: https://beta.venopayments.com/docs/api

Veno Payments sends a POST request to your specified `callback_url` when a PIX payment is confirmed. This section details the webhook payload and best practices.

```APIDOC
## Webhook

When a PIX is paid, we send a `POST` request to the `callback_url` you provided when creating the PIX.

### Headers Sent

| Header        | Value            |
|---------------|------------------|
| `Content-Type`| `application/json` |
| `User-Agent`  | `VenoPayments/2.0` |

### Payload Example

```json
{
  "event": "pix.paid",
  "data": {
    "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
    "txid": "pagloop-txid-abc123",
    "external_id": "pedido-123",
    "status": "paid",
    "amount": 10000,
    "paid_at": "2026-03-01T14:32:00Z",
    "end_to_end_id": "E12345678202603011432abcdef",
    "payer": {
      "name": "Joao Silva",
      "document": "12345678900"
    }
  }
}
```

### Events

| Event     | Description             |
|-----------|-------------------------|
| `pix.paid`| PIX has been paid and confirmed. |

### Retries

If your server does not respond with an HTTP `2xx` status code, we will automatically retry:

| Attempt | Interval |
|---------|----------|
| 1st     | Immediate|
| 2nd     | +2 seconds|
| 3rd     | +4 seconds|

### Best Practices

*   Respond with `200 OK` as quickly as possible.
*   Process business logic asynchronously.
*   Use `id` or `external_id` for idempotency, as you might receive the same webhook more than once.
*   Validate with `GET /api/v1/pix/{id}/status` if necessary.
```

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

### Check PIX Payment Status Request (cURL)

Source: https://beta.venopayments.com/docs/api

This cURL command shows how to query the status of a PIX payment using its unique ID. It requires the API Key for authentication.

```cURL
curl https://beta.venopayments.com/api/v1/pix/{id}/status \
  -H "Authorization: Bearer veno_live_xxxxx"
```

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

### PIX Payment Status Response (JSON)

Source: https://beta.venopayments.com/docs/api

The response for checking PIX payment status includes details like the payment ID, transaction ID, current status, amount, payment timestamp, end-to-end ID, external reference, and payer information if available.

```JSON
{
  "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
  "txid": "pagloop-txid-abc123",
  "status": "paid",
  "amount": 10000,
  "paid_at": "2026-03-01T14:32:00Z",
  "end_to_end_id": "E12345678202603...",
  "external_id": "pedido-123",
  "payer_name": "Joao Silva",
  "payer_document": "12345678900"
}
```

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

### Error Response JSON Structure

Source: https://beta.venopayments.com/docs/api

This JSON object represents a typical error response from the Venopayments API. It includes a machine-readable error code and a human-readable error message. This structure is consistent across all API errors.

```json
{
  "code": "BAD_REQUEST",
  "message": "amount must be greater than 0"
}
```

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

### PIX Payment Webhook Payload (JSON)

Source: https://beta.venopayments.com/docs/api

When a PIX payment is confirmed, Veno Payments sends a POST request to your specified callback URL with a JSON payload. This payload contains event details, including the payment status and relevant data. Ensure your server responds with a 2xx status code.

```JSON
{
  "event": "pix.paid",
  "data": {
    "id": "019c4586-07f3-7312-8472-0e8c708b33ab",
    "txid": "pagloop-txid-abc123",
    "external_id": "pedido-123",
    "status": "paid",
    "amount": 10000,
    "paid_at": "2026-03-01T14:32:00Z",
    "end_to_end_id": "E12345678202603011432abcdef",
    "payer": {
      "name": "Joao Silva",
      "document": "12345678900"
    }
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.