---
title: "How to integrate a crypto on-ramp API: payin quotes, deposit instructions, and webhooks"
seoTitle: "How to integrate a crypto on-ramp API: quote to webhook"
description: "The on-ramp API flow step by step: verify the customer, pick the wallet, quote, create the payin, show deposit instructions, and handle webhooks."
date: "2026-09-20"
updated: "2026-09-20"
author: "BlindPay Team"
category: "payments"
howto:
  name: "How to integrate a crypto on-ramp API"
  steps:
    - name: "Onboard and verify the customer"
      text: "Have the customer accept the provider's terms of service, create the customer with KYC or KYB data, and wait for the approval webhook before quoting."
    - name: "Choose where the stablecoins land"
      text: "Register an external wallet the customer controls, or use a provider-managed wallet or a virtual account, and save its ID."
    - name: "Request a live quote"
      text: "Send the amount in minor units, the payment method, the token, who pays the fee, and the destination wallet. Save the quote ID and its expiry."
    - name: "Create the payin and show deposit instructions"
      text: "Create the payin from the quote before it expires and show the payer the instructions for their rail: bank details and a memo code, a Pix code, a CLABE, or a payment link."
    - name: "Handle webhooks"
      text: "Verify each webhook signature on the raw body, deduplicate by message ID, and move your payment record forward only, never back from a final status."
    - name: "Reconcile and test failure paths"
      text: "Reconcile payins against your ledger daily, and force failed and refunded outcomes in the sandbox before going live."
faq:
  - q: "What is the basic flow of a crypto on-ramp API?"
    a: "Onboard and verify the customer, register the wallet that will receive the stablecoins, request a quote, create the payment from that quote, show the payer the deposit instructions, and listen for webhooks until the payment is complete. The quote is the step that locks the rate and fees."
  - q: "How long does an on-ramp quote stay valid?"
    a: "Usually a few minutes. On BlindPay a payin quote expires 5 minutes after creation, except OTC quotes, which expire in 10 seconds. The expiry is returned in epoch milliseconds, so parse it carefully, and request a new quote if the window has passed."
  - q: "Why use webhooks instead of polling for on-ramp status?"
    a: "Deposits arrive on the payer's schedule, not yours. A Pix payment can land in seconds and an ACH credit can take days. Webhooks tell you the moment the status changes, while polling either wastes calls or reacts late. Keep a daily reconciliation job as a backstop for missed events."
  - q: "What happens if the payer never sends the money?"
    a: "The payment waits for a window that depends on the rail, then fails. On BlindPay, Pix, SPEI, Transfers, and PSE payins wait up to 30 minutes before failing, and ACH or wire payins wait up to 5 business days. A created payin can't be cancelled, so let it expire and create a new quote if the payer comes back."
  - q: "Can I test an on-ramp integration without real money?"
    a: "Yes. A sandbox or development instance simulates deposits. On BlindPay, development payins complete about 30 seconds after creation and deliver a test stablecoin, USDB, on testnets. Set the amount to 666.00 to force a failure or 777.00 to force a refund, and check that your code handles both."
  - q: "Should I use an SDK or call the REST API directly?"
    a: "Use the SDK if one exists for your language, since it handles authentication and types. Generate a client from the OpenAPI spec otherwise. BlindPay ships SDKs for Node.js, Python, Go, PHP, and Swift, and an OpenAPI 3.1 spec for everything else."
---

A crypto on-ramp integration follows six steps: verify the customer, choose the wallet that receives the stablecoins, request a quote, create the payment and show the payer deposit instructions, handle webhooks until the payment settles, and reconcile. The quote locks the rate and fees. Webhooks, not polling, tell you when the fiat landed.

This guide covers the on-ramp direction: fiat in, stablecoins out. For the payout direction, see [integrating a stablecoin API](/resources/more/how-to-integrate-a-stablecoin-api). Examples use BlindPay's API on a development instance. Field names are real, but check the [payins docs](/docs/payins) for the current shape before you ship.

## Key takeaways

- The quote is the contract. It fixes the amount, fees, and destination for a short window, and the payment must be created inside it.
- Each rail shows the payer something different: bank details and a memo code, a Pix code, a CLABE, a CBU, or a payment link.
- Deposits arrive on the payer's schedule. Design for minutes on Pix and SPEI and days on ACH.
- Verify webhook signatures on the raw body, deduplicate retries, and never move a payment backwards from a final status.
- Force failures in the sandbox before production. `failed` and `refunded` mean different things for your ledger.

## What does an on-ramp integration look like?

Your backend talks to the on-ramp API. The provider talks to the banks and the blockchain. Events come back to you.

```text
your app ──► on-ramp API ──► bank rails + liquidity ──► stablecoins to the wallet
    ▲                                                          │
    └──────────────────────── webhooks ◄───────────────────────┘
```

