QivoPay

Criar Transação

Crie transações de pagamento únicas com múltiplos métodos de pagamento e gateways. Suporte completo a cartão de crédito, PIX e boleto bancário.

Use o parâmetro useBestGateway para roteamento automático para o gateway com menor taxa.

Endpoints Disponíveis

POST/transaction

Criar transação padrão (cartão, PIX, boleto)

POST/transaction/create-pix

Endpoint específico para transações PIX

Autenticação

Inclua sua API Key no header da requisição:

x-api-key: sua_api_key_aqui

Parâmetros Obrigatórios

amountnumber

Valor da transação em reais (ex: 100.50)

paymentMethodstring

Método de pagamento: "credit_card", "pix", "boleto"

customerobject

Dados do cliente: name, email, document, phone

billingAddressobject

Endereço de cobrança completo

transactionDetailsobject

Detalhes da transação (holderName, installmentCount, cardHash, etc.)

Parâmetros Opcionais Importantes

gatewaystring

Gateway específico: "mercadopago", "stripe", "asaas", "pagarme"

useBestGatewayboolean

Seleciona automaticamente o gateway com menor taxa

qivopayTaxAmountnumber

Taxa adicional da QivoPay

Exemplo de Requisição Completa

JSON
{
  "amount": 100.00,
  "netAmount": 95.00,
  "currency": "BRL",
  "gateway": "asaas",
  "paymentMethod": "credit_card",
  "description": "Pagamento produto X",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@email.com",
    "document": "12345678901",
    "phone": "11888888888"
  },
  "billingAddress": {
    "street": "Rua das Flores",
    "number": "456",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "São Paulo",
    "stateCode": "SP",
    "country": "Brazil",
    "countryCode": "BR",
    "postalCode": "01234567"
  },
  "transactionDetails": {
    "holderName": "Maria Silva",
    "installmentCount": 3,
    "cardHash": "hash_do_cartao"
  },
  "metadata": {
    "orderId": "ORD-123",
    "source": "website"
  },
  "dueDate": "2025-02-01",
  "useBestGateway": true,
  "projectId": "uuid-do-projeto",
  "qivopayTaxAmount": 3.50
}

Exemplo para PIX

POST /transaction/create-pix
{
  "amount": 50.00,
  "paymentMethod": "pix",
  "description": "Pagamento PIX",
  "customer": {
    "name": "João Santos",
    "email": "joao@email.com",
    "document": "98765432100",
    "phone": "11999999999"
  },
  "billingAddress": {
    "street": "Av. Paulista",
    "number": "1000",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310100"
  },
  "transactionDetails": {},
  "projectId": "uuid-do-projeto"
}

Resposta de Sucesso

201 Created
{
  "id": "uuid-transacao",
  "status": "pending",
  "amount": 100.00,
  "currency": "BRL",
  "paymentMethod": "credit_card",
  "gateway": "asaas",
  "customer": {
    "id": "uuid-cliente",
    "name": "Maria Silva",
    "email": "maria@email.com"
  },
  "gatewayTransactionId": "asaas_123456",
  "qrCode": null, // Presente apenas para PIX
  "pixKey": null, // Presente apenas para PIX
  "boletoUrl": null, // Presente apenas para boleto
  "createdAt": "2025-01-22T10:30:00Z",
  "updatedAt": "2025-01-22T10:30:00Z"
}

Validações Especiais

•Se gateway for "pagarme", apenas paymentMethod: "credit_card" é aceito
•Para cartão de crédito, cardHash ou cardId é obrigatório
•Se não informar customerId, todos os campos de customer são obrigatórios

Códigos de Erro Comuns

400Parâmetros obrigatórios ausentes ou inválidos
401API Key inválida ou ausente
422Dados de pagamento inválidos (cartão, etc.)
500Erro interno do gateway de pagamento
Anterior: Visão GeralPróximo: Listar Transações