---
title: "How to evaluate a payments API: 15 questions to ask before you integrate"
seoTitle: "How to evaluate a payments API: 15 questions to ask"
description: "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."
date: "2026-11-15"
updated: "2026-11-16"
category: "payments"
author: "BlindPay Team"
faq:
  - q: "What should a payments API sandbox include?"
    a: "A good sandbox exposes the same endpoints and response shapes as production, auto-approves identity checks, completes payments without real money, and lets you force failures and refunds with test values. It should also deliver real signed webhooks. BlindPay development instances approve KYC automatically and complete payins about 30 seconds after creation, while testing amounts force failed and refunded outcomes."
  - q: "What is idempotency in payments?"
    a: "Idempotency means a retried request cannot create a second payment. You send a unique key with the request, and if the same key and body arrive again, the API returns the original result instead of running it twice. BlindPay accepts an Idempotency-Key header of up to 255 characters on POST, PUT, PATCH and DELETE requests, and keeps keys for 24 hours."
  - q: "How do payment webhooks work?"
    a: "A webhook is an HTTP call the provider sends to your server when a status changes, so you do not poll. Each call is signed so you can verify its origin. BlindPay signs webhooks with Svix headers, svix-id, svix-timestamp and svix-signature. Verify the signature on the raw body, check the timestamp, and deduplicate on svix-id."
  - q: "How long does a payments API integration take?"
    a: "A first sandbox payment can take a day, but a production integration takes longer, mostly for compliance onboarding, webhook handling, error cases and reconciliation. Plan for roughly two weeks for a focused team to go from sandbox to a reviewed production plan, then add time for provider-side review and your own testing."
  - q: "Can AI coding agents integrate a payments API?"
    a: "Yes, when the provider offers machine-readable tooling. BlindPay publishes an OpenAPI spec, a hosted MCP server at mcp.blindpay.com with OAuth sign-in, a read-only MCP endpoint, Agent Skills and a CLI. An agent can quote and track payments through these. A person still reviews anything that moves money."
---

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](/resources/more/how-to-choose-a-payment-processor), [KYC and KYB in payments](/resources/more/kyc-and-kyb-in-payments), [payment orchestration explained](/resources/more/payment-orchestration-explained) and [payment infrastructure for fintechs, payroll and remittance](/resources/more/payment-infrastructure-for-fintechs-payroll-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.

| Criterion | What good looks like | How BlindPay meets it |
| --- | --- | --- |
| Spec and SDKs | OpenAPI spec and official SDKs in your language | OpenAPI 3.1 spec and SDKs for Node.js, Python, Go, PHP and Swift |
| Price before commit | A quote with fee breakdown and locked rate | Payout quotes lock rate and fees for 5 minutes |
| Safe retries | Idempotency keys with documented behavior | `Idempotency-Key` header, 24-hour retention |
| Events | Signed, deduplicable webhooks | Svix-signed webhooks with `svix-id` for dedupe |
| Sandbox | Same API, forced failures, no real money | Development instances with test amounts |
| States | Documented statuses and terminal states | `processing`, `on_hold`, `completed`, `failed`, `refunded` |
| Observability | Changelog and public status page | A [changelog](/changelog) and a [status page](https://status.blindpay.com) |
| Agent tooling | Machine-readable docs and tools | Hosted 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](https://spec.openapis.org/oas/v3.1.0) at `api.blindpay.com/doc` and official SDKs for Node.js, Python, Go, PHP and Swift ([SDKs](/docs/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](/pricing).
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](/docs/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](/docs/learn/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](/docs/learn/webhooks-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](/docs/learn/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](/docs/learn/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](/docs/kb/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](/docs/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](/docs/learn/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](/docs/learn/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](/docs/quickstart-payout) walks through each call, and [handle expired quotes](/resources/more/handle-expired-quotes-typescript-python) 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](/resources/more/stablecoin-api-webhooks-reconciliation) and the [webhook events catalog](/docs/learn/webhooks-events).

## 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](/resources/more/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](/docs/mcp)). 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](/blog/cli). See the [MCP page](/mcp), [Talk to your payment API](/blog/mcp) and [BlindPay Agent Skills](/blog/agent-skills). The protocol itself is documented at [modelcontextprotocol.io](https://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](/resources/more/stablecoin-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](https://app.blindpay.com) and follow the [payout quickstart](/docs/quickstart-payout).

## 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.

- BlindPay docs: [SDKs](/docs/sdks), [payout quotes](/docs/payout-quotes), [payouts](/docs/payouts), [idempotency](/docs/learn/idempotency), [webhooks](/docs/learn/webhooks), [webhook verification](/docs/learn/webhooks-verification), [sandbox vs production](/docs/learn/sandbox-vs-production), [KYC](/docs/kb/kyc), [MCP](/docs/mcp), [build with AI](/docs/build-with-ai)
- BlindPay: [changelog](/changelog), [status page](https://status.blindpay.com), [MCP page](/mcp), [BlindPay CLI](/blog/cli)
- [OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [BlindPay Node.js SDK on GitHub](https://github.com/blindpaylabs/blindpay-node)
