Weav Docsv1
Back to homeSupportGet API keys

API reference / Payments

List payments

View as Markdown
More actions
Open in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in GrokAsk questions about this pageConnect to CursorInstall the MCP server in CursorConnect to VS CodeInstall the MCP server in VS Code
GET/v1/payments

Newest first. Filter by status, channel, your reference or creation date.

Uses cursor pagination. Each item is a full payment object; the example response leaves some fields out to keep it short.

Query parameters

  • per_pageinteger
    Items per page, 25 by default; values above 100 become 100.
    At least 1Default: 25
  • cursorstring
    The next_cursor or prev_cursor from the previous page.
    Up to 1024 characters
  • date_fromstring (date)
    Start date (Asia/Manila), inclusive. Send with date_to.
  • date_tostring (date)
    End date (Asia/Manila), inclusive.
  • statusstring
    Only payments with this status.
    One of: PENDING COMPLETED FAILED CANCELLED REVERSED REFUNDED
  • channelstring
    Only payments on this channel.
    One of: QR_PH GCASH MAYA CARD PAY_AND_GO PALAWANPAY BAYAD
  • external_reference_idstring
    Your own order or invoice reference, exact match.
    Up to 64 characters
  • referencestring
    Exact match on reference_id, provider_reference_id or channel_reference_id, or a number in references (for example the QR Ph invoice number your customer gives you). A number in references can match more than one payment.
    Up to 64 characters
  • payment_method_idstring
    Only the payments charged to this saved payment method, or saving it. A subscription's history.
    Up to 32 characters

Headers

  • AuthorizationstringRequired
    Bearer plus your API key. See Authentication.

Responses

200 OK

A page of payments.

