API Docs | KoltPay

Clean documentation for launching payments fast

Everything you need to integrate Pix charges, withdrawals and card payments in one place, with real response examples and secure webhook verification.

Authentication

Send your integration key in x-api-key on every public request. The body must be JSON and monetary fields follow the format documented on each route.

Authentication

Send your integration key in x-api-key on every public request. The body must be JSON and monetary fields follow the format documented on each route.

Errors and responses

200 with code: 3DS_REQUIRED means the charge still needs buyer confirmation. 201 means the charge was created successfully. 400 covers invalid payloads or processing issues. 401 means the credential is invalid.

Webhook verification

See exactly what reaches your URL, including signature, idempotency and real payloads.

Webhook verification

Validate X-Koltpay-Signature with HMAC SHA-256 using the raw request body. Use X-Koltpay-Idempotency-Key to ignore duplicate deliveries.

Headers delivered to your endpoint

X-Koltpay-Signature: 4a6e53a6b5a5d4d4b31f1b4d0f0c0d2abf3c3f998b8e66741f90b8f5c6cb1234
X-Koltpay-Idempotency-Key: deposit:df8f54f7-7284-4197-b59a-8c494d206404
Content-Type: application/json

Webhook verification Node.js

const crypto = require('crypto');

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

  return signature === expected;
}

Pix In webhook JSON

This public documentation currently covers the flow delivered by the Pix provider used in this integration.

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

Pix Out webhook JSON

Pix withdrawals and transfers are confirmed by the provider layer and delivered to your URL through a straightforward event.

{
  "event": "withdrawal",
  "withdrawalId": "113598",
  "status": "APPROVED",
  "amount": "50.00",
  "description": "Withdrawal approved",
  "key_pix": "11999999999"
}

Card webhook JSON

When a card charge changes state, your URL receives approval, cancellation and also denied/failed charge events.

{
  "event": "payment.confirmed",
  "data": {
    "transactionId": 113598,
    "paymentId": "df8f54f7-7284-4197-b59a-8c494d206404",
    "merchantOrderId": "ORDER-1001",
    "amount": 10,
    "status": "PAID",
    "statusCode": 2,
    "customer": {
      "name": "John 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"
  }
}

Denied card webhook JSON

When the bank or banking processing declines the charge, your URL receives a `payment.denied` event with the buyer-facing message and the essential attempt data.

{
  "event": "payment.denied",
  "data": {
    "transactionId": 113626,
    "paymentId": "24f7f861-df85-43ee-99c1-605447f842d7",
    "merchantOrderId": "ORDER-1001",
    "amount": 50,
    "installments": 6,
    "status": "DENIED",
    "statusCode": 3,
    "message": "Payment denied. This usually happens because of insufficient funds, unavailable limit or a temporary bank block. Check with your bank and try again.",
    "returnMessage": "Payment denied. This usually happens because of insufficient funds, unavailable limit or a temporary bank block. Check with your bank and try again.",
    "customer": {
      "name": "John 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": "Authorization denied",
      "proofOfSale": "018002",
      "tid": "28988149835IMTSU6RFE",
      "authorizationCode": null,
      "eci": "2"
    }
  }
}

Pix In

Dedicated section for incoming Pix charges and the confirmation event delivered to your application.

POST /pix/qrcode

Generate an external Pix charge with QR Code.

x-api-key + JSON

Pix In webhook

This public documentation currently covers the flow delivered by the Pix provider used in this integration.

event: deposit

Pix In webhook JSON

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

POST /pix/qrcode Generate an external Pix charge with QR Code.

Pix Out

Dedicated section for Pix withdrawals and transfers, including approval and failure events.

POST /pix/withdraw

Request an external Pix withdrawal.

x-api-key + JSON

Pix Out webhook

Pix withdrawals and transfers are confirmed by the provider layer and delivered to your URL through a straightforward event.

event: withdrawal / withdrawal_approved

Pix Out webhook JSON

{
  "event": "withdrawal",
  "withdrawalId": "113598",
  "status": "APPROVED",
  "amount": "50.00",
  "description": "Withdrawal approved",
  "key_pix": "11999999999"
}

POST /pix/withdraw Request an external Pix withdrawal.

Card

Dedicated section for card charges, buyer authentication, listing and cancellation.

POST /card/charges

Create a card charge. Below BRL 5.00, only BRL 0.20 is allowed for tests; in normal operation, one-time charges should be at least BRL 5.00 and installment charges require at least BRL 5.00 per installment.

popupUrl quando a confirmacao do comprador for necessaria

GET /card/charges

List the card charges for this credential.

lista apenas transacoes desta credencial

PUT /card/charges/{paymentId}/cancel

Cancel a card charge using the PaymentId.

cancelamento total ou parcial

GET /card/charges/{paymentId}/cancellation

Fetch cancellation details and recover the receipt URL.

retorna os dados do cancelamento e a URL do comprovante

Card webhook

When a card charge changes state, your URL receives approval, cancellation and also denied/failed charge events.

event: payment.confirmed / payment.cancelled / payment.denied

Request example 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: 'John Silva',
        Identity: '12345678909',
        IdentityType: 'CPF'
      },
      Payment: {
        Type: 'CreditCard',
        Amount: 1000,
        Installments: 1,
        Capture: true,
        CreditCard: {
          CardNumber: '4111111111111111',
          Holder: 'JOHN SILVA',
          ExpirationDate: '12/2030',
          SecurityCode: '123',
          Brand: 'Visa'
        }
      }
    }
  })
});

Response example 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": "Use this URL inside an iframe on your checkout page. It loads a popup that waits for the card issuer response to decide whether a challenge will be shown or not."
  }
}

Denied card webhook JSON

{
  "event": "payment.denied",
  "data": {
    "transactionId": 113626,
    "paymentId": "24f7f861-df85-43ee-99c1-605447f842d7",
    "merchantOrderId": "ORDER-1001",
    "amount": 50,
    "installments": 6,
    "status": "DENIED",
    "statusCode": 3,
    "message": "Payment denied. This usually happens because of insufficient funds, unavailable limit or a temporary bank block. Check with your bank and try again.",
    "returnMessage": "Payment denied. This usually happens because of insufficient funds, unavailable limit or a temporary bank block. Check with your bank and try again.",
    "customer": {
      "name": "John 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": "Authorization denied",
      "proofOfSale": "018002",
      "tid": "28988149835IMTSU6RFE",
      "authorizationCode": null,
      "eci": "2"
    }
  }
}

POST /card/charges Create a card charge. Below BRL 5.00, only BRL 0.20 is allowed for tests; in normal operation, one-time charges should be at least BRL 5.00 and installment charges require at least BRL 5.00 per installment.

GET /card/charges List the card charges for this credential.

PUT /card/charges/{paymentId}/cancel Cancel a card charge using the PaymentId.

GET /card/charges/{paymentId}/cancellation Fetch cancellation details and recover the receipt URL.