Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Leitura rápida para entender como a Pix One pode ajudar o seu negócio.
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.
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.
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)
Para autenticar suas requisições, inclua as credenciais no cabeçalho HTTP de autorização:
Authorization: Basic {base64(sk_userKey:pk_userKey)}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 '{
....
}'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);$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;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.
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.
Para configurar webhooks, acesse seu painel na Pix One:
Navegue até Webhook
Insira a URL de destino para receber as notificações
Selecione os eventos que deseja monitorar
A Pix One utiliza o seguinte modelo padrão de envio para webhooks:
{
"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"
}
}
}A Pix One oferece os seguintes eventos para webhooks:
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
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.
Crie/gere transações pix.
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.
Para autenticação na API utilize nossa documentação de Autenticaçã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
{
"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"
}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
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"
}'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"
}
}Erro de autenticação
Dados inválidos