Transação Pix

Crie/gere transações pix.

Endpoint

Endpoint para gerar transações PIX

POST /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:

Autenticação

Parâmetros

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

Exemplo de montagem de request

{
  "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": "[email protected]",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Pix One\",\"user_email\":\"[email protected]\"}",
  "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

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": "[email protected]",
    "phone": "11987654321",
    "document": {
      "type": "cpf",
      "number": "12345678909"
    }
  },
  "metadata": "{\"provider\":\"Pix One Checkout\",\"user_email\":\"[email protected]\"}",
  "traceable": false,
  "externalRef": "pedido_123456",
  "postbackUrl": "https://seusite.com.br/webhook"
}'

Resposta e código HTTP

201

Transação criada e QR Code gerado

Exemplo de retorno:

{
  "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": "[email protected]",
      "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"
  }
}

401

400