Skip to main content

​
Overview

Capa’s API enables fintechs and platforms to integrate seamless cryptocurrency on-ramping, off-ramping, and fiat-to-fiat cross-ramp transfers. Users can exchange fiat currencies for cryptocurrencies and vice versa, or convert between different fiat currencies, with just a few simple steps. Capa currently supports MXN (Mexican Peso), DOP (Dominican Peso), USD (US Dollar), and EUR (Euro).

​
Integration Flow

The following steps apply to every integration regardless of which transaction types you plan to support.
1

Get your API key

To start testing, sign up at sandbox.capa.fi to get a staging API key immediately — no onboarding required. For production, use the partner dashboard to manage your API keys. See the API Key Guide for details on usage and regeneration.
2

Configure webhooks

Register your webhook URL via the Webhook Settings endpoint and implement HMAC signature validation to verify incoming events. See Webhooks for retry behavior and best practices.
3

Create and verify users

Create a user with externalUserId, email, and identifier, then complete identity verification via KYC link, direct KYC submission, or KYB link for businesses. See the User Creation and Verification guide.
4

Set up bank accounts and receivers (if needed)

For off-ramp and cross-ramp transactions, provide destination bank details inline, save them via the Bank Accounts API, or create Receivers for third-party payouts.
5

Get a quote (optional)

Use Get Quote Rate for a real-time estimate, or Create Quote to lock a guaranteed exchange rate for 10 seconds. Quoting works the same way across on-ramp, off-ramp, and cross-ramp transactions. For cross-ramp, use the dedicated Cross-Ramp Quote endpoints.
6

Create a transaction

With a verified user (and optionally a locked quote), create the transaction for your use case:
7

Monitor and manage transactions

Receive real-time status updates via Transaction Events and KYC Events webhooks. You can also list transactions or cancel a transaction as needed. See the Transactions Guide.

​
How It All Fits Together

​
Key Things to Know

  • KYC before transactions — A user must be fully verified before you can create any transaction for them.
  • Quotes are optional but short-lived — A locked quote expires after 10 seconds. If no quote is used, the rate is calculated at the time of funding.
  • Premium spread — If a quoteId is provided, the quote’s premiumSpread takes precedence over any value in the transaction request. Set it when creating the quote.
  • Webhook reliability — Return a 2xx response promptly. Failed deliveries are retried up to 5 times. As a fallback, poll the List Transactions or Get KYC Details endpoints.
  • No idempotency keys — Duplicate requests create duplicate resources. Build safeguards on your side to prevent double submissions.

​
Production Readiness Checklist

Before going live, make sure you have:
  • Webhook URL registered and HMAC signature validation implemented
  • User creation + KYC/KYB flow tested end-to-end in staging
  • At least one transaction of each type you support tested in staging
  • Error handling for common error codes (400, 401, 403, 404, 409, 429)
  • Safeguards against duplicate submissions (no idempotency key support)
  • Rate limiting handled (10 requests per second per partner)

​
API Environments

EnvironmentBase URLPurpose
Staginghttps://staging-api.capa.fiTesting and development
Productionhttps://api.capa.fiLive transactions with real funds

​
Staging vs Production

AspectStagingProduction
Fiat transfersSimulated (no real money moves)Real SPEI/ACH/SEPA transfers
Crypto transfersReal on-chain transactionsReal on-chain transactions
KYC verificationNot validated (random data accepted)Full identity verification
Exchange ratesMay differ from live marketLive market rates
Mock testingEnabled (see mock guide)Disabled

​
Rate Limits

All API endpoints are rate-limited to 10 requests per second per partner. Exceeding this limit returns a 429 Too Many Requests response. Rate limit information is not included in response headers.

​
Error Response Format

All error responses follow this structure: 
{
  "status": "failed",
  "code": "INVALID_USER_INPUT",
  "message": "Description of what went wrong",
  "errors": [
    { "field": "email", "message": "must be a valid email" }
  ]
}
Common error codes:
HTTP StatusCodeDescription
400INVALID_USER_INPUTValidation error (missing or invalid fields)
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENAction not allowed for this partner or user
404NOT_FOUNDResource not found
409USER_ALREADY_EXISTS_ERRORUser with this email or externalUserId already exists
429—Rate limit exceeded

​
Idempotency

The API does not currently support idempotency keys. Sending the same request twice will create two separate resources (e.g., two transactions). Ensure your integration includes safeguards to prevent duplicate submissions.

​
API Status

Monitor API availability at status.capa.fi.

​
🔌 Our API

​
Buy and Sell Cryptocurrency

Allow your users to purchase and sell digital assets such as USDC directly through our API, using supported fiat currencies including MXN, DOP, USD, and EUR.

​
Cross-Border Fiat Transfers

Enable your users to convert between fiat currencies (e.g., MXN to USD) without touching crypto. Capa handles the conversion and delivers funds to the target bank account.

​
Instant Transfers and Fast Settlement

With Capa, you can eliminate long wait times for international transfers. Our platform offers near-instant settlement for both crypto and fiat transactions, ensuring users can transact quickly and efficiently.

​
Local Banking and Crypto Integration

Capa provides a smooth integration between banking infrastructure and the world of cryptocurrencies. Your users will be able to deposit fiat currencies, which can be instantly converted to digital assets, and they can withdraw their crypto to fiat with ease.

​
What’s Next