# EccaEx API

## Documentation

- [Introduction](https://docs.ecca-ex.com/introduction.md): No description found
- [Payment Methods](https://docs.ecca-ex.com/payment-methods.md): Retrieve the list of active payment methods available for the authenticated merchant, including supported currency, amount limits, payment time, and commission split.
- [Invoices](https://docs.ecca-ex.com/invoices.md): Invoices are the core of the Merchant API. Create an invoice, redirect the customer to the hosted payment page, receive webhook updates, and track the invoice status from your backend.
- [Webhooks](https://docs.ecca-ex.com/webhooks.md): Receive real-time notifications when an invoice reaches a terminal state. Learn about payload structure, HMAC signature verification, the `is_adjusted` amount-adjustment flow, retry policy, webhook history API, manual resend API, and best practices.
- [Withdrawals](https://docs.ecca-ex.com/withdrawals.md): View your merchant withdrawal history and check the status of individual withdrawals.
- [Currencies](https://docs.ecca-ex.com/currencies.md): Retrieve the list of supported fiat currencies available for merchant invoices, together with the current exchange rate used by the payment system.
- [Errors](https://docs.ecca-ex.com/errors.md): Every error response follows the same structure, making it easy to handle errors consistently across all endpoints.

## API Reference

- [Authentication](https://docs.ecca-ex.com/authentication.md): No description found
- [Create invoice (no payment method yet)](https://docs.ecca-ex.com/api-reference/post-api-v1-create-invoice.md): Creates an invoice WITHOUT selecting a payment method first.

Next client-side steps:
1. `GET /api/v1/public/invoice/{order_id}/payment-methods` - show available methods;
2. `POST /api/v1/public/invoice/{order_id}/select-method` - select a method (creates a deal);
or `POST /api/v1/public/invoice/{order_id}/cancel` - cancel the invoice.

If the customer does not select a method within TTL (`invoice_expire_minutes`), the invoice is automatically marked as `expired` and a webhook is sent.
- [List merchant invoices (paginated)](https://docs.ecca-ex.com/api-reference/get-api-v1-invoices.md): Returns a paginated list of invoices belonging to the authenticated merchant, optionally filtered by status / currency. Each item also includes deal-level info if the customer has already picked a payment method.
- [Get a single merchant invoice by order_id or external_id](https://docs.ecca-ex.com/api-reference/get-api-v1-invoices-invoice_ref.md): Returns a single invoice (and the linked deal, if any) belonging to the authenticated merchant.

`invoice_ref` accepts either:
- our internal `order_id` (UUID assigned by the platform), or
- the merchant's own `external_id` (whatever the merchant supplied at invoice creation).

Lookup is scoped to the authenticated merchant, so an `external_id` from another merchant cannot be retrieved. `order_id` is tried first; if no match is found, `external_id` is tried next.

Returns 404 if neither lookup matches.
- [Get webhook events history for an invoice](https://docs.ecca-ex.com/api-reference/get-api-v1-invoices-invoice_ref-webhooks.md): Returns the full webhook delivery history for a specific invoice — every event that was generated (e.g. `invoice.success`, `invoice.fail`, `invoice.expired`, `invoice.adjusted`) along with all delivery attempts the worker has performed (and any manual resends triggered via `POST /invoices/{invoice_ref}/webhooks/resend`).

`invoice_ref` accepts either:
- our internal `order_id` (UUID assigned by the platform), or
- the merchant's own `external_id` supplied at invoice creation.

Lookup is scoped to the authenticated merchant. Events are ordered by creation time, newest first; attempts within an event are ordered by `try_number` ascending. Returns `events: []` (with `events_count=0`) if no webhooks have been generated for this invoice yet — this is a valid 200 response, not a 404.
- [Manually resend the latest webhook for an invoice](https://docs.ecca-ex.com/api-reference/post-api-v1-invoices-invoice_ref-webhooks-resend.md): Triggers an immediate delivery attempt for the **latest** webhook event of this invoice (regardless of its current status: `pending`, `success`, or `dead`). A new `WebhookEventAttempt` row with `trigger=manual` is recorded; the auto-retry schedule is not modified.

If the latest event is in the worker queue and currently being processed, the request is rejected with `WEBHOOK_RESEND_CONFLICT` (409) — try again in a few seconds.

A short cooldown is enforced between manual resends per event (default: 15s). On cooldown violation the response is `WEBHOOK_RESEND_COOLDOWN` (429) with `retry_after_sec` and `next_allowed_at` in the error meta.

`invoice_ref` accepts either our `order_id` (UUID) or the merchant's `external_id`. The response always echoes back our internal `order_id` and the new attempt's outcome (`ok`, `http_status`, `duration_ms`, `attempt_id`).
- [Get Merchant Currencies](https://docs.ecca-ex.com/api-reference/get-api-v1-currencies.md): No description found
- [List merchant withdrawals](https://docs.ecca-ex.com/api-reference/get-api-v1-withdrawals.md): Returns paginated list of merchant withdrawals with optional status filter.
- [Get Withdrawal](https://docs.ecca-ex.com/api-reference/get-api-v1-withdrawals-withdraw_uuid.md): No description found
- [Get Payment Methods](https://docs.ecca-ex.com/api-reference/get-api-v1-payment-methods.md): No description found

## Changelog

- [Ecca Docs Changelog](https://docs.ecca-ex.com/changelog.md): Release notes for updates to the Ecca documentation.