Quickstart

Create an account in the console, then take a payment end to end with the API. Only the money is test funds.

1. Create a business account

You choose your business name and country; the country sets your default currency and payout destinations. New businesses start in sandbox and move to live once KYB is approved — see Sandbox & live.

2. Create an API key

Open API keys in the console and create one for the environment you want (owner or admin). The raw key is shown once.

Prefer to script it? The same call, with a console session token and org id:

curl -s https://api.fluense.social/apikeys \
  -H "authorization: Bearer $SESSION" \
  -H 'content-type: application/json' \
  -d '{"org_id":"'$ORG'","env":"sandbox","name":"server"}'

{ "key": "fl_test_…", "id": "019a…", "prefix": "fl_test_ab12" }

3. Create a terminal

A terminal is a point of sale identified by its terminal id — encode it however your shoppers can read it: a QR code, an NFC tag, a deep link.

curl -s https://api.fluense.social/terminals \
  -H "authorization: Bearer $SESSION" \
  -H 'content-type: application/json' \
  -d '{"title":"Front counter"}'

{ "id": "019a…" }

4. Create a checkout

curl -s https://api.fluense.social/checkouts \
  -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{
    "terminal_id": "'$TERMINAL'",
    "currency": "USD",
    "items": [{"product_id":"sku-1","display_name":"Desk lamp","unit_price":8900,"qty":1,"cashback_rate":500}],
    "tax_amount": 800,
    "total": 9700,
    "order_id": "order-1001"
  }'

{ "id": "019a…", "terminal_id": "019a…" }

total must equal sum(unit_price x qty) + shipping_amount + tax_amount. Creating a checkout on a reusable terminal supersedes its previous pending checkout.

5. The shopper authorizes

The shopper reads the terminal (QR scan, NFC tap or pay link) and confirms in the Fluense app. This is a consumer session call, not yours:

POST /checkouts/{id}/authorize      # consumer session

{ "auth_id": "019a…" }

This places a 7-day hold. No money has moved yet.

6. Capture the charge

curl -s -X POST https://api.fluense.social/charges/$AUTH/capture \
  -H "x-api-key: $KEY"

{
  "journal_id": "019a…",
  "mdr_fee": 154,
  "buyer_amount": 0,
  "deferred_buyer_amount": 225,
  "recommender_amount": 75,
  "recommender_id": null,
  "recommenders": []
}

Capture is idempotent: retrying the same charge returns the same transaction reference and cashback. See Charges.

7. Receive webhooks

curl -s -X PUT https://api.fluense.social/orgs/$ORG/webhook \
  -H "authorization: Bearer $SESSION" \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/fluense/webhook"}'

{ "url": "https://example.com/fluense/webhook", "secret": "whsec_…" }

Verify x-fluense-signature on every delivery. See Webhooks.