Integrations
Buying and selling crypto: ramp providers
Converting between bank money and crypto is done by third-party providers, not by FurlPay. This page explains which provider adapters exist, what state each is in, and how the order record, partner keys and callbacks work.
FurlPay does not operate an on-ramp or off-ramp
Providers
In code the providers have internal names so that routes and logs are not tied to a vendor. Users are always shown the real company that processes their payment.
| Parameter | Type | Description |
|---|---|---|
| Coinbase (FurlGateway)optional | hosted checkout | Coinbase Developer Platform on-ramp and off-ramp. Opens a Coinbase-hosted page when the API key is set. Coinbase sends FurlPay no status updates. Contract status: in discussion. |
| Transak (FurlBridge)optional | adapter | On-ramp and off-ramp adapter with a signed webhook. No contract yet; the webhook is not linked to completed FurlPay orders. Contract status: in discussion. |
| Echo Money (FurlPayout)optional | not registered | Payout adapter code exists, but the provider's API and webhook scheme are unverified, so the adapter is never registered. No contract. |
Three states a deployment can be in
- Router on (
ONRAMP_LIVEorOFFRAMP_LIVE) — the router would pick an adapter for the customer's country, currency and payment method. Both flags are marked unimplemented and cannot be turned on by an environment variable. - Hosted checkout — the Coinbase key is set, so a session opens Coinbase's own page.
- Nothing configured — production returns
503. A demo session exists in development only.
The capability matrix
Whether a provider may be used for a corridor is data, not an assumption. Each row records the direction, country, currency, assets and payment methods, plus a contract status: none, in_discussion, signed_pending_credentials or live. Only a row that is live, with its evidence link and credentials, can be selected for a real transaction. No row is live today, and no row exists for Indian bank rails because there is no signed Indian partner.
Order records
Whenever a provider is involved, a ramp order is written before the provider is called, so a crash after the provider answers still leaves a record. The provider is given FurlPay's order ID as its reference. If the provider call fails, the order is marked failed and the API returns 502.
| Method | Path | Description |
|---|---|---|
| POST | /api/onramp/quote | Purchase quote from Coinbase's quote API when configured; 503 in production otherwise |
| POST | /api/onramp/session | Open an on-ramp checkout; returns orderId when a provider is involved |
| GET | /api/onramp/session/{id} | Session status |
| POST | /api/offramp/session | Open a Coinbase-hosted sell checkout; 503 without credentials |
| GET | /api/ramp/orders | The caller's ramp orders |
| GET | /api/ramp/orders/{orderId} | One ramp order |
| POST / GET | /api/offramp/beneficiary | Bank account collection; refuses today (see below) |
Bank accounts are not collected
Paying an unverified bank account is how a substituted beneficiary gets paid. FurlPay has no account-verification partner, so /api/offramp/beneficiary returns 503 beneficiary_verification_unavailable and stores nothing. The server-initiated off-ramp that would pay a verified beneficiary is therefore unavailable.
Partner integration
A business can embed the on-ramp with @furlpay/elements using a publishable key, instead of a user session. Whether ramps are enabled for a partner is an operations decision.
| Method | Path | Description |
|---|---|---|
| GET | /api/developer/ramp | Whether ramps are enabled for this account, and the configured callback |
| PUT | /api/developer/ramp | Set the callback URL; returns a new signing secret once |
| DELETE | /api/developer/ramp | Remove the callback |
Callbacks are signed with X-FurlPay-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 over t + "." + body. Callback URLs must be HTTPS and resolve to a public address; this is checked when set and again at every delivery. Failed callbacks are retried up to five times, from one minute to six hours apart.
Background maintenance
GET /api/cron/ramp-maintenance marks unpaid checkouts older than 30 minutes as abandoned, sends stuck deliveries and payouts to manual review, and retries due partner callbacks. It needs to run every few minutes and is not in the default cron list, so it must be scheduled by the deployment with the cron secret.
Setup
FURLGATEWAY_API_KEY_IDandFURLGATEWAY_API_KEY_SECRET(or the olderCDP_API_KEY_IDandCDP_API_KEY_SECRET) — Coinbase Developer Platform key for hosted checkout.FURLBRIDGE_API_KEY,FURLBRIDGE_SECRET_KEY,FURLBRIDGE_ACCESS_TOKEN,FURLBRIDGE_API_URL— Transak. The webhook at/api/webhooks/furlbridgeis verified as an HS256 token keyed with the access token.FURLPAY_PARTNER_WEBHOOK_KEY— seals partner callback secrets. Unset means/api/developer/rampreturns 503 and no callbacks are sent.FURLPAY_BENEFICIARY_ENCRYPTION_KEY— encryption key for stored bank details, for the day a verification partner exists.