Developer Hub

API ValuxPay

Documentação técnica para integração com nosso gateway de pagamentos

Introdução

A API ValuxPay permite que você integre seu site ou aplicativo à nossa plataforma de pagamentos, processando transações com cartão de crédito, débito, PIX e boleto bancário de forma simples e segura.

Nossa API é RESTful e utiliza JSON para comunicação. Todas as requisições devem ser feitas via HTTPS. As respostas incluem códigos HTTP padrão e mensagens descritivas.

URL Base - Produção

https://api.valuxpay.com/v1
Ambiente de produção (dados reais)

URL Base - Sandbox

https://sandbox.api.valuxpay.com/v1
Ambiente de testes (dados fictícios)

⚠️ Importante: Todas as requisições devem ser feitas com o header Content-Type: application/json. Nunca compartilhe suas chaves de API.

Autenticação

A autenticação é feita através de uma chave de API (API Key) que deve ser enviada no header X-API-Key. Você pode gerar suas chaves no painel administrativo da ValuxPay.

Exemplo de header

X-API-Key: sk_live_4x0q3r8z1m9w5v7y2b6n4j8k
Chave pública

Usada em operações não sensíveis, como tokenização de cartões pk_

Chave secreta

Usada em operações no servidor sk_. Nunca exponha no front-end.

Endpoints

Método Endpoint Descrição
POST /payments Criar um novo pagamento (cartão, PIX, boleto)
GET /payments/{id} Consultar detalhes de um pagamento
POST /payments/{id}/cancel Cancelar um pagamento (se status permitir)
GET /customers Listar clientes
POST /customers Criar um cliente
POST /webhooks Configurar um webhook

POST /payments

Cria um novo pagamento. O método de pagamento é definido pelo campo payment_method.

Requisição (exemplo com cartão de crédito)

{
  "amount": 19990,
  "currency": "BRL",
  "payment_method": "credit_card",
  "installments": 1,
  "card": {
    "number": "4111111111111111",
    "holder_name": "João Silva",
    "exp_month": 12,
    "exp_year": 2025,
    "cvv": "123"
  },
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678909"
  },
  "metadata": {
    "order_id": "12345"
  }
}

Resposta (sucesso)

{
  "id": "pay_123abc456def",
  "status": "authorized",
  "amount": 19990,
  "payment_method": "credit_card",
  "installments": 1,
  "created_at": "2024-10-05T14:48:00Z",
  "links": {
    "self": "/v1/payments/pay_123abc456def"
  }
}

GET /payments/{id}

Retorna os detalhes de um pagamento específico.

Exemplo de resposta

{
  "id": "pay_123abc456def",
  "status": "paid",
  "amount": 19990,
  "payment_method": "credit_card",
  "installments": 1,
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "created_at": "2024-10-05T14:48:00Z",
  "paid_at": "2024-10-05T14:49:00Z"
}

Exemplos de integração

cURL

curl -X POST https://api.valuxpay.com/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_4x0q3r8z1m9w5v7y2b6n4j8k" \
  -d '{
    "amount": 19990,
    "currency": "BRL",
    "payment_method": "credit_card",
    "card": {
      "number": "4111111111111111",
      "holder_name": "João Silva",
      "exp_month": 12,
      "exp_year": 2025,
      "cvv": "123"
    },
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com"
    }
  }'

JavaScript (fetch)

fetch('https://api.valuxpay.com/v1/payments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sk_live_4x0q3r8z1m9w5v7y2b6n4j8k'
  },
  body: JSON.stringify({
    amount: 19990,
    currency: 'BRL',
    payment_method: 'credit_card',
    card: {
      number: '4111111111111111',
      holder_name: 'João Silva',
      exp_month: 12,
      exp_year: 2025,
      cvv: '123'
    },
    customer: {
      name: 'João Silva',
      email: 'joao@email.com'
    }
  })
})
.then(response => response.json())
.then(data => console.log(data));

PHP (cURL)

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.valuxpay.com/v1/payments");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-Key: sk_live_4x0q3r8z1m9w5v7y2b6n4j8k"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "amount" => 19990,
    "currency" => "BRL",
    "payment_method" => "credit_card",
    "card" => [
        "number" => "4111111111111111",
        "holder_name" => "João Silva",
        "exp_month" => 12,
        "exp_year" => 2025,
        "cvv" => "123"
    ],
    "customer" => [
        "name" => "João Silva",
        "email" => "joao@email.com"
    ]
]));

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
?>

Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos importantes, como confirmação de pagamento, chargeback ou cancelamento. Você pode configurar URLs de callback no painel ou via API.

Formato do payload

{
  "event": "payment.paid",
  "id": "evt_123abc456def",
  "data": {
    "id": "pay_123abc456def",
    "amount": 19990,
    "status": "paid",
    "payment_method": "credit_card"
  },
  "created_at": "2024-10-05T14:50:00Z"
}
payment.created
payment.authorized
payment.paid
payment.failed
payment.canceled
payment.refunded
chargeback.created

✓ Responda com HTTP 200 para confirmar recebimento
✓ Verifique a assinatura do webhook (opcional)
✓ Implemente idempotência para evitar duplicatas
✓ Use URLs HTTPS

Códigos de Erro

Código Significado Descrição
400Bad RequestRequisição mal formatada ou campos inválidos
401UnauthorizedAPI Key ausente ou inválida
403ForbiddenSem permissão para acessar o recurso
404Not FoundRecurso não encontrado
422Unprocessable EntityErro de validação nos dados enviados
429Too Many RequestsLimite de requisições excedido
500Internal Server ErrorErro inesperado no servidor

Exemplo de resposta de erro (422)

{
  "error": {
    "code": "validation_error",
    "message": "Os seguintes campos são inválidos",
    "details": [
      {
        "field": "card.number",
        "message": "Número de cartão inválido"
      }
    ]
  }
}

Ambiente de Testes (Sandbox)

Utilize o ambiente sandbox para testar sua integração sem movimentar dinheiro real. As chaves de API para sandbox começam com sk_test_ e pk_test_.

Cartões de teste

4111111111111111 (Visa, sucesso)
5555555555554444 (Mastercard, sucesso)
4000000000000002 (Recusado genérico)
4000000000000010 (Saldo insuficiente)

PIX e boleto

No sandbox, o PIX é simulado com QR Code fixo e o boleto sempre é gerado com link de visualização. Pagamentos podem ser confirmados manualmente no painel de testes.

SDKs Oficiais

Node.js

npm install valuxpay

Documentação →

PHP

composer require valuxpay/sdk

Documentação →

Python

pip install valuxpay

Documentação →

Precisa de ajuda?

Nossa equipe de suporte técnico está disponível para auxiliar na integração. Entre em contato pelo e-mail dev@valuxpay.com ou pelo chat na plataforma.