# 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="autenticacao" %}
[autenticacao](https://docs.pixone.com.br/api/autenticacao)
{% 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 %}