{"openapi":"3.1.0","info":{"title":"Kirvex API","version":"1.0.0","description":"Public payments API for Kirvex.\n\nTest mode: there is one API host. The secret key decides the mode — a `sk_test_` key sends charges to the acquirer's SANDBOX and never moves real money; a `sk_live_` key charges for real. Objects carry `livemode` (false = test). A test key only sees and acts on test objects (a live charge is 404 for it, and vice versa). When the requested method has no sandbox configured, a test charge is refused with 422 `test_mode_unavailable` — never sent to production. Operations that only exist with real money (payouts, receivable anticipation, crypto invoices and withdrawals, recipients, subscriptions, payment links) refuse a test key with the same error. Webhook events carry a top-level `livemode`.","contact":{"name":"Kirvex","url":"https://kirvex.com.br"}},"servers":[{"url":"https://api.kirvex.com.br","description":"Test and live (the key decides)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"basic","description":"Use your secret API key (`sk_test_*` or `sk_live_*`) as the username; password blank. `sk_test_*` = test mode (acquirer sandbox only, never real money); `sk_live_*` = real charges."}},"schemas":{"Money":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string","pattern":"^\\d+$","description":"Integer cents as string"},"currency":{"type":"string","enum":["BRL"]}}},"Customer":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"document":{"type":"string","description":"CPF (11 digits) or CNPJ (14 digits)"}}},"ChargeStatus":{"type":"string","enum":["pending","authorized","captured","succeeded","failed","refunded","partially_refunded","voided"]},"Charge":{"type":"object","required":["id","object","livemode","status","method","amount","vendor","created_at"],"properties":{"id":{"type":"string","example":"ch_018f1c4b..."},"object":{"type":"string","enum":["charge"]},"livemode":{"type":"boolean","description":"false = created with a sk_test_ key against the acquirer's sandbox: no real money, never in the balance, payouts or reports."},"status":{"$ref":"#/components/schemas/ChargeStatus"},"method":{"type":"string","enum":["card","pix","boleto"]},"amount":{"$ref":"#/components/schemas/Money"},"vendor":{"type":"string","enum":["pagarme","efi","woovi","stripe"]},"vendor_ref":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"pix":{"type":"object","properties":{"qrCode":{"type":"string"},"qrCodeBase64":{"type":"string"}}},"boleto":{"type":"object","properties":{"barcode":{"type":"string"},"digitableLine":{"type":"string"},"pdfUrl":{"type":"string"}}}}},"CreateChargeRequest":{"type":"object","required":["amount","method"],"properties":{"amount":{"$ref":"#/components/schemas/Money"},"method":{"type":"string","enum":["card","pix","boleto"]},"description":{"type":"string","maxLength":500},"customer_id":{"type":"string","pattern":"^cus_[0-9a-f]{32}$","description":"If supplied, customer fields are pulled from the stored Customer."},"customer":{"$ref":"#/components/schemas/Customer"},"card":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"holderName":{"type":"string"},"installments":{"type":"integer","minimum":1,"maximum":12},"captureMode":{"type":"string","enum":["auto","manual"],"default":"auto"}}},"pix":{"type":"object","properties":{"expiresInSeconds":{"type":"integer","minimum":60,"maximum":86400}}},"boleto":{"type":"object","required":["expiresAt","payerName","payerDocument"],"properties":{"expiresAt":{"type":"string","format":"date-time"},"payerName":{"type":"string"},"payerDocument":{"type":"string"}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"CustomerObject":{"type":"object","required":["id","object","email","created_at"],"properties":{"id":{"type":"string","example":"cus_018f1c4b..."},"object":{"type":"string","enum":["customer"]},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"document":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CustomerCreateRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":200},"document":{"type":"string","maxLength":20},"phone":{"type":"string","maxLength":40},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"Refund":{"type":"object","required":["id","object","charge_id","status","amount","created_at"],"properties":{"id":{"type":"string","example":"re_018f1c4b..."},"object":{"type":"string","enum":["refund"]},"charge_id":{"type":"string"},"status":{"type":"string","enum":["pending","succeeded","failed"]},"amount":{"$ref":"#/components/schemas/Money"},"vendor":{"type":"string"},"vendor_ref":{"type":"string"},"reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"succeeded_at":{"type":"string","format":"date-time"}}},"RefundRequest":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/Money"},"reason":{"type":"string","maxLength":500}}},"WebhookEndpoint":{"type":"object","required":["id","object","url","status","event_types","created_at"],"properties":{"id":{"type":"string","example":"whe_018f1c4b..."},"object":{"type":"string","enum":["webhook_endpoint"]},"url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["enabled","disabled"]},"event_types":{"type":"array","items":{"type":"string"}},"secret_prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"disabled_at":{"type":"string","format":"date-time"}}},"WebhookEndpointCreateRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"event_types":{"type":"array","items":{"type":"string"}}}},"Payout":{"type":"object","required":["id","object","status","method","amount","created_at"],"properties":{"id":{"type":"string","example":"po_018f1c4b..."},"object":{"type":"string","enum":["payout"]},"status":{"type":"string","enum":["pending","in_transit","succeeded","failed"]},"method":{"type":"string","enum":["pix_chave","pix_dados_bancarios"]},"amount":{"$ref":"#/components/schemas/Money"},"vendor":{"type":"string"},"vendor_ref":{"type":"string"},"reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"succeeded_at":{"type":"string","format":"date-time"},"failed_at":{"type":"string","format":"date-time"},"failure_reason":{"type":"string"}}},"PayoutCreateRequest":{"type":"object","required":["amount","method"],"properties":{"amount":{"$ref":"#/components/schemas/Money"},"method":{"type":"string","enum":["pix_chave","pix_dados_bancarios"]},"pix_key":{"type":"string","description":"Required when method=pix_chave"},"bank_code":{"type":"string","description":"Required when method=pix_dados_bancarios"},"agency":{"type":"string"},"account":{"type":"string"},"account_type":{"type":"string","enum":["checking","savings","payment"],"description":"payment = conta de pagamento (digital banks, payment institutions)"},"holder_name":{"type":"string"},"holder_document":{"type":"string"},"reason":{"type":"string","maxLength":500},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"RecipientCreateRequest":{"type":"object","required":["name","email","document","type","bank_account"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","format":"email"},"document":{"type":"string","minLength":11,"maxLength":14},"type":{"type":"string","enum":["individual","company"]},"bank_account":{"type":"object","required":["bank_code","agencia","conta","conta_dv","type","holder_name","holder_document"],"properties":{"bank_code":{"type":"string","pattern":"^\\d{1,4}$"},"agencia":{"type":"string","minLength":1,"maxLength":10},"conta":{"type":"string","minLength":1,"maxLength":20},"conta_dv":{"type":"string","minLength":1,"maxLength":2},"type":{"type":"string","enum":["conta_corrente","conta_poupanca","conta_pagamento"]},"holder_name":{"type":"string","minLength":1,"maxLength":200},"holder_document":{"type":"string","minLength":11,"maxLength":14}}},"auto_anticipation":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"Recipient":{"type":"object","required":["id","object","vendor","vendor_ref","type","status"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["recipient"]},"vendor":{"type":"string","enum":["pagarme"]},"vendor_ref":{"type":"string"},"type":{"type":"string","enum":["individual","company"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"document":{"type":"string"},"status":{"type":"string","enum":["registration","active","inactive"]},"bank_account":{"type":"object","properties":{"bank_code":{"type":"string"},"agencia":{"type":"string"},"conta":{"type":"string"},"conta_dv":{"type":"string"},"type":{"type":"string"},"holder_name":{"type":"string"},"holder_document":{"type":"string"}}},"auto_anticipation":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Balance":{"type":"object","required":["object","merchant_balance"],"properties":{"object":{"type":"string","enum":["balance"]},"merchant_balance":{"$ref":"#/components/schemas/Money"},"fees_earned_lifetime":{"$ref":"#/components/schemas/Money"},"refunds_out_lifetime":{"$ref":"#/components/schemas/Money"},"acquirer_in":{"$ref":"#/components/schemas/Money"},"pending_capture":{"$ref":"#/components/schemas/Money"}}},"CursorPage":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","request_id"],"properties":{"type":{"type":"string","enum":["invalid_request","authentication","authorization","rate_limit","idempotency","card","compliance","vendor","api"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"},"vendor":{"type":"string"}}}}}}},"paths":{"/v1/charges":{"post":{"summary":"Create a charge","operationId":"createCharge","tags":["Charges"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChargeRequest"}}}},"responses":{"201":{"description":"Charge created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`test_mode_unavailable`: a sk_test_ key asked for a method with no acquirer sandbox configured. Nothing was charged; a test key never falls back to production. Also used for compliance blocks (`compliance_block`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"No vendor available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"summary":"List charges","operationId":"listCharges","tags":["Charges"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ChargeStatus"}},{"name":"method","in":"query","schema":{"type":"string","enum":["card","pix","boleto"]}}],"responses":{"200":{"description":"Cursor-paginated list of charges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage"}}}}}}},"/v1/charges/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a charge","operationId":"getCharge","tags":["Charges"],"parameters":[{"name":"expand","in":"query","description":"Comma-separated list of fields to inline (currently: refunds).","schema":{"type":"string"}}],"responses":{"200":{"description":"Charge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/charges/{id}/capture":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Capture an authorized charge","operationId":"captureCharge","tags":["Charges"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/Money"}}}}}},"responses":{"200":{"description":"Captured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"409":{"description":"Charge not in capturable state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/charges/{id}/void":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Void an authorized charge","operationId":"voidCharge","tags":["Charges"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Voided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"409":{"description":"Charge not voidable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/charges/{id}/refund":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Refund a charge (full or partial)","operationId":"refundCharge","tags":["Refunds"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"201":{"description":"Refund created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"409":{"description":"Charge not refundable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/refunds":{"get":{"summary":"List refunds","operationId":"listRefunds","tags":["Refunds"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"charge_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated list of refunds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage"}}}}}}},"/v1/refunds/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a refund","operationId":"getRefund","tags":["Refunds"],"responses":{"200":{"description":"Refund","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/payouts":{"post":{"summary":"Create a payout (Pix)","operationId":"createPayout","tags":["Payouts"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCreateRequest"}}}},"responses":{"201":{"description":"Payout created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"409":{"description":"Insufficient balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"summary":"List payouts","operationId":"listPayouts","tags":["Payouts"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Cursor-paginated payouts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage"}}}}}}},"/v1/payouts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a payout","operationId":"getPayout","tags":["Payouts"],"responses":{"200":{"description":"Payout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}}}}},"/v1/recipients":{"post":{"summary":"Create a recipient (recebedor)","operationId":"createRecipient","tags":["Recipients"],"description":"KYC-gated: the authenticated merchant must be active and KYC-approved. Provisions a Pagar.me recipient and stores its vendor_ref.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientCreateRequest"}}}},"responses":{"201":{"description":"Recipient created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recipient"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Merchant not KYC-approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Pagar.me not provisioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"summary":"List recipients","operationId":"listRecipients","tags":["Recipients"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Cursor-paginated recipients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage"}}}}}}},"/v1/balance":{"get":{"summary":"Get merchant balance","operationId":"getBalance","tags":["Balance"],"responses":{"200":{"description":"Current balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}}}}},"/v1/customers":{"post":{"summary":"Create a customer","operationId":"createCustomer","tags":["Customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreateRequest"}}}},"responses":{"201":{"description":"Customer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerObject"}}}}}},"get":{"summary":"List customers","operationId":"listCustomers","tags":["Customers"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"email","in":"query","schema":{"type":"string","format":"email"}},{"name":"document","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated list of customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage"}}}}}}},"/v1/customers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a customer","operationId":"getCustomer","tags":["Customers"],"responses":{"200":{"description":"Customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerObject"}}}}}},"patch":{"summary":"Update a customer","operationId":"updateCustomer","tags":["Customers"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreateRequest"}}}},"responses":{"200":{"description":"Updated customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerObject"}}}}}},"delete":{"summary":"Soft-delete a customer","operationId":"deleteCustomer","tags":["Customers"],"responses":{"200":{"description":"Customer deleted"}}}},"/v1/webhook_endpoints":{"post":{"summary":"Register a webhook endpoint","operationId":"createWebhookEndpoint","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreateRequest"}}}},"responses":{"201":{"description":"Endpoint registered (secret returned ONCE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"get":{"summary":"List webhook endpoints","operationId":"listWebhookEndpoints","tags":["Webhooks"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Cursor-paginated list of endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage"}}}}}}},"/v1/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","operationId":"getWebhookEndpoint","tags":["Webhooks"],"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"patch":{"summary":"Update a webhook endpoint","operationId":"updateWebhookEndpoint","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreateRequest"}}}},"responses":{"200":{"description":"Updated endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"delete":{"summary":"Disable a webhook endpoint","operationId":"disableWebhookEndpoint","tags":["Webhooks"],"responses":{"200":{"description":"Disabled endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}}}}