Transações

Transações representam pagamentos avulsos processados pela Veepag. Use este fluxo quando você precisa cobrar um cliente diretamente, consultar o histórico de pagamentos, capturar uma autorização ou cancelar/estornar uma operação.

Criar uma transação

POST /v1/transaction cria uma transação avulsa. Para pagamento com cartão, envie os dados em paymentProfile: número, validade, nome do portador e, quando necessário, CVV.

Para o cartão não passar pelo seu servidor, cifre os dados no browser e envie token no lugar de paymentProfile. O passo a passo está em Tokenização.

No exemplo abaixo, criamos uma transação no sandbox com um cliente informado no próprio payload.

curl --request POST 'https://sandbox.api.veepag.com/v1/transaction' \
  --header 'apiKey: keyId.secret' \
  --header 'Content-Type: application/json' \
  --data '{
    "companyId": "company_id",
    "amount": 9900,
    "installments": 1,
    "capture": true,
    "paymentProfile": {
      "cardNumber": "4111111111111111",
      "cardExpiration": "10/2026",
      "holderName": "MARIA SILVA",
      "cardCvv": "123"
    },
    "client": {
      "name": "Maria Silva",
      "doc": "12345678909",
      "email": "maria.silva@example.com"
    }
  }'

Em transações, envie amount em centavos. Por exemplo, 9900 representa R$ 99,00.

Configurar split na transação

Envie split no corpo de POST /v1/transaction para definir a divisão desta venda. Quando split.active for true, estas regras têm prioridade sobre o split configurado no produto ou na empresa. Se você omitir split ou enviar active: false, o fluxo pode usar o split ativo do produto ou, na ausência dele, o da empresa. Cada regra aponta para uma empresa recebedora e define a parcela por valor ou percentual. A empresa informada em companyId precisa estar cadastrada e configurada como recebedora na integração de pagamento.

{
  "companyId": "company_id",
  "amount": 9900,
  "installments": 1,
  "capture": true,
  "paymentProfile": {
    "cardNumber": "4111111111111111",
    "cardExpiration": "10/2026",
    "holderName": "MARIA SILVA",
    "cardCvv": "123"
  },
  "split": {
    "active": true,
    "rules": [
      {
        "companyId": "recipient_company_id_1",
        "percentage": 70
      },
      {
        "companyId": "recipient_company_id_2",
        "percentage": 30
      }
    ]
  }
}

Campo	Regra
`split.active`	Ativa as regras enviadas para esta transação.
`split.rules[].companyId`	ID da empresa que receberá esta parte do split. Ela precisa estar habilitada como recebedora e ter uma integração de pagamento válida.
`split.rules[].amount`	Valor fixo da regra em reais. O backend converte para centavos ao encaminhar ao processador. Exemplo: `12.5` representa R$ 12,50.
`split.rules[].percentage`	Percentual inteiro da regra. Envie `20` para representar 20%.
`split.rules[].chargeProcessingFee`	`true` (padrão Veepag) calcula o split sobre o valor líquido da taxa de processamento; `false` usa o valor bruto. Com split percentual, a taxa é dividida proporcionalmente entre os participantes.
`split.rules[].chargeRecipientProcessingFee`	`true` atribui a taxa inteira da transação ao recebedor desta regra; só um participante pode usar essa opção. Nesse modo, envie `chargeProcessingFee: false`.

Cada regra precisa informar amount ou percentage. Prefira informar apenas um dos dois; se ambos forem enviados, a Veepag usa amount. O padrão de chargeProcessingFee é true e o de chargeRecipientProcessingFee é false.

Há duas formas diferentes de tratar a taxa: chargeProcessingFee define o cálculo e a divisão proporcional associada à regra; chargeRecipientProcessingFee concentra a taxa inteira em um recebedor específico. Use chargeProcessingFee: false junto com chargeRecipientProcessingFee: true para atribuí-la integralmente a esse recebedor. Confira a regra comercial acordada para a sua conta antes de escolher os valores.

Consultar transações

GET /v1/transaction retorna um objeto paginado. Ele é indicado para telas administrativas, conciliação e buscas operacionais. Use rangeTime com sort.property para filtros temporais. Isso deixa a consulta mais clara e ajuda a evitar buscas amplas demais.

curl --request GET 'https://sandbox.api.veepag.com/v1/transaction?page=1&limit=20&sort.property=createdAt&sort.order=desc' \
  --header 'apiKey: keyId.secret'

GET /v2/transaction retorna um array direto, sem paginação. Ele exige companyId e um filtro por período de até 7 dias ou um identificador (id ou tid).

Capturar uma autorização

POST /v1/transaction/capture captura uma transação previamente autorizada. Use esse endpoint quando o pagamento foi autorizado antes, mas a captura ficou para uma etapa posterior. A captura usa o valor salvo na própria transação (transaction.amount.value). O campo amount existe no DTO, mas não é usado pelo fluxo atual de captura.

{
  "companyId": "company_id",
  "transactionId": "transaction_id"
}

Também é aceito tid. Pelo menos um identificador é necessário em runtime.

Cancelar uma transação

PUT /v1/transaction/cancel cancela ou estorna uma transação.

{
  "companyId": "company_id",
  "transactionId": "transaction_id",
  "cancelSubscription": false
}

Se cancelSubscription for true, a assinatura vinculada também pode ser cancelada. Use essa opção com cuidado quando a transação fizer parte de uma recorrência.

Exportar transações

GET /v1/transaction/exports exporta até 10.000 itens. Se o filtro exceder esse limite, reduza o período ou refine os filtros.

Para exportações grandes, prefira períodos menores. Isso melhora o tempo de resposta e facilita conferir os dados depois.

Comece aqui

Guias

Tokenização

API Reference

Criar uma transação

Configurar split na transação

Consultar transações

Capturar uma autorização

Cancelar uma transação

Exportar transações

​Criar uma transação

​Configurar split na transação

​Consultar transações

​Capturar uma autorização

​Cancelar uma transação

​Exportar transações

Criar uma transação

Configurar split na transação

Consultar transações

Capturar uma autorização

Cancelar uma transação

Exportar transações