Documentacao clara para colocar pagamentos no ar

Tudo o que voce precisa para integrar cobrancas Pix, saques e cartao em um unico lugar, com exemplos reais de resposta e validacao segura de webhook.

Autenticacao

Envie sua chave de integracao em x-api-key em todas as chamadas publicas. O corpo deve ser JSON e os valores monetarios seguem o formato documentado em cada rota.

Autenticacao

Envie sua chave de integracao em x-api-key em todas as chamadas publicas. O corpo deve ser JSON e os valores monetarios seguem o formato documentado em cada rota.

Codigos e respostas

200 com code: 3DS_REQUIRED significa que a cobranca precisa de confirmacao do comprador. 201 indica criacao com sucesso. 400 cobre payload invalido ou erro de processamento. 401 indica credencial invalida.

Validacao de webhook

Veja exatamente o que chega na sua URL, com assinatura, idempotencia e payloads reais.

Validacao de webhook

Valide X-Koltpay-Signature usando HMAC SHA-256 com o corpo bruto da requisicao. Use X-Koltpay-Idempotency-Key para ignorar entregas duplicadas.

Headers que chegam no seu endpoint

X-Koltpay-Signature: 4a6e53a6b5a5d4d4b31f1b4d0f0c0d2abf3c3f998b8e66741f90b8f5c6cb1234
X-Koltpay-Idempotency-Key: deposit:df8f54f7-7284-4197-b59a-8c494d206404
Content-Type: application/json
Validacao de webhook Node.js 
const crypto = require('crypto');

function verifySignature(rawBody, signature, signingSecret) {
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');

  return signature === expected;
}
Webhook de Pix In JSON

Hoje esta documentacao publica cobre o fluxo entregue pelo provedor Pix usado nesta integracao.

{
  "event": "deposit",
  "paymentId": "0196f5ef-5c86-71ff-8bc9-7d0f00f5c2b4",
  "status": "PAID",
  "amount": "10.00",
  "merchantOrderId": "PIX123ABC"
}
Webhook de Pix Out JSON

Saques e transferencias Pix sao confirmados pela camada de provedor e entregues para a sua URL com um evento objetivo.

{
  "event": "withdrawal",
  "withdrawalId": "113598",
  "status": "APPROVED",
  "amount": "50.00",
  "description": "Saque aprovado",
  "key_pix": "11999999999"
}
Webhook de cartao JSON

Quando a cobranca por cartao muda de estado, a sua URL recebe eventos de aprovacao, cancelamento e tambem de recusa/falha de cobranca.

{
  "event": "payment.confirmed",
  "data": {
    "transactionId": 113598,
    "paymentId": "df8f54f7-7284-4197-b59a-8c494d206404",
    "merchantOrderId": "PEDIDO123ABC",
    "amount": 10,
    "status": "PAID",
    "statusCode": 2,
    "customer": {
      "name": "Joao Silva",
      "identity": "12345678909",
      "identityType": "CPF"
    },
    "card": {
      "brand": "Master",
      "last4": "3754"
    },
    "threeDS": {
      "used": true,
      "dataOnly": false,
      "eci": "02",
      "cavv": "kBOeH3Wy3eMiwwAFQkut/ZhhN4fl",
      "xid": null,
      "version": "2.2.0",
      "referenceId": "766355f0-512d-4eec-b72f-73821039e246"
    },
    "provider": "bank_processing",
    "fee": 0.49,
    "netAmount": 9.51,
    "capturedAmount": 10,
    "cancelledAmount": 0,
    "settlementStatus": "PENDING_RELEASE",
    "releaseAt": "2026-06-18T12:20:29.000Z",
    "settledAt": null,
    "receivedDate": "2026-05-18 12:20:29"
  }
}
Webhook de cartao recusado JSON

Quando o banco ou o processamento bancario recusa a cobranca, a sua URL recebe um evento `payment.denied` com a mensagem amigavel e os dados essenciais da tentativa.

{
  "event": "payment.denied",
  "data": {
    "transactionId": 113626,
    "paymentId": "24f7f861-df85-43ee-99c1-605447f842d7",
    "merchantOrderId": "pedid1747466100",
    "amount": 50,
    "installments": 6,
    "status": "DENIED",
    "statusCode": 3,
    "message": "Pagamento recusado. Normalmente isso acontece por saldo insuficiente, limite indisponivel ou bloqueio temporario do banco. Verifique com seu banco e tente novamente.",
    "returnMessage": "Pagamento recusado. Normalmente isso acontece por saldo insuficiente, limite indisponivel ou bloqueio temporario do banco. Verifique com seu banco e tente novamente.",
    "customer": {
      "name": "Joao Silva",
      "identity": "01347898816",
      "identityType": "CPF"
    },
    "card": {
      "brand": "Master",
      "last4": "3754"
    },
    "threeDS": {
      "used": true,
      "dataOnly": false,
      "eci": "2",
      "cavv": "kBOTapBdfMU9QROIZwu4UJhhuAQP",
      "xid": null,
      "version": "2.2.0",
      "referenceId": "4a3a0a91-276b-4409-a767-1412742f11fb"
    },
    "acquirer": {
      "status": 3,
      "returnCode": "51",
      "returnMessage": "Autorizacao negada",
      "proofOfSale": "018002",
      "tid": "28988149835IMTSU6RFE",
      "authorizationCode": null,
      "eci": "2"
    }
  }
}

Pix In

Secao dedicada a cobrancas Pix de entrada e ao evento de confirmacao que a sua aplicacao recebe.

POST /pix/qrcode

Gera uma cobranca Pix externa com QR Code.

