Quickstart

Take your first test payment with Fynex in 5 minutes using hosted checkout.

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 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).
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

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 for details). Then export it:

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

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.

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:

   {
     "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 |

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.

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.

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

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 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).
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.

Quickstart

Prerequisites

Step-by-step

What just happened

See also