What data holds
  • paymentsarray of objectsRequired
    32 fields in payments
    • reference_idstring
    • external_reference_idstring | null
      Yours. For a checkout's payment, the checkout's (null when it has none).
    • checkout_reference_idstring | null
      The checkout this payment was started from, if any.
    • payment_method_idstring | null
      The saved payment method it was charged to, or the one it saves the card to (save_payment_method), if any.
    • provider_reference_idstring | null
      The provider's transaction ID, once the provider has one.
    • channel_reference_idstring | null
      A reference from the channel that is unique to this payment, once the payment completes. Null for channels whose numbers can repeat; those are in references.
    • referencesobject
      The provider's other numbers for this payment, keyed by type: invoice_number (the 6-digit QR Ph invoice number), receipt_number (Maya) or transaction_id (GCash). Saved once the provider confirms the payment; {} until then. They can repeat across payments: search with them, never identify a payment by one alone.
      3 fields in references
      • invoice_numberstring
      • receipt_numberstring
      • transaction_idstring
    • channelstring
      One of QR_PH, GCASH, MAYA, CARD, PAY_AND_GO, PALAWANPAY, BAYAD.
      One of: QR_PH GCASH MAYA CARD PAY_AND_GO PALAWANPAY BAYAD
    • customerobject
      The person paying, as you sent it. The email and mobile number turn null once Weav's retention period ends.
      3 fields in customer
      • namestring | null
      • emailstring | null
      • mobile_nostring | null
    • currencystring
      ISO 4217. PHP today; more as they're enabled for your account.
      One of: PHP
    • amountnumber
    • feenumber | null
      Null until a rate applies.
    • totalnumber | null
      amount plus fee, calculated by Weav. Null while fee is null.
    • fee_bearerstring
      MERCHANT, the fee comes out of amount (default). PAYER (fees on top), the customer is charged amount + fee and you receive the full amount.
      One of: MERCHANT PAYER
    • amount_chargednumber
      What the customer is charged. amount, or total when fee_bearer is PAYER.
    • amount_refundednumber
      The total refunded so far. The payment turns REFUNDED once it equals amount.
    • refundsarray of objects
      Refunds Weav recorded for this payment, oldest first. Refunds are made by Weav support on request.
      4 fields in refunds
      • reference_idstring
      • amountnumber
      • provider_reference_idstring | null
      • refunded_atstring (date-time)
    • statusstring
      PENDING, COMPLETED, FAILED, CANCELLED, REVERSED or REFUNDED. See Statuses.
      One of: PENDING COMPLETED FAILED CANCELLED REVERSED REFUNDED
    • descriptionstring | null
      As you sent it.
    • success_urlstring (uri) | null
    • cancel_urlstring (uri) | null
    • webhook_urlstring | null
      Where this payment's webhooks go, when not your webhook URL.
    • next_actionobject
      What your customer does next. type is DISPLAY_QR, REDIRECT, PAY_AT_COUNTER, or null once the payment is final. qr_string, checkout_url and payment_code are each null unless they apply. With HOSTED (the default), type is REDIRECT and checkout_url is Weav's payment page (the test checkout with a test key), for every channel. For QR Ph, qr_ph_app is the app you chose, and instructions lists the how-to-pay steps (title, description) when you asked for DIRECT.
      6 fields in next_action
      • typestring | null
        One of: DISPLAY_QR REDIRECT PAY_AT_COUNTER
      • qr_stringstring | null
        QR Ph payload to render as a QR code: error correction Q (M at minimum), a white quiet zone of at least 4 modules, and the full-color QR Ph symbol on a white box 23.81% of the code width (quiet zone excluded) in the exact center.
      • checkout_urlstring (uri) | null
      • payment_codestring | null
        For over-the-counter channels.
      • qr_ph_appstring | null
        QR Ph only. The bank or e-wallet app the steps are tailored to.
      • instructionsarray of objects | null
        QR Ph with next_action_format DIRECT only. How-to-pay steps to show the customer.
        2 fields in instructions
        • titlestring
        • descriptionstring
    • test_checkout_urlstring (uri) | null
      Test mode only: the test checkout page, where you pay, decline or let this payment expire, for every channel (a counter payment with DIRECT has no other way to finish). Anyone with the link can open it. Null in live mode.
    • failureobject | null
      code and message when the payment failed. Codes: EXPIRED, DECLINED, PROVIDER_ERROR.
      2 fields in failure
      • codestring
        One of: EXPIRED DECLINED PROVIDER_ERROR
      • messagestring
    • expires_atstring (date-time)
      When an unpaid payment fails (failure.code EXPIRED).
    • completed_atstring (date-time) | null
      When the customer paid, as the provider reports it.
    • failed_atstring (date-time) | null
      When the payment failed.
    • cancelled_atstring (date-time) | null
      When the payment was canceled.
    • reversed_atstring (date-time) | null
      When the payment was reversed.
    • created_atstring (date-time)
      When Weav created the payment.
    • updated_atstring (date-time)
      When the payment last changed.
  • paginationobjectRequired
    4 fields in pagination
    • per_pageintegerRequired
    • next_cursorstring | nullRequired
    • prev_cursorstring | nullRequired
    • is_last_pagebooleanRequired

401 Unauthorized

Missing, malformed or unknown API key (code 4010000).

403 Forbidden

The key can't make this request (code 4030000): an address outside the key's IP allowlist, a live key before your live mode is on, or an account that isn't active. A live key sent from a browser is refused (code 4030001): keep live keys on your server.

422 Unprocessable Content

One or more fields are invalid (code 4220000), or the channel is off (4220101) or doesn't take the currency (4220102).

429 Too Many Requests

Rate limited (code 4290000). Wait for Retry-After seconds.

GET

Try it: List payments

Test mode
Authorization
Query Optional
cURL
Uses $WEAV_API_KEY, never your key. Paste it into a terminal, or import it into Postman.
Response
Send the request to see Weav's answer here.
curl -X GET https://api.weavpayments.com/v1/payments \
    -H "Authorization: Bearer $WEAV_API_KEY"
{
    "code": "2000000",
    "success": true,
    "message": "OK",
    "data": {
        "payments": [
            {
                "reference_id": "PY7K3Q9M2X4TBA",
                "external_reference_id": "ORD-10541",
                "channel": "QR_PH",
                "currency": "PHP",
                "amount": 1250.0,
                "status": "COMPLETED",
                "completed_at": "2026-10-26T10:15:40+08:00",
                "created_at": "2026-10-26T10:12:00+08:00"
            }
        ],
        "pagination": {
            "per_page": 25,
            "next_cursor": "eyJpZCI6MTM0LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
            "prev_cursor": null,
            "is_last_page": false
        }
    }
}