# Quickstart

This guide takes you from zero to a successful sandbox payment using **hosted checkout** — the simplest integration path. Fynex hosts the card form; you redirect the customer and verify the result. Plan for about 5 minutes.

> [!NOTE]
> Examples use this environment's API, `https://api.fynex.ai`. Whether a payment is a test or real is decided by your **account**, not the host: a **Demo** account never moves real money. See [Going live](https://docs.fynex.ai/payments-api/v2/docs#tag/going-live) when you are ready for real payments.

## Prerequisites

- A seller API token — mint your own from the dashboard **Integration** page, or via the API (see [Authentication](https://docs.fynex.ai/payments-api/v2/docs#tag/authentication)).
- A seller account in **demo** mode. New accounts are created in `Demo` mode and activated automatically, so the sandbox calls below work right away. (If you ever get `403 seller account is not active`, the account isn't active — contact Fynex with your seller account ID. Going **live** for real-money payments requires KYB + a Fynex-assigned live terminal.)
- A terminal with `curl`.

## Step-by-step

1. **Get a token and configure your environment**

   Get your token yourself from the dashboard: log in to `https://dashboard.fynex.ai`, select your seller account, open the **Integration** page, reveal the token, and copy it (see [Authentication](https://docs.fynex.ai/payments-api/v2/docs#tag/authentication) for details). Then export it:

   ```bash
   export FYNEX_API="https://api.fynex.ai/payments-api/v1"
   export FYNEX_TOKEN="<the token you copied>"
   ```

2. **Create a hosted checkout session**

   Send a `POST /checkout` request with your order details. The `Idempotency-Key` header is mandatory — use a fresh UUID per request to prevent duplicate sessions.

```bash
curl -sS -X POST "$FYNEX_API/checkout" \
  -H "Authorization: Bearer $FYNEX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "externalOrderRef": "ORDER-DEMO-1",
    "amount": 19.99,
    "currencyCode": "GBP",
    "countryCode": "GB",
    "autoSettlement": true,
    "returnUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    }
  }'
```

   A `201 Created` response returns:

   ```json
   {
     "sessionId": "6f9b84e1-3b83-4fb9-9f42-a8ac27d11d6b",
     "checkoutUrl": "https://pay.fynex.ai/checkout/6f9b84e1-3b83-4fb9-9f42-a8ac27d11d6b",
     "expiresAt": "2026-04-29T11:30:00Z"
   }
   ```

   ### Request field reference

   | Field | Type | Required | Notes |
   |-------|------|----------|-------|
   | `externalOrderRef` | string | Yes | Your order ID — must be unique per seller |
   | `amount` | float | Yes | Major units (e.g., `19.99` for £19.99) |
   | `currencyCode` | string | Yes | 3-letter ISO code (e.g., `GBP`). Unsupported currencies may be rejected when the payment is processed. |
   | `countryCode` | string | No | 2-letter ISO code (e.g., `GB`) |
   | `autoSettlement` | bool | No | `true` to auto-capture; `false` for manual capture later |
   | `returnUrls.success` | string | Yes | Customer redirected here on success. The key is required; an empty string falls back to the seller's checkout settings, then the hosted checkout page |
   | `returnUrls.failure` | string | Yes | Customer redirected here on failure. The key is required; an empty string falls back to the seller's checkout settings, then the hosted checkout page |
   | `sellerMerchantName` | string | No | Displayed on the checkout page |
   | `logoUrl` | string | No | Merchant logo URL shown on the checkout page |
   | `locale` | string | No | Falls back to seller account locale, then `"en"` |
   | `description` | string | No | Order description shown to the customer |

3. **Redirect the customer to the checkout URL**

   Take `checkoutUrl` from the response and redirect the customer's browser to it:

   ```
   HTTP/1.1 302 Found
   Location: https://pay.fynex.ai/checkout/6f9b84e1-3b83-4fb9-9f42-a8ac27d11d6b
   ```

   Fynex hosts the card entry form. Your server stays out of PCI scope.

4. **Complete the payment with a test card**

   On the hosted checkout page, enter:

   - **Card number:** `4000 0000 0000 2701`
   - **Expiry:** any future month/year
   - **CVV:** any 3 digits

> [!NOTE]
> This is an authoritative frictionless-success card (a Mastercard equivalent also exists) — it authenticates without a challenge and
> reaches `lifecycleStatus` `captured`. For declines, 3DS challenges, and other specific outcomes, see
> [Test cards & sandbox](https://docs.fynex.ai/payments-api/v2/docs#tag/test-cards).

   Submit the form. The page will redirect to `returnUrls.success` on completion, or `returnUrls.failure` if the payment fails.

5. **Verify the result**

   Fynex delivers a `PaymentCompleted` webhook to the webhook URL(s) configured on your seller account (your receiver must return HTTP 200), and you can also poll for the payment status as a backstop. The simplest polling path for server-to-server backends is `GET /payments-api/v1/payments/{externalOrderRef}` — same bearer token you already have, returning the payment's `lifecycleStatus`, amount, currency, payment method, timestamps, and any seller-safe failure summary. For browser/dashboard contexts the GraphQL `genericPayment` query or the SSE stream are also available. See the [Polling & SSE guide](https://docs.fynex.ai/payments-api/v2/docs#tag/polling-sse) for the full verification pattern.

## What just happened

- Fynex created a draft payment tied to your seller account, returned a hosted page URL, and collected card details on its own domain — your integration never touches raw card data.
- `autoSettlement: true` means the payment was automatically captured when the card was charged. Set it to `false` if you want to capture manually later (see [Captures & Refunds](https://docs.fynex.ai/payments-api/v2/docs#tag/captures-refunds)).
- The `Idempotency-Key` you sent guarantees that retrying the same request (e.g., after a network timeout) returns the **same session** instead of creating a duplicate.

## See also

- **[Authentication & Tokens](https://docs.fynex.ai/payments-api/v2/docs#tag/authentication)** — How tokens work, how to rotate them, and what to do if one leaks.
- **[Hosted Checkout](https://docs.fynex.ai/payments-api/v2/docs#tag/hosted-checkout)** — Full hosted checkout reference — optional fields, return URL handling, and more.
- **[Polling & SSE](https://docs.fynex.ai/payments-api/v2/docs#tag/polling-sse)** — How to verify payment status without webhooks.
- **[Payment methods](https://docs.fynex.ai/payments-api/v2/docs#tag/payment-methods)** — Discover what payment methods are enabled on your account.