Skip to main content

Payment reports

Two read-only calls let your server, or an AI agent, read your approvals and declines without signing in to the dashboard:

CallUse it for
GET /v1/payment_intentsThe payments themselves: one item per payment intent, with filters.
GET /v1/payment_intents/summaryCounts, 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 429 with Retry-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, and created[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.

FilterKeeps
statusPayments with one of these statuses.
outcomePayments 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_codeFailed payments with one of these decline codes.
card_brandvisa, mastercard, amex, discover, unionpay, jcb, diners or unknown.
currencyOne ISO 4217 currency.
initiatormerchant for charges you start on a saved card (for example renewals), customer for every other payment.
storePayments 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:

  1. The store order's attribution.
  2. Its attribution pass-through fields.
  3. Its order metadata.
  4. The payment's own metadata.
  5. 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 as session_id, checkout_type and mirror, and keys whose name suggests personal data, such as email, customer_name, phone, address and ip. Since 2 November 2026, a query with such a key, or with a value over 128 characters, answers 400.

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 of hour, day, week, store, metadata, card_brand, currency, outcome and decline_code, with at most one time unit. metadata also needs group_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 as null. Leave group_by out for one total.
  • time_zone sets where hours, days and weeks start (weeks start on Monday). The default is UTC.
  • Filters are the list's, without status: use outcome.

The answer has totals and, when grouped, groups. Each has:

PartWhat it holds
countsattempts, approved, declined, decisioned, and one count per outcome.
ratesapproval_rate, bank_decline_rate and decline_rate, as fractions from 0 to 1. null when there was no traffic: never read null as 0%.
amountsPer currency, in minor units: approved and declined. Never added across currencies.
RateIs
approval_rateapproved ÷ attempts
bank_decline_ratebank_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 attempts can 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.

outcomeMeans
approvedThe payment was taken.
bank_declinedThe card's bank refused it.
merchant_rule_blockedOne of your own rules refused it. No bank was asked.
refused_before_bankThe processor or the routing refused it before any bank was asked.
request_rejectedThe payment provider refused the request. No bank was asked.
authentication_failedThe bank's security check did not pass. No charge was sent.
authentication_not_completedThe shopper did not finish the bank's security check.
abandonedFailed with no reason recorded, for example the shopper left.
provider_unavailableThe payment provider did not answer.
system_errorA fault on our side.
unclassifiedFailed with a reason not classified yet.
authorizedApproved as a hold that is not captured yet.
in_progressWaiting for the shopper or the bank.
voidedEnded with no money taken.

From the SDKs, the CLI and an AI agent​

ToolListSummary
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_intentsvonpay_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​

AnswerMeansWhat to do
400 validation_errorA parameter was refused. param names it as you sent it.Fix that parameter as selfHeal.llmHint says.
422 report_too_largeValid, 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_exceededA limit above, or another report request still running.Wait Retry-After seconds, then send the same request.
503 service_unavailableThe reporting database could not answer just now.Wait Retry-After seconds and send the same request again.