> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reconlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Go from an API key to a reconciled payment in five steps.

This walkthrough takes you end-to-end through ReconLayer's core loop: tell ReconLayer what payment you expect (a **payment intent**), submit evidence of what actually happened (**provider evidence**), and read back the reconciliation outcome (a **reconciliation case**).

All examples use ReconLayer's public API base URL.

```
https://api.reconlayer.com
```

<Steps>
  <Step title="Get an API key">
    API keys are created from the dashboard by a signed-in user (or via [`POST /v1/api-keys`](/api-reference/integrations/create-an-api-key) with a Clerk session token — this endpoint requires a signed-in dashboard session, not another API key).

    ```bash theme={null}
    curl -X POST https://api.reconlayer.com/v1/api-keys \
      -H "Authorization: Bearer <clerk-session-token>" \
      -H "x-organization-id: org_acme" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Quickstart integration",
        "scopes": ["cases_action", "cases_view"]
      }'
    ```

    ```json 201 Created theme={null}
    {
      "id": "key_01J...",
      "organizationId": "org_acme",
      "name": "Quickstart integration",
      "prefix": "rl_live_AbCd1234",
      "scopes": ["cases_action", "cases_view"],
      "status": "active",
      "plaintextKey": "rl_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdefghijk",
      "createdByUserId": "user_01J...",
      "lastUsedAt": null,
      "expiresAt": null,
      "revokedAt": null,
      "metadata": {},
      "createdAt": "2026-06-15T12:00:00.000Z",
      "updatedAt": "2026-06-15T12:00:00.000Z"
    }
    ```

    <Warning>
      `plaintextKey` is returned **once**. Copy it now — ReconLayer stores only its hash and cannot show it again. If you lose it, revoke the key and create a new one.
    </Warning>

    Export it for the rest of this walkthrough:

    ```bash theme={null}
    export RECONLAYER_API_KEY="rl_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdefghijk"
    ```

    From here on, every request authenticates with this key alone — the API key resolves your organization, so you don't need `x-organization-id`. See [Authentication](/api-reference/authentication) for the full credential model.
  </Step>

  <Step title="Create a payment intent">
    A **payment intent** tells ReconLayer what you expect to happen for a transfer — the canonical "what should occur" record that evidence is later reconciled against.

    This is a write endpoint, so it requires an `Idempotency-Key` header. Generate a fresh UUID before your first attempt and reuse it on any retry — see [Idempotency](/api-reference/idempotency).

    ```bash theme={null}
    curl -X POST https://api.reconlayer.com/v1/payment-intents \
      -H "Authorization: Bearer $RECONLAYER_API_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "externalReference": "invoice-9182",
        "sourceAmount": "100.00",
        "sourceCurrency": "USD",
        "destinationAmount": "100.00",
        "destinationCurrency": "USDC",
        "beneficiaryAccount": "0xA1b2C3d4E5f6789012345678901234567890aBcD",
        "beneficiaryName": "Acme Vendor LLC",
        "paymentType": "stablecoin",
        "clientCompletedAt": "2026-06-15T12:00:00Z",
        "statusOnClientSide": "completed"
      }'
    ```

    ```json 201 Created theme={null}
    {
      "caseId": "case_01J...",
      "paymentIntentId": "pi_01J...",
      "externalReference": "invoice-9182",
      "status": "reconciling",
      "verdict": null,
      "outcome": "created"
    }
    ```

    Save `paymentIntentId` and `caseId` — you'll use them in the next steps.

    <Tip>
      `outcome` is `"created"` the first time ReconLayer sees this `externalReference`. If you retry with a *new* `Idempotency-Key` but the *same* `externalReference` and matching fields, ReconLayer returns the existing payment intent with `"outcome": "reused"` and a `200` instead of creating a duplicate. If the fields don't match, you get `409 payment_intent_conflict`. See [API Design Principles](/api-reference/design-principles#business-level-uniqueness).
    </Tip>

    Full reference: [`POST /v1/payment-intents`](/api-reference/payment-intents/create-or-reuse-a-payment-intent).
  </Step>

  <Step title="Submit provider evidence">
    Once a payment intent exists, submit **evidence** describing what actually happened on the rail — for example, a confirmed transfer reported by your provider. ReconLayer's matcher reconciles this evidence against the payment intent's expected legs.

    This is also a write endpoint and requires its own `Idempotency-Key`.

    ```bash theme={null}
    curl -X POST https://api.reconlayer.com/v1/evidence/provider \
      -H "Authorization: Bearer $RECONLAYER_API_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "paymentIntentId": "pi_01J...",
        "provider": "bridge",
        "integrationKey": "bridge_main",
        "sourceRef": "transfer_01J...",
        "externalReference": "invoice-9182",
        "phase": "destination",
        "status": "confirmed",
        "amount": {
          "amount": "100.00",
          "currency": "USDC"
        },
        "occurredAt": "2026-06-15T12:05:00Z",
        "payload": {
          "raw": "provider-specific payload, stored as-is"
        }
      }'
    ```

    ```json 201 Created theme={null}
    {
      "accepted": true,
      "duplicate": false,
      "flowLegIds": ["leg_01J..."],
      "matchedCaseIds": ["case_01J..."],
      "rawRecordId": "raw_01J...",
      "signatureValid": null,
      "source": "bridge",
      "sourceRef": "transfer_01J..."
    }
    ```

    `matchedCaseIds` tells you which reconciliation case(s) this evidence was matched against — in this walkthrough, the case created alongside your payment intent in step 2.

    Full reference: [`POST /v1/evidence/provider`](/api-reference/reconciliation-cases/submit-provider-evidence). For on-chain transfer evidence, see [`POST /v1/evidence/onchain`](/api-reference/reconciliation-cases/submit-on-chain-evidence).
  </Step>

  <Step title="Fetch the reconciliation case">
    Read back the reconciliation outcome using the `caseId` from step 2 (or a `matchedCaseId` from step 3 — they're the same case in this walkthrough).

    ```bash theme={null}
    curl https://api.reconlayer.com/v1/reconciliation-cases/case_01J... \
      -H "Authorization: Bearer $RECONLAYER_API_KEY"
    ```

    ```json 200 OK theme={null}
    {
      "id": "case_01J...",
      "organizationId": "org_acme",
      "status": "open",
      "reconciliationStatus": "reconciled",
      "externalReference": "invoice-9182",
      "verdict": "matched",
      "unexplainedDelta": "0.00",
      "slaAgeMinutes": 5,
      "slaRisk": false,
      "requiredLegsTotal": 1,
      "requiredLegsPresent": 1,
      "evidenceCoverage": {
        "expected": "1",
        "provider": "1",
        "chain": "0",
        "bank": "0",
        "file": "0"
      },
      "providerFee": null,
      "networkFee": null,
      "developerFee": null,
      "fxSpread": null,
      "roundingDelta": null,
      "notes": null,
      "reconciledAt": "2026-06-15T12:05:01.000Z",
      "lastRunAt": "2026-06-15T12:05:01.000Z",
      "paymentIntent": { "...": "PaymentIntent summary" },
      "flowLegs": [ { "...": "FlowLegSummary" } ],
      "auditEvents": [ { "...": "AuditEvent" } ]
    }
    ```

    `reconciliationStatus: "reconciled"` and `verdict: "matched"` confirm the evidence you submitted in step 3 satisfied the expectation created in step 2.

    If the amounts didn't line up, `reconciliationStatus` would be `"unreconciled"` and `unexplainedDelta` would carry the difference — that's an exception for your team (or automation) to investigate.

    Full reference: [`GET /v1/reconciliation-cases/{caseId}`](/api-reference/reconciliation-cases/get-reconciliation-case-detail). To list and filter cases in bulk, see [`GET /v1/reconciliation-cases`](/api-reference/reconciliation-cases/list-reconciliation-cases).
  </Step>
</Steps>

## What's next

* [API Design Principles](/api-reference/design-principles) — idempotency, business-level uniqueness, and route conventions in depth.
* [Idempotency](/api-reference/idempotency) — the `Idempotency-Key` contract used in steps 2 and 3.
* [Errors](/api-reference/errors) — what `400`/`404`/`409`/`429` responses look like and how to handle them.
* [Pagination](/api-reference/pagination) — listing payment intents and reconciliation cases at scale.
* [Rate limits](/api-reference/rate-limits) — request limits and backoff guidance.
* [Authentication](/api-reference/authentication) — the full credential and organization-resolution model.