# Introdução

Leitura rápida para entender como a Pix One pode ajudar o seu negócio.


# Suporte


# Status da API

O endpoint de status permite verificar se a API da PIX One está operacional. Útil para monitoramento e verificação de disponibilidade do serviço.


# Autenticação

A API Pix One utiliza autenticação Basic Auth para todas as requisições. Esse método de autenticação é seguro e simples de implementar em suas ferramentas e sistemas.

## Credênciais de acesso

A autenticação na API Pix One é feita utilizando Basic Auth com suas chaves de API obtidas através de do painel da Pix One.

* **Username:** sk\_userKey (sua chave secreta)
* **Password:** pk\_userKey (sua chave pública)

## Como utilizar a autenticação

Para autenticar suas requisições, inclua as credenciais no cabeçalho HTTP de autorização:

```
Authorization: Basic {base64(sk_userKey:pk_userKey)}
```

#### Exemplo utilizando cURL

```sh
curl -X POST https://api.pixone.com.br/api/v1/transaction \
  -H "Authorization: Basic {base64(sk_userKey:pk_userKey)}" \
  -H "Content-Type: application/json" \
  -d '{
    ....
  }'
```

#### Exemplo em Javascript

```javascript
const response = await fetch('https://api.pixone.com.br/api/v1/transaction', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('sk_userKey:pk_userKey'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ....
  })
});

const data = await response.json();
console.log(data);
```

#### Exemplo em PHP

```php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.pixone.com.br/api/v1/transaction');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  ....
]));

$headers = [
  'Authorization: Basic ' . base64_encode('sk_userKey:pk_userKey'),
  'Content-Type: application/json'
];

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```


# Transação Pix

Crie/gere transações 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)
{% 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 %}


# Webhook

Os webhooks permitem que seu sistema receba notificações automáticas sobre eventos importantes na plataforma da Pix One. Isso elimina a necessidade de consultar a API constantemente para verificar mudanças de status.

## Como Funcionam os Webhooks

​Quando um evento ocorre na Pix One (como uma transação aprovada ou uma nova transação criada), nosso sistema envia uma requisição HTTP POST para uma URL que você definiu, contendo informações detalhadas sobre o evento.

## Configuração de Webhooks

Para configurar webhooks, acesse seu painel na Pix One:

1. Navegue até **Webhook**
2. Insira a URL de destino para receber as notificações
3. Selecione os eventos que deseja monitorar

{% hint style="info" %}
Sua URL de webhook deve estar acessível publicamente na internet para receber as notificações.
{% endhint %}

## Modelo de Webhook

A Pix One utiliza o seguinte modelo padrão de envio para webhooks:

```json
{
  "id": "string",
  "type": "transaction",
  "transaction": "url",
  "data": {
    "object": {
      "id": "string",
      "ip": "string | null",
      "fee": {
        "netAmount": "number",
        "fixedAmount": "number",
        "estimatedFee": "number",
        "spreadPercentage": "number"
      },
      "pix": {
        "qrcode": "string"
      },
      "items": [
        {
          "id": "integer",
          "title": "string",
          "saleId": "integer",
          "physical": "boolean",
          "quantity": "integer",
          "createdAt": "date-time",
          "productId": "integer | null",
          "unitPrice": "number",
          "productImg": "integer | null",
          "externalRef": "integer | null",
          "productDesc": "integer | null",
          "productFile": "integer | null",
          "productName": "integer | null",
          "productPage": "integer | null",
          "productType": "integer | null",
          "productBanner": "integer | null"
        }
      ],
      "amount": "number",
      "boleto": {
        "url": "string",
        "barcode": "string",
        "paidAt": "date-time | null"
      },
      "refundedAt": "date-time | null",
      "status": "paid | processing | pending | approved | refused | chargedback | refunded | cancelled | chargeback",
      "customer": {
        "id": "string",
        "name": "string",
        "email": "string",
        "phone": "string",
        "address": {
          "id": "integer",
          "fee": "number",
          "saleId": "integer",
          "street": "string",
          "tracking": "integer | null",
          "steetCity": "string",
          "streetState": "string",
          "streetNumber": "string",
          "streetCountry": "integer | null",
          "streetZipCode": "string",
          "tracking_code": "integer | null",
          "tracking_status": "string",
          "streetComplement": "string",
          "streetNeighborhood": "string"
        },
        "document": {
          "type": "string",
          "number": "string"
        }
      },
      "delivery": {
        "status": "string",
        "createdAt": "date-time",
        "trackingCode": "string | null"
      },
      "metadata": "object | null",
      "secureId": "string",
      "companyId": "string",
      "tenant": "string",
      "traceable": "boolean",
      "paidAmount": "number",
      "externalRef": "string | null",
      "postbackUrl": "string",
      "installments": "integer",
      "paymentMethod": "string",
      "refusedReason": "string | null",
      "splits": [
        {
          "Type": "object"
        }
      ],
      "refunds": [
        {
          "Type": "object"
        }
      ],
      "refundedAmount": "number",
      "createdAt": "date-time"
    }
  }
}
```

## Eventos Disponíveis

A Pix One oferece os seguintes eventos para webhooks:

| Evento                  | Descrição                           |
| ----------------------- | ----------------------------------- |
| transaction.paid        | Um pagamento foi confirmado         |
| transaction.processing  | Uma transação está em processamento |
| transaction.pending     | Uma transação está pendente         |
| transaction.approved    | Uma transação foi aprovada          |
| transaction.refused     | Uma transação foi recusada          |
| transaction.chargedback | Uma transação sofreu chargeback     |
| transaction.refunded    | Uma transação foi reembolsada       |
| transaction.cancelled   | Uma transação foi cancelada         |

## Política de Retentativas

Se seu endpoint retornar um código diferente de 200 ou não responder dentro de 10 segundos, a Pix One seguirá uma política de retentativas:

* 1ª retentativa: 1 minuto após a falha
* 2ª retentativa: 5 minutos após a falha
* 3ª retentativa: 30 minutos após a falha
* 4ª retentativa: 2 horas após a falha
* 5ª retentativa: 6 horas após a falha

Após cinco tentativas sem sucesso, o webhook será marcado como falho e não será reenviado automaticamente.