Three objects carry the whole flow: a **customer** (who is paying in), a **wallet** (where the stablecoins land), and a **payin** (one deposit, created from a quote). Everything else is detail on those three.

## How do you onboard and verify the customer?

Every payin belongs to a verified customer. On BlindPay that takes two calls.

1. **Terms of service.** Generate a terms-of-service URL with `POST /v1/e/instances/{instance_id}/tos`, send the customer to it, and keep the `tos_id` it returns.
2. **Create the customer.** `POST /v1/instances/{instance_id}/customers` with the `tos_id`, `type` (`individual` or `business`), and the KYC or KYB fields.

Then wait. KYC Standard for individuals is automated and takes about 60 seconds. KYB for businesses and KYC Enhanced for high-risk countries are manual reviews of 3 hours to 1 business day. A `customer.update` webhook tells you when `kyc_status` changes. Don't request quotes until it reads `approved`. [How to automate KYC and KYB](/resources/more/how-to-automate-kyc-kyb-stablecoin-payments) covers the data you need to collect.

## Where should the stablecoins land?

Pick the destination before you quote, because the quote needs its ID.

| Destination | ID | Custody | When to use it |
| --- | --- | --- | --- |
| External blockchain wallet | `bw_...` | The customer holds the keys | The customer already has a wallet, or you never want to hold funds |
| Managed wallet (beta) | `bl_...` | BlindPay custodies the balance | You want a balance without running wallet infrastructure |
| Virtual account | Settles to a linked wallet | Depends on the linked wallet | US payers send ACH or wire to a dedicated account number |

An external wallet is registered once per address. On EVM networks the customer can sign a message so BlindPay recovers the address from the signature. On Stellar, Solana, and Tron you submit the address directly, so validate it twice: a stablecoin sent to the wrong address can't be recovered. The network is read from the wallet record, so you never pass a network on the quote.

## How do you request a quote?

The payin quote locks the numbers. Send it the amount, the rail, the token, who pays the fee, and the destination.

```bash
curl https://api.blindpay.com/v1/instances/in_000000000000/payin-quotes \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "blockchain_wallet_id": "bw_000000000000",
    "payment_method": "pix",
    "currency_type": "sender",
    "request_amount": 100000,
    "cover_fees": false,
    "token": "USDB",
    "payer_rules": { "pix_allowed_tax_ids": ["14747677786"] }
  }'
```

Four fields cause most bugs:

- **`request_amount`** is an integer in minor units. `100000` is R$1,000.00. For MXN, COP, and ARS it must also be a whole currency unit (a multiple of 100).
- **`currency_type`** says which side the amount is in. On a payin quote, `sender` means fiat. On a payout quote it means stablecoin. Same field, opposite meaning.
- **`cover_fees`** decides who pays: `false` takes the fee out of the stablecoins delivered, `true` adds it to the fiat the payer sends.
- **`payer_rules`** names who may pay. Pix needs the allowed CPF or CNPJ tax IDs, Transfers 3.0 needs a CUIT or CUIL, and PSE needs the payer's name, document, email, phone, and bank code.

The response returns `sender_amount`, `receiver_amount`, the market rate (`commercial_quotation`), the rate with fees (`blindpay_quotation`), each fee line, and `expires_at` in epoch milliseconds. You have 5 minutes. [Stablecoin API quotes explained](/resources/more/stablecoin-api-quotes-explained) covers fee direction and units in depth.

## How do you create the payin and show deposit instructions?

Create the payin from the quote, then show the payer what their rail needs.

```bash
curl https://api.blindpay.com/v1/instances/in_000000000000/payins/evm \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 6f1c2a5e-payin-0001' \
  --data '{ "payin_quote_id": "pq_000000000000" }'
```

The path says `evm` for every method, including Pix, SPEI, PSE, and Transfers. The name is historical; it doesn't restrict the network. The response fills only the field for your rail:

| Payment method | Show the payer |
| --- | --- |
| ACH, wire | `blindpay_bank_details` plus the `memo_code` to include in the transfer |
| Pix | `pix_code`, as copyable text or a QR code |
| SPEI | The `clabe` to transfer to |
| Transfers 3.0 | The account (CVU, CBU, or alias) in `tracking_transaction.transfers_instruction` |
| PSE | The payment link in `tracking_transaction.pse_instruction` |

If the customer has an approved [virtual account](/resources/more/stablecoin-virtual-accounts-explained), ACH and wire deposits go to that dedicated account and the memo code is ignored. RTP is the exception: it always uses the memo-code path.

A created payin can't be cancelled. If the payer never pays, it fails after the rail's waiting window. Send the idempotency key on every create, so a network retry can't produce two payins. The header follows the [IETF Idempotency-Key draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/), and [why idempotency keys matter](/resources/more/stablecoin-api-idempotency-keys) covers the failure it prevents.

## How do you handle on-ramp webhooks?

Three events cover a payin's life:

