{"openapi":"3.0.3","info":{"title":"KoltPay API Reference","version":"1.0.0","description":"## Overview\nPublic payment reference focused on the main operations:\n- create external Pix charges\n- request external Pix withdrawals\n- create card charges\n- cancel card charges\n\n## Authentication\nSend your integration key in the `x-api-key` header.\n\n## Card flow\n1. Call `POST /card/charges`.\n2. If the API returns `code = 3DS_REQUIRED`, open the returned `popupUrl`.\n3. The popup completes authentication automatically.\n4. The final status is delivered to your application webhook.\n\n## How to verify if a webhook really came from KoltPay\nEvery KoltPay webhook includes:\n- `X-Koltpay-Signature`\n- `X-Koltpay-Idempotency-Key`\n\nThe signature is an HMAC SHA-256 generated from the raw request body using your webhook signing secret.\n\nNode.js example:\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` to ignore duplicate deliveries.\n\n## Main responses\n- `200` + `code: 3DS_REQUIRED`: buyer authentication is still required.\n- `201`: charge created successfully.\n- `400`: invalid body or processing error.\n- `401`: invalid or inactive `x-api-key`.","contact":{"name":"KoltPay"}},"servers":[{"url":"https://api.koltpay.com/v2","description":"Production API"}],"tags":[{"name":"Pix","description":"External Pix charge and external Pix withdrawal."},{"name":"Credit Card","description":"Public card charge endpoint."},{"name":"User Webhooks","description":"Signed webhook format sent to your application."}],"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":"Amount in BRL. Minimum: 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":"Amount in BRL. Minimum: 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":"Amount in cents. 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."},"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":"Amount in cents. 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."},"Installments":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"Number of installments. Maximum of 12x. For 1x, minimum amount is R$ 0.20. For >1x, minimum installment amount is 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 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."},"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":"Payloads delivered to your endpoint vary by product and processing stage. See the examples section on the page for Pix In, Pix Out and card events.","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":"Generate external Pix charge","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixChargeRequest"}}}},"responses":{"200":{"description":"Pix charge created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixChargeResponse"}}}},"400":{"description":"Invalid payload or minimum amount not met","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid or inactive API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pix/withdraw":{"post":{"tags":["Pix"],"summary":"Request external Pix withdrawal","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixWithdrawRequest"}}}},"responses":{"200":{"description":"Withdrawal accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixWithdrawResponse"}}}},"400":{"description":"Insufficient balance, minimum amount not met or invalid data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Saldo insuficiente"}}}}}},"401":{"description":"Missing, invalid or inactive API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized: Invalid or inactive API Key"}}}}}}}}},"/card/charges":{"get":{"tags":["Credit Card"],"summary":"List card charges","description":"Lists only the card transactions linked to this api_key, with filters and pagination.","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":"Charge list returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardListResponse"}}}},"400":{"description":"Validation or processing error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid or inactive API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Credit Card"],"summary":"Create card charge","description":"Main card endpoint. Below BRL 5.00, only the BRL 0.20 amount 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. If buyer authentication is required, the API returns a popup URL to continue the flow.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardChargeRequest"}}}},"responses":{"200":{"description":"Buyer authentication is pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardAwaiting3DSResponse"}}}},"201":{"description":"Charge created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardCreatedResponse"}}}},"400":{"description":"Validation or processing error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid or inactive API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/card/charges/{paymentId}/cancel":{"put":{"tags":["Credit Card"],"summary":"Cancel transaction by PaymentId","description":"Cancels the total or partial amount of a card charge using the PaymentId returned during creation.","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":"Cancellation completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardCreatedResponse"}}}},"400":{"description":"Invalid payload or cancellation not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid or inactive API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/card/charges/{paymentId}/cancellation":{"get":{"tags":["Credit Card"],"summary":"Get cancellation details and receipt","description":"Fetches cancellation details and returns the receipt URL for the reversal.","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"paymentId","required":true,"schema":{"type":"string"},"description":"PaymentId of the cancelled card charge."}],"responses":{"200":{"description":"Cancellation details returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCardCancellationResponse"}}}},"400":{"description":"Invalid payload or cancellation not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid or inactive API key","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"}}}}