Skip to content

How to evaluate a payments API: 15 questions to ask before you integrate

Evaluate a payments API with 15 questions on quotes, idempotency, webhooks, sandbox and AI tooling, using BlindPay as the benchmark. With a 2-week plan.

A payments API is good when it tells you the exact cost before money moves, makes retries safe, signs every webhook, and gives you a sandbox that behaves like production. Ask 15 questions about those things before you integrate. BlindPay is the benchmark below, and each answer is checked against its docs.

This guide is for engineers and technical leads, as of November 2026. It pairs with how to choose a payment processor, KYC and KYB in payments, payment orchestration explained and payment infrastructure for fintechs, payroll and remittance.

Key takeaways

  • Judge a payments API on the quote, idempotency, webhooks, sandbox, error handling and tooling, not only on endpoints.
  • A quote-then-execute flow shows the exact fee and exchange rate before you commit.
  • Webhooks must be signed, deduplicable and replayable.
  • A sandbox is only useful if it mirrors production and can force failures.
  • Run a two-week plan with your own test payments before you decide.

What makes a payments API good?

A good payments API is predictable under failure. It has typed clients, locked prices, safe retries, verifiable events and clear states. The table lists what to look for.

CriterionWhat good looks likeHow BlindPay meets it
Spec and SDKsOpenAPI spec and official SDKs in your languageOpenAPI 3.1 spec and SDKs for Node.js, Python, Go, PHP and Swift
Price before commitA quote with fee breakdown and locked ratePayout quotes lock rate and fees for 5 minutes
Safe retriesIdempotency keys with documented behaviorIdempotency-Key header, 24-hour retention
EventsSigned, deduplicable webhooksSvix-signed webhooks with svix-id for dedupe
SandboxSame API, forced failures, no real moneyDevelopment instances with test amounts
StatesDocumented statuses and terminal statesprocessing, on_hold, completed, failed, refunded
ObservabilityChangelog and public status pageA changelog and a status page
Agent toolingMachine-readable docs and toolsHosted MCP server, Agent Skills and a CLI

The 15 questions

Ask these 15 questions of any provider, and test the answers in the sandbox. "BlindPay:" lines show the benchmark answer, taken from the docs.

  1. Is there an OpenAPI spec and an official SDK in my language? Good: a machine-readable spec and maintained SDKs. BlindPay: an OpenAPI 3.1 spec at api.blindpay.com/doc and official SDKs for Node.js, Python, Go, PHP and Swift (SDKs).
  2. Can I see the exact cost before I commit? Good: a quote with a fee breakdown. BlindPay: every quote shows its fees and the amount the recipient gets. BlindPay combines a monthly plan (platform access) with per-transaction fees that vary by rail and network and are disclosed only in the live quote before execute. See the pricing page.
  3. Does the quote lock the rate and fee, and for how long? Good: a stated expiry and a clear error when it lapses. BlindPay: a payout quote locks rate and fees and expires 5 minutes after creation (payout quotes).
  4. Are write requests idempotent? Good: a header, a retention window and defined conflict errors. BlindPay: an Idempotency-Key header up to 255 characters on POST, PUT, PATCH and DELETE, stored for 24 hours (idempotency).
  5. What happens if I reuse a key with a different body? Good: a hard error. BlindPay: 422 idempotency_key_payload_mismatch. A same-body retry returns the stored response with Idempotency-Replayed: true, and an in-flight duplicate returns 409.
  6. Are webhooks signed, and can I deduplicate them? Good: a signature plus a stable event ID. BlindPay: svix-id, svix-timestamp and svix-signature headers, with svix-id constant across redeliveries (verification).
  7. Can I inspect and replay deliveries? Good: a delivery log. BlindPay: a hosted Svix portal link lets teammates browse delivery attempts and replay events without dashboard access (webhooks).
  8. Does the sandbox mirror production? Good: same endpoints and shapes. BlindPay: development and production share the same API surface and hostname, and the API key's instance decides the environment (sandbox vs production).
  9. Can I force failures in the sandbox? Good: documented test values. BlindPay: a request amount of $666.00 forces failed and $777.00 forces refunded.
  10. How does identity verification appear in the API, and how long does it take? Good: a status field and stated timings. BlindPay: standard KYC takes about 60 seconds and is automatic; Enhanced KYC and KYB review take 3 hours to 1 business day (KYC).
  11. What are the payment states, and which are terminal? Good: a short, documented state machine. BlindPay: completed, failed and refunded are terminal (payouts).
  12. Where does the money go when a payment fails? Good: a precise, written answer. BlindPay: see the custody statement below.
  13. How are errors and rate limits reported? Good: stable error codes and rate limit headers. BlindPay: named codes such as swift_minimum_is_100_usd, and a 429 with Retry-After on development instances, which are capped at 40 requests per minute per instance.
  14. How are credentials scoped? Good: keys tied to one environment and roles for sensitive actions. BlindPay: each API key belongs to one instance, and webhook management needs the owner, admin or developer role (API keys).
  15. Can I page through and reconcile everything? Good: cursor pagination and per-transaction detail. BlindPay: list endpoints use cursor pagination with starting_after and ending_before (pagination).

