Core concepts

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]

Payment

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

• You create it with POST /v1/payments, 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.
• 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.

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 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.
• GET /v1/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.
• It’s PENDING until their bank confirms it, then ACTIVE. See Saved cards and 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 gives available (what you can withdraw) and on_hold (withdrawals on their way to your bank).
• Every change is a ledger entry, 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. See Statuses.

Webhooks

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

• Set the URL with PUT /v1/webhook-endpoint.
• Events are named after what changed: PAYMENT_*, CHECKOUT_*, PAYMENT_METHOD_* and WITHDRAWAL_*. See Event types.
• Check each signature before you trust it. See 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.