Create a checkout

How it works

• Your customer chooses a channel. Weav starts a payment on it for the checkout’s total, the same as a payment you’d create yourself, with checkout_reference_id set. You get its PAYMENT_* webhooks as usual.
• QR Ph also shows as each bank and e-wallet app that pays it (UnionBank, BDO Pay, GrabPay and more), because many customers know their app better than QR Ph. Choosing one makes a QR Ph payment with qr_ph_app set: the page shows that app’s logo, colors and steps. Any QR Ph app can still pay it.
• They can change their mind: choosing another channel cancels the payment in progress (you get PAYMENT_CANCELLED) and starts a new one.
• When you pay the fee, every channel shows the same total. When your customer pays it (fees on top), each channel shows its own total, fee included.
• The first payment paid completes the checkout: status becomes COMPLETED, payment is that payment, and you get CHECKOUT_COMPLETED.
• Rarely, a customer pays a QR code and then pays again another way. The second payment is real money: it’s credited like any payment, and Weav refunds it with you.
• A checkout that runs out unpaid becomes EXPIRED (CHECKOUT_EXPIRED). A payment still in progress, such as a counter code good for 48 hours, keeps it open until that payment ends. If it’s paid, the checkout completes.

sequenceDiagram
    autonumber
    actor Customer as Your customer
    participant Server as Your server
    participant Weav
    Server->>Weav: POST /v1/checkouts
    Weav-->>Server: 201 OPEN, checkout_url
    Server-->>Customer: Sends them to checkout_url
    Customer->>Weav: Chooses a channel
    Note over Weav: Starts a payment on it,<br/>with checkout_reference_id
    opt They choose another channel
        Weav->>Server: PAYMENT_CANCELLED webhook<br/>for the first payment
        Note over Weav: Starts a new payment
    end
    Customer->>Weav: Pays
    Weav->>Server: PAYMENT_COMPLETED and<br/>CHECKOUT_COMPLETED webhooks

Statuses

flowchart LR
    O[OPEN] --> C[COMPLETED]
    O --> E[EXPIRED]
    O --> X[CANCELLED]
    E -. paid late .-> C
    class O warn
    class C ok
    class E error
    class X neutral

Headers

• AuthorizationstringRequired
  Bearer plus your API key. See Authentication.
• Idempotency-Keystring
  Optional. A unique value per new checkout, such as a UUID. Retrying with the same key and body returns the stored response; a different body returns 409. Without it, your external_reference_id is the key (a checkout with neither is never matched to an earlier one).
  Up to 255 characters

Body

JSON, with Content-Type: application/json.

• itemsarray of objects | null
  An order, up to 50 items. Each has name (up to 255 characters), quantity (1 to 9,999) and unit_amount (pesos, a JSON number). Weav multiplies and adds them up; the total must be within your payment limits.
  Up to 50 items
  4 fields in items

  • namestringRequired
    Up to 255 characters
  • quantityintegerRequired
    At least 1At most 9999
  • unit_amountnumberRequired
    Pesos, as a JSON number.
  • amountnumber
    quantity × unit_amount.
• amountnumber | null
  Pesos. Within your payment limits.
• currencystring | null
  One of: PHP
• descriptionstring | null
  What it's for, up to 255 characters. Your customer sees it.
  Up to 255 characters
• external_reference_idstring | null
  Unique across your checkouts in this mode when given.
  Up to 64 characters
• channelsarray of strings | null
  Only these channels. Default every channel that's on.
  One of: QR_PH GCASH MAYA CARD PAY_AND_GO PALAWANPAY BAYAD
• qr_ph_appsarray of strings | null
  QR Ph only as these bank or e-wallet apps, for example a UnionBank link. Needs QR Ph among the channels.
  One of: BDO CHINABANK GOTYME LANDBANK METROBANK PNB RCBC ROBINSONS_BANK SECURITY_BANK UNIONBANK GRABPAY SHOPEEPAY
• save_payment_methodboolean | null
  If your customer pays by card, also saves the card for later charges (auto-debit). Send customer.id. They agree to future charges on Weav's payment page, and their bank's check for this payment also confirms the card. Another way to pay saves nothing: send channels: [CARD] to take cards only. The payment's payment_method_id is the saved card: you get PAYMENT_COMPLETED, then PAYMENT_METHOD_SAVED. If that payment isn't paid, the card isn't kept (PAYMENT_METHOD_FAILED). Off until Weav turns on saving cards for your account (422 4220401).
• customerobject | null
  All optional. With a name, your customer isn't asked for one; with an email, they get a receipt.
  4 fields in customer

  • idstring
    With save_payment_method only, and required then: your own ID for this customer. Their saved cards are listed by it (GET /v1/payment-methods?customer_id=).
    Up to 64 charactersPattern: ^[A-Za-z0-9._:@-]+$
  • namestring | null
    Up to 255 characters
  • emailstring (email) | null
  • mobile_nostring | null
• success_urlstring (uri) | null
• cancel_urlstring (uri) | null
  HTTPS. Where your customer goes if they leave, or the checkout expires or is canceled.
  Up to 2048 characters
• webhook_urlstring (uri) | null
• expires_in_minutesinteger | null
  How long it stays open, 5 to 10,080 (7 days). Default 1,440 (24 hours).
  At least 5At most 10080Default: 1440

Responses