{"openapi":"3.1.0","info":{"title":"Nexora API","version":"1.0.0-rc.3","description":"Public server-to-server API for merchant payment integrations. Scope is derived from the API key; callers never select another tenant, merchant, or environment."},"servers":[{"url":"https://api.nexorapay.me","description":"Public API for this documentation host"}],"x-white-label-server-template":"https://api.{primary_domain}","tags":[{"name":"System"},{"name":"Balances"},{"name":"Payments"},{"name":"Refunds"},{"name":"Withdrawals"}],"paths":{"/v1/health":{"get":{"tags":["System"],"summary":"API health","security":[],"responses":{"200":{"description":"API is available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/auth/check":{"get":{"tags":["System"],"summary":"Validate API key and resolved merchant scope","description":"Read-only connectivity check. Requires a valid active Bearer API key for the requested White Label API hostname. Does not require a financial permission and does not create payments or withdrawals.","security":[{"merchantApiKey":[]}],"responses":{"200":{"description":"Key is valid for this API hostname and merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyConnectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/balances":{"get":{"tags":["Balances"],"summary":"List merchant balances","description":"Returns ledger-backed balances for the merchant and environment bound to the API key. Requires balances.read. MERCHANT_PENDING is confirmed money still awaiting settlement; MERCHANT_AVAILABLE is the amount eligible for withdrawals, subject to the normal withdrawal controls.","security":[{"merchantApiKey":[]}],"responses":{"200":{"description":"Balance list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/payments":{"post":{"tags":["Payments"],"summary":"Create a PIX, boleto, or hosted card payment","description":"Creates a payment in the merchant/environment bound to the API key. CARD uses PROVIDER_HOSTED / HOSTED_INVOICE only: no card number, CVV, or card token is accepted by this API. Provider processing is asynchronous.","security":[{"merchantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}}},"responses":{"202":{"description":"Payment accepted for processing","headers":{"Location":{"description":"Relative URL for the created payment","schema":{"type":"string"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Arche-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"get":{"tags":["Payments"],"summary":"List payments","description":"Cursor-paginated payment list for the merchant/environment bound to the API key. Requires payments.read.","security":[{"merchantApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Number of items to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page.","schema":{"type":"string","maxLength":512}},{"name":"status","in":"query","required":false,"description":"Optional exact status filter.","schema":{"type":"string","enum":["CREATED","PROCESSING","PENDING","OVERDUE","AUTHORIZED","PAID","FAILED","CANCELED","EXPIRED"]}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Payment list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/payments/{payment_id}":{"get":{"tags":["Payments"],"summary":"Get a payment","description":"Returns a payment only from the merchant/environment bound to the API key. Requires payments.read.","security":[{"merchantApiKey":[]}],"parameters":[{"name":"payment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/refunds":{"get":{"tags":["Refunds"],"summary":"List refunds","description":"Read-only refund list for the API-key scope. Requires refunds.read. Refund creation remains intentionally unavailable because provider execution and ledger financialization are not yet implemented end-to-end.","security":[{"merchantApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Number of items to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page.","schema":{"type":"string","maxLength":512}},{"name":"status","in":"query","required":false,"description":"Optional exact status filter.","schema":{"type":"string","enum":["REQUESTED","PROCESSING","PENDING","SUCCEEDED","FAILED","CANCELED"]}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Refund list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/refunds/{refund_id}":{"get":{"tags":["Refunds"],"summary":"Get a refund","security":[{"merchantApiKey":[]}],"parameters":[{"name":"refund_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Refund","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/withdrawals":{"get":{"tags":["Withdrawals"],"summary":"List withdrawals","description":"Cursor-paginated withdrawals for the API-key scope. Requires withdrawals.read.","security":[{"merchantApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Number of items to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page.","schema":{"type":"string","maxLength":512}},{"name":"status","in":"query","required":false,"description":"Optional exact status filter.","schema":{"type":"string","enum":["REQUESTED","REVIEW","RESERVED","PROCESSING","SUCCEEDED","FAILED","CANCELED"]}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Withdrawal list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"tags":["Withdrawals"],"summary":"Create a PIX withdrawal","description":"Creates a withdrawal to a PIX key. The API key scope determines tenant, merchant, and TEST/LIVE. Account limits, compliance, risk controls, available balance, and the merchant withdrawal mode remain authoritative.","security":[{"merchantApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithdrawalRequest"}}}},"responses":{"202":{"description":"Withdrawal accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithdrawalResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/withdrawals/{withdrawal_id}":{"get":{"tags":["Withdrawals"],"summary":"Get a withdrawal","security":[{"merchantApiKey":[]}],"parameters":[{"name":"withdrawal_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"Withdrawal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"merchantApiKey":{"type":"http","scheme":"bearer","bearerFormat":"merchant_api_key","description":"Merchant API key created in the Developers area."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for this logical payment creation request. Reusing the key with a different payload returns 409.","schema":{"type":"string","minLength":8,"maxLength":255}},"RequestId":{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-generated request identifier. Invalid values are replaced by the API.","schema":{"type":"string","minLength":8,"maxLength":128}}},"headers":{"RequestId":{"description":"Request correlation identifier","schema":{"type":"string"}},"ApiVersion":{"description":"Resolved public API version","schema":{"type":"string","const":"v1"}}},"schemas":{"ErrorObject":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}},"additionalProperties":false},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorObject"}},"additionalProperties":false},"HealthResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["status","version"],"properties":{"status":{"type":"string","const":"ok"},"version":{"type":"string","const":"v1"}},"additionalProperties":false}},"additionalProperties":false},"Balance":{"type":"object","required":["account_kind","currency","balance_minor","updated_at"],"properties":{"account_kind":{"type":"string","enum":["MERCHANT_PENDING","MERCHANT_AVAILABLE","MERCHANT_RESERVE","MERCHANT_BLOCKED","MERCHANT_CLEARING"]},"currency":{"type":"string","const":"BRL"},"balance_minor":{"type":"integer","format":"int64"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"BalanceListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["object","items"],"properties":{"object":{"type":"string","const":"balance_list"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Balance"}}},"additionalProperties":false}},"additionalProperties":false},"Payer":{"type":"object","required":["name","tax_id"],"properties":{"name":{"type":"string","minLength":2,"maxLength":200},"tax_id":{"type":"string","description":"CPF or CNPJ. Punctuation is accepted and normalized server-side."}},"additionalProperties":false},"CreatePaymentRequest":{"type":"object","required":["payment_method","amount_minor","payer"],"properties":{"payment_method":{"type":"string","enum":["PIX","BOLETO","CARD"]},"amount_minor":{"type":"integer","format":"int64","minimum":1,"description":"Amount in BRL cents."},"currency":{"type":"string","const":"BRL","default":"BRL"},"payer":{"$ref":"#/components/schemas/Payer"},"due_date":{"type":["string","null"],"format":"date","description":"Required for BOLETO and CARD. Not accepted for PIX."},"client_reference":{"type":["string","null"],"maxLength":160},"card_installments":{"type":["integer","null"],"minimum":1,"maximum":21,"description":"Required for CARD. The merchant/provider readiness may enforce a lower maximum."}},"additionalProperties":false},"CreatePaymentResult":{"type":"object","required":["payment_id","payment_method","status","environment"],"properties":{"payment_id":{"type":"string","format":"uuid"},"payment_method":{"type":"string","enum":["PIX","BOLETO","CARD"]},"status":{"type":"string","enum":["CREATED","PROCESSING","PENDING","AUTHORIZED","PAID","FAILED","CANCELED","EXPIRED"],"description":"PAID means the payer's payment is confirmed by the provider. It does not mean funds are immediately withdrawable; use GET /v1/balances and MERCHANT_AVAILABLE for withdrawal availability."},"environment":{"type":"string","enum":["TEST","LIVE"]},"card_experience":{"$ref":"#/components/schemas/CardExperience"}},"additionalProperties":false},"CreatePaymentResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CreatePaymentResult"}},"additionalProperties":false},"ProviderArtifact":{"type":"object","properties":{"kind":{"type":"string","enum":["PIX_COPY_PASTE","BOLETO_BARCODE","BOLETO_DIGITABLE_LINE","BOLETO_URL","CARD_CHECKOUT_URL"]},"value":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"Payment":{"type":"object","required":["payment_id","payment_method","amount_minor","currency","status","created_at","updated_at","artifacts"],"properties":{"payment_id":{"type":"string","format":"uuid"},"payment_method":{"type":"string","enum":["PIX","BOLETO","CARD"]},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","const":"BRL"},"status":{"type":"string","enum":["CREATED","PROCESSING","PENDING","OVERDUE","AUTHORIZED","PAID","FAILED","CANCELED","EXPIRED"],"description":"Commercial payment status. OVERDUE means the charge is past due but can still become PAID later. PAID means the payer's payment is confirmed by the provider. It does not mean funds are immediately withdrawable; use GET /v1/balances and MERCHANT_AVAILABLE for withdrawal availability."},"succeeded_refund_amount_minor":{"type":"integer","format":"int64","minimum":0},"open_refund_amount_minor":{"type":"integer","format":"int64","minimum":0},"client_reference":{"type":["string","null"],"maxLength":160},"due_date":{"type":["string","null"],"format":"date"},"card_installments":{"type":["integer","null"],"minimum":1,"maximum":21},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/ProviderArtifact"}},"card_experience":{"$ref":"#/components/schemas/CardExperience"}},"additionalProperties":false},"PaymentResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Payment"}},"additionalProperties":false},"WebhookEnvelope":{"type":"object","required":["id","type","occurred_at","data_version","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["payment.created","payment.paid","payment.failed","payment.canceled","payment.expired","withdrawal.created","withdrawal.succeeded","withdrawal.failed","withdrawal.canceled"]},"occurred_at":{"type":"string","format":"date-time"},"data_version":{"type":"integer","minimum":1},"data":{"type":"object","additionalProperties":true}},"additionalProperties":false},"PaymentListItem":{"type":"object","required":["payment_id","payment_method","amount_minor","currency","status","created_at","updated_at"],"properties":{"payment_id":{"type":"string","format":"uuid"},"payment_method":{"type":"string","enum":["PIX","BOLETO","CARD"]},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","const":"BRL"},"status":{"type":"string","enum":["CREATED","PROCESSING","PENDING","OVERDUE","AUTHORIZED","PAID","FAILED","CANCELED","EXPIRED"],"description":"Commercial payment status. OVERDUE means the charge is past due but can still become PAID later. PAID means the payer's payment is confirmed by the provider. It does not mean funds are immediately withdrawable; use GET /v1/balances and MERCHANT_AVAILABLE for withdrawal availability."},"succeeded_refund_amount_minor":{"type":"integer","format":"int64","minimum":0},"open_refund_amount_minor":{"type":"integer","format":"int64","minimum":0},"client_reference":{"type":["string","null"],"maxLength":160},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"PaymentListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["object","items","next_cursor"],"properties":{"object":{"type":"string","const":"payment_list"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PaymentListItem"}},"next_cursor":{"type":["string","null"]}}}}},"Refund":{"type":"object","required":["refund_id","payment_id","amount_minor","currency","status","created_at","updated_at"],"properties":{"refund_id":{"type":"string","format":"uuid"},"payment_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","const":"BRL"},"status":{"type":"string","enum":["REQUESTED","PROCESSING","PENDING","SUCCEEDED","FAILED","CANCELED"]},"client_reference":{"type":["string","null"],"maxLength":160},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"processing_at":{"type":["string","null"],"format":"date-time"},"pending_at":{"type":["string","null"],"format":"date-time"},"succeeded_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"},"canceled_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"RefundResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Refund"}}},"RefundListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["object","items","next_cursor"],"properties":{"object":{"type":"string","const":"refund_list"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"next_cursor":{"type":["string","null"]}}}}},"PixWithdrawalDestination":{"type":"object","required":["type","pix_key_type","pix_key"],"properties":{"type":{"type":"string","const":"PIX_KEY"},"pix_key_type":{"type":"string","enum":["CPF","CNPJ","EMAIL","PHONE","EVP"]},"pix_key":{"type":"string","minLength":1,"maxLength":320,"description":"The key is sent only to the trusted payout pipeline and is not returned by read endpoints."}},"additionalProperties":false},"CreateWithdrawalRequest":{"type":"object","required":["requested_amount_minor","destination"],"properties":{"requested_amount_minor":{"type":"integer","format":"int64","minimum":1},"currency":{"type":"string","const":"BRL","default":"BRL"},"destination":{"$ref":"#/components/schemas/PixWithdrawalDestination"},"client_reference":{"type":["string","null"],"maxLength":160}},"additionalProperties":false},"Withdrawal":{"type":"object","required":["withdrawal_id","requested_amount_minor","currency","status","destination_type","created_at","updated_at"],"properties":{"withdrawal_id":{"type":"string","format":"uuid"},"requested_amount_minor":{"type":"integer","format":"int64"},"fee_amount_minor":{"type":["integer","null"],"format":"int64"},"recipient_amount_minor":{"type":["integer","null"],"format":"int64"},"total_wallet_debit_minor":{"type":["integer","null"],"format":"int64"},"currency":{"type":"string","const":"BRL"},"status":{"type":"string","enum":["REQUESTED","REVIEW","RESERVED","PROCESSING","SUCCEEDED","FAILED","CANCELED"]},"approval_mode":{"type":["string","null"]},"manual_review_status":{"type":["string","null"]},"destination_type":{"type":"string"},"destination_masked_hint":{"type":["string","null"]},"client_reference":{"type":["string","null"],"maxLength":160},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"review_at":{"type":["string","null"],"format":"date-time"},"reserved_at":{"type":["string","null"],"format":"date-time"},"processing_at":{"type":["string","null"],"format":"date-time"},"succeeded_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"},"canceled_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"CreateWithdrawalResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["withdrawal_id","status","destination_type"],"properties":{"withdrawal_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"approval_mode":{"type":["string","null"]},"destination_type":{"type":"string","const":"PIX_KEY"},"pix_key_type":{"type":"string"},"destination_masked_hint":{"type":["string","null"]}}}}},"WithdrawalResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Withdrawal"}}},"WithdrawalListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["object","items","next_cursor"],"properties":{"object":{"type":"string","const":"withdrawal_list"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Withdrawal"}},"next_cursor":{"type":["string","null"]}}}}},"CardExperience":{"type":["object","null"],"description":"Public hosted-card state. Provider/internal error codes are intentionally not exposed.","required":["code","terminal","action"],"properties":{"code":{"type":"string","enum":["PREPARING","PAYMENT_REQUIRED","RISK_REVIEW","AUTHORIZED","MANUAL_REVIEW","SUCCEEDED","CANCELED","EXPIRED","RISK_REJECTED","AUTHENTICATION_FAILED","DECLINED"]},"terminal":{"type":"boolean"},"action":{"type":"string","enum":["WAIT","OPEN_CHECKOUT","NONE"]}},"additionalProperties":false},"ApiKeyConnectionResponse":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","required":["object","authenticated","environment","tenant_id","merchant_id","api_version"],"additionalProperties":false,"properties":{"object":{"type":"string","const":"api_key_connection"},"authenticated":{"type":"boolean","const":true},"environment":{"type":"string","enum":["TEST","LIVE"]},"tenant_id":{"type":"string","format":"uuid"},"merchant_id":{"type":"string","format":"uuid"},"api_version":{"type":"string","const":"v1"}}}}}},"responses":{"Unauthorized":{"description":"Authentication failed","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Arche-API-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"API key lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found in the API key scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Idempotency, eligibility or payment readiness conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PayloadTooLarge":{"description":"Request body exceeds the API limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Validation":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds before retry","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unavailable":{"description":"Temporary API failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"webhooks":{"merchantEvent":{"post":{"summary":"Merchant webhook delivery","description":"ARCHE sends subscribed merchant events to the configured HTTPS endpoint. Verify X-Arche-Signature with HMAC-SHA256 over X-Arche-Timestamp + '.' + the raw request body.","parameters":[{"name":"X-Arche-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Arche-Delivery-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Arche-Timestamp","in":"header","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"X-Arche-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1=[0-9a-f]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"200":{"description":"Delivery accepted"},"204":{"description":"Delivery accepted without response body"}}}}},"x-webhook-signature":{"scheme":"HMAC_SHA256_V1","header":"X-Arche-Signature","timestampHeader":"X-Arche-Timestamp","signingInput":"<timestamp>.<raw_request_body>","signatureFormat":"v1=<lowercase_hex_hmac_sha256>"},"x-public-api-status":{"release":"rc","card":"HOSTED_INVOICE_ONLY","refunds":{"read":true,"create":false,"providerExecution":false,"ledgerFinancialization":false,"reason":"Refund creation remains closed until provider execution, reconciliation, and ledger financialization are complete."},"withdrawals":{"read":true,"create_pix":true},"browserTryIt":false,"releaseCandidate":"1.0.0-rc.3","commercialPaymentStatus":true,"officialWebhookEventCount":9,"refundWebhookEvents":false},"x-payment-status-semantics":{"paid":"PAID means the payer's payment is confirmed by the provider. It does not mean funds are immediately withdrawable; use GET /v1/balances and MERCHANT_AVAILABLE for withdrawal availability.","withdrawalBalanceAccount":"MERCHANT_AVAILABLE","pendingBalanceAccount":"MERCHANT_PENDING","overdue":"OVERDUE is a commercial state only. A late provider confirmation can still move the payment to PAID."}}