x-api-key + JSON
Webhook de Pix In

Hoje esta documentacao publica cobre o fluxo entregue pelo provedor Pix usado nesta integracao.

event: deposit
Webhook de Pix In JSON 
{
  "event": "deposit",
  "paymentId": "0196f5ef-5c86-71ff-8bc9-7d0f00f5c2b4",
  "status": "PAID",
  "amount": "10.00",
  "merchantOrderId": "PIX123ABC"
}
POST /pix/qrcode Gera uma cobranca Pix externa com QR Code.

Pix Out

Secao dedicada a saques e transferencias Pix, incluindo eventos de aprovacao e falha.

POST /pix/withdraw

Solicita um saque Pix externo.

x-api-key + JSON
Webhook de Pix Out

Saques e transferencias Pix sao confirmados pela camada de provedor e entregues para a sua URL com um evento objetivo.

event: withdrawal / withdrawal_approved
Webhook de Pix Out JSON 
{
  "event": "withdrawal",
  "withdrawalId": "113598",
  "status": "APPROVED",
  "amount": "50.00",
  "description": "Saque aprovado",
  "key_pix": "11999999999"
}
POST /pix/withdraw Solicita um saque Pix externo.

Cartao

Secao dedicada a cobrancas por cartao, autenticacao do comprador, listagem e cancelamento.

POST /card/charges

Cria uma cobranca por cartao. Abaixo de R$ 5,00, somente R$ 0,20 e liberado para testes; em operacao normal, à vista a partir de R$ 5,00 e parcela minima de R$ 5,00 no parcelado.

popupUrl quando a confirmacao do comprador for necessaria
GET /card/charges

Lista as cobrancas por cartao desta credencial.

lista apenas transacoes desta credencial
PUT /card/charges/{paymentId}/cancel

Cancela uma cobranca por cartao usando o PaymentId.

cancelamento total ou parcial
GET /card/charges/{paymentId}/cancellation

Consulta os dados do cancelamento e recupera a URL do comprovante.

retorna os dados do cancelamento e a URL do comprovante
Webhook de cartao

Quando a cobranca por cartao muda de estado, a sua URL recebe eventos de aprovacao, cancelamento e tambem de recusa/falha de cobranca.

event: payment.confirmed / payment.cancelled / payment.denied
Exemplo de requisicao Node.js 
const response = await fetch('https://api.koltpay.com/v2/card/charges', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_koltpay_xxx'
  },
  body: JSON.stringify({
    payload: {
      MerchantOrderId: 'ORDER-1001',
      Customer: {
        Name: 'Joao Silva',
        Identity: '12345678909',
        IdentityType: 'CPF'
      },
      Payment: {
        Type: 'CreditCard',
        Amount: 1000,
        Installments: 1,
        Capture: true,
        CreditCard: {
          CardNumber: '4111111111111111',
          Holder: 'JOAO SILVA',
          ExpirationDate: '12/2030',
          SecurityCode: '123',
          Brand: 'Visa'
        }
      }
    }
  })
});
Exemplo de resposta JSON 
{
  "success": true,
  "message": "3DS authentication is required for credit card payments.",
  "code": "3DS_REQUIRED",
  "data": {
    "status": "AWAITING_3DS_AUTHENTICATION",
    "requiresThreeDS": true,
    "popupUrl": "/card/auth/checkout/SESSION_ID",
    "comment": "Dai voce utiliza esse URL por iframe na pagina de checkout do seu site. Ele vai carregar um popup aguardando a resposta do banco do cartao, para saber se vai enviar um desafio ou nao."
  }
}
Webhook de cartao recusado JSON 
{
  "event": "payment.denied",
  "data": {
    "transactionId": 113626,
    "paymentId": "24f7f861-df85-43ee-99c1-605447f842d7",
    "merchantOrderId": "pedid1747466100",
    "amount": 50,
    "installments": 6,
    "status": "DENIED",
    "statusCode": 3,
    "message": "Pagamento recusado. Normalmente isso acontece por saldo insuficiente, limite indisponivel ou bloqueio temporario do banco. Verifique com seu banco e tente novamente.",
    "returnMessage": "Pagamento recusado. Normalmente isso acontece por saldo insuficiente, limite indisponivel ou bloqueio temporario do banco. Verifique com seu banco e tente novamente.",
    "customer": {
      "name": "Joao Silva",
      "identity": "01347898816",
      "identityType": "CPF"
    },
    "card": {
      "brand": "Master",
      "last4": "3754"
    },
    "threeDS": {
      "used": true,
      "dataOnly": false,
      "eci": "2",
      "cavv": "kBOTapBdfMU9QROIZwu4UJhhuAQP",
      "xid": null,
      "version": "2.2.0",
      "referenceId": "4a3a0a91-276b-4409-a767-1412742f11fb"
    },
    "acquirer": {
      "status": 3,
      "returnCode": "51",
      "returnMessage": "Autorizacao negada",
      "proofOfSale": "018002",
      "tid": "28988149835IMTSU6RFE",
      "authorizationCode": null,
      "eci": "2"
    }
  }
}
POST /card/charges Cria uma cobranca por cartao. Abaixo de R$ 5,00, somente R$ 0,20 e liberado para testes; em operacao normal, à vista a partir de R$ 5,00 e parcela minima de R$ 5,00 no parcelado.
GET /card/charges Lista as cobrancas por cartao desta credencial.
PUT /card/charges/{paymentId}/cancel Cancela uma cobranca por cartao usando o PaymentId.
GET /card/charges/{paymentId}/cancellation Consulta os dados do cancelamento e recupera a URL do comprovante.