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çãoParâmetros
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
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
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"
}
}Atualizado