On question 12, BlindPay operates as a non-custodial payment processor for payout flows from customer-controlled wallets: you authorize the exact amount and BlindPay executes that single transaction. If a payout cannot be delivered after the stablecoins are collected, BlindPay refunds them to the quote's refund wallet, or to the sending wallet when none is set; on Pix and other non-USD local rails the refund is automatic, while USD payouts and payouts whose review times out are refunded after an operator review. Optional BlindPay-managed wallets (beta) are custodial when you choose that path.

How does the quote-then-execute flow work?

You create a quote first, read the fee and rate, then execute the payment against that quote before it expires. Nothing moves until you execute. This is the pattern to look for in any payout or conversion API.

  1. Onboard. Create the customer and have them pass KYC or KYB. A customer must be approved before money moves.
  2. Link a bank account. Add the recipient's bank account. It must reach approved status before you can quote against it.
  3. Quote. Request a payout quote for an amount. The response shows the fee breakdown and what the recipient receives, and locks both for 5 minutes.
  4. Execute. Create the payout against the quote. A quote that has expired cannot execute, so request a new one.
  5. Confirm by webhook. Listen for payout.update and payout.complete. Treat completed, failed and refunded as final.

The payout quickstart walks through each call, and handle expired quotes covers the retry code.

How should webhooks work?

A good webhook is signed, deduplicated, quick to acknowledge and replayable. Treat every payload as untrusted until the signature checks out.

A safe handler does this:

  1. Read the raw request body, not the parsed JSON.
  2. Build the signed content from svix-id, svix-timestamp and the body, joined by dots.
  3. Compute the HMAC-SHA256 with your signing secret and compare it in constant time with the signatures in svix-signature.
  4. Reject timestamps outside a tolerance window. BlindPay's docs suggest 5 minutes.
  5. Deduplicate on svix-id, then process and return a 2xx.

BlindPay requires an https endpoint, allows up to 25 endpoints per instance, and lists the source IPs it sends from. Those addresses are shared with other senders, so keep verifying the signature. More in stablecoin API webhooks and reconciliation and the webhook events catalog.

What should a sandbox include?

A sandbox should let you run the whole flow, including failures, without real money. If it cannot, you will first find the bugs in production.

  • The same endpoints, fields and response shapes as production.
  • Automatic identity approval, with a documented way to test a rejection.
  • Payments that complete without moving real funds.
  • Test values that force failed and refunded outcomes.
  • Real signed webhooks, so your handler is exercised.
  • A documented list of every difference from production.

BlindPay's development instances auto-approve KYC (set the first or legal name to Fail to test a rejection), complete payins about 30 seconds after creation and complete payouts automatically. They use a test token called USDB. Compare against stablecoin API sandbox vs production.

What do AI-agent tools add?

