{"openapi":"3.0.3","info":{"title":"KoltPay API Reference","version":"1.0.0","description":"## Visao geral\nReferencia publica de pagamentos focada nas operacoes principais:\n- gerar cobranca Pix externa\n- solicitar saque Pix externo\n- gerar cobranca por cartao\n- cancelar cobranca por cartao\n\n## Autenticacao\nEnvie sua chave de integracao no header `x-api-key`.\n\n## Fluxo de cartao\n1. Chame `POST /card/charges`.\n2. Se a API retornar `code = 3DS_REQUIRED`, abra a `popupUrl` retornada.\n3. A janela conclui a autenticacao automaticamente.\n4. O status final e enviado para o webhook da sua aplicacao.\n\n## Como validar se o webhook veio mesmo da KoltPay\nTodo webhook da KoltPay inclui:\n- `X-Koltpay-Signature`\n- `X-Koltpay-Idempotency-Key`\n\nA assinatura e um HMAC SHA-256 calculado a partir do corpo bruto da requisicao usando o seu segredo de assinatura.\n\nExemplo em Node.js:\n```js\nconst crypto = require('crypto');\nconst expected = crypto.createHmac('sha256', signingSecret).update(rawBody).digest('hex');\nconst valid = signature === expected;\n```\n\nUse `X-Koltpay-Idempotency-Key` para ignorar entregas duplicadas.\n\n## Principais respostas\n- `200` + `code: 3DS_REQUIRED`: ainda falta a autenticacao do comprador.\n- `201`: cobranca criada com sucesso.\n- `400`: corpo invalido ou erro de processamento.\n- `401`: `x-api-key` invalida ou inativa.","contact":{"name":"KoltPay"}},"servers":[{"url":"https://api.koltpay.com/v2","description":"API de producao"}],"tags":[{"name":"Pix","description":"Cobranca Pix externa e saque Pix externo."},{"name":"Credit Card","description":"Endpoint publico de cobranca por cartao."},{"name":"User Webhooks","description":"Formato dos webhooks assinados enviados para a sua aplicacao."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid payload"},"error":{"type":"object","nullable":true,"additionalProperties":true},"errors":{"type":"object","nullable":true,"additionalProperties":true}}},"PixChargeRequest":{"type":"object","required":["payload"],"properties":{"payload":{"type":"object","required":["Customer","Payment"],"properties":{"MerchantOrderId":{"type":"string","example":"PIX123ABC"},"Customer":{"type":"object","required":["Name","Identity"],"properties":{"Name":{"type":"string","example":"Joao Silva"},"Identity":{"type":"string","example":"12345678909"},"IdentityType":{"type":"string","example":"CPF"}}},"Payment":{"type":"object","required":["Type","Amount"],"properties":{"Type":{"type":"string","enum":["Pix"],"example":"Pix"},"Amount":{"type":"number","example":50,"description":"Valor em BRL. Minimo: 5.00."},"QrCode":{"type":"object","properties":{"Expiration":{"type":"integer","example":86400}}}}}}}}},"PixChargeResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"KoltPay":{"type":"object","properties":{"message":{"type":"string","example":"Payment via PIX QR code generated successfully"},"company_name":{"type":"string","example":"KoltPay"}}},"Payment":{"type":"object","properties":{"QrCodeString":{"type":"string","example":"00020101021226890014br.gov.bcb.pix..."},"QrCodeImageUrl":{"type":"string","example":"data:image/png;base64,iVBORw0KGgo..."},"Amount":{"type":"number","example":50},"PaymentId":{"type":"string","example":"pix_123456789"},"statusName":{"type":"string","example":"PENDING"}}}}}}},"PixWithdrawRequest":{"type":"object","required":["value","pixAddressKey","pixAddressKeyType"],"properties":{"value":{"type":"number","example":150,"description":"Valor em BRL. Minimo: 50.00."},"pixAddressKey":{"type":"string","example":"12345678909"},"pixAddressKeyType":{"type":"string","example":"CPF"},"description":{"type":"string","example":"External withdrawal"},"externalReference":{"type":"string","example":"wd-001"}}},"PixWithdrawResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"transfer_id":{"type":"string","example":"wd-1c9530f6-7d24-46a2-b3e0-27dcdb0c8af7"},"status":{"type":"string","example":"PENDING"},"value":{"type":"number","example":150},"tax_amount":{"type":"number","example":4.5},"total_deducted":{"type":"number","example":154.5}}},"CreditCardCancelRequest":{"type":"object","properties":{"amount":{"type":"integer","example":500,"description":"Valor em centavos. Abaixo de R$ 5,00, somente R$ 0,20 e liberado para testes. Em operacao normal, à vista a partir de R$ 5,00 e no parcelado cada parcela deve ter no minimo R$ 5,00."},"reason":{"type":"string","enum":["HighRisk"],"example":"HighRisk"}}},"CreditCardListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":113598},"merchantOrderId":{"type":"string","example":"PEDIDO123ABC"},"paymentId":{"type":"string","example":"e57d25e8-7695-428f-ad77-69281aca2fc3"},"customer":{"type":"object","properties":{"name":{"type":"string","example":"Joao Silva"},"identity":{"type":"string","example":"12345678909"},"identityType":{"type":"string","example":"CPF"}}},"payment":{"type":"object","properties":{"type":{"type":"string","example":"CreditCard"},"provider":{"type":"string","example":"bank_processing"},"brand":{"type":"string","example":"Visa"},"last4":{"type":"string","example":"1111"},"grossAmount":{"type":"number","example":10},"netAmount":{"type":"number","example":9.51},"amountCaptured":{"type":"number","example":10},"amountCancelled":{"type":"number","example":0}}},"status":{"type":"object","properties":{"code":{"type":"integer","example":2},"name":{"type":"string","example":"PAID"},"message":{"type":"string","example":"Operation Successful"},"settlement":{"type":"string","example":"PENDING_RELEASE"}}},"authorization":{"type":"object","properties":{"proofOfSale":{"type":"string","example":"014026"},"tid":{"type":"string","example":"28988149835IL23QAHLE"},"authorizationCode":{"type":"string","nullable":true,"example":"123456"}}},"threeDS":{"type":"object","properties":{"used":{"type":"boolean","example":true},"dataOnly":{"type":"boolean","example":false},"eci":{"type":"string","example":"05"},"version":{"type":"string","example":"2.2.0"},"referenceId":{"type":"string","example":"766355f0-512d-4eec-b72f-73821039e246"}}}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"totalItems":{"type":"integer","example":42},"totalPages":{"type":"integer","example":3},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}}},"summary":{"type":"object","properties":{"totalTransactions":{"type":"integer","example":42},"grossAmount":{"type":"number","example":1250},"netAmount":{"type":"number","example":1192.44},"capturedAmount":{"type":"number","example":1250},"cancelledAmount":{"type":"number","example":10},"statusBreakdown":{"type":"object","properties":{"pending":{"type":"integer","example":4},"paid":{"type":"integer","example":35},"cancelled":{"type":"integer","example":2},"reversed":{"type":"integer","example":1}}}}}}}}},"CreditCardChargeRequest":{"type":"object","required":["payload"],"properties":{"returnUrl":{"type":"string","format":"uri","example":"https://merchant.example/checkout/return"},"payload":{"type":"object","required":["Customer","Payment"],"properties":{"MerchantOrderId":{"type":"string","example":"PEDIDO123ABC"},"Customer":{"type":"object","required":["Name","Identity"],"properties":{"Name":{"type":"string","example":"Joao Silva"},"Identity":{"type":"string","example":"12345678909"},"IdentityType":{"type":"string","example":"CPF"},"Email":{"type":"string","example":"joao@email.com"},"Phone":{"type":"string","example":"5511999999999"},"Address":{"type":"object","properties":{"Street":{"type":"string","example":"Rua Exemplo"},"Number":{"type":"string","example":"100"},"ZipCode":{"type":"string","example":"07097000"},"City":{"type":"string","example":"Guarulhos"},"State":{"type":"string","example":"SP"},"Country":{"type":"string","example":"BRA"}}}}},"Payment":{"type":"object","required":["Type","Amount","CreditCard"],"properties":{"Type":{"type":"string","enum":["CreditCard"],"example":"CreditCard"},"Amount":{"type":"integer","minimum":20,"example":1000,"description":"Valor em centavos. Abaixo de R$ 5,00, somente R$ 0,20 e liberado para testes. Em operacao normal, à vista a partir de R$ 5,00 e no parcelado cada parcela deve ter no minimo R$ 5,00."},"Installments":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"Quantidade de parcelas. Máximo de 12x. Para pagamentos à vista (1x), valor mínimo é R$ 0,20. Para parcelado, parcela mínima de R$ 5,00."},"Capture":{"type":"boolean","example":true},"Authenticate":{"type":"boolean","example":true},"CreditCard":{"type":"object","required":["CardNumber","Holder","ExpirationDate","SecurityCode","Brand"],"properties":{"CardNumber":{"type":"string","example":"4111111111111111"},"Holder":{"type":"string","example":"JOAO SILVA"},"ExpirationDate":{"type":"string","example":"12/2030"},"SecurityCode":{"type":"string","example":"123"},"Brand":{"type":"string","example":"Visa"}}}}}}}}},"CreditCardAwaiting3DSResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"3DS authentication is required for credit card payments."},"code":{"type":"string","example":"3DS_REQUIRED"},"data":{"type":"object","properties":{"status":{"type":"string","example":"AWAITING_3DS_AUTHENTICATION"},"requiresThreeDS":{"type":"boolean","example":true},"authenticated":{"type":"boolean","example":false},"mode":{"type":"string","example":"popup"},"checkoutUrl":{"type":"string","example":"/card/auth/checkout/7e234ebc-489f-4f50-8d50-00c91c70240e"},"popupUrl":{"type":"string","example":"/card/auth/checkout/7e234ebc-489f-4f50-8d50-00c91c70240e","description":"Use este URL em um iframe na pagina de checkout do seu site. Ele carrega um popup que aguarda a resposta do banco do cartao para decidir se havera desafio."},"sessionId":{"type":"string","example":"7e234ebc-489f-4f50-8d50-00c91c70240e"},"expiresAt":{"type":"string","format":"date-time"}}}}},"CreditCardCreatedResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"integrationKeyId":{"type":"integer","example":5},"transactionId":{"type":"integer","example":113598},"transactionStatus":{"type":"string","example":"PENDING_RELEASE"},"settlementStatus":{"type":"string","example":"PENDING_RELEASE"},"releaseAt":{"type":"string","format":"date-time","nullable":true},"netAmount":{"type":"number","example":9.51},"threeDS":{"type":"object","properties":{"used":{"type":"boolean","example":true},"dataOnly":{"type":"boolean","example":false},"eci":{"type":"string","example":"05"},"version":{"type":"string","example":"2.2.0"},"referenceId":{"type":"string","example":"766355f0-512d-4eec-b72f-73821039e246"}}},"acquirer":{"type":"object","properties":{"merchantOrderId":{"type":"string","example":"PEDIDO123ABC"},"payment":{"type":"object","properties":{"paymentId":{"type":"string","example":"e57d25e8-7695-428f-ad77-69281aca2fc3"},"status":{"type":"integer","example":2},"returnCode":{"type":"string","example":"6"},"returnMessage":{"type":"string","example":"Operation Successful"},"amount":{"type":"integer","example":1000},"installments":{"type":"integer","example":1},"brand":{"type":"string","example":"Visa"},"last4":{"type":"string","example":"1111"}}}}}}}}},"CreditCardCancellationResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"MerchantOrderId":{"type":"string","example":"PEDIDO123ABC"},"AcquirerOrderId":{"type":"string","nullable":true,"example":"2026052012345678901"},"Customer":{"type":"object","properties":{"Name":{"type":"string","example":"Joao Silva"},"Identity":{"type":"string","example":"12345678909"},"Email":{"type":"string","nullable":true,"example":"joao@email.com"},"Address":{"type":"object","additionalProperties":true,"nullable":true}}},"Payment":{"type":"object","properties":{"Amount":{"type":"integer","example":1000},"VoidedAmount":{"type":"integer","example":1000},"VoidedDate":{"type":"string","example":"2026-05-20 14:45:11"},"Status":{"type":"string","example":"CANCELLED"},"PaymentId":{"type":"string","example":"c60b1253-0880-446c-9a91-73639f2cd7b4"},"ProofOfSale":{"type":"string","nullable":true,"example":"014026"},"AuthorizationCode":{"type":"string","nullable":true,"example":"123456"},"ReceivedDate":{"type":"string","nullable":true,"example":"2026-05-18 12:20:29"},"Brand":{"type":"string","nullable":true,"example":"Master"},"CardNumber":{"type":"string","nullable":true,"example":"537142******3754"},"Installments":{"type":"integer","nullable":true,"example":1}}},"ReceiptUrl":{"type":"string","format":"uri","example":"https://api.koltpay.com/v2/card/charges/c60b1253-0880-446c-9a91-73639f2cd7b4/receipt"}}}}},"UserWebhookEvent":{"type":"object","description":"Os payloads enviados para o seu endpoint variam conforme o produto e a etapa de processamento. Veja a secao de exemplos da pagina para Pix In, Pix Out e cartao.","properties":{"event":{"type":"string","example":"payment.updated"},"data":{"type":"object","properties":{"transactionId":{"type":"integer","example":113598},"paymentId":{"type":"string","example":"e57d25e8-7695-428f-ad77-69281aca2fc3"},"merchantOrderId":{"type":"string","example":"PEDIDO123ABC"},"amount":{"type":"number","example":10},"status":{"type":"string","example":"PAID"},"statusCode":{"type":"integer","example":2},"changeType":{"type":"integer","example":1},"settlementStatus":{"type":"string","example":"PENDING_RELEASE"},"returnMessage":{"type":"string","example":"Operation Successful"}}}}}}},"paths":{"/pix/qrcode":{"post":{"tags":["Pix"],"summary":"Gerar cobranca Pix externa","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixChargeRequest"}}}},"responses":{"200":{"description":"Cobranca Pix criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixChargeResponse"}}}},"400":{"description":"Payload invalido ou valor minimo nao atingido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key invalida ou inativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pix/withdraw":{"post":{"tags":["Pix"],"summary":"Solicitar saque Pix externo","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixWithdrawRequest"}}}},"responses":{"200":{"description":"Saque aceito","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixWithdrawResponse"}}}},"400":{"description":"Saldo insuficiente, valor minimo nao atingido ou dados invalidos","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Saldo insuficiente"}}}}}},"401":{"description":"API key ausente, invalida ou inativa","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized: Invalid or inactive API Key"}}}}}}}}},"/card/charges":{"get":{"tags":["Credit Card"],"summary":"Listar cobrancas por cartao","description":"Lista apenas as transacoes de cartao vinculadas a esta api_key, com filtros e paginacao.","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","example":1}},{"in":"query","name":"limit","schema":{"type":"integer","example":20}},{"in":"query","name":"status","schema":{"type":"string","enum":["PENDING","PAID","CANCELLED","REVERSED"]}},{"in":"query","name":"settlementStatus","schema":{"type":"string","enum":["NONE","PENDING_RELEASE","SETTLED","REVERSED"]}},{"in":"query","name":"merchantOrderId","schema":{"type":"string"}},{"in":"query","name":"paymentId","schema":{"type":"string"}},{"in":"query","name":"brand","schema":{"type":"string"}},{"in":"query","name":"dateFrom","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"dateTo","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Lista de cobrancas retornada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardListResponse"}}}},"400":{"description":"Erro de validacao ou processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key invalida ou inativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Credit Card"],"summary":"Gerar cobranca por cartao","description":"Endpoint principal de cartao. Abaixo de R$ 5,00, somente o valor de R$ 0,20 e liberado para testes. Em operacao normal, cobranças à vista partem de R$ 5,00 e no parcelado cada parcela deve ter no minimo R$ 5,00. Se a autenticacao do comprador for necessaria, a API retorna uma popup URL para continuar o fluxo.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardChargeRequest"}}}},"responses":{"200":{"description":"Autenticacao do comprador pendente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardAwaiting3DSResponse"}}}},"201":{"description":"Cobranca criada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardCreatedResponse"}}}},"400":{"description":"Erro de validacao ou processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key invalida ou inativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/card/charges/{paymentId}/cancel":{"put":{"tags":["Credit Card"],"summary":"Cancelar transacao por PaymentId","description":"Cancela o valor total ou parcial de uma cobranca de cartao usando o PaymentId retornado na criacao.","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"paymentId","required":true,"schema":{"type":"string"},"description":"PaymentId returned when the card charge was created."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardCancelRequest"}}}},"responses":{"200":{"description":"Cancelamento realizado com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardCreatedResponse"}}}},"400":{"description":"Payload invalido ou cancelamento nao permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key invalida ou inativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/card/charges/{paymentId}/cancellation":{"get":{"tags":["Credit Card"],"summary":"Consultar cancelamento e comprovante","description":"Consulta os dados do cancelamento e devolve a URL do comprovante dessa reversao.","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"paymentId","required":true,"schema":{"type":"string"},"description":"PaymentId of the cancelled card charge."}],"responses":{"200":{"description":"Dados do cancelamento retornados com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardCancellationResponse"}}}},"400":{"description":"Payload invalido ou cancelamento nao permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API key invalida ou inativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"x-koltpay":{"userWebhook":{"headers":{"signature":"X-Koltpay-Signature","idempotencyKey":"X-Koltpay-Idempotency-Key"},"payloadSchema":{"$ref":"#/components/schemas/UserWebhookEvent"}}}}