# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.