> For the complete documentation index, see [llms.txt](https://docs.pixone.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pixone.com.br/api/transacao-pix.md).

# Transação Pix

## Endpoint

Endpoint para gerar transações PIX

<mark style="color:green;">`POST`</mark> `/api/v1/transactions`

Este endpoint permite criar transações utilizando o método de pagamento PIX, gerando um QR Code que pode ser escaneado pelo cliente para realizar o pagamento.

## Autenticação

Para autenticação na API utilize nossa documentação de Autenticação:

{% content-ref url="/pages/Liktvccw2xQSkrWlcBE8" %}
[Autenticação](/api/autenticacao.md)
{% endcontent-ref %}

## Parâmetros

| Nome                       | Tipo                                                    | Descrição                                            |
| -------------------------- | ------------------------------------------------------- | ---------------------------------------------------- |
| `paymentMethod`            | `string` <mark style="color:red;">`obrigatório`</mark>  | Método de pagamento (deve ser “pix”)                 |
| `amount`                   | `integer` <mark style="color:red;">`obrigatório`</mark> | Valor total em centavos                              |
| `pix.expiresInDays`        | `integer` <mark style="color:red;">`obrigatório`</mark> | Dias para expiração do PIX                           |
| `customer`                 | `object` <mark style="color:red;">`obrigatório`</mark>  | Dados do cliente                                     |
| `customer.name`            | `string` <mark style="color:red;">`obrigatório`</mark>  | Nome completo do cliente                             |
| `customer.email`           | `string` <mark style="color:red;">`obrigatório`</mark>  | Email do cliente                                     |
| `customer.phone`           | `string` <mark style="color:red;">`obrigatório`</mark>  | Telefone do cliente                                  |
| `customer.document.type`   | `string` <mark style="color:red;">`obrigatório`</mark>  | Tipo do documento (cpf ou cnpj)                      |
| `customer.document.number` | `string` <mark style="color:red;">`obrigatório`</mark>  | Número do documento                                  |
| `externalRef`              | `string` <mark style="color:red;">`obrigatório`</mark>  | Referência externa para identificação da transação   |
| `postbackUrl`              | `string` <mark style="color:red;">`obrigatório`</mark>  | URL para receber notificações de alteração de status |
| `traceable`                | `boolean` <mark style="color:red;">`obrigatório`</mark> | Se a transação é rastreável                          |
| `items`                    | `array` <mark style="color:red;">`obrigatório`</mark>   | Lista de itens do pedido                             |
| `ip`                       | `string` <mark style="color:red;">`obrigatório`</mark>  | Endereço IP do cliente                               |
| `metadata`                 | `string` <mark style="color:red;">`obrigatório`</mark>  | Dados adicionais em formato JSON string              |

#### Exemplo de montagem de request

```json
{
  "paymentMethod": "pix",
  "ip": "172.18.0.1",
  "pix": {
    "expiresInDays": 1
  },
  "items": [
    {
      "title": "Produto teste",
      "quantity": 1,
      "tangible": false,
      "unitPrice": 1100,
      "product_image": "https://seusite.com.br/imagens/produto.png"
    }
  ],
  "amount": 1100,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Pix One\",\"user_email\":\"joao@email.com\"}",
  "traceable": false,
  "externalRef": "pedido_123456",
  "postbackUrl": "https://seusite.com.br/webhook"
}
```

## Status de transação

| Status    | Descrição                                          |
| --------- | -------------------------------------------------- |
| pending   | Aguardando pagamento                               |
| approved  | Pagamento recebido e confirmado                    |
| cancelled | Transação cancelada                                |
| expired   | Transação expirada (QR Code não foi pago no prazo) |
| refunded  | Transação estornada                                |

## Exemplo de utilização

#### Exemplo em cURL

```sh
curl --location 'https://api.pixone.com.br/api/v1/transactions' \
--header 'Authorization: Basic {base64(sk_userKey:pk_userKey)}' \
--header 'Content-Type: application/json' \
--data '{
  "paymentMethod": "pix",
  "ip": "172.18.0.1",
  "pix": {
    "expiresInDays": 1
  },
  "items": [
    {
      "title": "Produto teste",
      "quantity": 1,
      "tangible": false,
      "unitPrice": 1100,
      "product_image": "https://seusite.com.br/imagens/produto.png"
    }
  ],
  "amount": 1100,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Pix One Checkout\",\"user_email\":\"joao@email.com\"}",
  "traceable": false,
  "externalRef": "pedido_123456",
  "postbackUrl": "https://seusite.com.br/webhook"
}'
```

## Resposta e código HTTP

{% tabs %}
{% tab title="201" %}
Transação criada e QR Code gerado

**Exemplo de retorno:**

```json
{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": {
    "id": 12345,
    "status": "pending",
    "amount": 1100,
    "companyId": 1,
    "installments": 1,
    "refusedAmount": 0,
    "paidAmount": 0,
    "refundedAmount": 0,
    "paymentMethod": "pix",
    "acquirerType": "horizon",
    "secureId": "c30a4718-a548-4e07-aa1a-9db459015f48",
    "secureUrl": "https://pay.pixone.com/checkout/c30a4718-a548-4e07-aa1a-9db459015f48",
    "externalId": "pedido_123456",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "11987654321",
      "document": {
        "number": "12345678909",
        "type": "cpf"
      }
    },
    "pix": {
      "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "qrcodeText": "00020101021226880014br.gov.bcb.pix2566qrcodepix.pixone.com.br/v1/pix/31be673d9866c5ee3c1891a988a5864852040000530398654041.005802BR5925PIX ONE6009SAO PAULO62360532e673d9866c5ee3c1891a988a586486304A6C2",
      "expirationDate": "2025-05-03T15:57:33.751Z"
    },
    "traceable": false,
    "fees": 164,
    "createdAt": "2025-05-02T15:57:33.751Z"
  }
}
```

{% endtab %}

{% tab title="401" %}
Erro de autenticação
{% endtab %}

{% tab title="400" %}
Dados inválidos
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pixone.com.br/api/transacao-pix.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.