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

# Accept a payment

> Integrate Payzor into your backend and start accepting payments from AI agents, a complete walkthrough.

# Accept a payment

This is the full integration guide for businesses. At the end you'll have: charges flowing from your backend, agents paying them, webhooks confirming everything, and your money in a merchant balance.

## Prerequisites

* A console account on a Payzor deployment.
* Your merchant API key (`sk_mch_...`). If you don't have one, see [Quickstart step 1](/quickstart#1-register-your-business).

## Architecture

Your server never touches agent wallets directly. You create **charges**; Payzor moves money and tells you what happened via **webhooks**.

```text theme={null}
Your backend                Payzor                      Customer's agent
────────────                ──────                      ────────────────
POST /merchant/charges ───▶ charge (pending)
                            ◀────────────────────────── POST /charges/:id/pay
                            policy check → debit wallet
◀── webhook: payment.succeeded / charge.succeeded
GET /merchant/me ─────────▶ balance updated
```

## Step by step

### 1. Create the charge when it's time to bill

Wherever you'd normally ask for a card:

```bash theme={null}
curl -X POST https://your-payzor-host/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsdCents": 499,
    "description": "Pro plan - August",
    "externalId": "sub_42_invoice_8"
  }'
```

Store the returned `chargeId` against `externalId` in your database.

### 2. Give the agent something to pay with

The customer's agent needs to know *what* to pay. Common patterns:

* **Your API returns the pay URL.** Include `"/charges/<id>/pay"` in your API response where an agent would look.
* **Your docs tell agent developers** to wire `POST /charges/:id/pay` into their tool loop.

The agent calls it with its own key; Payzor enforces its policy. You do nothing else.

### 3. Handle the outcomes

| Agent receives                          | Meaning                      | What you should do                                     |
| --------------------------------------- | ---------------------------- | ------------------------------------------------------ |
| `{ paid: true, ... }`                   | Settled                      | Nothing, webhook will confirm.                         |
| `{ pendingApproval: true, approvalId }` | Waiting for the human        | Wait; if approved you'll get `payment.succeeded`.      |
| `{ error: "..." }`                      | Blocked by policy or balance | Let the agent decide (retry later, downgrade plan...). |

### 4. Verify it landed

Poll `GET /merchant/me` in dev. In production, rely on webhooks ([guide](/guides/webhooks)).

## Reconciliation

Every settled charge carries:

* `chargeId`: yours to store,
* `reference`: matches the entry in the agent's audit trail,
* `agentId`: who paid.

For bookkeeping exports, the console user can download `GET /export/transactions.csv`; every fact with sequence number and chain hash.

## Checklist before going live

<Checklist>
  <ChecklistItem>
    Webhook endpoint registered and signature verification implemented.
  </ChecklistItem>

  <ChecklistItem>
    Payout address set (`PUT /merchant/payout-address`); it passes KYT screening automatically.
  </ChecklistItem>

  <ChecklistItem>
    `externalId` stored for every charge so your invoices reconcile.
  </ChecklistItem>

  <ChecklistItem>
    Idempotent handling of duplicate webhooks (they can retry).
  </ChecklistItem>
</Checklist>