Build a Provider Capability Matrix Before Writing Payment Code

Build a payment API capability matrix around the operations your application needs. For each operation, record the documentation, availability conditions, test evidence and decision. Keep documented support separate from tested behavior: a feature label such as “refunds” leaves too many implementation questions unanswered.

Can this account perform the operation with this payment method, in this region, using this API version? Record each unanswered question and assign an owner before it becomes an assumption in the code.

Define the operations before comparing providers

Write requirements as actions you can observe: authorize a card payment and capture it after fulfillment; refund part of a completed payment; respond to a subscription ending; or request an in-person checkout and record its outcome. Mark which actions the first release requires and what result would satisfy each one.

For each action, identify the starting record, expected state change and reference your application must retain. “Support recurring payments” might mean receiving a subscription cancellation event and updating access. Creating a subscription or storing a payment method would need separate requirements.

Stripe describes a PaymentIntent as tracking a payment through its lifecycle. Use that document for payment-state requirements. Subscription events and terminal checkout cross other API or product boundaries and need their own rows.

Record the conditions that determine availability

Use the five columns below and keep a supporting record for each row: exact operation or endpoint, document section, date checked, API and SDK versions, webhook version where applicable, account role, environment, country, currency, payment method and open questions. Mark unconfirmed values as unknown.

Record the versions your integration selects. Stripe’s versioning reference covers request versions and webhook endpoint versions. Square’s versioning guide explains the application default and Square-Version override. A version shown on a documentation page does not tell you how your account is configured.

The matrix below uses provider documentation checked on October 31, 2026. These are proposed requirements; every test is not yet tested. Account eligibility, selected versions and target regions remain unconfirmed. The rows cover different operations and do not establish equivalent features or rank providers.

Read the conditions behind each row

For authorization and capture, Stripe’s hold guide limits separate capture to eligible payment methods and requires capture before expiry. It identifies ACH and iDEAL as methods that do not support separate authorization and capture. Record that boundary instead of marking every method supported because a capture API exists.

For refunds, Stripe’s refund guide distinguishes refunding a successful payment from canceling an uncaptured PaymentIntent. A completed-payment refund test cannot establish that the same action works for an uncaptured authorization. Keep the source state in the acceptance criteria.

For recurring events, Stripe’s subscription webhook guide documents asynchronous subscription activity and events including customer.subscription.deleted. Identify the business record that should change when that event arrives. A document describing an event does not prove that your destination receives it or your application handles it correctly.

For terminal checkout, Square’s Terminal API overview describes pairing a custom POS with Square Terminal, then requesting checkout. It also describes regional feature limits and Sandbox tests without hardware interactions. Keep software checkout evidence and physical device evidence separate. This is a Square workflow, not a Roots product specification. Roots Payments is an independent Square Reseller.

Apply these states to the operation and conditions recorded in each row:

• Supported: the documentation explicitly covers the exact operation and all recorded availability conditions have been confirmed. Keep the test result separate; supported does not mean tested.
• Conditional: documentation covers the operation, but a named condition such as method eligibility, account setup or device availability still needs confirmation.
• Unknown: evidence is missing, conflicting or too broad to answer the requirement. An absent search result is not proof of unavailability.
• Unavailable: an authoritative source explicitly rules out the operation for the recorded scope. For example, the Stripe hold guide rules out separate authorization and capture for ACH; do not extend that conclusion to every Stripe payment method.

Choose one narrow verification and retain the result

Once the conditions are clear enough to test, choose the smallest documented test that answers the row’s question. Stripe’s testing guide describes sandboxes and test values; Square’s Terminal overview covers Sandbox checkout testing. Use the applicable test environment. No production payment execution is needed for this worksheet.

Before running anything, write the expected starting state, action, resulting state and evidence to save. For authorization and capture, distinguish authorization from capture in the expected record. For refunds, specify whether the source payment is completed. For recurring events, identify the application transition. For terminal checkout, name whether the question concerns a Sandbox checkout status or physical device behavior.

Save the actual environment, selected versions, timestamp, sanitized request or event reference, observed result and test owner. If the result differs from the documented expectation, record the discrepancy and assign an investigation. Keep the decision open until it is resolved.

Make unresolved decisions visible to an owner

Give each open row an owner, a precise question and a next action. Replace “ask provider” with an answerable request: “Provider liaison: confirm whether our seller country and proposed payment method support this Terminal checkout feature.” Attach the response to the row so the integration lead can identify any remaining tests.

Record what depends on the answer. An uncertain capture window can invalidate the proposed fulfillment sequence; an unhandled subscription event can leave the application record unchanged. Resolve those questions before approving the affected work. A provider score cannot show which requirement blocks implementation.

Workflow in text

1. The product owner defines the operation and acceptance criteria, then hands them to the integration lead.
2. The integration lead checks official documentation and records version, region, method and account conditions. Supported in the confirmed scope proceeds to narrow verification.
3. Conditional or unknown goes on hold with a named owner. When authoritative evidence arrives, return to the documentation step. Unavailable stops that path; the product owner must change the requirement or choose another approach before re-evaluation.
4. The test owner runs the scoped verification and records the result. Missing or unexpected evidence returns to the unresolved branch.
5. When recorded results match expectations, the product and integration owners decide which work to approve. Review the decision when the operation, version or availability conditions change.

Approve the operations the evidence supports

An approval should name the operation, confirmed conditions, observed result and excluded work. If a mandatory row remains unknown or unavailable, leave the dependent architecture decision open while you investigate other rows. A passing test supports only the behavior it exercised.

If the lifecycle itself needs clarification, read authorization, capture and settlement. For the commercial roles behind an integration, see gateway, processor and merchant account responsibilities. Use those distinctions to sharpen the requirement before comparing API mechanics.

Bring your matrix and open questions to a payment infrastructure discussion, or review the custom integration service. For unresolved gateway architecture questions, see independent gateway options. Confirm the required endpoint, account and implementation with Roots; the provider examples above do not establish Roots support for them.

Related products and services

Payment infrastructure partnerships

Explore payment infrastructure partnerships and review the requirements for your payment setup.

Custom Payment Integration

Explore custom payment integration and review the requirements for your payment setup.

Payment Gateway

Explore payment gateway and review the requirements for your payment setup.