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

# Overview

> Approve or decline every card transaction in real time from your own systems.

In an External-mode project you own the money decision on every card transaction. Reap calls your endpoint, you return an approve or decline, and Reap relays that decision to the card network. Your systems are the source of truth for the per-user balance, the risk decision, and the per-user ledger - Reap keeps no per-user balance of its own to authorize against.

Reap does not step out of the loop, though. It still enforces its program-wide guardrails on every transaction before and around your decision - card and account state, your spend policies and limits, fraud monitoring, card-network rules, and the [master collateral](/program-configuration/funding-models#program-funded) that backs the program - any of which can decline a transaction regardless of your answer. See [Division of responsibility](#division-of-responsibility).

<Note>
  Applies to [Program-Funded](/program-configuration/funding-models#program-funded) projects using **External** [authorization mode](/program-configuration/authorization-mode). In Managed mode Reap authorizes against the balances you allocate, and these pages do not apply.
</Note>

## Division of responsibility

External authorization is a split contract. Reap still runs the deterministic, program-wide guardrails; you own the money decision.

| Concern                                                                                    | Who decides                                                                     |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Card and account status (frozen, blocked, closed)                                          | **Reap** - declined locally before you are called                               |
| [Spend policies](/spend-policies/overview) and platform limits                             | **Reap** - declined locally before you are called                               |
| Card-network (Visa) rules                                                                  | **Reap and the card network** - can decline independent of your answer          |
| Fraud monitoring                                                                           | **Reap** - can decline a suspected-fraud transaction independent of your answer |
| Per-cardholder balance and your own risk / controls                                        | **You** - via the authorization request                                         |
| [Master collateral](/program-configuration/funding-models#program-funded) covers the spend | **Reap** - checked after you approve                                            |
| Relaying the final outcome to the card network                                             | **Reap**                                                                        |

Reap runs its deterministic guardrails - card state, spend policies, and limits - before it calls you, so your endpoint is only asked about transactions that have already passed them; you never see one Reap has already declined. Card-network rules and fraud monitoring apply on top and can decline a transaction independent of your answer, including before your endpoint is ever called. That leaves your endpoint exactly one question: given the transaction in front of you, does the cardholder have the balance and do your own controls allow it?

## How it works

```mermaid theme={null}
sequenceDiagram
    participant Network as Card network
    participant Reap
    participant You as Your endpoint
    Network->>Reap: Authorization request
    Reap->>Reap: Local checks (card and account status, spend policies, limits)
    Reap->>You: CARD_AUTHORIZATION_REQUEST
    You-->>Reap: Approve or decline (within 1.6s)
    Reap->>Reap: Master collateral check
    Reap-->>Network: Approved or declined
    Note over Network,You: If approved, the async transaction lifecycle begins
    Reap->>You: CARD_TRANSACTION_CREATED, then UPDATED ...
```

## The authorization flow

<Steps>
  <Step title="A cardholder pays">
    The cardholder taps, swipes, or enters their card. The card network routes an authorization request to Reap through the card processor.
  </Step>

  <Step title="Reap runs its local checks">
    Reap validates card and account status, evaluates your [spend policies](/spend-policies/overview), and applies platform limits. Anything that fails is declined locally with a [decline reason](/transactions/decline-reasons) and never reaches you.
  </Step>

  <Step title="Reap calls your endpoint">
    Reap sends a signed [`CARD_AUTHORIZATION_REQUEST`](/transactions/external-authorization/authorization-request) as an HTTPS `POST` to your registered endpoint, carrying the card, amount, and merchant details.
  </Step>

  <Step title="You make the decision">
    Check your own ledger balance and risk controls, then return `APPROVE` or `DECLINE` within **1.6 seconds**. See [Handling requests](/transactions/external-authorization/handling-requests) for the response contract and latency budget.
  </Step>

  <Step title="Reap confirms collateral">
    If you approve, Reap verifies your [master collateral account](/program-configuration/funding-models#program-funded) covers the spend. In the rare case it does not, Reap declines regardless of your approval.
  </Step>

  <Step title="Reap relays the outcome">
    Reap forwards the approve or decline to the card network, which releases the goods or declines at the terminal.
  </Step>

  <Step title="Reap notifies you asynchronously">
    If the transaction was approved, the [transaction lifecycle](/transactions/lifecycle) begins: a `CARD_TRANSACTION_CREATED` webhook, then `CARD_TRANSACTION_UPDATED` for each clearing, reversal, or refund. These are the durable record you [reconcile your ledger](/transactions/external-authorization/reconciliation) against - the authorization request is the live decision, not the record.
  </Step>
</Steps>

## Next

<CardGroup cols={2}>
  <Card title="The authorization request" icon="webhook" href="/transactions/external-authorization/authorization-request">
    The request and response contract: envelope, payload, decline reasons, timeout, and fail-closed behavior.
  </Card>

  <Card title="Handling requests" icon="bolt" href="/transactions/external-authorization/handling-requests">
    Build an endpoint that stays fast, verifies signatures, and dedupes safely on the authorization hot path.
  </Card>

  <Card title="Keeping your ledger in sync" icon="scale" href="/transactions/external-authorization/reconciliation">
    Reconcile holds, clearings, reversals, and refunds against the async transaction lifecycle.
  </Card>

  <Card title="Setup and testing" icon="plug" href="/transactions/external-authorization/setup">
    Register your authorization endpoint and exercise it end to end in sandbox.
  </Card>
</CardGroup>