# Core concepts

The things you work with in Weav, what each one is for, and how they connect. Read this first, then [How payments work](https://docs.weavpayments.com/how-payments-work) for who does what in a payment.

```mermaid
flowchart TD
    CK[Checkout] -->|makes one or more| PY[Payment]
    PM[Payment method<br/>a saved card] -->|makes| PY
    CH[Channel] -.->|each payment uses one| PY
    PY -->|paid, less Weav's fee| BL[Balance]
    RF[Refunds and chargebacks] -->|come off| BL
    BL -->|you withdraw| WD[Withdrawal]
    WD --> BK[Your bank account]
```

Every change to a checkout, payment, payment method or withdrawal also reaches your server as a [webhook](#webhooks).

## Payment

One try to collect money from your customer, on one channel. Its ID starts with `PY`.

- You create it with [POST /v1/payments](https://docs.weavpayments.com/reference/payments/create-payment), on a channel or with a saved card. Weav also creates one for each channel your customer tries in a checkout.
- It starts `PENDING`, then becomes `COMPLETED`, `FAILED` or `CANCELLED`. A paid payment can later be refunded or reversed. See [Statuses](https://docs.weavpayments.com/statuses#payment).
- Once it's paid, the amount goes to your balance, less Weav's fee.
- Your `external_reference_id` (your order number, for example) ties it to your system and makes retries safe. See [Idempotency](https://docs.weavpayments.com/idempotency).

## Checkout

One link for one order, where your customer chooses how to pay. Its ID starts with `CK`.

- You create it with [POST /v1/checkouts](https://docs.weavpayments.com/reference/checkouts/create-checkout) and send your customer to its `checkout_url`.
- Each channel your customer tries is a payment, with `checkout_reference_id` set. The first payment that's paid completes the checkout.
- Use a checkout when you don't want to choose the channel yourself. Create a payment when you do.

## Channel

How your customer pays: QR Ph, GCash, Maya, a card, or cash at Pay & Go, PalawanPay or Bayad. Each payment uses one.

- Each channel asks your customer for something different: a QR code to scan, a page to pay on, or a code to bring to a counter. That's the payment's `next_action`. See [Channels](https://docs.weavpayments.com/channels).
- [GET /v1/channels](https://docs.weavpayments.com/reference/channels/list-channels) shows which channels your account can use right now, and your payment limits.

## Payment method

A card your customer saved, so you can charge it later without them there. Its ID starts with `PM`.

- Your customer saves it on a Weav page, on its own or while they pay. Card numbers never reach your systems.
- Each charge is a new payment: send its `payment_method_id` to [POST /v1/payments](https://docs.weavpayments.com/reference/payments/create-payment).
- It's `PENDING` until their bank confirms it, then `ACTIVE`. See [Saved cards](https://docs.weavpayments.com/saved-cards) and [Subscriptions](https://docs.weavpayments.com/subscriptions).

## Balance

The money Weav holds for you.

- Paid payments add to it, less Weav's fee. Refunds, chargebacks and withdrawals take from it.
- [GET /v1/balance](https://docs.weavpayments.com/reference/balance/get-balance) gives `available` (what you can withdraw) and `on_hold` (withdrawals on their way to your bank).
- Every change is a [ledger entry](https://docs.weavpayments.com/reference/balance/list-ledger-entries), with the balance after it. An entry never changes: a correction is a new entry.

## Withdrawal

Money from your balance to your bank account, by InstaPay or PESONet. Its ID starts with `WD`.

- You withdraw in the dashboard, because each one needs a code from a person's authenticator app. Or turn on automatic withdrawals there: once a day, Weav withdraws your available balance.
- The amount leaves your balance when you ask. If the withdrawal fails, it comes back.
- The API reads withdrawals: [GET /v1/withdrawals](https://docs.weavpayments.com/reference/withdrawals/list-withdrawals). See [Statuses](https://docs.weavpayments.com/statuses#withdrawal).

## Webhooks

Weav tells your server when something changes, with a signed `POST` to your webhook URL.

- Set the URL with [PUT /v1/webhook-endpoint](https://docs.weavpayments.com/reference/webhooks/set-webhook-endpoint).
- Events are named after what changed: `PAYMENT_*`, `CHECKOUT_*`, `PAYMENT_METHOD_*` and `WITHDRAWAL_*`. See [Event types](https://docs.weavpayments.com/webhooks/event-types).
- Check each signature before you trust it. See [Verifying signatures](https://docs.weavpayments.com/webhooks/verifying-signatures).
- Act on webhooks, not on where your customer's browser lands: landing on your `success_url` doesn't prove they paid.

## Test and live

Everything above exists in test mode and in live mode, apart from each other. Your API key's prefix decides which one you see: `wv_test_` or `wv_live_`. See [Test mode](https://docs.weavpayments.com/test-mode).