Reference

This page covers the partner-observable surface for the ramp and bank-linking endpoints — which endpoints return which status codes, how provider routing is decided, and what every related error code means. For full request and response schemas, see the auto-generated API reference.

Authentication

All endpoints use standard Sumvin partner authentication. The user is resolved from the auth context — no user_id parameter is accepted. Endpoints under the /v0/bank-linking/* namespace require the user to have the bank-linking entitlement. Without it, calls return 403 Forbidden with error code GATE-403-001.

Provider routing

Bank linking runs through the ramp partner. GET /v0/accounts/link/config surfaces the link-flow configuration:

provider — always "meld".
requires_institution_selection — true (you list institutions via GET /v0/bank-linking/institutions and pass the user’s selection on link initiation).

Call the config endpoint before every link flow. The /v0/bank-linking/* namespace is gated by GATE-403-001.

Status codes per endpoint

Ramp

Endpoint	Success	Notable errors
`GET /v0/ramp/quotes`	`200 OK` (quotes may be empty)	`400 RAMP_INVALID_PAIR` / `RAMP_UNKNOWN_ASSET` / `RAMP_UNSUPPORTED_ASSET`, `403 KYC_NOT_VERIFIED`, `502 RAMP_PROVIDER_ERROR`
`POST /v0/ramp/sessions`	`201 Created`	`400 RAMP_INVALID_PAIR` / `RAMP_UNKNOWN_ASSET` / `RAMP_UNSUPPORTED_ASSET`, `403 KYC_NOT_VERIFIED`, `502 RAMP_PROVIDER_ERROR`
`GET /v0/ramp/transactions`	`200 OK`	`403 KYC_NOT_VERIFIED`
`GET /v0/ramp/transactions/{transaction_id}`	`200 OK`	`403 KYC_NOT_VERIFIED`, `404 RAMP_TRANSACTION_NOT_FOUND`

Bank linking

Endpoint	Success	Notable errors
`GET /v0/accounts/link/config`	`200 OK`	—
`GET /v0/bank-linking/institutions`	`200 OK` (may be empty)	`403 GATE-403-001`
`POST /v0/accounts/link`	`202 Accepted`	`400 BANK_INSTITUTION_REQUIRED`
`POST /v0/bank-linking/accounts/{account_id}/processor-token`	`201 Created`	`403 GATE-403-001`, `403 BANK_ACCOUNT_UNAUTHORIZED`, `404 BANK_ACCOUNT_NOT_FOUND`

Linked account management

These endpoints operate on linked accounts.

Endpoint	Success
`GET /v0/accounts`	`200 OK`
`GET /v0/accounts/{account_id}`	`200 OK`
`POST /v0/accounts/{account_id}/sync`	`202 Accepted`
`DELETE /v0/accounts/{account_id}`	`204 No Content`

Ramp status lifecycle

Ramp transactions use an internal status field for partner UI:

`status`	Meaning
`pending`	Session created; user has not submitted payment.
`processing`	Payment submitted; settlement underway (fiat capture, on-chain delivery, or fiat payout).
`completed`	Terminal success. For buys, destination wallet holds the balance; for sells, fiat has been routed to the user’s destination.
`failed`	Terminal failure. Surface the reason to the user and offer a retry.
`cancelled`	User abandoned, or the transaction was refunded or voided.

meld_status mirrors provider-side state and is useful for debugging a stuck transaction. See the full mapping in the on-ramp quickstart.

Error code reference

Errors follow RFC 7807 Problem Details with a Sumvin error_code field.

Ramp

Error code	Title	When it fires
`RAMP_INVALID_PAIR`	Invalid Asset Pair	Both sides of `from_asset` / `to_asset` are fiat, or both are crypto. One side must be fiat, the other crypto.
`RAMP_UNKNOWN_ASSET`	Unknown Asset	The crypto symbol does not exist in the Sumvin catalog for the supplied `chain_id`. Discover valid pairs at `GET /v0/assets`.
`RAMP_UNSUPPORTED_ASSET`	Asset Not Supported for Ramp	The crypto pair exists in the catalog but no service provider offers a fiat ramp for it today. See Supported values for the rampable subset.
`KYC_NOT_VERIFIED` (`KYC-403-001`)	KYC Not Verified	The user has not completed KYC verification. The KYC gate on every `/v0/ramp/*` endpoint raises this. Route them through KYC and retry.
`RAMP_TRANSACTION_NOT_FOUND`	Ramp Transaction Not Found	`GET /v0/ramp/transactions/{transaction_id}` referenced an id that does not exist, or the transaction belongs to a different user.
`RAMP_PROVIDER_ERROR`	Ramp Provider Error	Upstream provider rejected the quote or session. Re-quote, try a different `service_provider`, or retry after a short backoff.

Bank linking

Error code	When it fires
`BANK_INSTITUTION_REQUIRED`	`POST /v0/accounts/link` was called on the bank-linking path without `institution_id`.
`BANK_LINK_TOKEN_FAILED`	`POST /v0/accounts/link` could not obtain a link token from the provider.
`BANK_PROVIDER_ERROR`	The upstream provider returned an error during token exchange or sync.
`BANK_ACCOUNT_NOT_FOUND`	The referenced account does not exist.
`BANK_ACCOUNT_UNAUTHORIZED`	The account exists but does not belong to the authenticated user.
`GATE-403-001`	The user does not have the bank-linking entitlement.

Webhooks

Provider webhooks terminate on Sumvin. You do not subscribe to them or post to them — their effects land on the partner-facing endpoints:

Completed bank link → account appears on GET /v0/accounts.
Connection status change → account status updates (active, refresh_required, disconnected, error).
Account disconnect → account soft-deleted from /v0/accounts.
Transaction aggregation → transactions appear on /v0/transactions for the affected accounts.
Ramp settlement → transaction on /v0/ramp/transactions moves to completed or failed.

Poll the relevant resource for the terminal state. Partner-facing webhooks are not yet available.

Ramps & banking
Supported values — currency, country, and payment-method codes
Bank linking
KYC passthrough
On-ramp quickstart

Introduction

Quickstarts

Guides

Product Guides

API Reference

Authentication

Provider routing

Status codes per endpoint

Ramp

Bank linking

Linked account management

Ramp status lifecycle

Error code reference

Ramp

Bank linking

Webhooks

​Authentication

​Provider routing

​Status codes per endpoint

​Ramp

​Bank linking

​Linked account management

​Ramp status lifecycle

​Error code reference

​Ramp

​Bank linking

​Webhooks

​Related

Authentication

Provider routing

Status codes per endpoint

Ramp

Bank linking

Linked account management

Ramp status lifecycle

Error code reference

Ramp

Bank linking

Webhooks

Related