- `payin.new` when the payin is created, including deposits into a virtual account.
- `payin.update` at intermediate steps, such as an arrival check or manual review.
- `payin.complete` when it finishes: delivered, refunded, or failed.

Every call is signed with `svix-id`, `svix-timestamp`, and `svix-signature` headers. Verify the signature on the exact raw bytes, before you parse the JSON, following [Svix's verification guide](https://docs.svix.com/receiving/verifying-payloads/how). The `svix-id` stays the same across redeliveries of one event, so it's your deduplication key. Events can arrive out of order, so store a status only if it moves the payment forward, and never overwrite `completed`, `failed`, or `refunded`. [Stablecoin API webhooks](/resources/more/stablecoin-api-webhooks-reconciliation) has the code-level detail.

## How do you reconcile on-ramp payments?

Treat webhooks as the fast path and a daily job as the truth.

The payin's top-level `status` is the source of truth: `processing`, `on_hold`, `completed`, `failed`, or `refunded`. Four `tracking_*` objects (`tracking_transaction`, `tracking_payment`, `tracking_complete`, `tracking_partner_fee`) expose a finer `step` for status screens. Each day, list payins with `GET /v1/instances/{instance_id}/payins` and compare them with your ledger: amounts, statuses, fees. Match on the payin ID, not the transaction hash, because a transaction replaced during a [gas spike](https://ethereum.org/en/developers/docs/gas/) can land under a different hash.

## What edge cases should you handle?

These show up in the first week of production:

- **Expired quote.** The payin create fails. Request a new quote; don't retry the old one.
- **Amount out of range.** Payin quotes enforce a minimum and maximum per currency, and the customer's per-transaction limit applies too. Read the error for the range instead of hardcoding it.
- **The payer never pays.** Pix, SPEI, Transfers, and PSE payins wait up to 30 minutes before failing. ACH and wire wait up to 5 business days.
- **On hold.** Transaction monitoring can hold a payin for review. Answer any request for information quickly; an unanswered one may end in a refund.
- **Refunded vs failed.** `refunded` means the deposit went back to the sender. Fiat refunds wait on the bank network and can carry fees. `failed` needs a look before you tell the customer anything.
- **Wrong destination.** A wallet registered with the wrong address receives the stablecoins anyway. Validate addresses at registration, not at delivery.

## How do you test an on-ramp integration?

Development instances run the whole flow without real money. Payins complete automatically about 30 seconds after creation and deliver USDB, a test stablecoin, on testnets such as Sepolia, Base Sepolia, Polygon Amoy, Stellar testnet, and Solana devnet.

Force the outcomes you can't wait for in real life: a payin for 666.00 fails and one for 777.00 is refunded. Run both through your webhook handler and ledger. Two things the sandbox can't show you: Tron has no testnet, and real deposits arrive on real rail timing. Plan one small supervised payin per rail in production. [Sandbox vs production](/resources/more/stablecoin-api-sandbox-vs-production) lists the rest.

## Abstracted or Advanced: which API flavor should you use?

BlindPay's docs come in two flavors over the same API, the same keys, and the same webhooks.

- **Abstracted** is for teams that think in bank payments. Payins are deposits, virtual accounts are deposit accounts, and the stablecoin settles behind the scenes in the linked wallet.
- **Advanced** exposes the stablecoin layer: chains, tokens, managed and external wallets, and on-chain authorization for payouts.

Choose Abstracted if your users never see a wallet address. Choose Advanced if your product is a wallet, or if your users pick the network. You can switch at any time; nothing about your account changes.

## How do you use a coding agent to build the integration?

AI coding agents are good at this kind of work, if they get the API's rules up front. BlindPay ships three surfaces for them:

- **An MCP server** (`@blindpay/mcp`) that exposes the API as tools for Claude Code, Codex, Cursor, and other MCP clients.
- **Agent Skills** that teach the agent the API's conventions.
- **Prebuilt prompts**, including a payin quickstart prompt that encodes the gotchas (minor units, the 5-minute quote window, the `evm` path).

A prompt that works: "Using the BlindPay API on a development instance, build a payin flow for Pix: create a customer, register a Solana wallet, request a payin quote with `cover_fees: false`, create the payin, render the Pix code, and handle `payin.*` webhooks with Svix signature verification and deduplication on `svix-id`. Write tests for completed, failed (666.00), and refunded (777.00)." The [build with AI](/docs/build-with-ai) page has the setup.

## What to do next

Get a development instance, run one Pix or ACH payin end to end, and force a failure and a refund. If your handler and ledger stay correct through all three, you're ready for the production checklist. If you're still choosing a provider, read [business vs consumer crypto on-ramps](/resources/more/business-vs-consumer-crypto-on-ramps) and [crypto on-ramp fees explained](/resources/more/crypto-on-ramp-fees-explained) first.

*This article is general information, not legal, tax, or financial advice. API fields and behavior change; the [BlindPay docs](/docs/payins) are the reference.*