Payment reports
Two read-only calls let your server, or an AI agent, read your approvals and declines without signing in to the dashboard:
| Call | Use it for |
|---|---|
GET /v1/payment_intents | The payments themselves: one item per payment intent, with filters. |
GET /v1/payment_intents/summary | Counts, amounts and approval and decline rates already computed, for one window, grouped if you want. |
Use the summary when you want rates. Its numbers come from the same query and definitions as your dashboard's decline report.
Keys and limits
- Use a read-only key. Create a restricted key with only
payment_intents.read. It cannot charge, refund or change anything, which makes it the right key for an agent. A full secret key works too. A publishable key is refused. - The key's mode decides what you see. A live key reads live payments only, a test key test payments only.
- Reports have their own limit: 120 requests a minute per key, separate from the allowance your charges and refunds use, and shared with the subscription product reads. Reporting never slows your payments. There is also a limit of 120 a minute for your whole account, all keys together, and 600 a minute from one IP address.
- One report request at a time per account, shared by the list and the summary. A second one while the first is running answers
429withRetry-After: 2. Page one request at a time. - The summary computes at most 30 answers a minute per account. A repeat of the same query within 45 seconds is answered from the cache and does not count.
On a 429, wait the Retry-After seconds, then send the same request again (rate limits).
The window
Both calls take created[gte] (inclusive) and created[lt] (exclusive), as Unix seconds or an ISO 8601 time with a zone. A date alone, or a time without a zone, is refused.
created[lt]defaults to now, andcreated[gte]to the longest window before it.- The list covers at most 31 days. The summary covers at most 31 days, or 7 days with
group_by=hour. A wider window is refused, never shortened: split it into smaller windows. Because the end is exclusive, consecutive windows never overlap. - Each answer repeats the window it covered in
created.
Both calls read a copy of the database that can be a few seconds behind. For one payment's state right after a charge, read GET /v1/payment_intents/{id}.
List payments
curl -G https://checkout.vonpay.com/v1/payment_intents \
-H "Authorization: Bearer $VON_PAY_READ_KEY" \
--data-urlencode "created[gte]=2026-10-01T00:00:00Z" \
--data-urlencode "created[lt]=2026-11-01T00:00:00Z" \
--data-urlencode "outcome=bank_declined" \
--data-urlencode "limit=100"
Filters. Send each one once. A list takes several values separated by commas, in one parameter.
| Filter | Keeps |
|---|---|
status | Payments with one of these statuses. |
outcome | Payments with one of these outcomes. For bank declines only, send outcome=bank_declined. For every failed attempt, list all the outcomes except approved, authorized, in_progress and voided. |
decline_code | Failed payments with one of these decline codes. |
card_brand | visa, mastercard, amex, discover, unionpay, jcb, diners or unknown. |
currency | One ISO 4217 currency. |
initiator | merchant for charges you start on a saved card (for example renewals), customer for every other payment. |
store | Payments whose store order went to this connected store's hostname. |
metadata[<key>]=<value> | One exact match on a field your integration or connected store sends with the payment. See The metadata filter. |
An unknown parameter is refused, not ignored. Generators that need plain names can send created_gte, created_lt, and metadata_key with metadata_value, instead of the bracket forms. Send one form of each, not both.
Paging. limit is 25 by default; above 100 counts as 100. While has_more is true, send the same request again with starting_after set to next_cursor. Keep every other parameter the same: the cursor works only with the request it came from.
Each item has the same fields as GET /v1/payment_intents/{id}, with card, processor_response and attempts, plus outcome, failure_class and store. It leaves out the buyer (buyer_id, buyer_email), the refund totals and the store order block in metadata. Each item still carries processor_response, which is untrusted text: drop it before you pass items to an AI model. It also has no late_money_outcome. Read one payment for those.
The list counts payment intents. A guest card payment taken through the embedded card form has no payment intent, so it is not listed. For an account that takes such payments, your own count from the list can be a little lower than the dashboard's and the summary's.
The metadata filter
metadata[<key>]=<value> reads a field the same way as the dashboard's decline report, so the two always agree. That includes fields that come from a connected store's order, not only the metadata you send. When a key is in more than one place, the first match wins, in this order:
- The store order's attribution.
- Its attribution pass-through fields.
- Its order metadata.
- The payment's own
metadata. - The checkout session's
metadata, for a payment taken through a checkout session.
- Key: 1 to 64 characters of letters, digits,
_,.,:and-. - Value: 1 to 128 characters, with no control characters. It is trimmed and compared case-sensitively. A stored number is compared as its text. A stored value that is empty, only spaces, longer than 128 characters, or not a string or a number never matches.
- Refused keys (
400 validation_error): keys the platform writes, such assession_id,checkout_typeandmirror, and keys whose name suggests personal data, such asemail,customer_name,phone,addressandip. Since 2 November 2026, a query with such a key, or with a value over 128 characters, answers400.
Results per connection
Each item's attempts lists every try of that payment on your payment connections, in order, with the connection, the result and the decline reason of each try (fields). To report approvals and declines per connection, count the items of attempts by processor_connection.id. Count only payments whose attempts_status is complete. These tries are not the attempts in the summary's counts, which count payments.
Summary
curl -G https://checkout.vonpay.com/v1/payment_intents/summary \
-H "Authorization: Bearer $VON_PAY_READ_KEY" \
--data-urlencode "created[gte]=2026-10-01T00:00:00Z" \
--data-urlencode "created[lt]=2026-11-01T00:00:00Z" \
--data-urlencode "group_by=day,store" \
--data-urlencode "time_zone=America/New_York"
group_by: up to 3 ofhour,day,week,store,metadata,card_brand,currency,outcomeanddecline_code, with at most one time unit.metadataalso needsgroup_by_metadata_key, the field whose values become groups. It reads the same places in the same order as the metadata filter, and refuses the same keys. A value that is empty, only spaces, not text or over 128 characters is grouped asnull. Leavegroup_byout for one total.time_zonesets where hours, days and weeks start (weeks start on Monday). The default isUTC.- Filters are the list's, without
status: useoutcome.
The answer has totals and, when grouped, groups. Each has:
| Part | What it holds |
|---|---|
counts | attempts, approved, declined, decisioned, and one count per outcome. |
rates | approval_rate, bank_decline_rate and decline_rate, as fractions from 0 to 1. null when there was no traffic: never read null as 0%. |
amounts | Per currency, in minor units: approved and declined. Never added across currencies. |
| Rate | Is |
|---|---|
approval_rate | approved ÷ attempts |
bank_decline_rate | bank_declined ÷ decisioned: the attempts minus those no bank was asked to decide (abandoned, a security check not finished or failed, your own rule, refused before the bank, a refused request) |
decline_rate | (declined − authentication_failed) ÷ (attempts − authentication_failed) |
- Groups list only the combinations that had an attempt. Fill empty buckets with zeros yourself. A time key is the bucket's start, in UTC.
- To combine groups or windows, add the counts and work the rate out again. Never average rates.
- The summary counts payment attempts, the dashboard's unit: guest card payments are included, and payments that are not attempts yet are left out. So its
attemptscan differ from the number of payments the list returns.
Outcomes
Each payment gets one outcome. The first eleven are attempts; the last three are not attempts yet.
outcome | Means |
|---|---|
approved | The payment was taken. |
bank_declined | The card's bank refused it. |
merchant_rule_blocked | One of your own rules refused it. No bank was asked. |
refused_before_bank | The processor or the routing refused it before any bank was asked. |
request_rejected | The payment provider refused the request. No bank was asked. |
authentication_failed | The bank's security check did not pass. No charge was sent. |
authentication_not_completed | The shopper did not finish the bank's security check. |
abandoned | Failed with no reason recorded, for example the shopper left. |
provider_unavailable | The payment provider did not answer. |
system_error | A fault on our side. |
unclassified | Failed with a reason not classified yet. |
authorized | Approved as a hold that is not captured yet. |
in_progress | Waiting for the shopper or the bank. |
voided | Ended with no money taken. |
From the SDKs, the CLI and an AI agent
| Tool | List | Summary |
|---|---|---|
Node SDK (@vonpay/checkout-node 4.5.0+) | paymentIntents.list(), listPages(), listAutoPaging() | paymentIntents.summary() |
Python SDK (vonpay-checkout 4.5.0+) | payment_intents.list(), list_pages(), list_auto_paging() | payment_intents.summary() |
CLI (@vonpay/checkout-cli 0.18.0+) | vonpay checkout payment-intents list (--all for every page) | vonpay checkout payment-intents summary |
MCP server (@vonpay/checkout-mcp 6.4.2+) | vonpay_checkout_list_payment_intents | vonpay_checkout_summarize_approvals |
The SDK pagers send one request at a time and resend exactly the first request plus the cursor, so they follow the paging rules above for you. See Node, Python, CLI and MCP server.
For a reporting agent, run the MCP server with VONPAY_MCP_TOOLS=read, so it has no tool that moves money, and give it a restricted key with only payment_intents.read.
Errors
| Answer | Means | What to do |
|---|---|---|
400 validation_error | A parameter was refused. param names it as you sent it. | Fix that parameter as selfHeal.llmHint says. |
422 report_too_large | Valid, but too big: the list took over 5 seconds, or the summary over 8 seconds or more than 2,000 groups. timeout_ms or max_groups says which. | Do not retry unchanged. Use a shorter window, more filters, fewer groups or a coarser time unit. |
429 rate_limit_exceeded | A limit above, or another report request still running. | Wait Retry-After seconds, then send the same request. |
503 service_unavailable | The reporting database could not answer just now. | Wait Retry-After seconds and send the same request again. |