> For the complete documentation index, see [llms.txt](https://refkit.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://refkit.gitbook.io/docs/integrate-refkit/manual-setup.md).

# Manual setup

Capture the affiliate landing request on your backend, then identify the Customer when they sign up.

## Before you start

In the dashboard, open **App > Integration > Manual setup** and add the displayed values to your server environment:

```env
REFKIT_API_URL=https://app.refkit.net
REFKIT_API_KEY=rk_test_app_...
```

Never expose `REFKIT_API_KEY` to browser code, logs, or committed files.

## 1. Capture the landing request

Affiliate links include a link code:

```
https://yourapp.com/pricing?via=alex
```

When `via` is present, call `POST /v1/capture` from the backend that receives the request:

```bash
curl https://app.refkit.net/v1/capture \
  -H "Authorization: Bearer $REFKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "via": "alex",
    "page": "https://yourapp.com/pricing?via=alex",
    "referrer": "https://search.example"
  }'
```

Response:

```json
{ "click_id": "clk_..." }
```

Store `click_id` in the existing secure session, first-party cookie, or database. It must still be available when the Customer signs up.

Authenticated server capture may also send `visitor_ip` and `visitor_user_agent`. Use the framework's trusted client-IP helper.

## 2. Identify the Customer

When the Customer account is created, call `POST /v1/identify` from the backend:

```bash
curl https://app.refkit.net/v1/identify \
  -H "Authorization: Bearer $REFKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "clk_...",
    "external_customer_id": "your-user-id",
    "email": "customer@example.com"
  }'
```

Use a stable `external_customer_id` from your application.

Ordinary integrations must send `click_id`. Direct `promotion_code` evidence is reserved for managed provider services using managed revenue credentials, and ordinary App API keys cannot use it. Managed providers must enable promotion-code fallback on the Program first. A valid click always wins when both inputs are supplied, and code attribution returns `click_id: null` rather than creating a synthetic click.

Response:

```json
{
  "customer_id": "rcus_...",
  "referral_id": "ref_...",
  "program_id": "prg_...",
  "click_id": "clk_...",
  "attribution_source": "click",
  "attributed": true,
  "stripe_metadata": {
    "refkit_click_id": "clk_...",
    "refkit_customer_id": "rcus_...",
    "refkit_program_id": "prg_..."
  }
}
```

## 3. Connect revenue

* Stripe Apps: [attach the returned Stripe metadata](/docs/integrate-refkit/stripe.md).
* API reporting Apps: [store `customer_id` and `program_id`, then report successful payments, renewals, refunds, and disputes](/docs/integrate-refkit/api-revenue.md). Keep combined refunds and active dispute exposure within the original payment.

## Browser fallback

If the landing request cannot run backend code, use `@refkitnet/sdk/browser` after any consent your App requires. Public browser capture does not use an API key and cannot accept visitor metadata from the body.

## Optional: outgoing events and payout automation

Configure one HTTPS endpoint under **App settings > Outgoing webhook** and select the lifecycle events your backend needs. Follow the [outgoing webhook guide](/docs/integrate-refkit/outgoing-webhooks.md) for the event catalog, payload, headers, and signature verification.

For external payout execution, subscribe to `payout.ready`. Use the execution ID from that event to call `GET /v1/payout-executions/:id` with a live API key scoped to the exact App. Report `succeeded` or `failed` with the same key and a unique `Idempotency-Key` header. RefKit records the result but never moves money.

## Verify

Follow [Test and go live](/docs/integrate-refkit/test-and-go-live.md). If a step does not complete, use [Troubleshooting](/docs/integrate-refkit/troubleshooting.md).