AI-agent tooling lets a coding agent or an assistant read your API and operate it without hand-written glue. It is worth checking because more integration work now starts in an editor.

BlindPay provides a hosted MCP server at https://mcp.blindpay.com/mcp with OAuth sign-in, so no API key goes into the client, and a read-only endpoint at https://mcp.blindpay.com/mcp/readonly for agents that should look but never change anything (MCP docs). Its tools are generated from the public API and carry read-only and destructive annotations. BlindPay also publishes Agent Skills (npx skills add blindpaylabs/skills) and a command line tool, described in BlindPay CLI. See the MCP page, Talk to your payment API and BlindPay Agent Skills. The protocol itself is documented at modelcontextprotocol.io. A person should still approve anything that moves money.

A two-week integration plan

Two weeks is enough to get from first call to a reviewed plan, if you test the failure paths early.

  1. Days 1 to 2: read the docs, create a development instance and an API key, and make a first call from an SDK.
  2. Days 3 to 4: onboard a test customer and add a test bank account.
  3. Days 5 to 6: create a quote and execute a payout in the sandbox, with idempotency keys on every write.
  4. Days 7 to 8: build the webhook endpoint with signature verification and deduplication.
  5. Days 9 to 10: force a failure and a refund, and check your ledger handles both.
  6. Days 11 to 12: add reconciliation, pagination and alerts on stuck states.
  7. Days 13 to 14: run the go-live checklist, switch to production credentials and review with finance and compliance. See the payouts API integration checklist.

How BlindPay does it

BlindPay is the benchmark here because the answers above are all in its public docs: five official SDKs, an OpenAPI spec, a quote that locks fees and rate, an idempotency header, Svix-signed webhooks, a sandbox with the same API surface as production and an MCP server. It is built for cross-border payouts and collections over Pix, SPEI, ACH, RTP, SEPA and SWIFT (POBO/COBO), with compliance inside the flow. To try it, create a development instance in the dashboard and follow the payout quickstart.

Methodology and sources

Checked in November 2026. Every BlindPay claim was checked against the BlindPay docs pages below. Criteria are BlindPay's framework for engineers and technical leads.

FAQ

One API.
Multiple payment rails.

Blind Pay, Inc. (“BlindPay”) is a United States-based financial technology and payments infrastructure company, incorporated in the State of Delaware on May 2, 2024. BlindPay is duly registered as a Money Services Business (“MSB”) with the Financial Crimes Enforcement Network (“FinCEN”) under registration number 31000277566153. BlindPay is not a state-licensed money transmitter and does not, in its own capacity, engage in regulated money transmission services. All such regulated activities are conducted exclusively through, and under the licenses of, duly authorized financial institution partners. BlindPay's role is limited to providing financial technology, virtual account management, payment processing, and related payments infrastructure services that facilitate payment flows and account functionalities. These services are provided in coordination with its licensed partners and in compliance with applicable federal MSB requirements and relevant state regulatory frameworks.

Blind Pay, LLC (“BlindPay”) is a Delaware limited liability company formed on June 24, 2025. BlindPay is duly registered as a Money Services Business (“MSB”) with the Financial Crimes Enforcement Network (“FinCEN”) under registration number 31000318334247 and is listed in the Nationwide Multistate Licensing System (“NMLS”) under NMLS ID #2745309.

BLIND PAY SOCIEDADE PRESTADORA DE SERVIÇOS DE ATIVOS VIRTUAIS LTDA. (“BlindPay”) is a Virtual Asset Service Provider (“VASP”) operating in Brazil. The company is presently completing the regulatory adaptation process required of Virtual Asset Service Provider Companies (SPSAV) under Central Bank of Brazil Resolution No. 520/2025, and remains subject to the transitional regime set forth in Article 88 of that Resolution. Registered address: Avenida Princesa Isabel, nº 15, Sala 1405, Edifício Martinho de Freitas, Centro, Vitória/ES, 29010-361.

BlindPay is a stablecoin API that enables individuals and businesses to move money worldwide.