# Fex Payments API

## Docs

- [Introduction](https://developer.fexpayments.com/Introduction.md)
- [Standard QR Flow - WebButton](https://developer.fexpayments.com/WebButton.md)
- [Get merchant transaction history](https://developer.fexpayments.com/api-reference/admin/get-merchant-transaction-history.md): Retrieve ledger transactions for the authenticated merchant. Accessible to `merchant` role users (scoped to their own `merchant_id` from the JWT) and `admin` role users (who must supply `?merchant_id=` to specify which merchant). Proxies to the internal ledger service.
- [Create counter (POS terminal)](https://developer.fexpayments.com/api-reference/counters/create-counter-pos-terminal.md): Create a new POS counter for the authenticated merchant. Returns Keycloak client credentials (`client_id` / `client_secret`) and a `webhook_secret` for HMAC signing — **these are shown only once, store them securely**. The counter's `client_id` can be used to obtain a machine token via Keycloak clie…
- [Deactivate counter](https://developer.fexpayments.com/api-reference/counters/deactivate-counter.md): Deactivate a counter. The associated Keycloak client credentials are revoked and no new payment intents can be created for this counter.
- [Get counter](https://developer.fexpayments.com/api-reference/counters/get-counter.md): Get details of a specific counter.
- [Initiate reverse QR payment (counter scan)](https://developer.fexpayments.com/api-reference/counters/initiate-reverse-qr-payment-counter-scan.md): Called by a POS terminal after scanning the user's QR code. Creates a payment intent with `status=pending_approval` targeted at the scanned user's wallet and publishes a `payment.approval_requested` NATS event so the user's mobile app can display the approval screen. **Requires a merchant JWT** (cli…
- [List counters](https://developer.fexpayments.com/api-reference/counters/list-counters.md): List all counters (POS terminals) for the authenticated merchant.
- [Rotate webhook secret](https://developer.fexpayments.com/api-reference/counters/rotate-webhook-secret.md): Generate a new HMAC signing secret for the counter's webhook. The old secret is immediately invalidated — update your webhook handler before calling this.
- [Update counter](https://developer.fexpayments.com/api-reference/counters/update-counter.md): Update counter name, location, or webhook URL.
- [Health check](https://developer.fexpayments.com/api-reference/health-check.md): Check if the service is running and healthy
- [Register a new merchant](https://developer.fexpayments.com/api-reference/onboarding/register-a-new-merchant.md): Creates a merchant account and provisions a Keycloak `client_credentials` client. Returns `client_id` and `client_secret` — **the secret is shown only once**. POS terminals authenticate using these credentials via Keycloak's token endpoint. **Requires platform admin JWT** (realm role `admin`).
- [Cancel payment intent](https://developer.fexpayments.com/api-reference/payment-intents/cancel-payment-intent.md): Cancel a pending payment intent. Only pending payments can be cancelled.
- [Create payment intent](https://developer.fexpayments.com/api-reference/payment-intents/create-payment-intent.md): Create a new payment intent with QR code for customer to scan and pay. `merchant_id` is taken from the JWT. POS terminals have a `counter_id` claim which will be associated with the intent.
- [Get payment intent](https://developer.fexpayments.com/api-reference/payment-intents/get-payment-intent.md): Get details of a specific payment intent (merchant view). Only returns intents belonging to the authenticated merchant.
- [List payment intents](https://developer.fexpayments.com/api-reference/payment-intents/list-payment-intents.md): Get a paginated list of payment intents for the authenticated merchant. `merchant_id` is taken from the JWT.
- [Refund payment](https://developer.fexpayments.com/api-reference/payment-intents/refund-payment.md): Issue a full refund for a completed payment intent. Only the merchant that received the payment can call this. The refund is published to the ledger as a `refund` transaction (debit merchant wallet, credit user wallet). Balance sync is asynchronous — the user's wallet balance updates within seconds…
- [Get payment intent (public)](https://developer.fexpayments.com/api-reference/public/get-payment-intent-public.md): Get payment intent details for QR code scan (no authentication required). Returns payment details for users who scan the QR code.
- [List merchants](https://developer.fexpayments.com/api-reference/public/list-merchants.md): Get a paginated list of all active merchants (public view — returns only ID and business name).
- [Cancellations & Refunds](https://developer.fexpayments.com/cancellations-and-refunds.md): Cancel pending intents and refund completed payments.
- [Counter Management](https://developer.fexpayments.com/counter-management.md): Create and manage POS counters and rotate webhook secrets.
- [Error Reference](https://developer.fexpayments.com/error-reference.md): HTTP error formats and common causes.
- [Generating an Access Token](https://developer.fexpayments.com/generating-an-access-token.md): Generate and refresh OAuth2 access tokens for FEX API calls.
- [Get Started with FEX Payments](https://developer.fexpayments.com/getting-started.md)
- [Getting Your Credentials](https://developer.fexpayments.com/getting-your-credentials.md): How merchants receive and store API credentials securely.
- [Overview](https://developer.fexpayments.com/overview.md)
- [Quick-Start Checklist](https://developer.fexpayments.com/quick-start-checklist.md): Pre-launch checklist for FEX merchant integrations.
- [Reverse QR Flow (Counter Scan)](https://developer.fexpayments.com/reverse-qr-flow-counter-scan.md): Counter scan flow where the POS scans the customer wallet QR.
- [Standard QR Flow](https://developer.fexpayments.com/standard-qr-flow.md): Merchant-initiated QR payment flow for POS terminals.
- [Transaction History](https://developer.fexpayments.com/transaction-history.md): Retrieve paginated merchant transaction history.
- [Webhooks](https://developer.fexpayments.com/webhooks.md): Webhook events, signatures, and delivery behavior.

## OpenAPI Specs

- [swagger](https://developer.fexpayments.com/swagger.json)
- [openapi](https://developer.fexpayments.com/api-reference/openapi.json)