Skip to main content
POST
/
transactions
Criar Transação
curl --request POST \
  --url https://api.example.com/transactions \
  --header 'Content-Type: application/json' \
  --data '
{
  "api_token": "<string>",
  "amount": 123,
  "offer_hash": "<string>",
  "payment_method": "<string>",
  "customer": {
    "customer.name": "<string>",
    "customer.email": "<string>",
    "customer.phone_number": "<string>",
    "customer.document": "<string>"
  },
  "cart": [
    {}
  ],
  "installments": 123,
  "expire_in_days": 123,
  "postback_url": "<string>",
  "address": {}
}
'
{
  "201": {},
  "400": {},
  "401": {},
  "422": {},
  "500": {}
}

​
Visão Geral

Uma transação representa uma operação de pagamento no sistema KlivoPay. Cada transação possui um identificador único (hash) e passa por diferentes status durante seu ciclo de vida:
  • pending - Aguardando pagamento
  • paid - Pagamento confirmado
  • canceled - Cancelada
  • refunded - Reembolsada

​
Métodos de Pagamento Suportados

PIX

Pagamento instantâneo via QR Code ou Copia e Cola

Cartão de Crédito

Aprovação imediata com suporte a parcelamento

Boleto Bancário

Pagamento com prazo de vencimento configurável

​
Endpoint

POST https://api.klivopay.com.br/api/public/v1/transactions

​
Parâmetros

​
Obrigatórios

​
api_token
string
required
Seu token de autenticação da API KlivoPay
​
amount
integer
required
Valor da transação em centavos. Exemplo: R$ 150,00 = 15000
​
offer_hash
string
required
Hash identificador da oferta do produto
​
payment_method
string
required
Método de pagamento: pix, credit_card ou billet
​
customer
object
required
Dados do cliente comprador

​
Opcionais

​
cart
array
Array de itens do carrinho com detalhes dos produtos
​
installments
integer
Número de parcelas para cartão de crédito (1 a 12)
​
expire_in_days
integer
Dias para vencimento do boleto (padrão: 3 dias)
​
postback_url
string
URL para receber notificações de mudança de status
​
address
object
Endereço de entrega (opcional para produtos digitais, recomendado para físicos)

​
Exemplo de Requisição

curl -X POST 'https://api.klivopay.com.br/api/public/v1/transactions' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_token": "seu_token_aqui",
    "amount": 15000,
    "offer_hash": "abc123def456",
    "payment_method": "pix",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "phone_number": "11987654321",
      "document": "12345678900"
    },
    "cart": [
      {
        "name": "Produto Exemplo",
        "quantity": 1,
        "unit_price": 15000
      }
    ]
  }'

​
Resposta de Sucesso

201 Created
{
  "success": true,
  "data": {
    "hash": "abc123def456ghi789",
    "status": "pending",
    "amount": 15000,
    "payment_method": "pix",
    "pix_qr_code": "00020126580014br.gov.bcb.pix...",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
    "created_at": "2025-01-20T10:15:00Z",
    "expires_at": "2025-01-20T10:30:00Z"
  }
}

​
Códigos de Resposta

​
201
Created
Transação criada com sucesso
​
400
Bad Request
Dados inválidos na requisição
​
401
Unauthorized
Token de API inválido ou ausente
​
422
Unprocessable Entity
Erro de validação nos dados enviados
​
500
Internal Server Error
Erro interno do servidor

​
Webhook / Postback

Quando o status da transação mudar, você receberá uma notificação no postback_url configurado: 
{
  "transaction_hash": "abc123def456ghi789",
  "status": "paid",
  "amount": 15000,
  "payment_method": "pix",
  "paid_at": "2025-01-20T10:20:00Z"
}
Configure o postback_url para receber atualizações automáticas sobre mudanças no status das transações.